upstream

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package upstream records one entry per attempted upstream mirror so a fetch that failed across every mirror can be logged with each mirror's own error — one mirror's TLS or DNS failure stays visible next to another's plain 404.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SanitizeURL

func SanitizeURL(raw string) string

SanitizeURL removes any userinfo component. An unparseable URL is returned unchanged: it came from configuration, and hiding it entirely would be worse than logging it verbatim.

Types

type Attempt

type Attempt struct {
	URL      string
	Status   int
	Err      error
	Duration time.Duration
}

Attempt is one mirror's outcome. Status is the upstream HTTP status, or 0 when the request never produced a response at all (TLS verification, DNS, connection refused, timeout, an open circuit breaker). That distinction is the reason this type exists: a 0 and a 404 mean very different things to an operator, and collapsing them hides misconfigured mirrors.

type Attempts

type Attempts []Attempt

Attempts is the ordered list of mirror outcomes for one logical fetch. It implements error, so a retry loop can return it directly, and zerolog.LogArrayMarshaler, so a log site can render every attempt as one structured array field.

func AttemptsFrom

func AttemptsFrom(err error) (Attempts, bool)

AttemptsFrom recovers the attempts from err, including when err wraps them. Log sites use it to attach the structured array to an error they did not produce themselves.

func (*Attempts) Add

func (a *Attempts) Add(rawURL string, status int, err error, d time.Duration)

Add appends one outcome. Credentials embedded in rawURL are stripped from the resulting URL field only. err's own text is not sanitised: it is the caller's responsibility. In practice net/http masks a *url.Error's password but leaves the username, and http.NewRequestWithContext on a malformed URL returns the raw URL unmasked.

func (Attempts) AllNotFound

func (a Attempts) AllNotFound() bool

AllNotFound reports whether every mirror answered 404 or 410 — the condition under which the proxy returns 404 rather than 502. An empty list is false: nothing was tried, so nothing proved the artifact absent.

func (Attempts) Error

func (a Attempts) Error() string

Error renders every attempt, so the flat message of a wrapped error still carries all mirrors even where the structured array is unavailable.

func (Attempts) MarshalZerologArray

func (a Attempts) MarshalZerologArray(arr *zerolog.Array)

MarshalZerologArray renders the attempts as an array of objects.

func (Attempts) Throttled added in v1.0.0

func (a Attempts) Throttled(t ThrottleLookup) (status int, retryAfter time.Duration, ok bool)

Throttled reports whether the fetch failed only because some mirror was throttling us: every attempt answered 404/410 or was throttled (an upstream 429/503, or a circuit-breaker fast-fail), and at least one was throttled. Such a failure is not proof of absence (the throttled mirror may have the artifact) and not an outage either, so the proxy answers with the throttle status instead of 404 or 502. status is 429 when any throttle was a 429, else 503; a fast-failed mirror takes the status that opened its circuit (429 when t is nil or does not know the host). retryAfter is the shortest cooldown t reports among the throttled hosts, 0 when it knows none.

func (Attempts) Unwrap

func (a Attempts) Unwrap() []error

Unwrap exposes the individual errors to errors.Is / errors.As.

type ThrottleLookup added in v1.0.0

type ThrottleLookup interface {
	Throttle(host string) (status int, retryIn time.Duration, ok bool)
}

ThrottleLookup reports whether an upstream host is in a post-throttle cooldown: the status that opened it (429 or 503) and the time left on it. *httpx.CircuitBreaker implements it; host is in URL.Host form.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL