claim

package
v0.13.3 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2020 License: MIT Imports: 15 Imported by: 3

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 (
	// 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.

View Source 
const (
	OutputContentDigest = "contentDigest"
)

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

Variables

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

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, error)

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 

func NewClaimStoreFileExtensions() map[string]string

NewClaimStoreFileExtensions builds a FileExtensions map suitable for use with a crud.FileSystem for a ClaimStore.

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) 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 EncryptionHandler 

type EncryptionHandler func([]byte) ([]byte, error)

EncryptionHandler is a function that transforms data by encrypting or decrypting it.

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]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 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 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

func NewResult 

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

NewResult creates a Result document with all required values set.

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)

type Store 

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

Store is a persistent store for claims.

func NewClaimStore 

func NewClaimStore(store *crud.BackingStore, encrypt EncryptionHandler, decrypt EncryptionHandler) Store

NewClaimStore creates a persistent store for claims using the specified backing key-blob store.

func NewMockStore 

func NewMockStore(encrypt EncryptionHandler, decrypt EncryptionHandler) Store

NewMockStore creates a mock claim store for unit testing.

func (Store) DeleteClaim 

func (s Store) DeleteClaim(claimID string) error

func (Store) DeleteInstallation 

func (s Store) DeleteInstallation(installation string) error

func (Store) DeleteOutput 

func (s Store) DeleteOutput(resultID string, outputName string) error

func (Store) DeleteResult 

func (s Store) DeleteResult(resultID string) error

func (Store) GetBackingStore 

func (s Store) GetBackingStore() *crud.BackingStore

GetBackingStore returns the data store behind this claim store.

func (Store) ListClaims 

func (s Store) ListClaims(installation string) ([]string, error)

func (Store) ListInstallations 

func (s Store) ListInstallations() ([]string, error)

func (Store) ListOutputs 

func (s Store) ListOutputs(resultID string) ([]string, error)

func (Store) ListResults 

func (s Store) ListResults(claimID string) ([]string, error)

func (Store) ReadAllClaims 

func (s Store) ReadAllClaims(installation string) ([]Claim, error)

func (Store) ReadAllInstallationStatus 

func (s Store) ReadAllInstallationStatus() ([]Installation, error)

func (Store) ReadAllResults 

func (s Store) ReadAllResults(claimID string) ([]Result, error)

func (Store) ReadClaim 

func (s Store) ReadClaim(claimID string) (Claim, 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) ReadLastClaim 

func (s Store) ReadLastClaim(installation string) (Claim, error)

func (Store) ReadLastOutput 

func (s Store) ReadLastOutput(installation string, name string) (Output, error)

ReadLastOutput returns the most recent value (last) of the specified Output associated with the installation.

func (Store) ReadLastOutputs 

func (s Store) ReadLastOutputs(installation string) (Outputs, error)

ReadLastOutputs returns the most recent (last) value of each output associated with the installation.

func (Store) ReadLastResult 

func (s Store) ReadLastResult(claimID string) (Result, error)

func (Store) ReadOutput 

func (s Store) ReadOutput(c Claim, r Result, outputName string) (Output, error)

func (Store) ReadResult 

func (s Store) ReadResult(resultID string) (Result, error)

func (Store) SaveClaim 

func (s Store) SaveClaim(c Claim) error

func (Store) SaveOutput 

func (s Store) SaveOutput(o Output) error

func (Store) SaveResult 

func (s Store) SaveResult(r Result) error

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.