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
• func Create(uri string) error
• func Register(driver Driver)
• type Driver
• type Engine
  • func Open(uri string) (Engine, error)

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 (
	// ErrInvalid is returned when an image was detected as being invalid.
	ErrInvalid = fmt.Errorf("invalid image detected")

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

Functions

func Create

func Create(uri string) error

Create creates a new image by one of the registered drivers that support the provided URI (if no such driver exists, an error is returned). If more than one driver supports the provided URI, the first of the candidate drivers to be registered is chosen.

func Register

func Register(driver Driver)

Register registers a new Driver in the global set of drivers. This is intended to be called from the init function in packages that implement cas.Engine (similar to the crypto package).

Types

type Driver

type Driver interface {
	// Supported returns whether the resource at the given URI is supported by
	// the driver (used for auto-detection). If two drivers support the same
	// URI, then the earliest registered driver takes precedence.
	//
	// Note that this is _not_ a validation of the URI -- if the URI refers to
	// an invalid or non-existent resource it is expected that the URI is
	// "supported".
	Supported(uri string) bool

	// Open "opens" a new CAS engine accessor for the given URI.
	Open(uri string) (Engine, error)

	// Create creates a new image at the provided URI.
	Create(uri string) error
}

Driver is an interface describing a CAS driver that can be used to create new cas.Engine instances. The intention is for this to be generic enough that multiple backends can be implemented for umoci and other tools without requiring changes to other components of such tools.

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)

	// 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).
	PutBlobJSON(ctx context.Context, data interface{}) (digest digest.Digest, size int64, err error)

	// PutReference adds a new reference descriptor blob to the image. This is
	// idempotent; a nil error means that "the descriptor is stored at NAME"
	// without implying "because of this PutReference() call". ErrClobber is
	// returned if there is already a descriptor stored at NAME, but does not
	// match the descriptor requested to be stored.
	PutReference(ctx context.Context, name string, descriptor ispec.Descriptor) (err error)

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

	// GetReference returns a reference from the image. Returns os.ErrNotExist
	// if the name was not found.
	GetReference(ctx context.Context, name string) (descriptor ispec.Descriptor, err 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)

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

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

	// ListReferences returns the set of reference names stored in the image.
	ListReferences(ctx context.Context) (names []string, 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.

func Open

func Open(uri string) (Engine, error)

Open returns a new cas.Engine created by one of the registered drivers that support the provided URI (if no such driver exists, an error is returned). If more than one driver supports the provided URI, the first of the candidate drivers to have been registered is chosen.