upstream

type ActiveHealthCheck struct {

	// Targets is the set of upstreams to probe; MUST be the same slice the wrapped
	// Balancer was built over (see NewActiveHealthCheck).
	Targets []*Target

	// Balancer is the wrapped strategy. It receives the health gate if it implements
	// the internal gate interface (all package balancers do).
	Balancer http.RoundTripper

	// Path and Method are the probe request's URL path and HTTP method. Default "/"
	// and GET.
	Path   string
	Method string

	// Scheme is the probe URL scheme. It matters ONLY for targets backed by the
	// dynamic multi-scheme Transport, which dispatches on it (use "h2c" or "unix" to
	// match an h2c/unix data path); the dedicated transports (HTTPTransport,
	// HTTPSTransport, H2CTransport, UnixTransport) force their own scheme and ignore
	// it. Default "http". A wrong scheme here probes the wrong protocol and can drive
	// a healthy backend down, so set it (or ProbeTransport) for non-http data paths.
	Scheme string

	// Interval is the time between probes for a target. Default 10s.
	Interval time.Duration

	// Timeout bounds a single probe (a per-probe context deadline). Default 5s.
	Timeout time.Duration

	// HealthyThld is the number of consecutive successful probes that mark a down
	// target up again. Default 1 (recover fast).
	HealthyThld int

	// UnhealthyThld is the number of consecutive failed probes that mark an up target
	// down. Default 3.
	UnhealthyThld int

	// ProbeTransport overrides the transport used for probes; nil reuses each
	// Target.Transport (so the probe exercises the real connection pool/TLS). Set it
	// to isolate probe traffic from the data pool, or for exotic schemes. Note a probe
	// shares the data transport's per-host connection budget: with a very small
	// MaxConn (e.g. 1) an in-flight probe can hold the only connection for up to
	// Timeout, briefly blocking data requests to that origin — set ProbeTransport to
	// avoid the contention.
	ProbeTransport http.RoundTripper

	// StartUnhealthy makes targets begin DOWN (fail-closed cold start): only the first
	// successful probe admits them. Default false — targets begin up, so a
	// misconfigured probe path cannot black-hole a fresh deploy.
	StartUnhealthy bool

	// IsHealthy decides whether a probe result is healthy; nil treats a non-error
	// response with status < 400 as healthy.
	IsHealthy func(resp *http.Response, err error) bool

	// OnStateChange observes this target's active-health gate flipping: ReasonProbeDown
	// (UnhealthyThld consecutive failing probes took an up target down, From StateClosed
	// To StateOpen, carrying a classified ProbeCause) and ReasonProbeRecover (HealthyThld
	// consecutive successes readmitted a down one, From StateOpen To StateClosed,
	// CauseNone). nil disables it at zero cost. It fires synchronously on the target's
	// sole prober goroutine, exactly once per crossing, AFTER the gate bit is published;
	// the callee owns its own concurrency across targets (see prom.UpstreamState). The
	// initial gate (StartUnhealthy or not) is NOT a transition and fires nothing — with
	// StartUnhealthy the first admitting probe is a genuine ReasonProbeRecover. A
	// graceful shutdown / Close never emits a spurious ReasonProbeDown. The ProbeCause
	// label is a bounded closed set.
	OnStateChange StateChangeFunc
	// contains filtered or unexported fields
}

