claim

package
v0.25.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 14, 2024 License: MIT Imports: 13 Imported by: 5

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

View Source 
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.

View Source 
const (
	ActionInstall   = "install"
	ActionUpgrade   = "upgrade"
	ActionUninstall = "uninstall"
	ActionUnknown   = "unknown"
)

Action constants define the CNAB action to be taken

View Source 
const (
	// OutputContentDigest is the output metadata key for the output's content digest.
	OutputContentDigest = "contentDigest"

	// OutputGeneratedByBundle is the output metadata key for if the output was
	// defined by the bundle and the value was set by the invocation image. Some
	// outputs are created by the executing driver or CNAB tool.
	OutputGeneratedByBundle = "generatedByBundle"

	// OutputInvocationImageLogs is a well-known output name used to store the logs from the invocation image.
	OutputInvocationImageLogs = "io.cnab.outputs.invocationImageLogs"
)

Output constants define metadata about outputs that may be stored on a claim Result.

View Source 
const 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.

Variables

View Source 
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 

func GetDefaultSchemaVersion() schema.Version

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 NewULID 

func NewULID() (string, error)

NewULID generates a string representation of a ULID.

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 

func (c Claim) GetLastResult() (Result, error)

GetLastResult returns the most recent (last) result associated with the claim.

func (Claim) GetStatus 

func (c Claim) GetStatus() string

GetStatus returns the status of the claim using the last result.

func (Claim) HasLogs added in v0.18.0 

func (c Claim) HasLogs() (hasLogs bool, ok bool)

HasLogs indicates if logs were persisted for the bundle action. When ok is false, this indicates that the result is indeterminate because results are not loaded on the claim.

func (Claim) IsModifyingAction 

func (c Claim) IsModifyingAction() (bool, error)

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.

func (Claim) NewResult 

func (c Claim) NewResult(status string) (Result, error)

NewResult is a convenience for creating a result with the necessary fields set on a Result.

func (Claim) Validate 

func (c Claim) Validate() error

Validate the Claim

type Claims 

type Claims []Claim

func (Claims) Len 

func (c Claims) Len() int

func (Claims) Less 

func (c Claims) Less(i, j int) bool

func (Claims) Swap 

func (c Claims) Swap(i, j int)

type Installation 

type Installation struct {
	Name string
	Claims
}

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 NewOutput 

func NewOutput(c Claim, r Result, name string, value []byte) Output

NewOutput creates a new Output document with all required values set.

func (Output) GetDefinition 

func (o Output) GetDefinition() (bundle.Output, bool)

GetDefinition returns the output definition, or false if the output is not defined.

func (Output) GetSchema 

func (o Output) GetSchema() (definition.Schema, bool)

GetSchema returns the schema for the output, or false if the schema is not defined.

type OutputMetadata 

type OutputMetadata map[string]map[string]string

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) GetGeneratedByBundle added in v0.18.0 

func (o *OutputMetadata) GetGeneratedByBundle(outputName string) (bool, bool)

GetGeneratedByBundle flag for the specified output.

func (OutputMetadata) GetMetadata added in v0.18.0 

func (o OutputMetadata) GetMetadata(outputName string, metadataKey string) (string, bool)

GetMetadata for the specified output and key.

func (*OutputMetadata) SetContentDigest 

func (o *OutputMetadata) SetContentDigest(outputName string, contentDigest string) error

SetContentDigest for the specified output.

func (*OutputMetadata) SetGeneratedByBundle added in v0.18.0 

func (o *OutputMetadata) SetGeneratedByBundle(outputName string, generatedByBundle bool) error

SetGeneratedByBundle for the specified output.

func (*OutputMetadata) SetMetadata added in v0.18.0 

func (o *OutputMetadata) SetMetadata(outputName string, metadataKey string, value string) error

SetMetadata for the specified output and key.

type Outputs 

type Outputs struct {
	// contains filtered or unexported fields
}

func NewOutputs 

func NewOutputs(outputs []Output) Outputs

func (Outputs) GetByIndex 

func (o Outputs) GetByIndex(i int) (Output, bool)

func (Outputs) GetByName 

func (o Outputs) GetByName(name string) (Output, bool)

func (Outputs) Len 

func (o Outputs) Len() int

func (Outputs) Less 

func (o Outputs) Less(i, j int) bool

func (Outputs) Swap 

func (o Outputs) Swap(i, j int)

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

func NewResult 

func NewResult(c Claim, status string) (Result, error)

NewResult creates a Result document with all required values set.

func (Result) HasLogs added in v0.18.0 

func (r Result) HasLogs() bool

HasLogs indicates if logs were persisted for the result.

func (Result) Validate 

func (r Result) Validate() error

Validate the Result

type Results 

type Results []Result

Results is a sortable list of Result documents.

func (Results) Len 

func (r Results) Len() int

func (Results) Less 

func (r Results) Less(i, j int) bool

func (Results) Swap 

func (r Results) Swap(i, j int)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.