ocispec

Documentation

Overview

Package ocispec provides a Go representation of the OCI Image Specification.

Index

• Constants
• func CompressionFormatFromMediaType(mediaType string) (compression.Format, error)
• func DetectMediaType(content []byte) string
• func Digest(content []byte) (digest.Digest, error)
• func IsCompressedBlob(mt string) bool
• func IsDockerSchema1Manifest(mt string) bool
• func MatchesDigest(content []byte, expectedDigest digest.Digest) (bool, error)
• func NewDescriptorFromBytes(mediaType string, content []byte) imgspecv1.Descriptor
• type BlobLayer
• type Compressor
• type Describable
• type FSGetter
• type FSGetterFunc
  • func (fn FSGetterFunc) GetFS(ctx context.Context) (fs.FS, error)
• type FSLayer
• type Image
• type ImageCloser
• type ImageMetadata
  • func (m *ImageMetadata) Size() int64
• type IndexManifest
• type Layer
• type LayerMetadata
  • func (m *LayerMetadata) Size() int64
• type Manifest
• type Uncompressor

Constants

const (
	// MediaTypeDescriptor specifies the media type for a content descriptor.
	MediaTypeDescriptor = "application/vnd.oci.descriptor.v1+json"

	// MediaTypeLayoutHeader specifies the media type for the oci-layout.
	MediaTypeLayoutHeader = "application/vnd.oci.layout.header.v1+json"

	// MediaTypeImageIndex specifies the media type for an image index.
	MediaTypeImageIndex = "application/vnd.oci.image.index.v1+json"

	// MediaTypeImageManifest specifies the media type for an image manifest.
	MediaTypeImageManifest = "application/vnd.oci.image.manifest.v1+json"

	// MediaTypeImageConfig specifies the media type for the image configuration.
	MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json"

	// MediaTypeEmptyJSON specifies the media type for an unused blob containing the value "{}".
	MediaTypeEmptyJSON = "application/vnd.oci.empty.v1+json"
)

const (
	// MediaTypeImageLayer is the media type used for layers referenced by the manifest.
	MediaTypeImageLayer = "application/vnd.oci.image.layer.v1.tar"

	// MediaTypeImageLayerGzip is the media type used for gzipped layers
	// referenced by the manifest.
	MediaTypeImageLayerGzip = "application/vnd.oci.image.layer.v1.tar+gzip"

	// MediaTypeImageLayerZstd is the media type used for zstd compressed
	// layers referenced by the manifest.
	MediaTypeImageLayerZstd = "application/vnd.oci.image.layer.v1.tar+zstd"
)

const (
	// MediaTypeImageLayerNonDistributable is the media type for layers referenced by
	// the manifest but with distribution restrictions.
	MediaTypeImageLayerNonDistributable = "application/vnd.oci.image.layer.nondistributable.v1.tar"

	// MediaTypeImageLayerNonDistributableGzip is the media type for
	// gzipped layers referenced by the manifest but with distribution
	// restrictions.
	MediaTypeImageLayerNonDistributableGzip = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip"

	// MediaTypeImageLayerNonDistributableZstd is the media type for zstd
	// compressed layers referenced by the manifest but with distribution
	// restrictions.
	MediaTypeImageLayerNonDistributableZstd = "application/vnd.oci.image.layer.nondistributable.v1.tar+zstd"
)

Non-distributable layer media-types.

Deprecated: Non-distributable layers are deprecated, and not recommended for future use. Implementations SHOULD NOT produce new non-distributable layers. https://github.com/opencontainers/image-spec/pull/965

