Documentation
¶
Overview ¶
Package ocischeme decides whether an OCI registry should be reached over plain HTTP or HTTPS.
Zarf's --plain-http flag is a global, process-wide setting, but many registries Zarf talks to during a single command are not the registry the user meant that flag for — a third-party Helm chart URL, a container image reference, or a chart's own OCI dependency, all discovered by reading package data rather than named directly on the command line. Forcing the global flag onto those registries is wrong in both directions: it can force plain HTTP onto a registry that only speaks HTTPS (breaking the fetch), or leave a registry that only speaks plain HTTP unreachable because the flag wasn't set for an unrelated reason.
This package answers the question per host instead: it probes the host directly and only falls back to plain HTTP on definitive proof — either the same port answers plaintext HTTP underneath a failed TLS handshake, or (only for a bare hostname with no explicit port, where HTTPS and HTTP resolve to different default ports) a real HTTP response on the conventional HTTP port once the HTTPS default port has proven completely unreachable. It never falls back on a TLS certificate error or an ordinary non-2xx status code — those prove something is listening and speaking a protocol, which is not evidence the correct scheme is different.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithNegotiator ¶
func WithNegotiator(ctx context.Context, n *Negotiator) context.Context
WithNegotiator returns a copy of ctx carrying n, retrievable with From.
Types ¶
type Negotiator ¶
type Negotiator struct {
// contains filtered or unexported fields
}
Negotiator decides, per host, whether Zarf should speak plain HTTP or HTTPS to a registry reference that was discovered by reading package data rather than named explicitly on the command line. Decisions are cached per host, and concurrent callers negotiating the same host share a single in-flight probe.
A Negotiator is safe for concurrent use.
func From ¶
func From(ctx context.Context) *Negotiator
From returns the Negotiator carried by ctx. If none is present — e.g. because ctx was never passed through the zarf CLI's root command, or in a unit test — it returns a shared default Negotiator (see defaultNegotiator) so callers still get caching, just not scoped to a single command invocation.
func (*Negotiator) Invalidate ¶
func (n *Negotiator) Invalidate(host string)
Invalidate drops any cached decision for host, forcing the next UsePlainHTTP call to re-probe.
Callers should only invalidate in response to a transport-level failure that plausibly means the cached scheme is now wrong — e.g. a TLS handshake failure when a request was sent over HTTPS, or a connection reset/refused when a request was sent over the cached plain-HTTP scheme.
func (*Negotiator) UsePlainHTTP ¶
func (n *Negotiator) UsePlainHTTP(ctx context.Context, host string, opts ProbeOptions) (bool, error)
UsePlainHTTP returns true if host should be reached over plain HTTP rather than HTTPS, deciding by probing the host directly (see decide). A cached decision is reused until it expires; see Options.TTL. Failures are cached too, but only for negativeCacheTTL.
type Options ¶
type Options struct {
// TTL controls how long a negotiated decision is cached before it is re-probed.
// Zero means decisions never expire, which is correct for a Zarf CLI invocation
// (a short-lived process) but not for a long-running process such as the Zarf
// Agent admission webhook, which should set a positive TTL.
TTL time.Duration
}
Options configures a Negotiator.
type ProbeOptions ¶
type ProbeOptions struct {
// InsecureSkipTLSVerify disables TLS certificate verification during the HTTPS
// probe. A certificate error is never, by itself, a reason to fall back to plain
// HTTP; this only affects whether the HTTPS probe accepts a self-signed/invalid
// certificate as a successful connection. Ignored if Transport is set.
InsecureSkipTLSVerify bool
// Transport, when set, is used for the probe instead of the package's default
// transport. Provide this when reaching the host requires something a generic
// transport can't do, like presenting a client certificate to an mTLS-secured
// registry. If it retries internally, probing is slower and less precise than
// the package's no-retry default; see probeTimeout.
Transport http.RoundTripper
}
ProbeOptions configures a single scheme-negotiation probe.
Source Files