Documentation
¶
Overview ¶
Package origin pulls bytes from upstream OCI registries.
scope:
- Multi-registry: one *Client serves every UpstreamRegistry configured by the operator. - Endpoints: GET /v2/, GET /v2/<repo>/blobs/<digest>, GET /v2/<repo>/manifests/<digest>. - Auth: optional Basic auth (credentials from a hostPath file in "username:password" format) plus the OCI Distribution Spec bearer- token flow (401 -> realm/service/scope -> token -> retry). - Failure classification: maps HTTP status and network errors to ifaces.FailureClass for the design doc propagation. Tag-resolution requests are not handled here (the mirror returns 503 on tag manifests so containerd falls through to origin directly - the design doc / the design doc).
Out of scope for (lands later):
- the design doc negative-cache cooldown integration . - Per-pull retries with backoff (caller's responsibility for now). - Resumable / ranged pulls (the design doc layer-pull semantics).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the concrete OriginPuller. It fans out to one *registry per configured upstream and routes calls by OriginRef.Registry.
func New ¶
New builds a Client from the operator config. Returns an error if any upstream credentials file cannot be read.
func (*Client) Head ¶
Head implements ifaces.OriginPuller.
HEAD is a deliberately separate code path from Pull. Two design points matter:
1. HEAD does NOT fire onPullStart. p2p_origin_pull_total counts byte-pull attempts; mixing HEAD in inflated the counter against an operation that produces no bytes, never commits to cache, and therefore can fire neither p2p_origin_pull_success_total (because mirror+puller-pump bump success after Commit, and HEAD never writes a cache entry) nor a downstream-failure counter (HEAD doesn't io.Copy a body, so it can't fail at the body-copy boundary). Leaving HEAD out keeps the started == success + failure + in_flight identity intact for the pull arithmetic. This constraint ensures exactly this drift.
2. HEAD also does NOT fire onPullFailure. The pull-failure hook double-bumps p2p_origin_pull_failure_total{kind,class} + p2p_origin_failure_total{class} (see cmd/gantry/main.go's origin.WithMetrics closure); both belong to the pull family. A future batch can add a dedicated p2p_origin_head_total / _failure_total pair if operators need HEAD-specific signal, but for now HEAD failures surface to operators via the mirror's HTTP status and access log alone.
func (*Client) Pull ¶
Pull implements ifaces.OriginPuller.
Returns the raw response-body ReadCloser; the caller is responsible for streaming the body and reporting per-operation success via their own metric hook (the mirror's serveDigest verifies stream completion; the puller pump's runOriginPull does the equivalent after commit, reopen, and advertiser mark-present). origin reports STARTED unconditionally on entry and FAILURE on its own error paths only; it does NOT wrap the response body in a success-on-Close counter because Close has no way to know whether the higher-level operation actually succeeded (HEAD never reads the body; io.Copy + cache.Commit failures both fire Close on a deferred path).
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithMetrics ¶
WithMetrics registers metric callbacks.
start fires once at the top of every Pull invocation, before the registry lookup. failure fires once on any terminal error path (unknown registry, transport error, non-2xx response, auth failure). Success is NOT emitted here - see the metricsHooks doc for why and where it belongs.
Source Files