cas

README

umoci/oci/cas

This is a reimplemented version of the currently in-flight image-tools CAS PR, which combines the cas and refs interfaces into a single Engine that represents the image. In addition, I've implemented more auto-detection and creature comforts.

When the PR is merged, these changes will probably go upstream as well.

Documentation

Index

• Constants
• Variables
• type Engine

Constants

const (
	// BlobAlgorithm is the name of the only supported digest algorithm for blobs.
	// FIXME: We can make this a list.
	BlobAlgorithm = digest.SHA256
)

Variables

var (
	// ErrNotExist is effectively an implementation-neutral version of
	// os.ErrNotExist.
	ErrNotExist = fmt.Errorf("no such blob or index")

	// ErrInvalid is returned when an image was detected as being invalid.
	ErrInvalid = fmt.Errorf("invalid image detected")

	// ErrUnknownType is returned when an unknown (or otherwise unparseable)
	// mediatype is encountered. Callers should not ignore this error unless it
	// is in a context where ignoring it is more friendly to spec extensions.
	ErrUnknownType = fmt.Errorf("unknown mediatype encountered")

	// ErrNotImplemented is returned when a requested operation has not been
	// implementing the backing image store.
	ErrNotImplemented = fmt.Errorf("operation not implemented")

	// ErrClobber is returned when a requested operation would require clobbering a
	// reference or blob which already exists.
	ErrClobber = fmt.Errorf("operation would clobber existing object")
)

Exposed errors.

Types

type Engine

type Engine interface {
	// PutBlob adds a new blob to the image. This is idempotent; a nil error
	// means that "the content is stored at DIGEST" without implying "because
	// of this PutBlob() call".
	PutBlob(ctx context.Context, reader io.Reader) (digest digest.Digest, size int64, err error)

	// GetBlob returns a reader for retrieving a blob from the image, which the
	// caller must Close(). Returns ErrNotExist if the digest is not found.
	GetBlob(ctx context.Context, digest digest.Digest) (reader io.ReadCloser, err error)

	// PutIndex sets the index of the OCI image to the given index, replacing
	// the previously existing index. This operation is atomic; any readers
	// attempting to access the OCI image while it is being modified will only
	// ever see the new or old index.
	PutIndex(ctx context.Context, index ispec.Index) (err error)

	// GetIndex returns the index of the OCI image. Return ErrNotExist if the
	// digest is not found. If the image doesn't have an index, ErrInvalid is
	// returned (a valid OCI image MUST have an image index).
	//
	// It is not recommended that users of cas.Engine use this interface
	// directly, due to the complication of properly handling references as
	// well as correctly handling nested indexes. casext.Engine provides a
	// wrapper for cas.Engine that implements various reference resolution
	// functions that should work for most users.
	GetIndex(ctx context.Context) (index ispec.Index, ierr error)

	// DeleteBlob removes a blob from the image. This is idempotent; a nil
	// error means "the content is not in the store" without implying "because
	// of this DeleteBlob() call".
	DeleteBlob(ctx context.Context, digest digest.Digest) (err error)

	// ListBlobs returns the set of blob digests stored in the image.
	ListBlobs(ctx context.Context) (digests []digest.Digest, err error)

	// Clean executes a garbage collection of any non-blob garbage in the store
	// (this includes temporary files and directories not reachable from the
	// CAS interface). This MUST NOT remove any blobs or references in the
	// store.
	Clean(ctx context.Context) (err error)

	// Close releases all references held by the engine. Subsequent operations
	// may fail.
	Close() (err error)
}

Engine is an interface that provides methods for accessing and modifying an OCI image, namely allowing access to reference descriptors and blobs.