oci

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Jun 18, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	LayerMediaType = types.MediaType("application/vnd.pacto.bundle.layer.v1.tar+gzip")
)

Variables

This section is empty.

Functions

func BestTag 

func BestTag(tags []string, constraint string) (string, error)

BestTag selects the highest semver tag from tags. If constraint is non-empty, only tags satisfying the semver constraint are considered.

func BundleToTarGz 

func BundleToTarGz(fsys fs.FS) ([]byte, error)

BundleToTarGz creates a tar.gz archive of all files in the bundle FS. Used by the pack command to produce a local archive.

func CacheDirFor added in v1.5.0 

func CacheDirFor(home string) string

CacheDirFor returns the on-disk OCI cache directory for the given home directory, honoring XDG_CACHE_HOME. Exported so other components (e.g. the dashboard diagnostics) resolve the exact same path.

func ExportedUserHomeDirFn 

func ExportedUserHomeDirFn() func() (string, error)

ExportedUserHomeDirFn returns the current userHomeDirFn for testing.

func FilterSemverTags 

func FilterSemverTags(tags []string) []string

FilterSemverTags returns only valid semver tags, sorted descending (latest first). Thin wrapper over pkg/semver so the resolver and the dashboard share one impl.

func HasExplicitTag 

func HasExplicitTag(ref string) bool

HasExplicitTag reports whether an OCI reference includes an explicit tag or digest (e.g. "repo:v1" or "repo@sha256:...").

func NewKeychain 

func NewKeychain(opts CredentialOptions) authn.Keychain

NewKeychain builds a keychain that tries, in order: 1. Explicit credentials (flags/env vars) 2. Pacto config (~/.config/pacto/config.json) 3. gh CLI token (for GitHub registries) 4. Docker config, credential helpers, and cloud auto-detection

func PactoConfigDir 

func PactoConfigDir() (string, error)

PactoConfigDir returns the pacto configuration directory. It respects $XDG_CONFIG_HOME, defaulting to ~/.config/pacto.

func PactoConfigPath 

func PactoConfigPath() (string, error)

PactoConfigPath returns the path to pacto's dedicated config file. It respects $XDG_CONFIG_HOME, defaulting to ~/.config/pacto/config.json.

func ResolveRef 

func ResolveRef(ctx context.Context, lister TagLister, ref, constraint string) (string, error)

ResolveRef resolves an OCI reference that may be missing a tag by querying available tags and selecting the best semver match. If the ref already has an explicit tag or digest, it is returned unchanged.

func SetUserHomeDirFn 

func SetUserHomeDirFn(fn func() (string, error)) func() (string, error)

SetUserHomeDirFn sets userHomeDirFn and returns the previous value for deferred restore.

Types

type ArtifactNotFoundError 

type ArtifactNotFoundError struct {
	Ref string
	Err error
}

ArtifactNotFoundError indicates the reference does not exist (404).

func (*ArtifactNotFoundError) Error 

func (e *ArtifactNotFoundError) Error() string

func (*ArtifactNotFoundError) Unwrap 

func (e *ArtifactNotFoundError) Unwrap() error

type AuthenticationError 

type AuthenticationError struct {
	Ref      string
	Err      error
	Tried    []string
	Rejected []string
}

AuthenticationError indicates credential rejection (401/403).

func (*AuthenticationError) Error 

func (e *AuthenticationError) Error() string

func (*AuthenticationError) Unwrap 

func (e *AuthenticationError) Unwrap() error

type BundleStore 

type BundleStore interface {
	Push(ctx context.Context, ref string, bundle *contract.Bundle) (string, error)
	Pull(ctx context.Context, ref string) (*contract.Bundle, error)
	Resolve(ctx context.Context, ref string) (string, error)
	ListTags(ctx context.Context, repo string) ([]string, error)
}

BundleStore handles push and pull of contract bundles to/from OCI registries.

type CachedStore 

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