type CircuitBreakingLoadBalancer struct {

	// Targets is the set of upstreams to balance across.
	Targets []*Target

	// FailureThreshold is the number of consecutive failures that trips a CLOSED
	// target to OPEN. Defaults to 5.
	FailureThreshold int

	// SuccessThreshold is the number of consecutive HALF-OPEN probe successes that
	// closes a target. Defaults to 2.
	SuccessThreshold int

	// OpenTimeout is the base cooldown a target stays OPEN before a probe is allowed.
	// It doubles on each repeat trip, capped at MaxOpenTimeout. Defaults to 5s.
	OpenTimeout time.Duration

	// MaxOpenTimeout caps the backed-off OPEN cooldown. Defaults to 1m.
	MaxOpenTimeout time.Duration

	// ProbeTimeout bounds how long a HALF-OPEN probe may hold its slot. If a probe
	// does not complete within it (e.g. a transport with no response timeout hangs),
	// its slot is reclaimed and the target re-opens, so one stuck probe cannot wedge
	// the target half-open forever. Set it above the upstream transport's response
	// timeout so it only fires for genuinely hung probes. Defaults to 2m (above the
	// HTTP transports' 1m default response-header timeout).
	ProbeTimeout time.Duration

	// HalfOpenMaxProbes is the maximum number of concurrent HALF-OPEN probes (a
	// connect+headers admission cap, not an in-flight-body cap). Defaults to 1.
	HalfOpenMaxProbes int32

	// IsFailure decides whether a round-trip result counts as a failure. When nil,
	// any transport error other than a client-canceled request counts. Set it to
	// also treat responses such as 5xx as failures. In HALF-OPEN a non-failure
	// counts as a probe success, so by default a client-canceled probe nudges the
	// breaker toward closing rather than being treated as neutral (a wrongly closed
	// but still-broken target simply re-trips on the next real failure).
	IsFailure func(resp *http.Response, err error) bool

	// OnStateChange observes per-target circuit state transitions (nil disables);
	// see prom.UpstreamState. It is fired synchronously from the goroutine that
	// commits the transition, exactly once per transition, after the new state is
	// published. The callee owns its own concurrency.
	OnStateChange StateChangeFunc
	// contains filtered or unexported fields
}

type EjectingLoadBalancer struct {

	// Targets is the set of upstreams to balance across.
	Targets []*Target

	// MaxFails is the number of consecutive failures that ejects a target.
	// Defaults to 3.
	MaxFails int

	// EjectTimeout is the base cooldown a target stays ejected. It doubles on
	// each consecutive ejection, capped at MaxEjectTimeout. Defaults to 30s.
	EjectTimeout time.Duration

	// MaxEjectTimeout caps the ejection cooldown. Defaults to 5m.
	MaxEjectTimeout time.Duration

	// IsFailure decides whether a round-trip result counts as a failure. When
	// nil, any transport error other than a client-canceled request counts.
	// Set it to also treat responses such as 5xx as failures.
	IsFailure func(resp *http.Response, err error) bool

	// OnStateChange observes a target being ejected (ReasonEject) or returned to
	// rotation on a confirmed success (ReasonRecover); nil disables it. It reflects
	// committed eject/recover events, NOT cooldown-expiry rotation membership: a
	// target whose cooldown has expired but has not yet served a successful request
	// still reads StateOpen until that success. Alert on the prom.UpstreamState
	// transitions counter, which is exact. The callee owns its own concurrency.
	OnStateChange StateChangeFunc
	// contains filtered or unexported fields
}

type H2CTransport struct {
	HTTP2Transport *http2.Transport
	HTTPTransport  *http.Transport

	// DialContext, if non-nil, replaces the default net.Dialer used to open
	// TCP connections to the upstream. nil uses an internal net.Dialer with
	// the default dial timeout and keep-alive (today's behavior, unchanged).
	// Use it to observe dial errors, re-resolve endpoints, or wrap the
	// connection. A custom dialer is responsible for honoring its own
	// timeouts; the default dial timeout is ignored when DialContext is set.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// contains filtered or unexported fields
}

type HTTPSTransport struct {
	DialTimeout           time.Duration
	TCPKeepAlive          time.Duration
	DisableKeepAlives     bool
	MaxConn               int
	MaxIdleConns          int
	IdleConnTimeout       time.Duration
	ExpectContinueTimeout time.Duration
	ResponseHeaderTimeout time.Duration
	TLSClientConfig       *tls.Config

	// DialContext, if non-nil, replaces the default net.Dialer used to open
	// TCP connections to the upstream (the TLS handshake is then performed on
	// top of that connection). nil uses an internal net.Dialer built from
	// DialTimeout/TCPKeepAlive (today's behavior, unchanged). Use it to
	// observe dial errors, re-resolve endpoints, or wrap the connection. A
	// custom dialer is responsible for honoring its own timeouts; DialTimeout
	// is ignored when DialContext is set.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// contains filtered or unexported fields
}

