content

Documentation

Index

• Variables
• func AdaptInfo(info Info) filters.Adaptor
• func Copy(ctx context.Context, cw Writer, or io.Reader, size int64, ...) error
• func CopyReader(cw Writer, r io.Reader) (int64, error)
• func CopyReaderAt(cw Writer, ra ReaderAt, n int64) error
• func Exists(ctx context.Context, provider InfoProvider, desc ocispec.Descriptor) (bool, error)
• func NewReader(ra ReaderAt) io.Reader
• func ReadBlob(ctx context.Context, provider Provider, desc ocispec.Descriptor) ([]byte, error)
• func WriteBlob(ctx context.Context, cs Ingester, ref string, r io.Reader, ...) error
• type Info
• type InfoProvider
• type InfoReaderProvider
• type IngestManager
• type Ingester
• type Manager
• type Opt
  • func WithLabels(labels map[string]string) Opt
• type Provider
• type ReaderAt
• type Status
• type Store
• type WalkFunc
• type Writer
  • func OpenWriter(ctx context.Context, cs Ingester, opts ...WriterOpt) (Writer, error)
• type WriterOpt
  • func WithDescriptor(desc ocispec.Descriptor) WriterOpt
  • func WithRef(ref string) WriterOpt
• type WriterOpts

Variables

var ErrReset = errors.New("writer has been reset")

Functions

func AdaptInfo

func AdaptInfo(info Info) filters.Adaptor

AdaptInfo returns `filters.Adaptor` that handles `content.Info`.

func Copy

func Copy(ctx context.Context, cw Writer, or io.Reader, size int64, expected digest.Digest, opts ...Opt) error

Copy copies data with the expected digest from the reader into the provided content store writer. This copy commits the writer.

This is useful when the digest and size are known beforehand. When the size or digest is unknown, these values may be empty.

Copy is buffered, so no need to wrap reader in buffered io.

func CopyReader

func CopyReader(cw Writer, r io.Reader) (int64, error)

CopyReader copies to a writer from a given reader, returning the number of bytes copied. Note: if the writer has a non-zero offset, the total number of bytes read may be greater than those copied if the reader is not an io.Seeker. This copy does not commit the writer.

func CopyReaderAt

func CopyReaderAt(cw Writer, ra ReaderAt, n int64) error

CopyReaderAt copies to a writer from a given reader at for the given number of bytes. This copy does not commit the writer.

func Exists

func Exists(ctx context.Context, provider InfoProvider, desc ocispec.Descriptor) (bool, error)

Exists returns whether an attempt to access the content would not error out with an ErrNotFound error. It will return an encountered error if it was different than ErrNotFound.

func NewReader

func NewReader(ra ReaderAt) io.Reader

NewReader returns a io.Reader from a ReaderAt

func ReadBlob

func ReadBlob(ctx context.Context, provider Provider, desc ocispec.Descriptor) ([]byte, error)

ReadBlob retrieves the entire contents of the blob from the provider.

Avoid using this for large blobs, such as layers.

func WriteBlob

func WriteBlob(ctx context.Context, cs Ingester, ref string, r io.Reader, desc ocispec.Descriptor, opts ...Opt) error

WriteBlob writes data with the expected digest into the content store. If expected already exists, the method returns immediately and the reader will not be consumed.

This is useful when the digest and size are known beforehand.

Copy is buffered, so no need to wrap reader in buffered io.

Types

type Info

type Info struct {
	Digest    digest.Digest
	Size      int64
	CreatedAt time.Time
	UpdatedAt time.Time
	Labels    map[string]string
}

Info holds content specific information

type InfoProvider

type InfoProvider interface {
	// Info will return metadata about content available in the content store.
	//
	// If the content is not present, ErrNotFound will be returned.
	Info(ctx context.Context, dgst digest.Digest) (Info, error)
}

InfoProvider provides info for content inspection.

type InfoReaderProvider

type InfoReaderProvider interface {
	InfoProvider
	Provider
}

InfoReaderProvider provides both info and reader for the specific content.

type IngestManager

type IngestManager interface {
	// Status returns the status of the provided ref.
	Status(ctx context.Context, ref string) (Status, error)

	// ListStatuses returns the status of any active ingestions whose ref match
	// the provided regular expression. If empty, all active ingestions will be
	// returned.
	ListStatuses(ctx context.Context, filters ...string) ([]Status, error)

	// Abort completely cancels the ingest operation targeted by ref.
	Abort(ctx context.Context, ref string) error
}

