oci

package
v0.22.2 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2025 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package oci implemens utilities for interacting with Open Container Initiative image reference, annotations, distribution (registry) APIs and more. SEE: https://github.com/opencontainers/distribution-spec/blob/main/spec.md SEE: https://github.com/opencontainers/image-spec/blob/main/annotations.md SEE: https://github.com/opencontainers/image-spec/blob/main/spec.md SEE: https://github.com/distribution/reference SEE: https://github.com/opencontainers/artifacts

Index

Constants

View Source 
const (
	// APIErrorCodeBlobUnknown is returned when a blob is unknown to the
	// registry.
	APIErrorCodeBlobUnknown = "BLOB_UNKNOWN"
	// APIErrorCodeBlobUploadInvalid is returned when a blob upload is
	// invalid.
	APIErrorCodeBlobUploadInvalid = "BLOB_UPLOAD_INVALID"
	// APIErrorCodeBlobUploadUnknown is returned when a blob upload is
	// unknown to the registry.
	APIErrorCodeBlobUploadUnknown = "BLOB_UPLOAD_UNKNOWN"
	// APIErrorCodeDigestInvalid is returned when a provided digest did
	// not match uploaded content.
	APIErrorCodeDigestInvalid = "DIGEST_INVALID"
	// APIErrorCodeManifestBlobUnknwon is returned when a manifest
	// references a manifest or blob that is unknown to the registry.
	APIErrorCodeManifestBlobUnknwon = "MANIFEST_BLOB_UNKNOWN"
	// APIErrorCodeManifestInvalid is returned when a manifest is
	// invalid.
	APIErrorCodeManifestInvalid = "MANIFEST_INVALID"
	// APIErrorCodeManifestUnknown is returned when a manifest is unknown
	// to the registry.
	APIErrorCodeManifestUnknown = "MANIFEST_UNKNOWN"
	// APIErrorCodeNameInvalid is returned when an invalid repository
	// name is used.
	APIErrorCodeNameInvalid = "NAME_INVALID"
	// APIErrorCodeNameUnknown is returned when a repository name is not
	// known to registry.
	APIErrorCodeNameUnknown = "NAME_UNKNOWN"
	// APIErrorCodeSizeInvalid is returned when a provided length did not
	// match content length.
	APIErrorCodeSizeInvalid = "SIZE_INVALID"
	// APIErrorCodeUnauthorized is returned when authentication required.
	APIErrorCodeUnauthorized = "UNAUTHORIZED"
	// APIErrorCodeDenied is returned when the requested access to the
	// resource is denied.
	APIErrorCodeDenied = "DENIED"
	// APIErrorCodeUnsupported is returned when the operation is
	// unsupported.
	APIErrorCodeUnsupported = "UNSUPPORTED"
	// APIErrorCodeTooManyRequests is returned when the client has sent
	// too many requests.
	APIErrorCodeTooManyRequests = "TOOMANYREQUESTS"
)
View Source 
const SBOMTypeSPDX = "spdx"

Variables

This section is empty.

Functions

func ErrorIsResourceUnknown added in v0.16.0 

func ErrorIsResourceUnknown(err error) bool

ErrorIsResourceUnknown returns true if the error is an APIError which points at the error being that the resource (blob, manifest, name) us unknown to the registry.

func ManifestsMaybeEqual added in v0.16.0 

func ManifestsMaybeEqual(a any, b any, platform *Platform) bool

ManifestsMaybeEqual returns true if the manifests may be equal when resolved on the (optionally) specified platform.

func NameFromAPI added in v0.16.0 

func NameFromAPI(path string) string

NameFromAPI returns the OCI name based on the distribution spec API endpoint. Assumes name has at least two components. SEE: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#endpoints

Types

type APIError added in v0.16.0 

type APIError struct {
	Status     string
	StatusCode int
	Code       APIErrorCode
	Message    string
	Detail     string
}

APIError is a common error type returned by Client.

func (APIError) Error added in v0.16.0 

func (d APIError) Error() string

Error implements error.

type APIErrorCode added in v0.16.0 

type APIErrorCode string

APIErrorCode holds known / well-defined OCI API errors.

type Annotations 

type Annotations map[string]string

Annotations holds OCI annotations.

