oci

Documentation

Overview

Package oci contains tools for handling OCI images.

Index

• func CreateLayout(ref Ref) (structfs.Tree, error)
• func ParseDigest(digest string) (algorithm string, encoded string, err error)
• func WalkRefs(digest string, ref Ref, fn func(digest string, ref Ref) error) error
• type Blobs
• type Image
  • func AsImage(ref Ref, err error) (*Image, error)
  • func (i *Image) Blob(descriptor *ocispecv1.Descriptor) (io.ReadCloser, error)
  • func (i *Image) Descriptors() iter.Seq[*ocispecv1.Descriptor]
  • func (i *Image) Digest() string
  • func (i *Image) MediaType() string
  • func (i *Image) RawManifest() []byte
  • func (i *Image) ReadBlobVerified(descriptor *ocispecv1.Descriptor) ([]byte, error)
  • func (i *Image) StructfsBlob(descriptor *ocispecv1.Descriptor) structfs.Blob
• type Index
  • func ReadLayoutIndex(path string) (*Index, error)
  • func (i *Index) Digest() string
  • func (i *Index) MediaType() string
  • func (i *Index) RawManifest() []byte
  • func (i *Index) Ref(descriptor *ocispecv1.Descriptor) (Ref, error)
• type Ref
  • func NewRef(rawManifest []byte, mediaType string, expectedDigest string, blobs Blobs) (Ref, error)
  • func ReadLayout(path string) (Ref, error)

Functions

func CreateLayout

func CreateLayout(ref Ref) (structfs.Tree, error)

CreateLayout builds an OCI layout from a Ref.

func ParseDigest

func ParseDigest(digest string) (algorithm string, encoded string, err error)

ParseDigest splits a digest into its components. It returns an error if the algorithm is not supported, or if encoded is not valid for the algorithm.

func WalkRefs

func WalkRefs(digest string, ref Ref, fn func(digest string, ref Ref) error) error

WalkRefs iterates over all Refs reachable from ref in DFS post-order. Each digest is only visited once, even if reachable multiple times.

For each Ref, we also pass the digest by which it is referenced. This may be different from ref.Digest() if we ever support multiple digest algorithms.

Types

type Blobs

type Blobs interface {
	// Blob returns the contents of a blob from its descriptor.
	// It does not verify the contents against the digest.
	//
	// This is only called on images.
	Blob(*ocispecv1.Descriptor) (io.ReadCloser, error)
	// Manifest returns the contents of a manifest from its descriptor.
	// It does not verify the contents against the digest.
	//
	// This is only called on indexes.
	Manifest(*ocispecv1.Descriptor) ([]byte, error)
	// Blobs returns the [Blobs] for the manifest from its descriptor.
	// Most implementations simply return the receiver itself, but this
	// allows combining Refs from different sources into an Index.
	//
	// This is only called on indexes.
	Blobs(*ocispecv1.Descriptor) (Blobs, error)
}

Blobs is the interface which image sources implement to retrieve the content of blobs and manifests.

type Image

type Image struct {
	// Manifest contains the parsed image manifest.
	Manifest *ocispecv1.Manifest
	// contains filtered or unexported fields
}

Image represents an OCI image.

func AsImage

func AsImage(ref Ref, err error) (*Image, error)

AsImage can be conveniently wrapped around a call which returns a Ref or error, when only *Image can be handled.

func (*Image) Blob

func (i *Image) Blob(descriptor *ocispecv1.Descriptor) (io.ReadCloser, error)

Blob returns the contents of a blob from its descriptor. It does not verify the contents against the digest.

func (*Image) Descriptors

func (i *Image) Descriptors() iter.Seq[*ocispecv1.Descriptor]

Descriptors returns an iterator over all descriptors in the image (config and layers).

func (*Image) Digest

func (i *Image) Digest() string

func (*Image) MediaType

func (i *Image) MediaType() string

func (*Image) RawManifest

func (i *Image) RawManifest() []byte

func (*Image) ReadBlobVerified

func (i *Image) ReadBlobVerified(descriptor *ocispecv1.Descriptor) ([]byte, error)

ReadBlobVerified reads a blob into a byte slice and verifies it against the digest.

func (*Image) StructfsBlob

func (i *Image) StructfsBlob(descriptor *ocispecv1.Descriptor) structfs.Blob

StructfsBlob wraps an image and descriptor into a structfs.Blob.

type Index

type Index struct {
	// Manifest contains the parsed index manifest.
	Manifest *ocispecv1.Index
	// contains filtered or unexported fields
}

Index represents an OCI image index.

func ReadLayoutIndex

func ReadLayoutIndex(path string) (*Index, error)

ReadLayoutIndex reads the index from an OS path to an OCI layout directory.

func (*Index) Digest

func (i *Index) Digest() string

func (*Index) MediaType

func (i *Index) MediaType() string

func (*Index) RawManifest

func (i *Index) RawManifest() []byte

func (*Index) Ref

func (i *Index) Ref(descriptor *ocispecv1.Descriptor) (Ref, error)

Ref reads a manifest from its descriptor and wraps it in a Ref. The manifest is verified against the digest.

type Ref

type Ref interface {
	// RawManifest returns the bytes of the manifest.
	// The returned value is shared and must not be modified.
	RawManifest() []byte
	// Digest returns the computed digest of RawManifest, in the default digest
	// algorithm. Only sha256 is supported currently.
	Digest() string
	// MediaType returns the media type of the manifest.
	MediaType() string
	// contains filtered or unexported methods
}

Ref is either an *Index or *Image.

func NewRef

func NewRef(rawManifest []byte, mediaType string, expectedDigest string, blobs Blobs) (Ref, error)

NewRef verifies the manifest against the expected digest if not empty, then parses it according to mediaType and returns a Ref.

func ReadLayout

func ReadLayout(path string) (Ref, error)

ReadLayout reads a manifest from an OS path to an OCI layout directory. It expects the index to point to exactly one manifest, which is common.