oci

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2026 License: MPL-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MediaTypePkgYAML is both the manifest artifactType and the media type of the
	// single layer carrying a package's raw pkg.yaml bytes.
	MediaTypePkgYAML = "application/vnd.nem.pkg.v1+yaml"

	// AnnotationTitle holds the package name on each index entry (required).
	AnnotationTitle = "org.opencontainers.image.title"
	// AnnotationDescription holds an optional one-line package description.
	AnnotationDescription = "org.opencontainers.image.description"
	// AnnotationSchemaVersion is the index-level catalog format signal.
	AnnotationSchemaVersion = "org.vi-dev.nem.catalog.schemaVersion"

	// CatalogSchemaVersion is the current catalog index format version.
	CatalogSchemaVersion = "1"
)

OCI catalog wire-format identifiers shared by the producer (Publisher) and the consumer (internal/catalog), so the on-registry format cannot drift between them.

Variables

View Source 
var ErrMissingCatalogBase error = MissingCatalogBaseError{}

ErrMissingCatalogBase is the zero-value sentinel for errors.Is.

View Source 
var ErrNotAManifest error = NotAManifestError{}
View Source 
var ErrNotAnImageIndex error = NotAnImageIndexError{}
View Source 
var ErrUnsupportedPlatform error = UnsupportedPlatformError{}

Functions

func IsDigestRef added in v0.4.0 

func IsDigestRef(reference string) bool

IsDigestRef reports whether reference is an OCI content digest (algorithm:hex) rather than a tag — i.e. a digest-pinned reference.

func IsRelative 

func IsRelative(ref string) bool

IsRelative reports whether ref lacks a registry/repository base — i.e. it is empty, or begins with ":" (tag) or "@" (digest).

func JoinRef 

func JoinRef(repository, reference string) string

JoinRef appends reference to a repository with the separator the reference implies: "@" for a digest, ":" for a tag.

func MirrorPopulated added in v0.6.0 

func MirrorPopulated(storeDir string) (bool, error)

MirrorPopulated reports whether the oras OCI-layout store at storeDir holds a mirrored catalog index — i.e. its index.json tags a manifest with the localCatalogTag reference. It reads the layout without creating it, so it is safe for read-only diagnostics (unlike NewMirror, which creates the store). A store that has never been synced (no index.json) returns (false, nil).

func OpenArchive 

func OpenArchive(ctx context.Context, c Client, ref string, platform Platform) (io.ReadCloser, int64, error)

OpenArchive pulls ref (which must be an OCI Image Index), selects the entry matching platform, fetches that per-platform manifest, and streams its single layer blob.

func OpenSource 

func OpenSource(ctx context.Context, c Client, ref string) (io.ReadCloser, int64, error)

OpenSource pulls ref (which must be a plain image manifest) and streams its single layer blob. Source is platform-independent, so there is no selection.

func ResolveRef 

func ResolveRef(rawRef, kind, name, base string) (string, error)

ResolveRef turns an authored oci.ref template into an absolute ref template (still containing any {{.Version}} placeholder). kind is "archives" or "sources"; base is the catalog base ("" when none is available). A relative ref with no base yields MissingCatalogBaseError.

func SplitRef 

func SplitRef(ref string) (name, reference string)

SplitRef splits an absolute reference "<name>[:<tag>][@<digest>]" into the repository name and the reference (digest if present, else tag). A registry port colon (e.g. "localhost:5000/foo") is not mistaken for a tag.

func ValidPackageName added in v0.4.0 

func ValidPackageName(name string) bool

ValidPackageName reports whether name is a valid catalog package name — the constraint the catalog index enforces on every entry title.

func ValidTag added in v0.4.0 

func ValidTag(tag string) bool

ValidTag reports whether tag is a valid OCI registry tag.

func WithDefaultTag 

func WithDefaultTag(ref string) string

WithDefaultTag appends ":{{.Version}}" when ref carries neither a tag nor a digest. An empty ref becomes the bare default tag.

Types

type Client 

type Client interface {
	// PullManifest fetches the manifest addressed by ref (its tag or digest).
	PullManifest(ctx context.Context, ref string) ([]byte, ocispec.Descriptor, error)
	// PullManifestByDigest fetches a manifest by digest from ref's repository.
	PullManifestByDigest(ctx context.Context, ref, digest string) ([]byte, error)
	// PullBlob fetches a blob described by target from ref's repository.
	PullBlob(ctx context.Context, ref string, target ocispec.Descriptor) (io.ReadCloser, int64, error)
}

Client is the minimal ORAS surface OpenArchive/OpenSource need. Every method is scoped to the repository named in ref.

func NewClient 

func NewClient(cred CredentialFunc, opts ...Option) Client

NewClient builds a Client that pulls from OCI registries using cred.

type CredentialFunc 

type CredentialFunc func(ctx context.Context, host string) (orasauth.Credential, error)

CredentialFunc returns registry credentials for a host, in oras-go's shape.

func Keychain 

func Keychain(resolver auth.Resolver) CredentialFunc

Keychain composes credentials: the Docker credential store first, then the nem resolver's per-registry fallback, then anonymous. The Docker store loads lazily and memoized; a load failure degrades to the nem/anonymous path.

type Mirror added in v0.4.0 

type Mirror struct {
	// contains filtered or unexported fields
}

Mirror caches an OCI catalog's metadata graph in a local oras OCI-layout store, mirroring the catalog image index at <base>. Archive/source blobs are not cached here.

func NewMirror added in v0.4.0 

func NewMirror(storeDir string, cred CredentialFunc) (*Mirror, error)