type HTTPTransport struct {
	DialTimeout           time.Duration
	TCPKeepAlive          time.Duration
	DisableKeepAlives     bool
	MaxConn               int
	MaxIdleConns          int
	IdleConnTimeout       time.Duration
	ExpectContinueTimeout time.Duration
	ResponseHeaderTimeout time.Duration

	// DialContext, if non-nil, replaces the default net.Dialer used to open
	// TCP connections to the upstream. nil uses an internal net.Dialer built
	// from DialTimeout/TCPKeepAlive (today's behavior, unchanged). Use it to
	// observe dial errors, re-resolve endpoints, or wrap the connection. A
	// custom dialer is responsible for honoring its own timeouts; DialTimeout
	// is ignored when DialContext is set.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// contains filtered or unexported fields
}

type HedgingLoadBalancer struct {

	// Next is the wrapped balancer. Each attempt calls Next.RoundTrip, which picks
	// and advances past a target, so a hedge lands on a different one.
	Next http.RoundTripper

	// HedgeDelay is how long to wait for the in-flight request before launching a
	// hedge. <= 0 disables hedging (pure pass-through to Next.RoundTrip).
	HedgeDelay time.Duration

	// MaxHedge is the number of extra speculative attempts beyond the original (each
	// HedgeDelay-spaced). Defaults to 1 (at most one hedge -> 2x fan-out).
	MaxHedge int

	// HedgeOnError launches the next hedge immediately on a losing transport error
	// rather than waiting out HedgeDelay. NewHedgingLoadBalancer enables it; a bare
	// HedgingLoadBalancer{} literal leaves it false (a bool can't be defaulted in init).
	HedgeOnError bool

	// IsHedgeable decides whether a request may be hedged; nil uses the idempotent
	// body-less rule (and never hedges a request already being retried).
	IsHedgeable func(r *http.Request) bool

	// IsWinner decides whether a leg's result wins the race; nil means "a response
	// with no transport error". Set it to, say, only accept non-5xx.
	IsWinner func(resp *http.Response, err error) bool
	// contains filtered or unexported fields
}

type LatencyEjectingLoadBalancer struct {

	// Targets is the set of upstreams to balance across.
	Targets []*Target

	// EjectionFactor ejects a target whose decayed mean TTFB is >= the pool median
	// times this. Must be > 1 (a factor <= 1 would eject the median itself).
	// Defaults to 3.0; below ~2.0 is aggressive (ejects on normal tail jitter).
	EjectionFactor float64

	// MinSamples is the number of measured round-trips a target must accumulate
	// before it is eligible to be ejected or to count toward the pool median. It
	// gates cold-start noise (a first request's TLS handshake / cold pool) and, since
	// a re-probed target's sample count is reset on ejection, also gates re-probes.
	// Defaults to 100.
	MinSamples uint64

	// MinHosts is the minimum number of eligible targets for a valid pool median; a
	// pool with fewer never latency-ejects. Defaults to 3 (a median needs >= ~3 to be
	// robust to the outlier it is meant to expose).
	MinHosts int

	// HalfLife is the wall-clock half-life of the time-decayed latency EWMA, so the
	// effective window is independent of a target's request rate. Defaults to 10s.
	HalfLife time.Duration

	// MinEjectDelta is an additive floor: a target must also exceed the median by at
	// least this to be ejected, which kills the ratio instability of a fast pool (3ms
	// is 3x a 1ms median but operationally irrelevant). Defaults to 50ms.
	MinEjectDelta time.Duration

	// MinEjectLatency is an absolute floor: a target below it is never ejected,
	// however slow it is relative to peers. Defaults to 0 (off).
	MinEjectLatency time.Duration

	// MaxEjectionPercent caps the fraction of the pool that may be latency-ejected at
	// once, so the pool cannot progressively drain. Defaults to 30. It is a near-hard
	// cap: a concurrent burst of decisions can transiently overshoot it by the
	// in-flight concurrency (the counts are lock-free scans), self-correcting as
	// cooldowns expire — the exact anti-oscillation guarantee comes from the median
	// being robust, not from this count.
	MaxEjectionPercent int

	// PanicThreshold: if more than this percent of the pool is ejected, the slowdown
	// is treated as systemic — no further ejections happen and pick routes to all
	// targets (including slow ones). Defaults to 50; init raises it above
	// MaxEjectionPercent so it is never dead code.
	PanicThreshold int

	// EjectTimeout is the base cooldown a target stays ejected, doubling on each
	// repeat ejection up to MaxEjectTimeout. Defaults to 30s.
	EjectTimeout time.Duration

	// MaxEjectTimeout caps the ejection cooldown. Defaults to 5m.
	MaxEjectTimeout time.Duration

	// OnStateChange observes a target being ejected (ReasonEject) or healed back into
	// rotation (ReasonRecover); nil disables it. Like EjectingLoadBalancer, it
	// reflects committed eject/recover events, not cooldown-expiry rotation
	// membership. See prom.UpstreamState. The callee owns its own concurrency.
	OnStateChange StateChangeFunc
	// contains filtered or unexported fields
}

