registry

package
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2026 License: Apache-2.0, MIT Imports: 20 Imported by: 0

Documentation

Overview

Package registry provides a high-level client for pushing and pulling blob archives to/from OCI registries.

The client uses the oras subpackage for low-level OCI operations and adds blob-archive-specific functionality like manifest caching and lazy blob access via HTTP range requests.

Index

Constants

View Source 
const (
	// ArtifactType identifies blob archives as an OCI 1.1 artifact type.
	ArtifactType = "application/vnd.meigma.blob.v1"

	// MediaTypeIndex is the media type for the FlatBuffers index blob.
	MediaTypeIndex = "application/vnd.meigma.blob.index.v1+flatbuffers"

	// MediaTypeData is the media type for the concatenated data blob.
	MediaTypeData = "application/vnd.meigma.blob.data.v1"
)

Media types for blob archives in OCI registries.

Variables

View Source 
var (
	// ErrNotFound is returned when a blob archive does not exist at the reference.
	ErrNotFound = errors.New("client: not found")

	// ErrInvalidReference is returned when a reference string is malformed.
	ErrInvalidReference = errors.New("client: invalid reference")

	// ErrInvalidManifest is returned when a manifest is not a valid blob archive manifest.
	ErrInvalidManifest = errors.New("client: invalid blob manifest")

	// ErrMissingIndex is returned when the manifest does not contain an index blob.
	ErrMissingIndex = errors.New("client: missing index blob")

	// ErrMissingData is returned when the manifest does not contain a data blob.
	ErrMissingData = errors.New("client: missing data blob")

	// ErrDigestMismatch is returned when content does not match its expected digest.
	ErrDigestMismatch = errors.New("client: digest mismatch")

	// ErrPolicyViolation is returned when a policy rejects a manifest.
	ErrPolicyViolation = errors.New("client: policy violation")

	// ErrReferrersUnsupported is returned when referrers are not supported by the OCI client.
	ErrReferrersUnsupported = errors.New("client: referrers unsupported")
)

Sentinel errors for client operations.

Functions

This section is empty.

Types

type BlobManifest 

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

BlobManifest wraps an OCI manifest for a blob archive.

It provides convenient access to the index and data blob descriptors, annotations, and other metadata.

func NewTestManifest 

func NewTestManifest(digestStr string, created time.Time, indexSize, dataSize int64) *BlobManifest

NewTestManifest creates a BlobManifest for testing purposes. This is not intended for production use.

func (*BlobManifest) Annotations 

func (m *BlobManifest) Annotations() map[string]string

Annotations returns the manifest annotations.

func (*BlobManifest) Created 

func (m *BlobManifest) Created() time.Time

Created returns the creation timestamp from annotations.

Returns zero time if the annotation is not present or cannot be parsed.

func (*BlobManifest) DataDescriptor 

func (m *BlobManifest) DataDescriptor() ocispec.Descriptor

DataDescriptor returns the descriptor for the data blob.

func (*BlobManifest) Digest 

func (m *BlobManifest) Digest() string

Digest returns the manifest digest.

func (*BlobManifest) IndexDescriptor 

func (m *BlobManifest) IndexDescriptor() ocispec.Descriptor

IndexDescriptor returns the descriptor for the index blob.

func (*BlobManifest) Raw 

func (m *BlobManifest) Raw() ocispec.Manifest

Raw returns the underlying OCI manifest.

type Client 

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

Client provides high-level operations for blob archives in OCI registries.

func New 

func New(opts ...Option) *Client

New creates a new blob archive client with the given options.

If no OCIClient is provided via WithOCIClient, a default ORAS-based client is created using any pass-through options (WithPlainHTTP, etc.).

func (*Client) Fetch 

func (c *Client) Fetch(ctx context.Context, ref string, opts ...FetchOption) (*BlobManifest, error)

Fetch retrieves the manifest for a blob archive without downloading data.

This is useful for inspecting archive metadata or checking if an archive exists without the overhead of downloading blob content.

func (*Client) FetchDescriptor 

func (c *Client) FetchDescriptor(ctx context.Context, ref string, desc ocispec.Descriptor) ([]byte, error)

FetchDescriptor fetches raw content for the given descriptor.

func (*Client) Inspect 

func (c *Client) Inspect(ctx context.Context, ref string, opts ...InspectOption) (*InspectResult, error)

Inspect retrieves archive metadata without downloading file data.

This fetches the manifest and index blob, providing access to:

  • Manifest metadata (digest, created time, annotations)
  • File index (paths, sizes, hashes, modes)

The data blob is NOT downloaded. Use Client.Pull to extract files.

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, ref string, opts ...PullOption) (*blob.Blob, error)

Pull retrieves a blob archive from an OCI registry.

The returned Blob is lazy: file data is fetched on demand via HTTP range requests. The index blob is downloaded immediately as it is small.

The caller should close the Blob when done if it wraps file resources.

func (*Client) Push 

func (c *Client) Push(ctx context.Context, ref string, b *blob.Blob, opts ...PushOption) error

Push pushes a blob archive to an OCI registry.

The archive is pushed as two blobs (index and data) with a manifest linking them. The ref must include a tag (e.g., "registry.com/repo:v1.0.0").

Use WithTags to apply additional tags to the same manifest.

func (*Client) Referrers 

func (c *Client) Referrers(ctx context.Context, ref string, subject ocispec.Descriptor, artifactType string) ([]ocispec.Descriptor, error)

Referrers lists referrer descriptors for the given subject manifest.

func (*Client) Sign 

func (c *Client) Sign(ctx context.Context, ref string, signer ManifestSigner, opts ...SignOption) (string, error)

Sign creates a signature for a manifest and attaches it as a referrer.

The ref must include a tag or digest. The signer creates the signature bundle, which is pushed as an OCI 1.1 referrer artifact linked to the manifest.

Returns the digest of the signature manifest.

func (*Client) Tag 

func (c *Client) Tag(ctx context.Context, ref, digest string) error

Tag creates or updates a tag pointing to an existing manifest.

The ref specifies the repository and new tag (e.g., "registry.com/repo:latest"). The digest must be the full digest of an existing manifest (e.g., "sha256:abc...").

type FetchOption 

type FetchOption func(*fetchConfig)

FetchOption configures a Fetch operation.

func WithSkipCache 

func WithSkipCache() FetchOption

WithSkipCache bypasses the manifest cache for this fetch.

The fetched manifest is still added to the cache after retrieval.

type InspectOption 

type InspectOption func(*inspectConfig)

InspectOption configures an Inspect operation.

func WithInspectMaxIndexSize 

func WithInspectMaxIndexSize(maxBytes int64) InspectOption

WithInspectMaxIndexSize sets the maximum number of bytes allowed for the index blob.

Use a value <= 0 to disable the limit.

func WithInspectSkipCache 

func WithInspectSkipCache() InspectOption

WithInspectSkipCache bypasses the ref, manifest, and index caches.

This forces a fresh fetch from the registry even if cached data exists.

type InspectResult 

type InspectResult struct {
	// Manifest contains the parsed OCI manifest for the blob archive.
	Manifest *BlobManifest

	// IndexData contains the raw FlatBuffers-encoded index blob.
	IndexData []byte
}

InspectResult contains manifest and index metadata without the data blob.

type ManifestSigner 

type ManifestSigner interface {
	SignManifest(ctx context.Context, payload []byte) (data []byte, mediaType string, err error)
}

ManifestSigner signs OCI manifest payloads.

type OCIClient 

type OCIClient interface {
	// PushBlob pushes a blob to the repository.
	// The descriptor must contain the pre-computed digest and size.
	PushBlob(ctx context.Context, repoRef string, desc *ocispec.Descriptor, r io.Reader) error

	// FetchBlob fetches a blob from the repository.
	// The caller is responsible for closing the returned reader.
	FetchBlob(ctx context.Context, repoRef string, desc *ocispec.Descriptor) (io.ReadCloser, error)

	// PushManifest pushes a manifest to the repository with the given tag.
	PushManifest(ctx context.Context, repoRef, tag string, manifest *ocispec.Manifest) (ocispec.Descriptor, error)

	// FetchManifest fetches a manifest from the repository by descriptor.
	FetchManifest(ctx context.Context, repoRef string, expected *ocispec.Descriptor) (ocispec.Manifest, []byte, error)

	// Resolve resolves a reference (tag or digest) to a descriptor.
	Resolve(ctx context.Context, repoRef, ref string) (ocispec.Descriptor, error)

	// Tag creates or updates a tag pointing to the given descriptor.
	Tag(ctx context.Context, repoRef string, desc *ocispec.Descriptor, tag string) error

	// PushManifestByDigest pushes a manifest without a tag, referenced only by digest.
	// This is used for OCI 1.1 referrer artifacts that don't need a tag.
	PushManifestByDigest(ctx context.Context, repoRef string, manifest *ocispec.Manifest) (ocispec.Descriptor, error)

	// BlobURL returns the URL for direct blob access via HTTP range requests.
	BlobURL(repoRef, digest string) (string, error)

	// AuthHeaders returns HTTP headers with authentication for direct blob access.
	AuthHeaders(ctx context.Context, repoRef string) (http.Header, error)

	// InvalidateAuthHeaders clears cached auth headers for the repository host.
	InvalidateAuthHeaders(repoRef string) error
}

OCIClient defines the interface for OCI registry operations.

This interface abstracts the low-level OCI operations, allowing different implementations (e.g., ORAS-based, mock for testing).

type Option 

type Option func(*Client)

Option configures a Client.

func WithDockerConfig 

func WithDockerConfig() Option

WithDockerConfig enables reading credentials from ~/.docker/config.json. This is passed through to the default ORAS client.

func WithIndexCache 

func WithIndexCache(ic cache.IndexCache) Option

WithIndexCache sets the cache for index blob lookups.

func WithLogger 

func WithLogger(logger *slog.Logger) Option

