oci

Documentation

Overview

Package oci provides access to an OCI content store. Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md

Index

• type ReadOnlyStorage
  • func NewStorageFromFS(fsys fs.FS) *ReadOnlyStorage
  • func NewStorageFromTar(path string) (*ReadOnlyStorage, error)
  • func (s *ReadOnlyStorage) Exists(_ context.Context, target ocispec.Descriptor) (bool, error)
  • func (s *ReadOnlyStorage) Fetch(_ context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
• type ReadOnlyStore
  • func NewFromFS(ctx context.Context, fsys fs.FS) (*ReadOnlyStore, error)
  • func NewFromTar(ctx context.Context, path string) (*ReadOnlyStore, error)
  • func (s *ReadOnlyStore) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)
  • func (s *ReadOnlyStore) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
  • func (s *ReadOnlyStore) Predecessors(ctx context.Context, node ocispec.Descriptor) ([]ocispec.Descriptor, error)
  • func (s *ReadOnlyStore) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)
  • func (s *ReadOnlyStore) Tags(ctx context.Context, last string, fn func(tags []string) error) error
• type Storage
  • func NewStorage(root string) (*Storage, error)
  • func (s *Storage) Delete(ctx context.Context, target ocispec.Descriptor) error
  • func (s *Storage) Push(_ context.Context, expected ocispec.Descriptor, content io.Reader) error
• type Store
  • func New(root string) (*Store, error)
  • func NewWithContext(ctx context.Context, root string) (*Store, error)
  • func (s *Store) Delete(ctx context.Context, target ocispec.Descriptor) error
  • func (s *Store) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)
  • func (s *Store) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
  • func (s *Store) GC(ctx context.Context) error
  • func (s *Store) Predecessors(ctx context.Context, node ocispec.Descriptor) ([]ocispec.Descriptor, error)
  • func (s *Store) Push(ctx context.Context, expected ocispec.Descriptor, reader io.Reader) error
  • func (s *Store) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)
  • func (s *Store) SaveIndex() error
  • func (s *Store) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error
  • func (s *Store) Tags(ctx context.Context, last string, fn func(tags []string) error) error
  • func (s *Store) Untag(ctx context.Context, reference string) error

Types

type ReadOnlyStorage

type ReadOnlyStorage struct {
	// contains filtered or unexported fields
}

ReadOnlyStorage is a read-only CAS based on file system with the OCI-Image layout. Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md

func NewStorageFromFS

func NewStorageFromFS(fsys fs.FS) *ReadOnlyStorage

NewStorageFromFS creates a new read-only CAS from fsys.

func NewStorageFromTar

func NewStorageFromTar(path string) (*ReadOnlyStorage, error)

NewStorageFromTar creates a new read-only CAS from a tar archive located at path.

func (*ReadOnlyStorage) Exists

func (s *ReadOnlyStorage) Exists(_ context.Context, target ocispec.Descriptor) (bool, error)

Exists returns true if the described content Exists.

func (*ReadOnlyStorage) Fetch

func (s *ReadOnlyStorage) Fetch(_ context.Context, target ocispec.Descriptor) (io.ReadCloser, error)

Fetch fetches the content identified by the descriptor.

type ReadOnlyStore

type ReadOnlyStore struct {
	// contains filtered or unexported fields
}

ReadOnlyStore implements `oras.ReadonlyTarget`, and represents a read-only content store based on file system with the OCI-Image layout. Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md

func NewFromFS

func NewFromFS(ctx context.Context, fsys fs.FS) (*ReadOnlyStore, error)

NewFromFS creates a new read-only OCI store from fsys.

func NewFromTar

func NewFromTar(ctx context.Context, path string) (*ReadOnlyStore, error)

NewFromTar creates a new read-only OCI store from a tar archive located at path.

func (*ReadOnlyStore) Exists

func (s *ReadOnlyStore) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)

Exists returns true if the described content exists.

func (*ReadOnlyStore) Fetch

func (s *ReadOnlyStore) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)

Fetch fetches the content identified by the descriptor.

func (*ReadOnlyStore) Predecessors

func (s *ReadOnlyStore) Predecessors(ctx context.Context, node ocispec.Descriptor) ([]ocispec.Descriptor, error)

Predecessors returns the nodes directly pointing to the current node. Predecessors returns nil without error if the node does not exists in the store.

func (*ReadOnlyStore) Resolve

func (s *ReadOnlyStore) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)

Resolve resolves a reference to a descriptor. If the reference to be resolved is a tag, the returned descriptor will be a full descriptor declared by github.com/opencontainers/image-spec/specs-go/v1. If the reference is a digest the returned descriptor will be a plain descriptor (containing only the digest, media type and size).

func (*ReadOnlyStore) Tags

func (s *ReadOnlyStore) Tags(ctx context.Context, last string, fn func(tags []string) error) error

