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 ¶
- func SanitizeURL(raw string) string
- type Attempt
- type Attempts
- func (a *Attempts) Add(rawURL string, status int, err error, d time.Duration)
- func (a Attempts) AllNotFound() bool
- func (a Attempts) Error() string
- func (a Attempts) MarshalZerologArray(arr *zerolog.Array)
- func (a Attempts) Throttled(t ThrottleLookup) (status int, retryAfter time.Duration, ok bool)
- func (a Attempts) Unwrap() []error
- type ThrottleLookup
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SanitizeURL ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
MarshalZerologArray renders the attempts as an array of objects.
func (Attempts) Throttled ¶ added in v1.0.0
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.
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.