const (
	// MediaTypeDockerV2S2ManifestList specifies the mediaType for manifest lists.
	MediaTypeDockerV2S2ManifestList = "application/vnd.docker.distribution.manifest.list.v2+json"

	// MediaTypeDockerV2S2Manifest specifies the mediaType for the current version.
	MediaTypeDockerV2S2Manifest = "application/vnd.docker.distribution.manifest.v2+json"

	// MediaTypeDockerV2S2ImageConfig specifies the mediaType for the image configuration.
	MediaTypeDockerV2S2ImageConfig = "application/vnd.docker.container.image.v1+json"

	// MediaTypeDockerV2S2ImageLayer is the mediaType used for layers which
	// are not compressed.
	MediaTypeDockerV2S2ImageLayer = "application/vnd.docker.image.rootfs.diff.tar"

	// MediaTypeDockerV2S2ImageLayerGzip is the mediaType used for layers referenced by the
	// manifest.
	MediaTypeDockerV2S2ImageLayerGzip = "application/vnd.docker.image.rootfs.diff.tar.gzip"

	// MediaTypeDockerV2S2ForeignImageLayer is used for schema 2 foreign layers, indicating
	// layers that must be downloaded from foreign URLs.
	MediaTypeDockerV2S2ForeignImageLayer = "application/vnd.docker.image.rootfs.foreign.diff.tar"

	// MediaTypeDockerV2S2ForeignImageLayerGzip is used for gzipped schema 2 foreign layers,
	// indicating layers that must be downloaded from foreign URLs.
	MediaTypeDockerV2S2ForeignImageLayerGzip = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip"

	// MediaTypeDockerPluginConfig specifies the mediaType for plugin configuration.
	MediaTypeDockerPluginConfig = "application/vnd.docker.plugin.v1+json"
)

V2 Schema2 See https://docker-docs.uclv.cu/registry/spec/manifest-v2-2/

const (
	// MediaTypeDockerV2S1Manifest specifies the mediaType for the current version. Note
	// that for schema version 1, the the media is optionally "application/json".
	MediaTypeDockerV2S1Manifest = "application/vnd.docker.distribution.manifest.v1+json"

	// MediaTypeDockerV2S1SignedManifest specifies the mediatype for current SignedManifest version.
	MediaTypeDockerV2S1SignedManifest = "application/vnd.docker.distribution.manifest.v1+prettyjws"

	// MediaTypeDockerV2S1ManifestLayer specifies the media type for manifest layers.
	MediaTypeDockerV2S1ManifestLayer = "application/vnd.docker.container.image.rootfs.diff+x-gtar"
)

V2 Schema1 See https://docker-docs.uclv.cu/registry/spec/manifest-v2-1/

NOTE: Docker Image Manifest v2, Schema 1 is deprecated since 2015. Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.

const (
	// DefaultMediaType is the media type used when no media type is specified.
	DefaultMediaType string = "application/octet-stream"
)

Functions

func CompressionFormatFromMediaType

func CompressionFormatFromMediaType(mediaType string) (compression.Format, error)

CompressionFormatFromMediaType returns the compression format from the media type.

func DetectMediaType

func DetectMediaType(content []byte) string

DetectMediaType infers the manifest type from the given []byte and returns the corresponding media type. If the type is unknown or unrecognized, it returns an empty string.

NOTE: Typically, we should directly obtain the media type externally rather than inferring it through parsing. However, there might be situations where it's not possible to obtain the manifest's media type externally, such as when the manifest is a local file.

func Digest

func Digest(content []byte) (digest.Digest, error)

Digest returns the a digest of a docker manifest, with any necessary implied transformations like stripping v1s1 signatures.

func IsCompressedBlob

func IsCompressedBlob(mt string) bool

IsCompressedLayer returns true if the mediaType is a compressed blob type.

func IsDockerSchema1Manifest

func IsDockerSchema1Manifest(mt string) bool

IsDockerSchema1Manifest returns true if the mediaType is docker schema1 manifest.

func MatchesDigest

func MatchesDigest(content []byte, expectedDigest digest.Digest) (bool, error)

MatchesDigest returns true if the manifest matches expectedDigest. Error may be set if this returns false.

func NewDescriptorFromBytes

func NewDescriptorFromBytes(mediaType string, content []byte) imgspecv1.Descriptor