IngestManager provides methods for managing ingestions. An ingestion is a not-yet-complete writing operation initiated using Ingester and identified by a ref string.

type Ingester

type Ingester interface {
	// Writer initiates a writing operation (aka ingestion). A single ingestion
	// is uniquely identified by its ref, provided using a WithRef option.
	// Writer can be called multiple times with the same ref to access the same
	// ingestion.
	// Once all the data is written, use Writer.Commit to complete the ingestion.
	Writer(ctx context.Context, opts ...WriterOpt) (Writer, error)
}

Ingester writes content

type Manager

type Manager interface {
	InfoProvider

	// Update updates mutable information related to content.
	// If one or more fieldpaths are provided, only those
	// fields will be updated.
	// Mutable fields:
	//  labels.*
	Update(ctx context.Context, info Info, fieldpaths ...string) (Info, error)

	// Walk will call fn for each item in the content store which
	// match the provided filters. If no filters are given all
	// items will be walked.
	Walk(ctx context.Context, fn WalkFunc, filters ...string) error

	// Delete removes the content from the store.
	Delete(ctx context.Context, dgst digest.Digest) error
}

Manager provides methods for inspecting, listing and removing content.

type Opt

type Opt func(*Info) error

Opt is used to alter the mutable properties of content

func WithLabels

func WithLabels(labels map[string]string) Opt

WithLabels allows labels to be set on content

type Provider

type Provider interface {
	// ReaderAt only requires desc.Digest to be set.
	// Other fields in the descriptor may be used internally for resolving
	// the location of the actual data.
	ReaderAt(ctx context.Context, desc ocispec.Descriptor) (ReaderAt, error)
}

Provider provides a reader interface for specific content

type ReaderAt

type ReaderAt interface {
	io.ReaderAt
	io.Closer
	Size() int64
}

ReaderAt extends the standard io.ReaderAt interface with reporting of Size and io.Closer

type Status

type Status struct {
	Ref       string
	Offset    int64
	Total     int64
	Expected  digest.Digest
	StartedAt time.Time
	UpdatedAt time.Time
}

Status of a content operation (i.e. an ingestion)

type Store

type Store interface {
	Manager
	Provider
	IngestManager
	Ingester
}

Store combines the methods of content-oriented interfaces into a set that are commonly provided by complete implementations.

Overall content lifecycle:

• Ingester is used to initiate a write operation (aka ingestion)
• IngestManager is used to manage (e.g. list, abort) active ingestions
• Once an ingestion is complete (see Writer.Commit), Provider is used to query a single piece of content by its digest
• Manager is used to manage (e.g. list, delete) previously committed content

Note that until ingestion is complete, its content is not visible through Provider or Manager. Once ingestion is complete, it is no longer exposed through IngestManager.

type WalkFunc

type WalkFunc func(Info) error

WalkFunc defines the callback for a blob walk.

type Writer

type Writer interface {
	// Close closes the writer, if the writer has not been
	// committed this allows resuming or aborting.
	// Calling Close on a closed writer will not error.
	io.WriteCloser

	// Digest may return empty digest or panics until committed.
	Digest() digest.Digest

	// Commit commits the blob (but no roll-back is guaranteed on an error).
	// size and expected can be zero-value when unknown.
	// Commit always closes the writer, even on error.
	// ErrAlreadyExists aborts the writer.
	Commit(ctx context.Context, size int64, expected digest.Digest, opts ...Opt) error

	// Status returns the current state of write
	Status() (Status, error)

	// Truncate updates the size of the target blob
	Truncate(size int64) error
}

Writer handles writing of content into a content store

func OpenWriter

func OpenWriter(ctx context.Context, cs Ingester, opts ...WriterOpt) (Writer, error)

OpenWriter opens a new writer for the given reference, retrying if the writer is locked until the reference is available or returns an error.

type WriterOpt

type WriterOpt func(*WriterOpts) error

WriterOpt is used for passing options to Ingester.Writer.

func WithDescriptor

func WithDescriptor(desc ocispec.Descriptor) WriterOpt

WithDescriptor specifies an OCI descriptor. Writer may optionally use the descriptor internally for resolving the location of the actual data. Write does not require any field of desc to be set. If the data size is unknown, desc.Size should be set to 0. Some implementations may also accept negative values as "unknown".

func WithRef

func WithRef(ref string) WriterOpt

WithRef specifies a ref string.

type WriterOpts

type WriterOpts struct {
	Ref  string
	Desc ocispec.Descriptor
}

WriterOpts is internally used by WriterOpt.