CachedStore wraps a BundleStore with in-memory and disk caching. Pulled bundles are kept in memory (fastest) and persisted to disk under ~/.cache/pacto/oci/ so they survive across process invocations. ListTags results are cached in memory for the lifetime of the process.

func NewCachedStore 

func NewCachedStore(inner BundleStore) *CachedStore

NewCachedStore creates a BundleStore that caches pulled bundles on disk. If the cache directory cannot be determined, caching is silently disabled.

func (*CachedStore) CacheDir 

func (c *CachedStore) CacheDir() string

CacheDir returns the resolved on-disk cache directory (e.g. ~/.cache/pacto/oci). Returns empty string if no cache directory could be determined at creation time.

func (*CachedStore) DisableCache 

func (c *CachedStore) DisableCache()

DisableCache skips reading from the disk cache (cold-start mode) and clears the in-memory caches (both pulled bundles and listed tags). Disk writes remain enabled so that same-session pulls (e.g. fetch-all-versions) are still persisted and available for enrichment.

func (*CachedStore) ListTags 

func (c *CachedStore) ListTags(ctx context.Context, repo string) ([]string, error)

func (*CachedStore) Pull 

func (c *CachedStore) Pull(ctx context.Context, ref string) (*contract.Bundle, error)

func (*CachedStore) Push 

func (c *CachedStore) Push(ctx context.Context, ref string, bundle *contract.Bundle) (string, error)

func (*CachedStore) Resolve 

func (c *CachedStore) Resolve(ctx context.Context, ref string) (string, error)

type Client 

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

Client implements BundleStore using go-containerregistry.

func NewClient 

func NewClient(keychain authn.Keychain, opts ...ClientOption) *Client

NewClient creates a new OCI client with the given keychain.

func (*Client) ListTags 

func (c *Client) ListTags(ctx context.Context, repo string) ([]string, error)

ListTags returns all tags available for the given repository.

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, ref string) (*contract.Bundle, error)

Pull fetches an OCI image from the given reference and converts it to a Bundle.

func (*Client) Push 

func (c *Client) Push(ctx context.Context, ref string, bundle *contract.Bundle) (string, error)

Push converts a Bundle to an OCI image and pushes it to the given reference. Returns the digest of the pushed image.

func (*Client) Resolve 

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

Resolve resolves a reference to its digest.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures the OCI Client.

func WithNameOptions 

func WithNameOptions(opts ...name.Option) ClientOption

WithNameOptions adds name.Option values used when parsing OCI references.

type CredSource added in v1.9.0 

type CredSource struct {
	Name          string
	Authenticator authn.Authenticator
}

CredSource is a named credential source resolved for a registry.

type CredentialOptions 

type CredentialOptions struct {
	Username string
	Password string
	Token    string
}

CredentialOptions holds explicit credentials provided via CLI flags or env vars.

type InvalidBundleError 

type InvalidBundleError struct {
	Ref string
	Err error
}

InvalidBundleError indicates the pulled artifact is not a valid Pacto bundle.

func (*InvalidBundleError) Error 

func (e *InvalidBundleError) Error() string

func (*InvalidBundleError) Unwrap 

func (e *InvalidBundleError) Unwrap() error

type InvalidRefError 

type InvalidRefError struct {
	Ref string
	Err error
}

InvalidRefError indicates the OCI reference could not be parsed.

func (*InvalidRefError) Error 

func (e *InvalidRefError) Error() string

func (*InvalidRefError) Unwrap 

func (e *InvalidRefError) Unwrap() error

type NoMatchingVersionError 

type NoMatchingVersionError struct {
	Ref        string
	Constraint string
	Err        error
}

NoMatchingVersionError indicates no tags satisfy the compatibility constraint.

func (*NoMatchingVersionError) Error 

func (e *NoMatchingVersionError) Error() string

func (*NoMatchingVersionError) Unwrap 

func (e *NoMatchingVersionError) Unwrap() error

type PactoAuth 

type PactoAuth struct {
	Auth string `json:"auth"`
}