func (Annotations) Authors added in v0.20.0 

func (a Annotations) Authors() string

Authors contains contact details of the people or organization responsible for the image.

func (Annotations) BaseDigest added in v0.20.0 

func (a Annotations) BaseDigest() string

BaseDigest is the digest of the image this image is based on.

func (Annotations) BaseName added in v0.20.0 

func (a Annotations) BaseName() string

BaseName is the digest of the image this image is based on.

func (Annotations) Created added in v0.20.0 

func (a Annotations) Created() time.Time

Created is the date and time on which the image was built.

func (Annotations) Description added in v0.20.0 

func (a Annotations) Description() string

Description is a human-readable description of the software packaged in the image.

func (Annotations) DockerReferenceDigest added in v0.20.0 

func (a Annotations) DockerReferenceDigest() string

DockerReferenceDigest is the digest of the image for which the reference type annotation is valid. Used for attestation manifests.

func (Annotations) DockerReferenceType added in v0.20.0 

func (a Annotations) DockerReferenceType() string

DockerReferenceType describes the type of artifact. Used for attestation manifests.

func (Annotations) Documentation added in v0.20.0 

func (a Annotations) Documentation() string

Documentation is a URL to get documentation on the image.

func (Annotations) InTotoPredicateType added in v0.20.0 

func (a Annotations) InTotoPredicateType() string

InTotoPredicateType returns the predicate type of a layer. SEE: https://in-toto.io. SEE: https://github.com/in-toto/attestation/tree/v1.0/spec/predicates.

func (Annotations) Licenses added in v0.20.0 

func (a Annotations) Licenses() string

Licenses is the License(s) under which contained software is distributed, as an SPDX License Expression.

func (Annotations) Merge added in v0.16.0 

func (a Annotations) Merge(b Annotations) Annotations

Merge returns the merge of a and b. If both are nil, nil is returned. If the values exist in both sets, values in b takes precedence.

func (Annotations) RefName added in v0.20.0 

func (a Annotations) RefName() string

RefName is the name of the reference for a target (string).

func (Annotations) Revision added in v0.20.0 

func (a Annotations) Revision() string

Revision is the source control revision identifier for the packaged software.

func (Annotations) Source 

func (a Annotations) Source() string

Source is a URL to get source code for building the image.

func (Annotations) Title added in v0.20.0 

func (a Annotations) Title() string

Title is a human-readable title of the image.

func (Annotations) URL added in v0.13.0 

func (a Annotations) URL() string

URL is a URL to find more information on the image.

func (Annotations) Vendor added in v0.20.0 

func (a Annotations) Vendor() string

Vendor is the name of the distributing entity, organization or individual.

func (Annotations) Version added in v0.20.0 

func (a Annotations) Version() string

Version is the version of the packaged software.

type AttestationManifest added in v0.20.0 

type AttestationManifest struct {
	Layers []AttestationManifestLayer `json:"layers"`
}

AttestationManifest represent an attestation image manifest.

func (*AttestationManifest) ProvenanceDigest added in v0.20.0 

func (a *AttestationManifest) ProvenanceDigest() (string, string, bool)

ProvenanceDigest returns the in-toto predicate type and digest of the first layer containing provenance.

func (*AttestationManifest) SBOMDigest added in v0.20.0 

func (a *AttestationManifest) SBOMDigest() (string, string, bool)

SBOMDigest returns the in-toto predicate type and digest of the first layer containing a (well-known type of) SBOM.

type AttestationManifestLayer added in v0.20.0 

type AttestationManifestLayer struct {
	MediaType   string      `json:"mediaType"`
	Digest      string      `json:"digest"`
	Size        int         `json:"size"`
	Annotations Annotations `json:"annotations"`
}

AttestationManifestLayer represents a layer entry in an attestation image manifest.

type Blob added in v0.16.0 

type Blob interface {
	io.Reader
	io.Closer
	// Digest returns the blob's digest so far.
	// Valid once the entire blob has been read.
	// It is the caller's responsibility to ensure the entire blob has been read.
	Digest() string
	Info() BlobInfo
}

type BlobInfo added in v0.16.0 

