oci

package
v0.18.0-beta.1 Latest Latest
Warning

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

 Go to latest Published: Feb 23, 2025 License: MIT Imports: 16 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"
)

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
}

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

type Annotations 

type Annotations map[string]string

func (Annotations) CreatedTime added in v0.13.0 

func (a Annotations) CreatedTime() time.Time

func (Annotations) DocumentationURL added in v0.13.0 

func (a Annotations) DocumentationURL() string

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.

func (Annotations) Source 

func (a Annotations) Source() string

func (Annotations) URL added in v0.13.0 

func (a Annotations) URL() string

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.Client
	AuthFunc func(*http.Request) error
}

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.

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 a [Manifest] or a [ManifestIndex] 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)

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     string
	Count    int
	AllPages bool
}

type ImageIndex added in v0.16.0 

type ImageIndex struct {
	ContentType   string
	SchemaVersion int
	MediaType     string
	Manifests     []ImageManifest
	Digest        string
	Annotations   Annotations
}

type ImageManifest added in v0.16.0 

type ImageManifest struct {
	ContentType   string
	SchemaVersion int
	MediaType     string
	Platform      *Platform
	Digest        string
	Annotations   Annotations
}

type Platform 

type Platform struct {
	OS           string
	Architecture string
	Variant      string
}

type Reference 

type Reference struct {
	Domain string
	Path   string

	HasTag bool
	Tag    string

	HasDigest bool
	Digest    string
}

func ParseReference 

func ParseReference(v string) (Reference, error)

func (Reference) Canonical 

func (r Reference) Canonical() Reference

func (Reference) MarshalJSON 

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

func (Reference) Name 

func (r Reference) Name() string

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

func (*Reference) UnmarshalJSON 

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

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.

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.