NewMirror opens (or creates) the OCI-layout store at storeDir and builds a Mirror that authenticates remote pulls with cred. AutoGC is disabled so GC runs only inside Sync.

func NewMirrorWithSource added in v0.4.0 

func NewMirrorWithSource(storeDir string, src oras.ReadOnlyTarget) (*Mirror, error)

NewMirrorWithSource builds a Mirror that copies from src instead of a remote registry, for tests in other packages.

func (*Mirror) LoadIndex added in v0.4.0 

func (m *Mirror) LoadIndex(ctx context.Context, desc ocispec.Descriptor) ([]byte, error)

LoadIndex fetches and digest+size-verifies the image-index blob at desc. desc must carry an accurate Size (use the descriptor from Resolve or Sync).

func (*Mirror) LoadLayer added in v0.4.0 

func (m *Mirror) LoadLayer(ctx context.Context, manDesc ocispec.Descriptor, wantMediaType string) ([]byte, error)

LoadLayer fetches the package manifest at manDesc, verifies it, then fetches and verifies its single layer, requiring that layer's media type to equal wantMediaType.

func (*Mirror) Resolve added in v0.4.0 

func (m *Mirror) Resolve(ctx context.Context) (ocispec.Descriptor, error)

Resolve returns the locally-mirrored catalog index descriptor. It returns errdef.ErrNotFound when the catalog has never been synced.

func (*Mirror) Sync added in v0.4.0 

func (m *Mirror) Sync(ctx context.Context, catalogRef string) (ocispec.Descriptor, error)

Sync mirrors the catalog graph at catalogRef into the local store, tags it "catalog", then reclaims the prior generation with GC. The caller must hold the process lock. Returns the mirrored index descriptor.

type MissingCatalogBaseError 

type MissingCatalogBaseError struct {
	Package string
}

MissingCatalogBaseError reports a relative oci.ref used where no catalog base is available to resolve it (e.g. a git or local-dir catalog).

func (MissingCatalogBaseError) Error 

func (e MissingCatalogBaseError) Error() string

func (MissingCatalogBaseError) Is 

func (e MissingCatalogBaseError) Is(target error) bool

type NotAManifestError 

type NotAManifestError struct{ Ref, Got string }

NotAManifestError reports that a source ref resolved to an image index rather than a plain image manifest.

func (NotAManifestError) Error 

func (e NotAManifestError) Error() string

func (NotAManifestError) Is 

func (e NotAManifestError) Is(target error) bool

type NotAnImageIndexError 

type NotAnImageIndexError struct{ Ref, Got string }

NotAnImageIndexError reports that an archive ref resolved to a media type other than an OCI image index.

func (NotAnImageIndexError) Error 

func (e NotAnImageIndexError) Error() string

func (NotAnImageIndexError) Is 

func (e NotAnImageIndexError) Is(target error) bool

type Option 

type Option func(*realClient)

Option configures a Client built by NewClient.

func WithPlainHTTP 

func WithPlainHTTP() Option

WithPlainHTTP makes the client use http:// (for local registries / tests).

type PackageBlob added in v0.4.0 

type PackageBlob struct {
	Name        string
	Description string
	PkgYAML     []byte
}

PackageBlob is one package to publish: its name/description (for the index entry annotations) and the raw pkg.yaml bytes (stored byte-exact as the layer).

type PackageDigest added in v0.4.0 

type PackageDigest struct {
	Name           string
	ManifestDigest string
	Size           int64
}

PackageDigest reports what was published for one package.

type Platform 

type Platform struct {
	OS   string
	Arch string
}

Platform is the runtime target used to select an archive from an Image Index.

type PublishResult added in v0.4.0 

type PublishResult struct {
	IndexDigest string
	Packages    []PackageDigest
}

PublishResult reports the published (or planned) catalog index and its packages.

type Publisher added in v0.4.0 

type Publisher struct {
	// contains filtered or unexported fields
}

Publisher writes catalog metadata (the image index and per-package pkg.yaml manifests) to an OCI registry. It is the write-path counterpart to Mirror.

func NewPublisher added in v0.4.0 

func NewPublisher(cred CredentialFunc) *Publisher

NewPublisher builds a Publisher authenticating remote pushes with cred. cred may be nil when only PublishToTarget against a local target is used (e.g. tests).

func (*Publisher) Plan added in v0.4.0 

func (p *Publisher) Plan(ctx context.Context, pkgs []PackageBlob) (PublishResult, error)

Plan packs the same content into an in-memory target and returns the digests Publish would produce, performing no registry writes.

func (*Publisher) Publish added in v0.4.0 

func (p *Publisher) Publish(ctx context.Context, catalogRepo string, pkgs []PackageBlob, tags []string) (PublishResult, error)

Publish packs and pushes every package into <catalogRepo>, assembles the catalog image index, and tags it with each tag. Returns the resulting digests.

func (*Publisher) PublishToTarget added in v0.4.0 

func (p *Publisher) PublishToTarget(ctx context.Context, target oras.Target, pkgs []PackageBlob, tags []string) (PublishResult, error)

PublishToTarget is the core: it packs each package into an image manifest, pushes the manifests and the assembled index into target, and tags the index with tags (none means push without tagging). Exported so other packages' tests can publish into a local store without a registry.

type UnsupportedPlatformError 

type UnsupportedPlatformError struct {
	Ref       string
	Want      Platform
	Available []Platform
}

UnsupportedPlatformError reports that an image index contained no entry matching the requested platform.

func (UnsupportedPlatformError) Error 

func (e UnsupportedPlatformError) Error() string

func (UnsupportedPlatformError) Is 

func (e UnsupportedPlatformError) Is(target error) bool

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.