casext

Documentation

Overview

Package casext provides extensions to the standard cas.Engine interface, allowing for generic functionality to be used on top of any implementation of cas.Engine.

Index

• Variables
• func IsValidReferenceName(refname string) bool
• func MapDescriptors(i interface{}, mapFunc DescriptorMapFunc) error
• type Blob
  • func (b *Blob) Close() error
• type DescriptorMapFunc
• type DescriptorPath
  • func (d DescriptorPath) Descriptor() ispec.Descriptor
  • func (d DescriptorPath) Root() ispec.Descriptor
• type Engine
  • func NewEngine(engine cas.Engine) Engine
  • func (e Engine) DeleteReference(ctx context.Context, refname string) error
  • func (e Engine) FromDescriptor(ctx context.Context, descriptor ispec.Descriptor) (_ *Blob, Err error)
  • func (e Engine) GC(ctx context.Context, policies ...GCPolicy) error
  • func (e Engine) GetVerifiedBlob(ctx context.Context, descriptor ispec.Descriptor) (io.ReadCloser, error)
  • func (e Engine) ListReferences(ctx context.Context) ([]string, error)
  • func (e Engine) PutBlobJSON(ctx context.Context, data interface{}) (digest.Digest, int64, error)
  • func (e Engine) ResolveReference(ctx context.Context, refname string) ([]DescriptorPath, error)
  • func (e Engine) UpdateReference(ctx context.Context, refname string, descriptor ispec.Descriptor) error
  • func (e Engine) Walk(ctx context.Context, root ispec.Descriptor, walkFunc WalkFunc) error
• type GCPolicy
• type WalkFunc

Variables

var ErrSkipDescriptor = errors.New("[internal] do not recurse into descriptor")

ErrSkipDescriptor is a special error returned by WalkFunc which will cause Walk to not recurse into the descriptor currently being evaluated by WalkFunc. This interface is roughly equivalent to filepath.SkipDir.

Functions

func IsValidReferenceName

func IsValidReferenceName(refname string) bool

IsValidReferenceName returns whether the provided annotation value for "org.opencontainers.image.ref.name" is actually valid according to the OCI specification. This only matches against the MUST requirement, not the SHOULD requirement. The EBNF defined in the specification is:

refname   ::= component ("/" component)*
component ::= alphanum (separator alphanum)*
alphanum  ::= [A-Za-z0-9]+
separator ::= [-._:@+] | "--"

func MapDescriptors

func MapDescriptors(i interface{}, mapFunc DescriptorMapFunc) error

MapDescriptors applies the given function once for every instance of ispec.Descriptor found in the given type, and replaces it with the returned value (which may be the same). This is done through the reflection API in Go, which means that hidden attributes may be inaccessible. DescriptorMapFunc will only be executed once for every ispec.Descriptor found.

Types

type Blob

type Blob struct {
	// Descriptor is the {mediatype,digest,length} 3-tuple. Note that this
	// isn't updated if the Data is modified.
	Descriptor ispec.Descriptor

	// Data is the "parsed" blob taken from the OCI image's blob store, and is
	// typed according to the media type. The default mappings from MIME =>
	// type is as follows (more can be registered using RegisterParser).
	//
	// ispec.MediaTypeDescriptor => ispec.Descriptor
	// ispec.MediaTypeImageManifest => ispec.Manifest
	// ispec.MediaTypeImageIndex => ispec.Index
	// ispec.MediaTypeImageLayer => io.ReadCloser
	// ispec.MediaTypeImageLayerGzip => io.ReadCloser
	// ispec.MediaTypeImageLayerNonDistributable => io.ReadCloser
	// ispec.MediaTypeImageLayerNonDistributableGzip => io.ReadCloser
	// ispec.MediaTypeImageConfig => ispec.Image
	// unknown => io.ReadCloser
	Data interface{}
}

Blob represents a "parsed" blob in an OCI image's blob store. MediaType offers a type-safe way of checking what the type of Data is.

func (*Blob) Close

func (b *Blob) Close() error

Close cleans up all of the resources for the opened blob.

type DescriptorMapFunc

type DescriptorMapFunc func(ispec.Descriptor) ispec.Descriptor

DescriptorMapFunc is a function that is used to provide a mapping between different descriptor values with MapDescriptors. It will not be called concurrently, and will only be called once for each recursively resolved element.

type DescriptorPath

type DescriptorPath struct {
	// Walk is the set of descriptors walked to reach Descriptor (inclusive).
	// The order is the same as the order of the walk, with the target being
	// the last entry and the entrypoint from index.json being the first.
	Walk []ispec.Descriptor `json:"descriptor_walk"`
}

DescriptorPath is used to describe the path of descriptors (from a top-level index) that were traversed when resolving a particular reference name. The purpose of this is to allow libraries like github.com/opencontainers/umoci/mutate to handle generic manifest updates given an arbitrary descriptor walk. Users of ResolveReference that don't care about the descriptor path can just use .Descriptor.

func (DescriptorPath) Descriptor

func (d DescriptorPath) Descriptor() ispec.Descriptor