NewDescriptorFromBytes returns a descriptor, given the content and media type. If no media type is specified, "application/octet-stream" will be used.

Types

type BlobLayer

type BlobLayer interface {
	Layer
	Describable
	Compressor
	Uncompressor
}

BlobLayer represents a Blob type Layer object obtained through the Image Manifest. It corresponds to the layer from a remote image or the layer from containerd.

type Compressor

type Compressor interface {
	// Compressed returns a reader that compressed what is read.
	// The reader must be closed when reading is finished.
	Compressed(ctx context.Context) (io.ReadCloser, error)
}

Compressor can compress data.

type Describable

type Describable interface {
	// Descriptor returns the descriptor for the resource.
	Descriptor() imgspecv1.Descriptor
}

Describable defines a resource that can be described.

type FSGetter

type FSGetter interface {
	// GetFS returns a filesystem.
	GetFS(ctx context.Context) (fs.FS, error)
}

FSGetter can return a filesystem.

type FSGetterFunc

type FSGetterFunc func(ctx context.Context) (fs.FS, error)

FSGetterFunc is a function that implements FSGetter.

func (FSGetterFunc) GetFS

func (fn FSGetterFunc) GetFS(ctx context.Context) (fs.FS, error)

GetFS implements FSGetter.

type FSLayer

type FSLayer interface {
	Layer
	FSGetter
}

FSLayer represents a file-system based Layer object.

type Image

type Image interface {
	// Metadata returns the metadata of the image.
	Metadata() ImageMetadata

	// ConfigFile returns the image config file bytes.
	ConfigFile(ctx context.Context) ([]byte, error)

	// Layers returns a list of layer objects contained in the current image in order.
	// The list order is from the oldest/base layer to the most-recent/top layer.
	Layers(ctx context.Context) ([]Layer, error)
}

Image defines the interface for an image.

Images may originate from different storage backends and can be converted between them:

• remote: Retrieved using the OCI Distribution-defined interface by calling the image repository's RESTful API
• docker-archive: Retrieved by parsing the tarball file generated by docker save
• docker-daemon: Retrieved through TCP communication with the Docker daemon
• docker-rootdir: Retrieved by directly accessing the filesystem where Docker stores images (/var/lib/docker)
• oci-layout: Retrieved by accessing the filesystem of the OCI Image Layout directory
• oci-archive: Retrieved by parsing the archive file corresponding to the OCI Image Layout
• others: Refer to https://github.com/containers/image

type ImageCloser

type ImageCloser interface {
	Image
	io.Closer
}

ImageCloser declares an image object that requires resource release after use. The caller must invoke Close() to release resources after use.

NOTE: Releasing resources here may refer to closing network connections, cleaning up temporary files, or closing file handles, etc.

type ImageMetadata

type ImageMetadata struct {
	// ID is the unique identifier of the image, which is the hash of the config file.
	ID digest.Digest `json:"id,omitempty" yaml:"id,omitempty"`

	// Name indicates the original reference name used to retrieve the current image,
	// which can be in the form of Repo:Tag, Repo@Digest, Image ID, or Partial Image ID.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// RepoTags lists all the aliases associated with the image in the Repo:Tag format.
	RepoTags []string `json:"repo_tags,omitempty" yaml:"repo_tags,omitempty"`

	// RepoDigests lists all the aliases associated with the image in the Repo@Digest format.
	RepoDigests []string `json:"repo_digests,omitempty" yaml:"repo_digests,omitempty"`

	// Digest is the hash of the image manifest corresponding to the current image
	// object when the manifest is of the index/manifest list type.
	Digest digest.Digest `json:"digest,omitempty" yaml:"digest,omitempty"`

	// IndexDigest is the sha256 hash of the original manifest, which could be an index/manifest
	// list type or an image manifest type.
	IndexDigest digest.Digest `json:"index_digest,omitempty" yaml:"index_digest,omitempty"`

	// Platform specifies the system platform information corresponding to the image.
	Platform *imgspecv1.Platform `json:"platform,omitempty" yaml:"platform,omitempty"`

	// CompressedSize represents the total compressed size of all the layers included in the image.
	CompressedSize int64 `json:"compressed_size,omitempty" yaml:"compressed_size,omitempty"`

	// UncompressedSize represents the total uncompressed size of all the layers included in the image.
	UncompressedSize int64 `json:"uncompressed_size,omitempty" yaml:"uncompressed_size,omitempty"`

	// IsCompressed indicates whether the current size is compressed.
	IsCompressed bool `json:"is_compressed,omitempty" yaml:"is_compressed,omitempty"`
}

