Documentation ¶
Overview ¶
Package claim manages data associated with the Claim Spec https://github.com/cnabio/cnab-spec/blob/cnab-claim-1.0.0-DRAFT+b5ed2f3/400-claims.md
There are three types of claim data: Claim, Result and Output. How they are stored is not dictated by the spec, however we have selected access patterns around the lowest common denominator (filesystem). Each implementation has metadata available that allow for optimizations, for example using queries based on a foreign key, if the underlying storage systems supports it. The claim data creates a hierarchy representing a fourth type of data that isn't stored but is represented in-memory: Installation.
Below is the general layout of the data assuming the filesystem as the storage layer. Claims are grouped by the name of the installation, and keyed by the claim ID. Results are grouped by the claim ID and keyed by the result ID. Outputs are grouped by the result ID and are keyed by the "ResultID-OutputName" to generate a unique key. The groups allow for querying by storage systems that support it.
claims/
INSTALLATION/ CLAIM_ID
results/
CLAIM_ID/ RESULT_ID
outputs/
RESULT_ID/ RESULT_ID-OUTPUT_NAME
Example ¶
claims/
mysql/ 01EAZDEPCBPEEHQG9C4AF5X1PY.json (install) 01EAZDEW0R8MQ0GS5D5EAQA2J9.json (upgrade) wordpress/ 01EAZDF3ARH5J2D7A30A8Z9QRW.json (install)
results/
01EAZDEPCBPEEHQG9C4AF5X1PY/ (mysql - install) 01EAZDGPM8EQKXA544AHCBMYXH.json (success) 01EAZDEW0R8MQ0GS5D5EAQA2J9 (mysql - upgrade) 01EAZDHFZJE34ND6GE3BVPP1JA (success) 01EAZDF3ARH5J2D7A30A8Z9QRW (wordpress - install) 01EAZDJ8FPR0CD8BNG8EBBGA0N (running)
outputs/
01EAZDGPM8EQKXA544AHCBMYXH/ 01EAZDGPM8EQKXA544AHCBMYXH-CONNECTIONSTRING
Index ¶
- Constants
- Variables
- func GetDefaultSchemaVersion() (schema.Version, error)
- func MustNewULID() string
- func NewClaimStoreFileExtensions() map[string]string
- func NewULID() (string, error)
- type Claim
- func (c Claim) GetLastResult() (Result, error)
- func (c Claim) GetStatus() string
- func (c Claim) IsModifyingAction() (bool, error)
- func (c Claim) NewClaim(action string, bun bundle.Bundle, parameters map[string]interface{}) (Claim, error)
- func (c Claim) NewResult(status string) (Result, error)
- func (c Claim) Validate() error
- type Claims
- type EncryptionHandler
- type Installation
- type InstallationByModified
- type InstallationByName
- type Output
- type OutputMetadata
- type Outputs
- type Provider
- type Result
- type Results
- type Store
- func (s Store) DeleteClaim(claimID string) error
- func (s Store) DeleteInstallation(installation string) error
- func (s Store) DeleteOutput(resultID string, outputName string) error
- func (s Store) DeleteResult(resultID string) error
- func (s Store) GetBackingStore() crud.ManagedStore
- func (s Store) ListClaims(installation string) ([]string, error)
- func (s Store) ListInstallations() ([]string, error)
- func (s Store) ListOutputs(resultID string) ([]string, error)
- func (s Store) ListResults(claimID string) ([]string, error)
- func (s Store) ReadAllClaims(installation string) ([]Claim, error)
- func (s Store) ReadAllInstallationStatus() ([]Installation, error)
- func (s Store) ReadAllResults(claimID string) ([]Result, error)
- func (s Store) ReadClaim(claimID string) (Claim, error)
- func (s Store) ReadInstallation(installation string) (Installation, error)
- func (s Store) ReadInstallationStatus(installation string) (Installation, error)
- func (s Store) ReadLastClaim(installation string) (Claim, error)
- func (s Store) ReadLastOutput(installation string, name string) (Output, error)
- func (s Store) ReadLastOutputs(installation string) (Outputs, error)
- func (s Store) ReadLastResult(claimID string) (Result, error)
- func (s Store) ReadOutput(c Claim, r Result, outputName string) (Output, error)
- func (s Store) ReadResult(resultID string) (Result, error)
- func (s Store) SaveClaim(c Claim) error
- func (s Store) SaveOutput(o Output) error
- func (s Store) SaveResult(r Result) error
Constants ¶
const ( StatusSucceeded = "succeeded" StatusCanceled = "canceled" StatusFailed = "failed" StatusRunning = "running" StatusPending = "pending" StatusUnknown = "unknown" // Deprecated: StatusSuccess has been replaced by StatusSucceeded. StatusSuccess = StatusSucceeded // Deprecated: StatusFailure has been replaced by StatusFailed. StatusFailure = StatusFailed )
Status constants define the CNAB status fields on a Result.
const ( ActionInstall = "install" ActionUpgrade = "upgrade" ActionUninstall = "uninstall" ActionUnknown = "unknown" )
Action constants define the CNAB action to be taken
const ( // Deprecated: ItemType has been replaced by ItemTypeClaims. ItemType = "claims" ItemTypeInstallations = "installations" ItemTypeClaims = "claims" ItemTypeResults = "results" ItemTypeOutputs = "outputs" )
ItemType is the location in the backing store where claims are persisted.
const (
OutputContentDigest = "contentDigest"
)
Output constants define metadata about outputs that may be stored on a claim Result.
Variables ¶
var ( // ErrInstallationNotFound represents an installation not found in claim storage ErrInstallationNotFound = errors.New("Installation does not exist") // ErrClaimNotFound represents a claim not found in claim storage ErrClaimNotFound = errors.New("Claim does not exist") // ErrResultNotFound represents a result not found in claim storage ErrResultNotFound = errors.New("Result does not exist") // ErrOutputNotFound represents an output not found in claim storage ErrOutputNotFound = errors.New("Output does not exist") )
var CNABSpecVersion string = "cnab-claim-1.0.0-DRAFT+b5ed2f3"
CNABSpecVersion represents the CNAB Spec version of the Claim that this library implements This value is prefixed with e.g. `cnab-claim-` so isn't itself valid semver.
var ValidName = regexp.MustCompile("^[a-zA-Z0-9._-]+$")
ValidName is a regular expression that indicates whether a name is a valid claim name.
Functions ¶
func GetDefaultSchemaVersion ¶
GetDefaultSchemaVersion returns the default semver CNAB schema version of the Claim that this library implements
func MustNewULID ¶
func MustNewULID() string
MustNewULID generates a string representation of a ULID and panics on failure instead of returning an error.
func NewClaimStoreFileExtensions ¶
NewClaimStoreFileExtensions builds a FileExtensions map suitable for use with a crud.FileSystem for a ClaimStore.
Types ¶
type Claim ¶
type Claim struct { // SchemaVersion is the version of the claim schema. SchemaVersion schema.Version `json:"schemaVersion"` // Id of the claim. ID string `json:"id"` // Installation name. Installation string `json:"installation"` // Revision of the installation. Revision string `json:"revision"` // Created timestamp of the claim. Created time.Time `json:"created"` // Action executed against the installation. Action string `json:"action"` // Bundle is the definition of the bundle. Bundle bundle.Bundle `json:"bundle"` // BundleReference is the canonical reference to the bundle used in the action. BundleReference string `json:"bundleReference,omitempty"` // Parameters are the key/value pairs that were passed in during the operation. Parameters map[string]interface{} `json:"parameters,omitempty"` // Custom extension data applicable to a given runtime. Custom interface{} `json:"custom,omitempty"` // contains filtered or unexported fields }
Claim is an installation claim receipt.
Claims represent information about a particular installation, and provide the necessary data to upgrade and uninstall a CNAB package.
func New ¶
func New(installation string, action string, bun bundle.Bundle, parameters map[string]interface{}) (Claim, error)
New creates a new Claim initialized for an operation.
func (Claim) GetLastResult ¶
GetLastResult returns the most recent (last) result associated with the claim.
func (Claim) IsModifyingAction ¶
IsModifyingAction determines if the Claim's action modifies the bundle. Non-modifying actions are not required to be persisted by the Claims spec.
func (Claim) NewClaim ¶
func (c Claim) NewClaim(action string, bun bundle.Bundle, parameters map[string]interface{}) (Claim, error)
NewClaim is a convenience for creating a new claim from an existing claim.
type EncryptionHandler ¶
EncryptionHandler is a function that transforms data by encrypting or decrypting it.
type Installation ¶
Installation represents the installation of a bundle.
func NewInstallation ¶
func NewInstallation(name string, claims []Claim) Installation
NewInstallation creates an Installation and ensures the contained data is sorted.
func (Installation) GetInstallationTimestamp ¶
func (i Installation) GetInstallationTimestamp() (time.Time, error)
GetInstallationTimestamp searches the claims associated with the installation for the first claim for Install and returns its timestamp.
func (Installation) GetLastClaim ¶
func (i Installation) GetLastClaim() (Claim, error)
GetLastClaim returns the most recent (last) claim associated with the installation.
func (Installation) GetLastResult ¶
func (i Installation) GetLastResult() (Result, error)
GetLastResult returns the most recent (last) result associated with the installation.
func (Installation) GetLastStatus ¶
func (i Installation) GetLastStatus() string
GetLastStatus returns the status from the most recent (last) result associated with the installation, or "unknown" if it cannot be determined.
type InstallationByModified ¶
type InstallationByModified []Installation
InstallationByModified sorts installations by which has been modified most recently Assumes that the installation's claims have already been sorted first, for example with SortClaims or manually.
func (InstallationByModified) Len ¶
func (ibm InstallationByModified) Len() int
func (InstallationByModified) Less ¶
func (ibm InstallationByModified) Less(i, j int) bool
func (InstallationByModified) SortClaims ¶
func (ibm InstallationByModified) SortClaims()
SortClaims presorts the claims on each installation before the installations can be sorted.
func (InstallationByModified) Swap ¶
func (ibm InstallationByModified) Swap(i, j int)
type InstallationByName ¶
type InstallationByName []Installation
func (InstallationByName) Len ¶
func (ibn InstallationByName) Len() int
func (InstallationByName) Less ¶
func (ibn InstallationByName) Less(i, j int) bool
func (InstallationByName) Swap ¶
func (ibn InstallationByName) Swap(i, j int)
type Output ¶
type Output struct { // Name of the output. Name string // Value of the output persisted to storage. Value []byte // contains filtered or unexported fields }
Output represents a bundle output generated by an operation.
func (Output) GetDefinition ¶
GetDefinition returns the output definition, or false if the output is not defined.
type OutputMetadata ¶
type OutputMetadata map[string]interface{}
OutputMetadata is the output metadata from an operation. Any metadata can be stored, however this provides methods for safely querying and retrieving well-known metadata.
func (OutputMetadata) GetContentDigest ¶
func (o OutputMetadata) GetContentDigest(outputName string) (string, bool)
GetContentDigest for the specified output.
func (OutputMetadata) SetContentDigest ¶
func (o OutputMetadata) SetContentDigest(outputName string, contentDigest string) error
SetContentDigest for the specified output.
type Provider ¶
type Provider interface { // ListInstallations returns Installation names sorted in ascending order. ListInstallations() ([]string, error) // ListClaims returns Claim IDs associated with an Installation sorted in ascending order. ListClaims(installation string) ([]string, error) // ListResults returns Result IDs associated with a Claim, sorted in ascending order. ListResults(claimID string) ([]string, error) // ListOutputs returns the names of outputs associated with a result that // have been persisted. It is possible for results to have outputs that were // generated but not persisted see // https://github.com/cnabio/cnab-spec/blob/cnab-claim-1.0.0-DRAFT+b5ed2f3/400-claims.md#outputs // for more information. ListOutputs(resultID string) ([]string, error) // ReadInstallation returns the specified Installation with all Claims and their Results loaded. ReadInstallation(installation string) (Installation, error) // ReadInstallationStatus returns the specified Installation with the last Claim and its last Result loaded. ReadInstallationStatus(installation string) (Installation, error) // ReadAllInstallationStatus returns all Installations with the last Claim and its last Result loaded. ReadAllInstallationStatus() ([]Installation, error) // ReadClaim returns the specified Claim. ReadClaim(claimID string) (Claim, error) // ReadAllClaims returns all claims associated with an Installation, sorted in ascending order. ReadAllClaims(installation string) ([]Claim, error) // ReadLastClaim returns the last claim associated with an Installation. ReadLastClaim(installation string) (Claim, error) // ReadResult returns the specified Result. ReadResult(resultID string) (Result, error) // ReadAllResult returns all results associated with a Claim, sorted in ascending order. ReadAllResults(claimID string) ([]Result, error) // ReadLastResult returns the last result associated with a Claim. ReadLastResult(claimID string) (Result, error) // ReadAllOutputs returns the most recent (last) value of each Output associated // with the installation. ReadLastOutputs(installation string) (Outputs, error) // ReadLastOutput returns the most recent value (last) of the specified Output associated // with the installation. ReadLastOutput(installation string, name string) (Output, error) // ReadOutput returns the contents of the named output associated with the specified Result. ReadOutput(claim Claim, result Result, outputName string) (Output, error) // SaveClaim persists the specified claim. // Associated results, Claim.Results, must be persisted separately with SaveResult. SaveClaim(claim Claim) error // SaveResult persists the specified result. SaveResult(result Result) error // SaveOutput persists the output, encrypting the value if defined as // sensitive (write-only) in the bundle. SaveOutput(output Output) error // DeleteInstallation removes all data associated with the specified installation. DeleteInstallation(installation string) error // DeleteClaim removes all data associated with the specified claim. DeleteClaim(claimID string) error // DeleteResult removes all data associated with the specified result. DeleteResult(resultID string) error // DeleteOutput removes an output persisted with the specified result. DeleteOutput(resultID string, outputName string) error }
Provider interface for claim data.
type Result ¶
type Result struct { // Id of the result. ID string `json:"id"` // ClaimId associated with the claim that generated the result. ClaimID string `json:"claimId"` // Created timestamp of the result. Created time.Time `json:"created"` // Message communicates the outcome of the operation. Message string `json:"message,omitempty"` // Status of the operation, for example StatusSucceeded. Status string `json:"status"` // OutputMetadata generated by the operation, mapping from the output names to // metadata about the output. OutputMetadata OutputMetadata `json:"outputs,omitempty"` // Custom extension data applicable to a given runtime. Custom interface{} `json:"custom,omitempty"` // contains filtered or unexported fields }
Result tracks the result of an operation on a CNAB installation
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a persistent store for claims.
func NewClaimStore ¶
func NewClaimStore(store crud.ManagedStore, encrypt EncryptionHandler, decrypt EncryptionHandler) Store
NewClaimStore creates a persistent store for claims using the specified backing datastore.
func NewMockStore ¶
func NewMockStore(encrypt EncryptionHandler, decrypt EncryptionHandler) Store
NewMockStore creates a mock claim store for unit testing.
func (Store) DeleteClaim ¶
func (Store) DeleteInstallation ¶
func (Store) DeleteResult ¶
func (Store) GetBackingStore ¶
func (s Store) GetBackingStore() crud.ManagedStore
GetBackingStore returns the data store behind this claim store.
func (Store) ListInstallations ¶
func (Store) ReadAllInstallationStatus ¶
func (s Store) ReadAllInstallationStatus() ([]Installation, error)
func (Store) ReadInstallation ¶
func (s Store) ReadInstallation(installation string) (Installation, error)
func (Store) ReadInstallationStatus ¶
func (s Store) ReadInstallationStatus(installation string) (Installation, error)
func (Store) ReadLastOutput ¶
ReadLastOutput returns the most recent value (last) of the specified Output associated with the installation.
func (Store) ReadLastOutputs ¶
ReadLastOutputs returns the most recent (last) value of each output associated with the installation.