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 CreateLayout(path string) error
• func GC(ctx context.Context, engine Engine) error
• type Blob
  • func FromDescriptor(ctx context.Context, engine Engine, descriptor *ispec.Descriptor) (*Blob, error)
  • func (b *Blob) Close()
• type Engine
  • func Open(path 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 = "sha256"
)

const ImageLayoutVersion = "1.0.0"

ImageLayoutVersion is the version of the image layout we support. This value is *not* the same as imagespec.Version, and the meaning of this field is still under discussion in the spec. For now we'll just hardcode the value and hope for the best.

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 CreateLayout

func CreateLayout(path string) error

CreateLayout creates a new OCI image layout at the given path. If the path already exists, os.ErrExist is returned. However, all of the parent components of the path will be created if necessary.

func GC

func GC(ctx context.Context, engine Engine) 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.

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 string

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

func FromDescriptor

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

FromDescriptor parses the blob referenced by the given descriptor.

func (*Blob) Close

func (b *Blob) Close()

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

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 string, 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.
	PutBlobJSON(ctx context.Context, data interface{}) (digest string, 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 string) (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 string) (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 []string, err error)

	// ListReferences returns the set of reference names stored in the image.
	ListReferences(ctx context.Context) (names []string, err error)

	// GC 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.
	GC(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(path string) (Engine, error)

Open will create an Engine reference to the OCI image at the provided path. If the image format is not supported, ErrNotImplemented will be returned. If the path does not exist, os.ErrNotExist will be returned.