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
- type DescriptorMapFunc
- type DescriptorPath
- type Engine
- func (e Engine) DeleteReference(ctx context.Context, refname string) error
- func (e Engine) FromDescriptor(ctx context.Context, descriptor ispec.Descriptor) (*Blob, error)
- func (e Engine) GC(ctx context.Context) error
- func (e Engine) ListReferences(ctx context.Context) ([]string, error)
- func (e Engine) Paths(ctx context.Context, root ispec.Descriptor) ([]DescriptorPath, error)
- func (e Engine) PutBlobJSON(ctx context.Context, data interface{}) (digest.Digest, int64, error)
- func (e Engine) Reachable(ctx context.Context, root ispec.Descriptor) ([]digest.Digest, 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 WalkFunc
Constants ¶
This section is empty.
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 ¶ added in v0.4.1
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 ¶ added in v0.3.0
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 { // MediaType is the OCI media type of Data. MediaType string // Digest is the digest of the parsed image. Note that this does not update // if Data is changed (it is the digest that this blob was parsed *from*). Digest digest.Digest // Data is the "parsed" blob taken from the OCI image's blob store, and is // typed according to the media type. The mapping from MIME => type is as // follows. // // ispec.MediaTypeDescriptor => ispec.Descriptor // ispec.MediaTypeImageManifest => ispec.Manifest // ispec.MediaTypeImageManifestList => ispec.ManifestList // ispec.MediaTypeImageLayer => io.ReadCloser // ispec.MediaTypeImageLayerGzip => io.ReadCloser // ispec.MediaTypeImageLayerNonDistributable => io.ReadCloser // ispec.MediaTypeImageLayerNonDistributableGzip => io.ReadCloser // ispec.MediaTypeImageConfig => ispec.Image 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.
type DescriptorMapFunc ¶ added in v0.3.0
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 ¶ added in v0.3.0
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/openSUSE/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 ¶ added in v0.3.0
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 ¶ added in v0.3.0
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 ¶
Engine is a wrapper around cas.Engine that provides additional, generic extensions to the transport-dependent cas.Engine implementation.
func NewEngine ¶ added in v0.3.1
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 ¶ added in v0.3.0
DeleteReference removes all entries in the index that match the given refname.
func (Engine) FromDescriptor ¶
FromDescriptor parses the blob referenced by the given descriptor.
func (Engine) GC ¶
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.
func (Engine) ListReferences ¶ added in v0.3.0
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) Paths ¶
func (e Engine) Paths(ctx context.Context, root ispec.Descriptor) ([]DescriptorPath, error)
Paths returns the set of descriptor paths that can be traversed from the provided root descriptor. It is effectively shorthand for Walk(). Note that there may be repeated descriptors in the returned slice, due to different blobs containing the same (or a similar) descriptor. However, the DescriptorPaths should be unique.
func (Engine) PutBlobJSON ¶ added in v0.3.0
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) Reachable ¶
Reachable returns the set of digests which can be reached using a descriptor path from the provided root descriptor. It is effectively a shorthand for Walk(). The returned slice will *not* contain any duplicate digest.Digest entries. Note that without descriptors, a digest is not particularly meaninful (OCI blobs are not self-descriptive).
func (Engine) ResolveReference ¶ added in v0.3.0
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 ¶ added in v0.3.0
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.
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.