type BlobInfo struct {
	// ContentType is the blob's content type.
	ContentType string
	// ContentLength is the size of the blob as reported by the server, if
	// reported at all. SHOULD be reported by all servers.
	ContentLength int64
	// Digest is the digest of the blob as reported by the server, if reported at
	// all. SHOULD be reported by all servers. If it is reported MUST match the
	// blob's actual digest.
	Digest string
}

type Client 

type Client struct {
	Client   httputil.Requester
	AuthFunc func(*http.Request) error
}

func (*Client) Do added in v0.19.0 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do implements httputil.Requester, handling authentication challenges sent by OCI registries.

func (*Client) DoCached added in v0.19.0 

func (c *Client) DoCached(req *http.Request) (*http.Response, error)

DoCached implements httputil.Requester, handling authentication challenges sent by OCI registries.

func (*Client) GetAnnotations 

func (c *Client) GetAnnotations(ctx context.Context, ref Reference, options *GetAnnotationsOptions) (Annotations, error)

GetAnnotations tries to identify annotations for the reference. Fetches manifests as necessary. To narrow down the search and to avoid unnecessary fetches, specify the available options. NOTE: The filter is only applied if more than one manifest exists.

func (*Client) GetAttestationManifest added in v0.20.0 

func (c *Client) GetAttestationManifest(ctx context.Context, ref Reference, digest string) (*AttestationManifest, error)

GetAttestationManifest downloads an AttestationManifest from an OCI registry. Helper method for Client.GetManifestBlob followed by parsing and validating an AttestationManifest.

func (*Client) GetBlob 

func (c *Client) GetBlob(ctx context.Context, ref Reference, digest string, cache bool) (Blob, error)

GetBlob downloads a blob from an OCI registry. SEE: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-blobs

func (*Client) GetManifest 

func (c *Client) GetManifest(ctx context.Context, ref Reference) (any, error)

GetManifest downloads an ImageManifest or an ImageIndex from an OCI registry. SEE: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pull

func (*Client) GetManifestBlob added in v0.16.0 

func (c *Client) GetManifestBlob(ctx context.Context, ref Reference) (Blob, error)

GetManifestBlob downloads a manifest from an OCI registry. SEE: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pull

func (*Client) GetTags 

func (c *Client) GetTags(ctx context.Context, image Reference, options *GetTagsOptions) ([]string, error)

GetTags retrieves available tags stored in a registry for a specific image.

func (*Client) HeadBlob added in v0.16.0 

func (c *Client) HeadBlob(ctx context.Context, ref Reference, digest string) (*BlobInfo, error)

HeadBlob gets information about a blob from an OCI registry. SEE: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-blobs

type GetAnnotationsOptions 

type GetAnnotationsOptions struct {
	Manifests    []ImageManifest
	Digest       string
	Architecture string
	OS           string
	Variant      string
}

type GetTagsOptions 

type GetTagsOptions struct {
	// Last is the name of the last tag of the previous page. Used for pagination.
	Last string
	// Count is the number of tags to return.
	// The server might not respect the choice.
	Count int
	// AllPages determines if the pagination is automatically handled to return
	// all available tags.
	AllPages bool
}

type ImageIndex added in v0.16.0 

type ImageIndex struct {
	// ContentType is the MIME type as returned by the server providing the
	// index.
	ContentType string
	// SchemaVersion specifies the image manifest schema version.
	SchemaVersion int
	// MediaType is the MIME type of the image index.
	MediaType string
	// Manifests contains the manifests provided by the index. Note that these may
	// or may not hold the same information as if each manifest was retrieved
	// individually.
	Manifests []ImageManifest
	// Digest is the digest of the index, including the "sha256:" prefix.
	Digest string
	// Annotations contains user-defined labels of the index.
	Annotations Annotations
}

ImageIndex represents an group of images manifests. This is an abstraction for all known image index formats (be it legacy Docker manifests or standard OCI manifests).

func (*ImageIndex) AttestationManifestDigest added in v0.20.0 

func (i *ImageIndex) AttestationManifestDigest() map[string]string

AttestationManifestDigests returns the digests for attestation manifests contained in the index, mapped by the manifest digest the attestation is for. SEE: https://docs.docker.com/build/metadata/attestations/attestation-storage/#attestation-manifest-descriptor.

func (*ImageIndex) HasAttestationManifest added in v0.20.0 