ImageMetadata represents the metadata of an image.

func (*ImageMetadata) Size

func (m *ImageMetadata) Size() int64

Size returns the size of the image, taking into account whether it is compressed.

type IndexManifest

type IndexManifest interface {
	Manifest

	// Manifests returns a list of all child manifest descriptors.
	Manifests() []imgspecv1.Descriptor
}

IndexManifest extends Manifest when the raw manifest is an indexed type manifest that contains multiple child manifests.

type Layer

type Layer interface {
	// Metadata returns the metadata of the layer.
	Metadata() LayerMetadata
}

Layer is the minimal interface for an image layer.

type LayerMetadata

type LayerMetadata struct {
	// DiffID is the hash of the tar file after the layer is decompressed, corresponding
	// to rootfs.DiffID in the image config.
	DiffID digest.Digest `json:"diff_id,omitempty" yaml:"diff_id,omitempty"`

	// ChainID returns the hash of the entire stack of DiffIDs from the bottom to the
	// current layer.
	//
	// NOTE:
	//   - ChainID(A) = DiffID(A)
	//   - ChainID(A|B) = sha256sum(ChainID(A) + " " + DiffID(B))
	//   - ChainID(A|B|C) = sha256sum(ChainID(A|B) + " " + DiffID(C))
	ChainID digest.Digest `json:"chain_id,omitempty" yaml:"chain_id,omitempty"`

	// IsCompressed indicates whether the current size is compressed.
	IsCompressed bool `json:"is_compressed,omitempty" yaml:"is_compressed,omitempty"`

	// CompressedSize represents the compressed size of the current layer.
	CompressedSize int64 `json:"compressed_size,omitempty" yaml:"compressed_size,omitempty"`

	// UncompressedSize represents the uncompressed size of the current layer.
	UncompressedSize int64 `json:"uncompressed_size,omitempty" yaml:"uncompressed_size,omitempty"`

	// Parent indicates the parent layer of the current layer. If the current layer has no
	// parent, it returns nil.
	Parent Layer `json:"-" yaml:"-"`

	// History indicates the build history information. It the history is not found, it returns nil.
	History *imgspecv1.History
}

LayerMetadata defines the metadata of a layer.

func (*LayerMetadata) Size

func (m *LayerMetadata) Size() int64

Size returns the size of the layer, taking into account whether it is compressed.

type Manifest

type Manifest interface {
	// MediaType returns the media type of current manifest object.
	MediaType() string

	// References returns a list of objects which make up this manifest.
	// A reference is anything which can be represented by a imgspecv1.Descriptor.
	// These can consist of layers, resources or other manifests.
	//
	// While no particular order is required, implementations should return
	// them from highest to lowest priority. For example, one might want to
	// return the base layer before the top layer.
	References() []imgspecv1.Descriptor

	// Payload provides the serialized format of the manifest.
	Payload() ([]byte, error)
}

Manifest represents a registry object specifying a set of references and an optional target.

type Uncompressor

type Uncompressor interface {
	// Uncompressed returns a reader that uncompresses what is read.
	// The reader must be closed when reading is finished.
	Uncompressed(ctx context.Context) (io.ReadCloser, error)
}

Uncompressor can uncompress data.