PactoAuth represents a single registry auth entry.

type PactoConfig 

type PactoConfig struct {
	Auths map[string]PactoAuth `json:"auths"`
}

PactoConfig represents the structure of pacto's config.json file.

type PactoKeychain added in v1.9.0 

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

PactoKeychain resolves credentials across ordered named sources and supports falling through to the next source when the registry rejects the current one.

func (*PactoKeychain) Candidates added in v1.9.0 

func (k *PactoKeychain) Candidates(target authn.Resource) ([]CredSource, error)

Candidates returns all non-anonymous credential sources for the target, in priority order, each tagged with its source name.

func (*PactoKeychain) Resolve added in v1.9.0 

func (k *PactoKeychain) Resolve(target authn.Resource) (authn.Authenticator, error)

Resolve returns the first non-anonymous authenticator, preserving back-compat with go-containerregistry's remote.WithAuthFromKeychain callers.

type RegistryUnreachableError 

type RegistryUnreachableError struct {
	Ref string
	Err error
}

RegistryUnreachableError indicates a network or DNS failure.

func (*RegistryUnreachableError) Error 

func (e *RegistryUnreachableError) Error() string

func (*RegistryUnreachableError) Unwrap 

func (e *RegistryUnreachableError) Unwrap() error

type ResolveMode 

type ResolveMode int

ResolveMode controls whether remote fetching is allowed. 

const (
	// LocalOnly restricts resolution to the local disk cache.
	LocalOnly ResolveMode = iota
	// RemoteAllowed permits fetching from the OCI registry on cache miss.
	RemoteAllowed
)

type Resolver 

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

Resolver provides lazy, on-demand resolution of Pacto bundles from OCI references. It checks the local disk cache first and optionally falls back to pulling from the remote registry.

func NewResolver 

func NewResolver(store BundleStore) *Resolver

NewResolver creates a Resolver backed by the given BundleStore. The store should be a CachedStore so that successful pulls persist to disk.

func (*Resolver) FetchAllVersions 

func (r *Resolver) FetchAllVersions(ctx context.Context, ref string) ([]string, error)

FetchAllVersions lists all semver tags for the given OCI repo reference and pulls each one, ensuring they are cached by the underlying BundleStore. Returns the version list sorted descending (latest first).

func (*Resolver) ListVersions 

func (r *Resolver) ListVersions(ctx context.Context, ref string) ([]string, error)

ListVersions returns all semver tags available for the given OCI repo reference. The ref should be untagged (e.g. "ghcr.io/org/svc-pacto"). Non-semver tags are excluded. Results are sorted descending (latest first).

func (*Resolver) Resolve 

func (r *Resolver) Resolve(ctx context.Context, ref string, mode ResolveMode) (*contract.Bundle, error)

Resolve fetches a Pacto bundle for the given OCI reference.

In LocalOnly mode, only the disk cache is checked. In RemoteAllowed mode, a cache miss triggers a pull from the registry.

Errors are typed:

  • *InvalidRefError: ref cannot be parsed
  • *ArtifactNotFoundError: not in registry (404)
  • *AuthenticationError: credentials rejected (401/403)
  • *RegistryUnreachableError: network/DNS failure
  • *InvalidBundleError: pulled artifact is not a valid Pacto bundle

func (*Resolver) ResolveConstrained 

func (r *Resolver) ResolveConstrained(ctx context.Context, ref, constraint string, mode ResolveMode) (*contract.Bundle, error)

ResolveConstrained fetches a Pacto bundle, resolving untagged refs using the compatibility constraint to select the best matching version from the OCI registry's available tags.

If the ref already has an explicit tag or digest, the constraint is ignored. If the ref is untagged and constraint is empty, the highest semver tag is used.

Additional error type:

  • *NoMatchingVersionError: no tags satisfy the constraint

type TagLister 

type TagLister interface {
	ListTags(ctx context.Context, repo string) ([]string, error)
}

TagLister can list available tags for an OCI repository.

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.