oci

package
v1.0.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 12, 2026 License: Apache-2.0, Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package oci provides OCI-compatible types for model distribution. It replaces go-containerregistry types with native OCI implementations.

Index

Constants

View Source 
const UploadingLayerID = "uploading"

UploadingLayerID is a sentinel layer ID used to identify push operations. During push, there is no real layer available yet, so this fake ID signals that the operation is an upload rather than a download.

Variables

This section is empty.

Functions

func Hasher 

func Hasher(name string) (hash.Hash, error)

Hasher returns a hash.Hash for the named algorithm (e.g. "sha256")

func RawManifest 

func RawManifest(i WithManifest) ([]byte, error)

RawManifest computes the raw manifest bytes from a manifest object.

func Size 

func Size(i interface {
	WithRawManifest
	WithRawConfigFile
	WithLayers
}) (int64, error)

Size computes the total size of an image (manifest + config + layers).

Types

type ConfigFile 

type ConfigFile struct {
	Architecture  string          `json:"architecture"`
	Author        string          `json:"author,omitempty"`
	Container     string          `json:"container,omitempty"`
	Created       Time            `json:"created,omitempty"`
	DockerVersion string          `json:"docker_version,omitempty"`
	History       []History       `json:"history,omitempty"`
	OS            string          `json:"os"`
	RootFS        RootFS          `json:"rootfs"`
	Config        ContainerConfig `json:"config"`
	OSVersion     string          `json:"os.version,omitempty"`
	Variant       string          `json:"variant,omitempty"`
	OSFeatures    []string        `json:"os.features,omitempty"`
}

ConfigFile is the configuration file that holds the metadata describing how to launch a container. See: https://github.com/opencontainers/image-spec/blob/master/config.md

func ParseConfigFile 

func ParseConfigFile(r io.Reader) (*ConfigFile, error)

ParseConfigFile parses the io.Reader's contents into a ConfigFile.

type ContainerConfig 

type ContainerConfig struct {
	AttachStderr    bool                `json:"AttachStderr,omitempty"`
	AttachStdin     bool                `json:"AttachStdin,omitempty"`
	AttachStdout    bool                `json:"AttachStdout,omitempty"`
	Cmd             []string            `json:"Cmd,omitempty"`
	Healthcheck     *HealthConfig       `json:"Healthcheck,omitempty"`
	Domainname      string              `json:"Domainname,omitempty"`
	Entrypoint      []string            `json:"Entrypoint,omitempty"`
	Env             []string            `json:"Env,omitempty"`
	Hostname        string              `json:"Hostname,omitempty"`
	Image           string              `json:"Image,omitempty"`
	Labels          map[string]string   `json:"Labels,omitempty"`
	OnBuild         []string            `json:"OnBuild,omitempty"`
	OpenStdin       bool                `json:"OpenStdin,omitempty"`
	StdinOnce       bool                `json:"StdinOnce,omitempty"`
	Tty             bool                `json:"Tty,omitempty"`
	User            string              `json:"User,omitempty"`
	Volumes         map[string]struct{} `json:"Volumes,omitempty"`
	WorkingDir      string              `json:"WorkingDir,omitempty"`
	ExposedPorts    map[string]struct{} `json:"ExposedPorts,omitempty"`
	ArgsEscaped     bool                `json:"ArgsEscaped,omitempty"`
	NetworkDisabled bool                `json:"NetworkDisabled,omitempty"`
	MacAddress      string              `json:"MacAddress,omitempty"`
	StopSignal      string              `json:"StopSignal,omitempty"`
	Shell           []string            `json:"Shell,omitempty"`
}

ContainerConfig is the execution parameters configuration.

type Descriptor 

type Descriptor struct {
	MediaType    MediaType         `json:"mediaType"`
	Size         int64             `json:"size"`
	Digest       Hash              `json:"digest"`
	Data         []byte            `json:"data,omitempty"`
	URLs         []string          `json:"urls,omitempty"`
	Annotations  map[string]string `json:"annotations,omitempty"`
	Platform     *Platform         `json:"platform,omitempty"`
	ArtifactType string            `json:"artifactType,omitempty"`
}

Descriptor describes a blob in a registry.

func LayerDescriptor 

func LayerDescriptor(l Layer) (*Descriptor, error)

LayerDescriptor computes a descriptor from a layer.

type Hash 

type Hash struct {
	// Algorithm holds the algorithm used to compute the hash.
	Algorithm string

	// Hex holds the hex portion of the content hash.
	Hex string
}

Hash is an unqualified digest of some content, e.g. sha256:deadbeef This type is compatible with go-containerregistry's v1.Hash.

func ConfigName 

func ConfigName(i WithRawConfigFile) (Hash, error)

ConfigName computes the config name (digest of config file) from raw config bytes.

func Digest 

func Digest(i WithRawManifest) (Hash, error)

