Struct UpstreamGroup 

pub struct UpstreamGroup {
    pub name: String,
    pub health: HealthConfig,
    /* private fields */
}

A named upstream: its endpoint set, the round-robin cursor, and the health policy (ADR 000017).

Fields

name: String

The upstream name routes refer to.

health: HealthConfig

The active-health-check policy (the prober reads path / interval_ms / timeout_ms).

Implementations

impl UpstreamGroup

pub fn try_acquire(self: &Arc<Self>) -> Option<RequestPermit>

Try to take an in-flight slot under the circuit-breaker cap (ADR 000028). None means the upstream is at max_requests and the fast path should fail closed (503). An unlimited breaker (max_requests == 0, the default) always succeeds with a zero-cost no-op permit. Lock-free: an optimistic increment that backs out if it crossed the cap, so concurrent callers never hold more than max_requests permits at once.

impl UpstreamGroup

pub fn pick(&self, key: Option<HashInput<'_>>) -> Option<Pick>

Pick an instance per the upstream’s LB algorithm (ADR 000035), or None when nothing is eligible (the fast path then fails closed 503 — ADR 000017). key is the request’s hash key for maglev; round-robin / least-request ignore it, and None (no key) falls back to round-robin.

pub fn pick_excluding( &self, exclude: &Arc<UpstreamInstance>, key: Option<HashInput<'_>>, ) -> Option<Pick>

Pick an instance OTHER than exclude, to retry a failed forward on a different instance (ADR 000023). Same algorithm dispatch as pick; for maglev the affinity target is excluded, so it falls back to round-robin over the remaining eligible set.

pub fn has_eligible(&self) -> bool

Whether this upstream has at least one eligible instance (healthy and not outlier-ejected). A cursor-free, allocation-free probe the weighted traffic split (ADR 000034) uses to skip a backend whose group can serve nothing (renormalize over healthy). Same eligibility as the pick path minus the retry exclude; a false here means a pick would return None.

impl UpstreamGroup

pub fn record_outcome( &self, instance: &Arc<UpstreamInstance>, gateway_failure: bool, ) -> bool

Record one forward’s outcome against instance for outlier detection (ADR 000032). gateway_failure is true only for a gateway-class 5xx (502/503/504) the upstream actually RETURNED — never a circuit-breaker shed or a per-try timeout (those are other axes). Returns true iff this call ejected the instance (the caller bumps the ejection metric). A success resets the failure streak and ejection backoff; consecutive failures past the threshold eject the instance for a backing-off window — unless that would push the pool past max_ejection_percent, in which case it stays in rotation (fail-closed must not self-DoS).

impl UpstreamGroup

pub fn request_timeout(&self) -> Duration

The PER-TRY timeout the fast path applies to one forward attempt (ADR 000019, per-try by ADR 000031). Duration::ZERO means no per-try bound (e.g. a streaming / long-poll backend); otherwise one attempt is bounded and overrun fails closed 504.

pub fn overall_timeout(&self) -> Duration

The OVERALL request deadline across all attempts + backoff (ADR 000031); Duration::ZERO means no overall bound (only the per-try request_timeout applies). Exceeding it fails closed 504 request-timeout with no further retry.

pub fn max_retries(&self) -> u64

The max number of retries to a different instance on a retryable forward failure (ADR 000023); 0 disables retry.

pub fn hash_key_source(&self) -> Option<&HashKeySource>

The hash-key source for a maglev upstream (ADR 000035), or None for the other algorithms. The fast path reads this to project a HashInput from the request.

pub fn scheme(&self) -> &'static str

The scheme the fast path forwards (and health-probes) this upstream with (ADR 000042): https when [upstream.tls] is declared, else http.

pub fn tls_client_config(&self) -> Option<&Arc<ClientConfig>>

The rustls client config for this upstream’s TLS forward leg (ADR 000042), or None for plain HTTP/1.1. The Arc is stable across reloads while [upstream.tls] is unchanged, so the fast path can key its per-config connection pool on the Arc’s identity.

pub fn tls_sni(&self) -> Option<&ServerName<'static>>

The [upstream.tls] sni verification-name override (ADR 000050), or None when the fast path should derive the SNI / verification name from the connected address (the pre-000050 behaviour).

pub fn endpoints(&self) -> Arc<Endpoints>

A snapshot of the current endpoint set (instances + LB state). One atomic load; the returned Arc stays valid across a concurrent re-resolution swap.

pub fn resolve_interval(&self) -> Option<Duration>

How often the fast path should re-resolve this group’s hostname addresses, or None when re-resolution is off (the default).

pub fn configured_addresses(&self) -> &[(String, u32)]

The manifest-declared (address, weight) list — the re-resolution input.

pub fn update_endpoints(&self, resolved: &[(String, u32)]) -> bool

Replace the endpoint set with resolved (address, weight) pairs — the periodic-DNS endpoint-discovery swap. An unchanged pair keeps its instance Arc (health and in-flight state survive, exactly like a reload’s reconcile); a new pair starts pessimistic (ADR 000017 — a fresh address must prove itself before entering rotation); a vanished pair is dropped (in-flight requests finish on their cloned Arc). The LB state is recompiled (a Maglev table indexes the new set). Returns false (and swaps nothing) when the set is unchanged, so an idle refresh tick costs one atomic load and a compare.

Trait Implementations

impl Debug for UpstreamGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.