type LeastConnLoadBalancer struct {

	// Targets is the set of upstreams to balance across.
	Targets []*Target

	// OnShed observes a shed (this balancer returned ErrUnavailable before any
	// round-trip): ShedEmpty for no targets, ShedSaturated when every gate-up target
	// is at its MaxConcurrent cap, ShedAllDark when the active-HC gate marked the
	// whole pool down. Nil disables it at zero hot-path cost; see prom.UpstreamShed.
	// It fires synchronously on the request goroutine, before ErrUnavailable returns.
	OnShed ShedFunc
	// contains filtered or unexported fields
}

type ProbeCause uint8

type Reason uint8

type RoundRobinLoadBalancer struct {
	Targets []*Target
	// contains filtered or unexported fields
}

type RoundTripFunc func(r *http.Request, info RoundTripInfo)

type RoundTripInfo struct {
	// Host is the resolved upstream target the request was sent to (r.URL.Host after
	// load balancing). Unlike the client Host header, it is operator-configured and
	// therefore bounded, so it is safe as a metric label. It may be empty when the
	// load balancer rejected the request before choosing a target (ErrUnavailable).
	Host string

	// Duration is the time to the response headers: the transport round-trip
	// (connect + send request + time-to-first-byte), measured before the body is
	// streamed on to the client. It is set on both success and error.
	Duration time.Duration

	// Status is the upstream response's status code, or 0 when the round-trip failed
	// before any response (Err is then non-nil).
	Status int

	// Err is the transport error — connection refused, timeout, ErrUnavailable when
	// the load balancer had no target, etc. — or nil once a response was received,
	// regardless of that response's status code.
	Err error

	// Attempt is the zero-based retry index: 0 on the first try, 1 on the first
	// retry, and so on (read from the proxy's retry context). Existing observers
	// simply see a new zero-valued field.
	Attempt int
}

type ShedFunc func(ShedReason)

type ShedReason uint8

type State uint8

type StateChange struct {
	Host   string // resolved upstream target (operator-configured, bounded label)
	From   State
	To     State
	Reason Reason
	// Cause classifies a probe failure on the ActiveHealthCheck down crossing
	// (Reason == ReasonProbeDown). It is CauseNone (the zero value) on every other
	// event, including a probe recover and all circuit-breaker / ejecting transitions.
	Cause ProbeCause
}

type StateChangeFunc func(StateChange)

type Target struct {
	Transport http.RoundTripper
	Host      string

	// Weight biases the weighted balancers toward this target:
	// WeightedRoundRobinLoadBalancer gives it a proportionally larger share of the
	// request COUNT; LeastConnLoadBalancer lets it hold a proportionally larger
	// share of concurrent in-flight requests. Values <= 0 are treated as 1.
	// RoundRobinLoadBalancer, EjectingLoadBalancer, and CircuitBreakingLoadBalancer
	// ignore this field and weight every target equally.
	Weight int

	// MaxConcurrent caps the in-flight requests LeastConnLoadBalancer routes to this
	// target (the bulkhead pattern), isolating blast radius: a slow backend can hold
	// at most this many in-flight requests and cannot drain the pool. A request
	// counts as in-flight until its response body is closed (not at the headers), so
	// the cap bounds true end-to-end concurrency including slow body streams. Beyond
	// the cap, requests route to another under-cap target; when EVERY target is at
	// its cap the balancer sheds (ErrUnavailable -> 503) rather than overloading a
	// saturated origin. The cap is hard — never exceeded, even under a concurrent
	// burst. Values <= 0 mean unbounded (the default). Only LeastConnLoadBalancer
	// honors it; the other balancers ignore it.
	//
	// WARNING: a slot is held until the response body is closed; nothing else
	// reclaims it. A backend that sends headers then stalls mid-body keeps its slot
	// until the request's context is cancelled (which closes the body). No
	// http.Transport timeout covers that stall: ResponseHeaderTimeout bounds only
	// time-to-headers, and IdleConnTimeout reaps only idle pooled connections, never
	// an in-flight stalled one. To bound a held slot you must cap TOTAL request time
	// so the context is cancelled mid-body — a request-scoped context deadline the
	// transport honors (note pkg/timeout disarms once upstream headers are written,
	// so it does NOT cover a mid-body stall). Without such a total-time bound, after
	// MaxConcurrent stalled requests the target sheds all traffic permanently — the
	// cap becomes a latch, not a limiter.
	MaxConcurrent int
}