Descriptor returns the final step in the DescriptorPath, which is the target descriptor being referenced by DescriptorPath. This is just shorthand for accessing the last entry of DescriptorPath.Walk. Descriptor will *panic* if DescriptorPath is invalid.

func (DescriptorPath) Root

func (d DescriptorPath) Root() ispec.Descriptor

Root returns the first step in the DescriptorPath, which is the point where the walk started. This is just shorthand for DescriptorPath.Walk[0]. Root will *panic* if DescriptorPath is invalid.

type Engine

type Engine struct {
	cas.Engine
}

Engine is a wrapper around cas.Engine that provides additional, generic extensions to the transport-dependent cas.Engine implementation.

func NewEngine

func NewEngine(engine cas.Engine) Engine

NewEngine returns a new Engine which acts as a wrapper around the given cas.Engine and provides additional, generic extensions to the transport-dependent cas.Engine implementation.

func (Engine) DeleteReference

func (e Engine) DeleteReference(ctx context.Context, refname string) error

DeleteReference removes all entries in the index that match the given refname.

func (Engine) FromDescriptor

func (e Engine) FromDescriptor(ctx context.Context, descriptor ispec.Descriptor) (_ *Blob, Err error)

FromDescriptor parses the blob referenced by the given descriptor.

func (Engine) GC

func (e Engine) GC(ctx context.Context, policies ...GCPolicy) error

GC will perform a mark-and-sweep garbage collection of the OCI image referenced by the given CAS engine. The root set is taken to be the set of references stored in the image, and all blobs not reachable by following a descriptor path from the root set will be removed.

GC will only call ListBlobs and ListReferences once, and assumes that there is no change in the set of references or blobs after calling those functions. In other words, it assumes it is the only user of the image that is making modifications. Things will not go well if this assumption is challenged.

Furthermore, GC policies (zero or more) can also be specified which given a blob's digest can indicate whether that blob needs to garbage collected. The blob is skipped for garbage collection if a policy returns false.

func (Engine) GetVerifiedBlob

func (e Engine) GetVerifiedBlob(ctx context.Context, descriptor ispec.Descriptor) (io.ReadCloser, error)

GetVerifiedBlob returns a VerifiedReadCloser for retrieving a blob from the image, which the caller must Close() *and* read-to-EOF (checking the error code of both). Returns ErrNotExist if the digest is not found, and ErrBlobDigestMismatch on a mismatched blob digest. In addition, the reader is limited to the descriptor.Size.

func (Engine) ListReferences

func (e Engine) ListReferences(ctx context.Context) ([]string, error)

ListReferences returns all of the ref.name entries that are specified in the top-level index. Note that the list may contain duplicates, due to the nature of references in the image-spec.

func (Engine) PutBlobJSON

func (e Engine) PutBlobJSON(ctx context.Context, data interface{}) (digest.Digest, int64, error)

PutBlobJSON adds a new JSON blob to the image (marshalled from the given interface). This is equivalent to calling PutBlob() with a JSON payload as the reader. Note that due to intricacies in the Go JSON implementation, we cannot guarantee that two calls to PutBlobJSON() will return the same digest.

TODO: Use a proper JSON serialisation library, which actually guarantees

consistent output. Go's JSON library doesn't even attempt to sort
map[...]... objects (which have their iteration order randomised in
Go).

func (Engine) ResolveReference

func (e Engine) ResolveReference(ctx context.Context, refname string) ([]DescriptorPath, error)

ResolveReference will attempt to resolve all possible descriptor paths to Manifests (or any unknown blobs) that match a particular reference name (if descriptors are stored in non-standard blobs, Resolve will be unable to find them but will return the top-most unknown descriptor). ResolveReference assumes that "reference name" refers to the value of the "org.opencontainers.image.ref.name" descriptor annotation. It is recommended that if the returned slice of descriptors is greater than zero that the user be consulted to resolve the conflict (due to ambiguity in resolution paths).

TODO: How are we meant to implement other restrictions such as the

architecture and feature flags? The API will need to change.

func (Engine) UpdateReference

func (e Engine) UpdateReference(ctx context.Context, refname string, descriptor ispec.Descriptor) error

UpdateReference replaces an existing entry for refname with the given descriptor. If there are multiple descriptors that match the refname they are all replaced with the given descriptor.

func (Engine) Walk

func (e Engine) Walk(ctx context.Context, root ispec.Descriptor, walkFunc WalkFunc) error

Walk preforms a depth-first walk from a given root descriptor, using the provided CAS engine to fetch all other necessary descriptors. If an error is returned by the provided WalkFunc, walking is terminated and the error is returned to the caller.

type GCPolicy

type GCPolicy func(ctx context.Context, digest digest.Digest) (bool, error)

GCPolicy is a policy function that returns 'true' if a blob can be GC'ed

type WalkFunc

type WalkFunc func(descriptorPath DescriptorPath) error

WalkFunc is the type of function passed to Walk. It will be a called on each descriptor encountered, recursively -- which may involve the function being called on the same descriptor multiple times (though because an OCI image is a Merkle tree there will never be any loops). If an error is returned by WalkFunc, the recursion will halt and the error will bubble up to the caller.

TODO: Also provide Blob to WalkFunc so that callers don't need to load blobs

more than once. This is quite important for remote CAS implementations.