WithLogger sets a logger for the client. The logger is propagated to the underlying ORAS client. If nil, a discard logger is used (default behavior).

func WithManifestCache 

func WithManifestCache(mc cache.ManifestCache) Option

WithManifestCache sets the cache for manifest lookups.

func WithOCIClient 

func WithOCIClient(c OCIClient) Option

WithOCIClient sets a custom OCI client. If not set, a default ORAS-based client is created.

When a custom OCIClient is provided, pass-through options like WithPlainHTTP and WithDockerConfig are ignored.

func WithOrasOptions 

func WithOrasOptions(opts ...oras.Option) Option

WithOrasOptions sets options that are passed through to the ORAS client. This is used internally by the blob.Client to configure the underlying ORAS client.

func WithPlainHTTP 

func WithPlainHTTP(enabled bool) Option

WithPlainHTTP enables plain HTTP (no TLS) for registries. This is passed through to the default ORAS client.

func WithPolicies 

func WithPolicies(policies ...Policy) Option

WithPolicies adds policies that must pass for Fetch and Pull operations.

func WithPolicy 

func WithPolicy(policy Policy) Option

WithPolicy adds a policy that must pass for Fetch and Pull operations.

func WithRefCache 

func WithRefCache(rc cache.RefCache) Option

WithRefCache sets the cache for reference to digest mappings.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header for requests. This is passed through to the default ORAS client.

type Policy 

type Policy interface {
	Evaluate(ctx context.Context, req PolicyRequest) error
}

Policy evaluates whether a manifest is trusted.

type PolicyClient 

type PolicyClient interface {
	Referrers(ctx context.Context, ref string, subject ocispec.Descriptor, artifactType string) ([]ocispec.Descriptor, error)
	FetchDescriptor(ctx context.Context, ref string, desc ocispec.Descriptor) ([]byte, error)
}

PolicyClient exposes minimal client capabilities for policies.

type PolicyFunc 

type PolicyFunc func(ctx context.Context, req PolicyRequest) error

PolicyFunc is an adapter to allow ordinary functions as policies.

func (PolicyFunc) Evaluate 

func (f PolicyFunc) Evaluate(ctx context.Context, req PolicyRequest) error

Evaluate calls f(ctx, req).

type PolicyRequest 

type PolicyRequest struct {
	Ref      string
	Digest   string
	Manifest *BlobManifest
	Subject  ocispec.Descriptor
	Client   PolicyClient
}

PolicyRequest provides context for policy evaluation.

type PullOption 

type PullOption func(*pullConfig)

PullOption configures a Pull operation.

func WithBlobOptions 

func WithBlobOptions(opts ...blob.Option) PullOption

WithBlobOptions passes options to the created Blob.

These options configure the Blob's behavior, such as decoder settings and verification options.

func WithBlockCache added in v1.1.2 

func WithBlockCache(bc cache.BlockCache) PullOption

WithBlockCache sets a block cache to wrap the HTTP data source. This caches HTTP range request blocks for improved performance on random access patterns.

func WithMaxIndexSize 

func WithMaxIndexSize(maxBytes int64) PullOption

WithMaxIndexSize sets the maximum number of bytes allowed for the index blob.

Use a value <= 0 to disable the limit.

func WithPullProgress added in v1.1.0 

func WithPullProgress(fn blob.ProgressFunc) PullOption

WithPullProgress sets a callback to receive progress updates during pull. The callback receives events for manifest and index fetching. The callback may be invoked concurrently and must be safe for concurrent use.

func WithPullSkipCache 

func WithPullSkipCache() PullOption

WithPullSkipCache bypasses the ref and manifest caches.

This forces a fresh fetch from the registry even if cached data exists.

type PushOption 

type PushOption func(*pushConfig)

PushOption configures a Push operation.

func WithAnnotations 

func WithAnnotations(annotations map[string]string) PushOption

WithAnnotations sets custom annotations on the manifest.

Standard annotations like org.opencontainers.image.created are set automatically and can be overridden.

func WithProgress added in v1.1.0 

func WithProgress(fn blob.ProgressFunc) PushOption

WithProgress sets a callback to receive progress updates during push. The callback receives events for index and data blob uploads. The callback may be invoked concurrently and must be safe for concurrent use.

func WithTags 

func WithTags(tags ...string) PushOption

WithTags applies additional tags to the pushed manifest.

The primary tag from the ref is always applied. These tags are applied after the initial push succeeds.

type SignOption 

type SignOption func(*signConfig)

SignOption configures a Sign operation.

Source Files

View all Source files

Directories

Path Synopsis
Package cache provides caching interfaces for the blob client.
 Package cache provides caching interfaces for the blob client.
disk
Package disk provides disk-backed implementations of client cache interfaces.
 Package disk provides disk-backed implementations of client cache interfaces.
Package mocks provides mock implementations for testing.
 Package mocks provides mock implementations for testing.
Package oras provides a generic OCI client layer wrapping the ORAS library.
 Package oras provides a generic OCI client layer wrapping the ORAS library.

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.