type TargetLoad struct {
	Host   string // resolved upstream target (operator-configured, bounded label)
	Active int64  // in-flight requests right now
	Cap    int64  // MaxConcurrent bulkhead cap; 0 == unbounded
}

type Transport struct {
	DialTimeout           time.Duration
	TCPKeepAlive          time.Duration
	DisableKeepAlives     bool
	MaxConn               int
	MaxIdleConns          int
	IdleConnTimeout       time.Duration
	ExpectContinueTimeout time.Duration
	ResponseHeaderTimeout time.Duration
	DisableCompression    bool
	TLSClientConfig       *tls.Config

	// DialContext, if non-nil, replaces the default net.Dialer used to open
	// TCP connections to the upstream for the http and h2c (plaintext) paths.
	// nil uses an internal net.Dialer built from DialTimeout/TCPKeepAlive
	// (today's behavior, unchanged). Use it to observe dial errors, re-resolve
	// endpoints, or wrap the connection. A custom dialer is responsible for
	// honoring its own timeouts; DialTimeout is ignored when DialContext is
	// set. The unix-socket path is unaffected.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// contains filtered or unexported fields
}

type UnixTransport struct {
	DisableKeepAlives     bool
	MaxIdleConns          int
	IdleConnTimeout       time.Duration
	ExpectContinueTimeout time.Duration
	ResponseHeaderTimeout time.Duration
	// contains filtered or unexported fields
}

type Upstream struct {
	Transport   http.RoundTripper
	ErrorLog    *log.Logger
	OnRoundTrip RoundTripFunc // observe each origin round-trip (nil disables); see prom.Upstream

	// RetryPolicy decides whether a request is eligible to be retried after a
	// transport error. nil uses the default canRetry: an idempotent method
	// (GET/HEAD/OPTIONS/TRACE) AND a body that is either absent or rewindable
	// (r.Body is nil/http.NoBody, OR r.GetBody != nil). Set it to widen
	// eligibility — e.g. to retry an idempotent PUT/DELETE — or to narrow it.
	//
	// RETRY AMPLIFICATION — READ BEFORE WIDENING. An eligible request may be sent
	// to upstreams up to Retries+1 times (one initial attempt plus Retries
	// re-attempts). If the same Upstream is also fronted by a HedgingLoadBalancer,
	// each of those attempts can additionally fan out to MaxHedge speculative
	// copies, so the worst-case origin load multiplies (≈ (Retries+1) × (MaxHedge+1)).
	// Size Retries (and MaxHedge) for that ceiling, and only mark a request
	// retryable here when the upstream is genuinely idempotent for it — a retried
	// non-idempotent request can double-apply a side effect (a duplicate POST, a
	// second charge). A body-bearing request is only retried when r.GetBody is set
	// (so each attempt can be rewound to the full body); without GetBody, even an
	// eligible method is not retried.
	RetryPolicy func(r *http.Request) bool

	Host          string // override host
	Path          string // target prefix path
	Retries       int
	BackoffFactor time.Duration
}

type WeightedRoundRobinLoadBalancer struct {

	// Targets is the set of upstreams to balance across.
	Targets []*Target
	// contains filtered or unexported fields
}