go example: sdk: api: declarative specs: 1

[AmitKumarDas]

Introduction

• go module path: myproject/go.mod
• go module name: myproj.com
• go package name: myproject/pkg/carvelgen

package carvelgen

/*
    APIs
 */

// PackageBundle generates a package bundle
func PackageBundle(specs AnyPackageBundle) (PackageBundleResult, error)

// PackageBundles is a bulk operation to generate one or more package bundles
func PackageBundles(specs []AnyPackageBundle) (PackageBundleResultList, error)

// PackageCR generates a Package CR yaml
func PackageCR(specs AnyPackageCR) (PackageCRResult, error)

// PackageMetadataCR generates a PackageMetadata CR yaml
func PackageMetadataCR(specs AnyPackageMetadataCR) (PackageMetadataCRResult, error)

// NestedBundle is same as PackageBundle. However, it has its own signature
// such that it can be extended without impacting PackageBundle
func NestedBundle(specs AnyNestedBundle) (NestedBundleResult, error)

/*
    Contracts

var _ AnyPackageBundle = PackageBundleGobuildDepSpecs{} // pre-built package
var _ AnyPackageBundle = PackageBundleRemotePackageCRSpecs{} // pre-built package
var _ AnyPackageBundle = PackageBundleSpecs{} // pre-built package; available locally
var _ AnyPackageBundle = PackageBundleBuildsquidSpecs{} // pre-built package
var _ AnyPackageBundle = PackageBundlePackageCRSpecs{} // pre-built package
var _ AnyPackageBundle = PackageBundleBuildSpecs{} // build the package

type Compatibility interface {
  isDeprecated() bool
  deprecationMessage() string
}

type AnyPackageBundle interface {
  Compatibility
  isPackageBundleSpecs() bool
  packageBundle() (PackageBundleResult, error)
}

 */

type AnyPackageBundle interface {}
type AnyPackageCR interface {}
type AnyPackageMetadataCR interface {}
type AnyNestedBundle interface {}

type AnyBundleConfig interface {} // e.g. &YttSpecs{}
type AnyImageLock interface {} // e.g. ImageLockKbldSpecs{}

// AnyOperation can define a CLI execution i.e. fire & forget
type AnyOperation interface {} // e.g. &PackageCRCopySpecs{}, &PackageBundleCopySpecs{}

/*
    Outputs
 */

type PackageBundleResult struct {}
type PackageBundleResultList struct {}
type PackageCRResult struct {}
type PackageMetadataCRResult struct {}
type NestedBundleResult struct {}
type OperationResult struct {}

type PackageBundleError struct {}
type PackageCRError struct {}
type PackageMetadataCRError struct {}
type NestedBundleError struct {}
type OperationError struct {}

/*
    Specs
 */

type PackageBundleGobuildDepSpecs struct {
  GobuildDepName string
}

type PackageBundleRemotePackageCRSpecs struct {
  URL string
}

type NestedBundleBuildSpecs struct {
  PackageBundleBuildSpecs
}

type PackageBundleBuildSpecs struct {
  OCIRegistryURL string
  BundleName string
  BundleTag string
  BundleContents BundleContentsSpecs
  Output AnyOperation // output as a .tar.gz & place it a declared file path
  PreBuild PackageBundlePreBuildSpecs // [optional]; e.g. use this to start the OCI registry
  PostBuild PackageBundlePostBuildSpecs // [optional];e.g. use this to resolve Package CR
  Debug bool // [optional];useful during debugging/ troubleshooting
  DryRun bool // [optional]; useful to try at production; without impacting production 

  internalSpecs PackageBundleBuildSpecsInternal // private; values are set internally
}

type PackageBundleBuildSpecsInternal struct {
  SchemaVersion string // version of the specifications
  WorkingDir string // some tmp directory; will be used to run file operations
}

type PackageBundlePreBuildSpecs struct { // name format: <Entity><Action>Specs
  Operations []AnyOperation // e.g. &RegistryStartSpecs{...}
}

type PackageBundlePostBuildSpecs struct { // name format: <Entity><Action>Specs
  Operations []AnyOperation // e.g. &PackageCRResolveSpecs{...}, &PackageCRCopySpecs{...}
}

type BundleContentsSpecs struct { // name format: <Entity>Specs
  BundlePath string
  BundleConfigPath string // [optional]; can be derived from BundlePath
  BundleDotImgpkgPath string // [optional]; can be derived from BundlePath
  ExtraBundleConfigs []AnyBundleConfig // [optional]
  ImageLock AnyImageLock
}

type YttSpecs struct { // name format: <Entity>Specs
  Files []string
  Values map[string]string
  OutputFiles string
}

type ImageLockKbldSpecs struct { // name format: <Entity><SubEntity>Specs
  Files []string
  Output string
}