api names: experiment with the design with flexibility in mind

[AmitKumarDas]

• Put some futuristic constraints early on to get to better designs & names
• List down all the alternatives & take a decision
• Last updated date: 15/JUL/2024

Attempt 1

package carvelgen

func Bundle(specs BundleSpecs) (BundleResult, error)
func NestedBundle(specs BundleSpecs) (NestedBundleResult, error)

Attempt 2

package carvelgen

type AnyBundle interface {}

// Bundle is the entity name
var _ AnyBundle = BundleSpecs{}

// NestedBundle is fit to be considered as the entity name
// Note: It is important to avoid considering `Nested` as a behaviour
// Note: `Nest` can be considered as behaviour
// Note: `Nested` can be considered as the state of the entity 
var _ AnyBundle = NestedBundleSpecs{}

// Bundle creates a new bundle
// Nice: No need for NestedBundle API
func Bundle(specs AnyBundle) (BundleResult, error)

Attempt 3

// Package carvel deals all things about carvel 
// Note: Removed `gen` suffix. 
// Note: It is not good practice to tie behaviour & entity together to name a package
// Note: Package `carvelgen` can not expose List, Get, Delete etc. APIs
package carvel

// NewBundle creates a new package bundle instance
// Idiomatic: NewXXX implies creating a memory object
// Avoid: NewPackageBundle etc. since carvel folks can understand without the extra bits
func NewBundle()

// CreateBundle creates a new bundle in the PWD with .tar.gz as the file extension
// Note: CreateBundle differentiates clearly from NewBundle
func CreateBundle()

// GetBundle fetches the bundle as a file from Gobuild, Artifactory, etc.
// Note: The specifics of fetching from Gobuild or Artifactory is handled via Specs
// E.g.: GobuildBundleGetSpecs, ArtifactoryBundleGetSpecs
//
// Even better with GobuildBundleSpecs, ArtifactoryBundleSpecs, etc.
// Since it is best to avoid attaching behaviour with entity to name another entity
func GetBundle()

// DeleteBundle deletes the bundle from Gobuild, Artifactory, etc.
// Note: The specifics of deleting the exact bundle from Gobuild or Artifactory
// is handled via Specs
// E.g.: GobuildBundleSpecs, ArtifactoryBundleSpecs
func DeleteBundle()

// ListBundle lists the bundles from artifactory, gobuild, etc.
// Note: The specifics of listing from Gobuild, Artifactory, etc is handled via Specs
// E.g.: GobuildBundleSpecs, ArtifactoryBundleSpecs
func ListBundle()

Attempt 4

• file: relm/pkg/carvel/bundle.go

package carvel

// Note: Single method contract per API
type AnyBundleNew interface {
  newBundle()
}

type AnyBundleCreate interface {
  createBundle()
}

type AnyBundleGet interface {
  getBundle()
}

// Notes:
// - Single specs for all contracts wherever possible
// - One or more specs for all contracts if required
// - `Action` field will help switch to the exact contract method
// - `State` [optional] field further allows to switch logic per action

var _ AnyBundleNew = BundleSpecs {} // Action: New

var _ AnyBundleCreate = BundleSpecs {} // Action: Create
var _ AnyBundleCreate = PackageCRBundleSpecs {} // Action: Create
var _ AnyBundleCreate = GobuildBundleSpecs {} // Action: Create
var _ AnyBundleCreate = ArtifactoryBundleSpecs {} // Action: Create
var _ AnyBundleCreate = BuildsquidBundleSpecs {} // Action: Create

var _ AnyBundleGet = GobuildBundleSpecs {} // Action: Get
var _ AnyBundleGet = ArtifactoryBundleSpecs {} // Action: Get

var _ AnyBundleList = GobuildBundleSpecs {} // Action: List
var _ AnyBundleList = ArtifactoryBundleSpecs {} // Action: List

var _ AnyBundlePush = ArtifactoryBundleSpecs {} // Action: Push
var _ AnyBundlePush = DevArtifactoryBundleSpecs {} // Action: Push
var _ AnyBundlePush = CDNBundleSpecs {} // Action: Push

/*
  These signatures say it all
 */

func CreateBundle(specs AnyBundleCreate) (BundleResult, error)
func GetBundle(specs AnyBundleGet) (BundleResult, error)
func ListBundle(specs AnyBundleList, more ...AnyBundleList) (BundleResult, error)
func DeleteBundle(specs AnyBundleDelete) (BundleResult, error)
func PushBundle(specs AnyBundlePush) (BundleResult, error)
func NewBundle(specs AnyBundleNew) (Bundle, error) // * Bundle, not BundleResult