oci

Documentation

Overview

Package oci is a small client for the OCI distribution (registry v2) protocol: listing a repository's tags, resolving a tag's manifest digest, and answering the bearer-token challenge a registry returns on the first unauthenticated request. It is the shared heavy lifting behind every clover provider that talks to a registry - container images and Helm OCI charts alike speak the same wire protocol, so the transport, auth, and pagination live here once.

Index

• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) Digest(ctx context.Context, repo Repo, tag string) (string, error)
  • func (c *Client) Get(ctx context.Context, url, bearer string) (*http.Response, error)
  • func (c *Client) HTTPClient() *http.Client
  • func (c *Client) ResolveAuth(host string) *authn.AuthConfig
  • func (c *Client) StatusErr(action string, resp *http.Response) error
  • func (c *Client) Tags(ctx context.Context, repo Repo, deep bool) ([]string, bool, error)
• type Option
  • func WithErrorContext(label, hint string) Option
  • func WithKeychain(kc authn.Keychain) Option
  • func WithRateHeaders(h ratelimit.Headers) Option
  • func WithTokenEnv(env string) Option
  • func WithTransport(rt http.RoundTripper) Option
• type Repo

Types

type Client

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

Client talks the OCI registry v2 protocol. It holds a single lazily-built HTTP client so one cache and one rate-limit budget are shared across every lookup a run makes. The zero value is not usable; build one with New.

func New

func New(opts ...Option) *Client

New returns a registry client, defaulting to the keychain that reads the user's existing docker login so clover piggybacks on credentials docker already stores.

func (*Client) Digest

func (c *Client) Digest(ctx context.Context, repo Repo, tag string) (string, error)

Digest resolves the content digest a tag points at. By default it returns the multi-arch index digest from the Docker-Content-Digest header (a HEAD). When repo.Platform is set, it instead returns that os/arch's manifest digest from the index - what `docker pull --platform` would pin.

func (*Client) Get

func (c *Client) Get(ctx context.Context, url, bearer string) (*http.Response, error)

Get issues a GET, attaching a bearer token when one is given.

func (*Client) HTTPClient

func (c *Client) HTTPClient() *http.Client

HTTPClient lazily builds the shared HTTP client, wrapping the transport with caching and rate-limit handling so the cache and budget are shared run-wide. It is exported so a consumer's non-registry calls (a Hub web API, a Helm index.yaml) reuse the same cache and rate-limit budget.

func (*Client) ResolveAuth

func (c *Client) ResolveAuth(host string) *authn.AuthConfig

ResolveAuth resolves credentials for a registry host: first the configured token env var (a ready bearer token), then the docker login the keychain holds. It returns nil for anonymous access.

func (*Client) StatusErr

func (c *Client) StatusErr(action string, resp *http.Response) error

StatusErr builds the error for a non-OK registry response. An auth or rate-limit status (401/403/429) appends the hint, so the guidance lands at the moment it is actionable for the registry actually in use.

func (*Client) Tags

func (c *Client) Tags(ctx context.Context, repo Repo, deep bool) ([]string, bool, error)

Tags lists a repository's tags from the registry v2 tags endpoint, answering the bearer-token challenge a registry returns on the first, unauthenticated request. A shallow lookup (deep=false) reads only the first page and reports truncated=true when a further page exists; a deep lookup follows the Link header to exhaustion (registry tags are lexically ordered, so a deep lookup is what guarantees the newest version is seen).

type Option

type Option func(*Client)

Option configures a Client.

func WithErrorContext

func WithErrorContext(label, hint string) Option

WithErrorContext sets the prefix for the client's errors and the hint appended to auth and rate-limit failures, so guidance lands in the consumer's voice.

func WithKeychain

func WithKeychain(kc authn.Keychain) Option

WithKeychain overrides the credential keychain.

func WithRateHeaders

func WithRateHeaders(h ratelimit.Headers) Option

WithRateHeaders overrides the rate-limit header names.

func WithTokenEnv

func WithTokenEnv(env string) Option

WithTokenEnv names the environment variable that, when set, supplies a ready bearer token overriding every other credential source.

func WithTransport

func WithTransport(rt http.RoundTripper) Option

WithTransport overrides the HTTP transport, for tests. A nil transport leaves the cached, rate-limited default in place.

type Repo

type Repo struct {
	Host       string
	AuthHost   string
	Repository string
	Platform   string
}

Repo identifies a repository within a registry. Host serves the /v2 API; AuthHost is where credentials are keyed (it diverges from Host only for Docker Hub, whose registry is registry-1.docker.io but whose login is stored under index.docker.io) and defaults to Host when empty; Repository is the path within the registry and the basis for the pull scope. Platform, when set (os/arch), selects that platform's manifest digest from a multi-arch index instead of the index digest.