Digest computes the digest of an image from its raw manifest.

func FromDigest 

func FromDigest(d digest.Digest) Hash

FromDigest creates a Hash from an opencontainers/go-digest Digest.

func NewHash 

func NewHash(s string) (Hash, error)

NewHash validates the input string is a hash and returns a strongly typed Hash object.

func SHA256 

func SHA256(r io.Reader) (Hash, int64, error)

SHA256 computes the Hash of the provided io.Reader's content.

func (Hash) MarshalJSON 

func (h Hash) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (Hash) MarshalText 

func (h Hash) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. This is required to use Hash as a key in a map when marshalling JSON.

func (Hash) String 

func (h Hash) String() string

String reverses NewHash returning the string-form of the hash.

func (Hash) ToDigest 

func (h Hash) ToDigest() digest.Digest

ToDigest converts a Hash to an opencontainers/go-digest Digest.

func (*Hash) UnmarshalJSON 

func (h *Hash) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler

func (*Hash) UnmarshalText 

func (h *Hash) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. This is required to use Hash as a key in a map when unmarshalling JSON.

type HealthConfig 

type HealthConfig struct {
	Test        []string      `json:",omitempty"`
	Interval    time.Duration `json:",omitempty"`
	Timeout     time.Duration `json:",omitempty"`
	StartPeriod time.Duration `json:",omitempty"`
	Retries     int           `json:",omitempty"`
}

HealthConfig holds configuration settings for the HEALTHCHECK feature.

type History 

type History struct {
	Author     string `json:"author,omitempty"`
	Created    Time   `json:"created,omitempty"`
	CreatedBy  string `json:"created_by,omitempty"`
	Comment    string `json:"comment,omitempty"`
	EmptyLayer bool   `json:"empty_layer,omitempty"`
}

History is one entry of a list recording how this container image was built.

type Image 

type Image interface {
	// Layers returns the ordered collection of filesystem layers that comprise this image.
	// The order of the list is oldest/base layer first, and most-recent/top layer last.
	Layers() ([]Layer, error)

	// MediaType of this image's manifest.
	MediaType() (MediaType, error)

	// Size returns the size of the manifest.
	Size() (int64, error)

	// ConfigName returns the hash of the image's config file, also known as
	// the Image ID.
	ConfigName() (Hash, error)

	// ConfigFile returns this image's config file.
	ConfigFile() (*ConfigFile, error)

	// RawConfigFile returns the serialized bytes of ConfigFile().
	RawConfigFile() ([]byte, error)

	// Digest returns the sha256 of this image's manifest.
	Digest() (Hash, error)

	// Manifest returns this image's Manifest object.
	Manifest() (*Manifest, error)

	// RawManifest returns the serialized bytes of Manifest()
	RawManifest() ([]byte, error)

	// LayerByDigest returns a Layer for interacting with a particular layer of
	// the image, looking it up by "digest" (the compressed hash).
	LayerByDigest(Hash) (Layer, error)

	// LayerByDiffID is an analog to LayerByDigest, looking up by "diff id"
	// (the uncompressed hash).
	LayerByDiffID(Hash) (Layer, error)
}

Image defines the interface for interacting with an OCI image.

type IndexManifest 

type IndexManifest struct {
	SchemaVersion int64             `json:"schemaVersion"`
	MediaType     MediaType         `json:"mediaType,omitempty"`
	Manifests     []Descriptor      `json:"manifests"`
	Annotations   map[string]string `json:"annotations,omitempty"`
	Subject       *Descriptor       `json:"subject,omitempty"`
}

IndexManifest represents an OCI image index (multi-platform manifest list).

func ParseIndexManifest 

func ParseIndexManifest(r io.Reader) (*IndexManifest, error)

ParseIndexManifest parses the io.Reader's contents into an IndexManifest.

type Layer 

type Layer interface {
	// Digest returns the Hash of the compressed layer.
	Digest() (Hash, error)

	// DiffID returns the Hash of the uncompressed layer.
	DiffID() (Hash, error)

	// Compressed returns an io.ReadCloser for the compressed layer contents.
	Compressed() (io.ReadCloser, error)

	// Uncompressed returns an io.ReadCloser for the uncompressed layer contents.
	Uncompressed() (io.ReadCloser, error)

	// Size returns the compressed size of the Layer.
	Size() (int64, error)

	// MediaType returns the media type of the Layer.
	MediaType() (MediaType, error)
}

Layer is an interface for accessing the properties of a particular layer of an Image.

func ConfigLayer 

func ConfigLayer(i WithRawConfigFile) (Layer, error)

ConfigLayer returns a layer representing the config blob.

type Manifest 

type Manifest struct {
	SchemaVersion int64             `json:"schemaVersion"`
	MediaType     MediaType         `json:"mediaType,omitempty"`
	Config        Descriptor        `json:"config"`
	Layers        []Descriptor      `json:"layers"`
	Annotations   map[string]string `json:"annotations,omitempty"`
	Subject       *Descriptor       `json:"subject,omitempty"`
}

