api in pairs: main && test apis: action, state, specs: bulk specs

[AmitKumarDas]

• golang module: relm
• golang package: relm/pkg/carvel
• golang file: relm/pkg/carvel/bundle.go
• last updated date: 23/JUL/2024

package carvel

type AnySpecsValidate interface {
 // public; external clients can invoke
 ValidateSpecs() error
}

type AnyBundlePush interface {
 // AnySpecsValidate ensures the instance of AnyBundlePush can be validated
 AnySpecsValidate

 // private; avoid custom implementations by external client
 pushBundle() (BundleResult, error)
}

type AnyBundlePushAssert interface {
 AnyBundlePush

 assertBundlePush() (AssertResult, error)
}

var _ AnyBundleCreate = &NestedBundleCreateSpecs{}
var _ AnyBundlePush = &BundlePushSpecs{}
var _ AnyPackageCRResolve = &PackageCRResolveSpecs{}
var _ AnyFileCopy = &FileCopySpecs{}

// Copy Package Metadata CR yaml to output location
var myFile1 = FileCopySpecs {
 Source: "path/to/component/package-meta-cr.yaml",
 Destination: "nested/bundle/config/component-v1.0.0/package-meta-cr.yaml",
}

// Resolve Package CR yaml & copy the resolved yaml to output location
var myPkgCR2 = PackageCRResolveSpecs {
 Method: YttFileOut, // Low level operation; declarative
 Source: "path/to/component/package.yaml",
 Destination: "nested/bundle/config/component/package.yaml", 
 KeyValues: map[string]string {
 "version": "v1.0.0",
 "image": "address/component_bundle@sha256:digestxxxx",
 },
}

// Push a bundle file (that was created earlier) to registry, 
// Then resolve the corresponding Package CR yaml using above registry endpoint, 
// Finally copy the resolved Package CR yaml to declared output location
var myBundle1 = &BundlePushSpecs {
 Method: ImgpkgCopyTarToRepo, // Low level operation; declarative
 Source: BundleSourceSpecs {
 BundleFilePath: "${GOBUILD_RELM_PATH}/bundle.tar.gz",
 },
 Destination: BundleDestinationSpecs {
 Address: "localhost:5000",
 BundlePath: "bundles/relm_bun",
 BundleTag: "v1.0.0", 
 },
 PackageCR: &PackageCRResolveSpecs { // [optional];
 Method: YttFileOut,
 Source: "relm/package.yaml", // templated file
 Destination: "nested/bundle/config/relm/package.yaml", 
 KeyValues: map[string]string {
 "version": "v1.0.0",
 "image": "localhost:5000/bundles/relm_bun:v1.0.0",
 },
 KeyValueRefs: map[string]string { // Alternative to KeyValues
 "version": LookupBundleTag,
 "image": LookupBundleURLTag,
 },
 refValues: map[string]string { // Private/Internal; filled up by BundleSpecs
 LookupBundleTag: "v1.0.0",
 LookupBundleURLTag: "localhost:5000/bundles/relm_bun:v1.0.0",
 LookupBundleURLDigest: "localhost:5000/bundles/relm_bun@sha256:digestxxx",
 },
 },
}

• Summary

- One interface per action i.e. API
- Interfaces determine the main behaviour i.e. API
- Use prefix `Any` for interface names
- Use suffix `Specs` for struct names
- One struct (i.e. specs) for multiple interfaces wherever possible
- Every API should have corresponding Assert API
- Read (i.e. Maintainability) over Write (i.e. Implementation)
 - Distinct, Non ambiguous, Easy to understand
- Use verbose field names in Specs struct
- Use verbose method / function names
 - E.g.: getXXX, runXXX, createXXX, newXXX, etc.
- Keywords:
 - `XXXState` # PackageCRState, etc.; Multiple States per Action
 - `PostOperation` # PreOperation, etc.
 - `Method` # ImgpkgCopy, Ytt, CranePull, etc.
 - Names the `Low Level Operations`
 - `Target` # w.r.t Assert i.e. TargetUnderTest