func (i *ImageIndex) HasAttestationManifest() bool

AttestationManifestDigest returns whether or not the index contains an attestation manifest. SEE: https://docs.docker.com/build/metadata/attestations/attestation-storage/#attestation-manifest-descriptor.

type ImageManifest added in v0.16.0 

type ImageManifest struct {
	// ContentType is the MIME type as returned by the server providing the
	// manifest.
	ContentType string
	// SchemaVersion specifies the image manifest schema version.
	SchemaVersion int
	// MediaType is the MIME type of the image manifest.
	MediaType string
	// Platform optionally holds details about the platform the image supports.
	Platform *Platform
	// Digest is the digest of the index, including the "sha256:" prefix.
	Digest string
	// Annotations contains user-defined labels of the manifest.
	Annotations Annotations
}

ImageManifest represents an image manifest. This is an abstraction for all known image manifest formats (be it legacy Docker manifests or standard OCI manifests).

type Platform 

type Platform struct {
	// OS is the operating system supported by the manifest.
	OS string
	// Architecture is the architecture supported by the manifest.
	Architecture string
	// Variant is the architecture variant supported by the manifest.
	// Typically a value such as "v8" for ARM images.
	Variant string
}

type ProvenanceAttestation added in v0.20.0 

type ProvenanceAttestation struct {
	BuildStartedOn  time.Time
	BuildFinishedOn time.Time
	// Source is the VCS source containing the code.
	Source string
	// SourceRevision is the revision (typically sha-1) of the version built.
	SourceRevision string
	// Dockerfile contains the full Dockerfile of the image, if possible.
	Dockerfile     string
	BuildArguments map[string]string
}

ProvenanceAttestation holds information gathered from an in-toto provenance attestation document containing moby buildkit metadata. SEE: https://github.com/in-toto/attestation. SEE: https://docs.docker.com/build/metadata/attestations/slsa-provenance/.

func (*ProvenanceAttestation) UnmarshalJSON added in v0.20.0 

func (a *ProvenanceAttestation) UnmarshalJSON(d []byte) error

type Reference 

type Reference struct {
	// Domain is the hostname of the registry.
	Domain string
	// Path is the namespace / project path of the reference.
	Path string

	// HasTag is true if the reference includes a tag.
	HasTag bool
	// Tag holds the tag specified in the reference.
	Tag string

	// HasDigest is true if the reference includes a digest.
	HasDigest bool
	// Digest holds the digest specified in the reference.
	Digest string
}

Reference represents an OCI reference, i.e. an container image string.

func ParseReference 

func ParseReference(v string) (Reference, error)

ParseReference parses a reference string. The returned reference is always canonical.

func (Reference) Canonical 

func (r Reference) Canonical() Reference

Canonical converts the reference to its canonical form (i.e. with all fields explicitly set to their implicit default value). Panics if the refernece is invalid. A reference returned by ParseReference is always canonical.

func (Reference) MarshalJSON 

func (r Reference) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Reference) Name 

func (r Reference) Name() string

Name returns the name of the reference in a way typically used by users.

func (Reference) Reference added in v0.16.0 

func (r Reference) Reference() string

Reference returns the reference as used by OCI distribution APIs.

func (Reference) String 

func (r Reference) String() string

String returns the most compact way of describing the reference.

func (*Reference) UnmarshalJSON 

func (r *Reference) UnmarshalJSON(b []byte) error

MarshalJSON implements json.Unmarshaler.

func (Reference) Version 

func (r Reference) Version() string

Version is the familiar version of the reference, such as its tag, digest or "latest", if no tag or digest is specified. Mostly useful for human-readable use cases. For use with APIs, see Reference.Reference.

type SBOMAttestation added in v0.20.0 

type SBOMAttestation struct {
	Type SBOMType
	SBOM string
}

SBOMAttestation holds information gathered from an in-toto SBOM attestation document. SEE: https://github.com/in-toto/attestation. SEE: https://docs.docker.com/build/metadata/attestations/sbom/.

func (*SBOMAttestation) UnmarshalJSON added in v0.20.0 

func (a *SBOMAttestation) UnmarshalJSON(d []byte) error

type SBOMType added in v0.20.0 

type SBOMType string

Source Files

View all Source files

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.