Manifest represents an OCI image manifest.

func ParseManifest 

func ParseManifest(r io.Reader) (*Manifest, error)

ParseManifest parses the io.Reader's contents into a Manifest.

func (*Manifest) ComputeDigest 

func (m *Manifest) ComputeDigest() (Hash, error)

ComputeDigest computes the digest of the manifest.

func (*Manifest) RawManifest 

func (m *Manifest) RawManifest() ([]byte, error)

RawManifest returns the serialized bytes of the Manifest.

type MediaType 

type MediaType string

MediaType is an enumeration of the supported mime types that an element of an image might have. 

const (
	// OCI manifest types
	OCIManifestSchema1   MediaType = "application/vnd.oci.image.manifest.v1+json"
	OCIImageIndex        MediaType = "application/vnd.oci.image.index.v1+json"
	OCIConfigJSON        MediaType = "application/vnd.oci.image.config.v1+json"
	OCILayer             MediaType = "application/vnd.oci.image.layer.v1.tar"
	OCILayerGzip         MediaType = "application/vnd.oci.image.layer.v1.tar+gzip"
	OCILayerZstd         MediaType = "application/vnd.oci.image.layer.v1.tar+zstd"
	OCIUncompressedLayer MediaType = "application/vnd.oci.image.layer.v1.tar"
	OCIContentDescriptor MediaType = "application/vnd.oci.descriptor.v1+json"
	OCIArtifactManifest  MediaType = "application/vnd.oci.artifact.manifest.v1+json"
	OCIEmptyJSON         MediaType = "application/vnd.oci.empty.v1+json"

	// Docker manifest types
	DockerManifestSchema2   MediaType = "application/vnd.docker.distribution.manifest.v2+json"
	DockerManifestList      MediaType = "application/vnd.docker.distribution.manifest.list.v2+json"
	DockerConfigJSON        MediaType = "application/vnd.docker.container.image.v1+json"
	DockerLayer             MediaType = "application/vnd.docker.image.rootfs.diff.tar.gzip"
	DockerForeignLayer      MediaType = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip"
	DockerUncompressedLayer MediaType = "application/vnd.docker.image.rootfs.diff.tar"
)

Common media types used in OCI and Docker image specifications.

func (MediaType) IsDistributable 

func (m MediaType) IsDistributable() bool

IsDistributable returns true if a layer is distributable (not foreign).

func (MediaType) IsImage 

func (m MediaType) IsImage() bool

IsImage returns true if the media type is a manifest type.

func (MediaType) IsIndex 

func (m MediaType) IsIndex() bool

IsIndex returns true if the media type is an index type.

type Platform 

type Platform struct {
	Architecture string   `json:"architecture"`
	OS           string   `json:"os"`
	OSVersion    string   `json:"os.version,omitempty"`
	OSFeatures   []string `json:"os.features,omitempty"`
	Variant      string   `json:"variant,omitempty"`
}

Platform represents the target platform of an image.

type RootFS 

type RootFS struct {
	Type    string `json:"type"`
	DiffIDs []Hash `json:"diff_ids"`
}

RootFS holds the ordered list of file system deltas that comprise the container image's root filesystem.

type Time 

type Time struct {
	time.Time
}

Time is a wrapper around time.Time to help with deep copying

func (*Time) DeepCopyInto 

func (t *Time) DeepCopyInto(out *Time)

DeepCopyInto creates a deep-copy of the Time value.

type Update 

type Update struct {
	Complete int64
	Total    int64
	Error    error
}

Update represents a progress update during image operations.

type WithConfigFile 

type WithConfigFile interface {
	ConfigFile() (*ConfigFile, error)
}

WithConfigFile represents types that can provide a config file.

type WithLayers 

type WithLayers interface {
	Layers() ([]Layer, error)
}

WithLayers represents types that can provide layers.

type WithManifest 

type WithManifest interface {
	Manifest() (*Manifest, error)
}

WithManifest represents types that can provide a manifest.

type WithRawConfigFile 

type WithRawConfigFile interface {
	RawConfigFile() ([]byte, error)
}

WithRawConfigFile represents types that can provide raw config file bytes.

type WithRawManifest 

type WithRawManifest interface {
	RawManifest() ([]byte, error)
}

WithRawManifest represents types that can provide raw manifest bytes.

Source Files

View all Source files

Directories

Path Synopsis
Package authn provides authentication support for registry operations.
 Package authn provides authentication support for registry operations.
Package reference provides image reference parsing using the distribution/reference library.
 Package reference provides image reference parsing using the distribution/reference library.
Package remote provides registry operations using containerd's remotes.
 Package remote provides registry operations using containerd's remotes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.