Tags lists the tags presented in the `index.json` file of the OCI layout, returned in ascending order. If `last` is NOT empty, the entries in the response start after the tag specified by `last`. Otherwise, the response starts from the top of the tags list.

See also `Tags()` in the package `registry`.

type Storage

type Storage struct {
	*ReadOnlyStorage
	// contains filtered or unexported fields
}

Storage is a CAS based on file system with the OCI-Image layout. Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md

func NewStorage

func NewStorage(root string) (*Storage, error)

NewStorage creates a new CAS based on file system with the OCI-Image layout.

func (*Storage) Delete

func (s *Storage) Delete(ctx context.Context, target ocispec.Descriptor) error

Delete removes the target from the system.

func (*Storage) Push

func (s *Storage) Push(_ context.Context, expected ocispec.Descriptor, content io.Reader) error

Push pushes the content, matching the expected descriptor.

type Store

type Store struct {
	// AutoSaveIndex controls if the OCI store will automatically save the index
	// file when needed.
	//   - If AutoSaveIndex is set to true, the OCI store will automatically save
	//     the changes to `index.json` when
	//      1. pushing a manifest
	//      2. calling Tag() or Delete()
	//   - If AutoSaveIndex is set to false, it's the caller's responsibility
	//     to manually call SaveIndex() when needed.
	//   - Default value: true.
	AutoSaveIndex bool

	// AutoGC controls if the OCI store will automatically clean dangling
	// (unreferenced) blobs created by the Delete() operation. This includes the
	// referrers and the unreferenced successor blobs of the deleted content.
	// Tagged manifests will not be deleted.
	//   - Default value: true.
	AutoGC bool
	// contains filtered or unexported fields
}

Store implements `oras.Target`, and represents a content store based on file system with the OCI-Image layout. Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md

func New

func New(root string) (*Store, error)

New creates a new OCI store with context.Background().

func NewWithContext

func NewWithContext(ctx context.Context, root string) (*Store, error)

NewWithContext creates a new OCI store.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, target ocispec.Descriptor) error

Delete deletes the content matching the descriptor from the store. Delete may fail on certain systems (i.e. NTFS), if there is a process (i.e. an unclosed Reader) using target. If s.AutoGC is set to true, Delete will recursively remove the dangling blobs caused by the current delete. If s.AutoDeleteReferrers is set to true, Delete will recursively remove the referrers of the manifests being deleted.

func (*Store) Exists

func (s *Store) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)

Exists returns true if the described content exists.

func (*Store) Fetch

func (s *Store) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)

Fetch fetches the content identified by the descriptor. It returns an io.ReadCloser. It's recommended to close the io.ReadCloser before a Delete operation, otherwise Delete may fail (for example on NTFS file systems).

func (*Store) GC

func (s *Store) GC(ctx context.Context) error

GC removes garbage from Store. Unsaved index will be lost. To prevent unexpected loss, call SaveIndex() before GC or set AutoSaveIndex to true. The garbage to be cleaned are:

• unreferenced (dangling) blobs in Store which have no predecessors
• garbage blobs in the storage whose metadata is not stored in Store

func (*Store) Predecessors

func (s *Store) Predecessors(ctx context.Context, node ocispec.Descriptor) ([]ocispec.Descriptor, error)

Predecessors returns the nodes directly pointing to the current node. Predecessors returns nil without error if the node does not exists in the store.

func (*Store) Push

func (s *Store) Push(ctx context.Context, expected ocispec.Descriptor, reader io.Reader) error

Push pushes the content, matching the expected descriptor.

func (*Store) Resolve

func (s *Store) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)

Resolve resolves a reference to a descriptor. If the reference to be resolved is a tag, the returned descriptor will be a full descriptor declared by github.com/opencontainers/image-spec/specs-go/v1. If the reference is a digest the returned descriptor will be a plain descriptor (containing only the digest, media type and size).

func (*Store) SaveIndex

func (s *Store) SaveIndex() error

SaveIndex writes the `index.json` file to the file system.

• If AutoSaveIndex is set to true (default value), the OCI store will automatically save the changes to `index.json` on Tag() and Delete() calls, and when pushing a manifest.
• If AutoSaveIndex is set to false, it's the caller's responsibility to manually call this method when needed.

func (*Store) Tag

func (s *Store) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error

Tag tags a descriptor with a reference string. reference should be a valid tag (e.g. "latest"). Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md#indexjson-file

func (*Store) Tags

func (s *Store) Tags(ctx context.Context, last string, fn func(tags []string) error) error

Tags lists the tags presented in the `index.json` file of the OCI layout, returned in ascending order. If `last` is NOT empty, the entries in the response start after the tag specified by `last`. Otherwise, the response starts from the top of the tags list.

See also `Tags()` in the package `registry`.

func (*Store) Untag

func (s *Store) Untag(ctx context.Context, reference string) error