Struct Upstream 

pub struct Upstream {

    pub name: String,
    pub load_balancer: LoadBalancer,
    pub hash_on: Option<HashOn>,
    pub protocol: UpstreamProtocol,
    pub trusted_ca_file: Option<String>,
    pub use_system_roots: bool,
    pub endpoints: Vec<Endpoint>,
    pub connection_cap: Option<u32>,
    pub slow_start_ms: Option<u64>,
    pub health: Option<PassiveHealth>,
    pub active_health: Option<ActiveHealth>,
    pub retries: Option<RetryConfig>,
    pub breaker: Option<BreakerConfig>,
    pub max_pending: Option<u32>,
    pub timeouts: Option<Timeouts>,
    pub oauth2_client_credentials: Option<OAuth2ClientCredentials>,
    pub dns_discovery: Option<DnsDiscovery>,
    pub peak_ewma: Option<PeakEwmaConfig>,
    pub locality: Option<UpstreamLocality>,
    pub pq: bool,
    pub cert_pinning: Option<CertPinningConfig>,
    pub mtls: Option<UpstreamMtls>,
    pub pool: Option<UpstreamPoolConfig>,
}

Load-balancing pool: algorithm, protocol, endpoints.

Fields

name: String

load_balancer: LoadBalancer

hash_on: Option<HashOn>

DP-07 (#236): what to hash for consistent-hash load balancers (ip_hash and maglev). Defaults to client_ip (the pre-#236 behavior). When set to cookie or header, the gateway extracts the value from the request and uses it as the hash key; if the cookie/header is absent, it falls back to the client IP.

protocol: UpstreamProtocol

Protocol used toward upstream endpoints.

trusted_ca_file: Option<String>

Path to a PEM file of CA certificates this upstream’s TLS connections trust INSTEAD of the default public (webpki) root set (#121): the way to proxy an https/http2 upstream whose server certificate chains to a private CA. The file may carry several certificates (a typical CA bundle). Only meaningful for the TLS protocols — no TLS is negotiated toward http1 endpoints, so validation rejects that combination. Active http health probes for this upstream verify against the same roots. The file must exist and be readable at config compile time; validation names this field otherwise.

use_system_roots: bool

REL-08 (#219): when true, the upstream’s TLS connections trust the OS-native root CA store (loaded via rustls-native-certs) INSTEAD of the bundled webpki root set. Useful in deployments whose private CAs are provisioned through the host’s trust store (e.g. corporate PKI, cloud metadata CAs). Mutually exclusive with trusted_ca_file (validation rejects a configuration that sets both). Only meaningful for the TLS protocols (https/http2/h3) — no TLS is negotiated toward http1 endpoints, so validation rejects that combination. Active health probes for this upstream verify against the same roots. Defaults to false (webpki roots).

endpoints: Vec<Endpoint>

Static endpoint list for this upstream. When dns_discovery is present, this becomes the initial/fallback set (used until the first DNS resolution completes and as a fallback when DNS fails and fail_open is true); it may be empty. When dns_discovery is absent, this is the complete endpoint set and must be non-empty (validation rejects an empty list).

connection_cap: Option<u32>

Maximum number of concurrent outbound connections to this upstream (active plus pooled idle). Defaults to 256 when absent. Enforced by the upstream client (DW-008); excess connection attempts wait for a slot rather than fail. Raised from 64 to 256 (#270) to avoid unbounded memory growth under high concurrency.

slow_start_ms: Option<u64>

Slow-start window in milliseconds (DW-011): an endpoint entering the upstream’s set ramps its effective load-balancing weight from ~0 up to its configured weight over this window. Absent (or 0) disables the ramp. Applies to the weighted algorithms (round_robin; ip_hash vnode counts stay fixed so ring consistency is preserved). Validation bounds the value to at most 10 minutes.

health: Option<PassiveHealth>

Passive health checking / outlier detection (DW-012): eject endpoints that fail real traffic (transport errors and 5xx), let them back via half-open trial probes after eject_ms. Absent disables passive health entirely (no ejections).

active_health: Option<ActiveHealth>

Active health checks (DW-013): synthetic HTTP/TCP probes per endpoint on a fixed interval with full jitter. Probe results report into the SAME per-endpoint ejection machinery as passive health, so an endpoint failing its probes leaves load-balancer rotation and a success streak returns it. Requires the passive health block (which owns the ejection/recovery windows); rejected by validation otherwise. Absent disables active probing.

retries: Option<RetryConfig>

Upstream retries (DW-014): bounded per-request retry attempts with exponential backoff + full jitter, a retry budget, and opt-in size-capped request-body buffering. Absent (or attempts left at its default 0) disables retries entirely: every request gets exactly one attempt and the proxy path keeps its zero-copy streaming body.

breaker: Option<BreakerConfig>

Per-upstream circuit breaker (DW-015): opens the WHOLE upstream on consecutive failures or a rolling error ratio, fails fast with 503 while open, probes half-open after breaker.open_ms. Absent disables the breaker entirely (no fail-fast, behavior identical to pre-DW-015).

max_pending: Option<u32>

Maximum number of requests WAITING for an outbound connection slot to this upstream (DW-015). 0/absent (the default) means a bounded queue of 256 — the default bounds memory under high concurrency (#270). A positive value rejects excess requests IMMEDIATELY with 503 “upstream saturated” instead of letting them wait. To restore the pre-#270 unbounded queueing behavior, set a very large value.

timeouts: Option<Timeouts>

oauth2_client_credentials: Option<OAuth2ClientCredentials>

OAuth2 client-credentials proxying (DW-035): the gateway acts as an OAuth2 client itself, obtaining an access token from an external token endpoint via the client-credentials flow and forwarding it to this upstream as a Bearer token (replacing any client-supplied Authorization header). For service-to- service calls where the gateway authenticates to the upstream with a token it obtains from an OAuth2 token endpoint. Absent (the default): no token acquisition; the upstream sees whatever Authorization the client sent (subject to the authn family’s pass-through rules). See the security::oauth2 module docs for the flow, caching, and the mTLS-to-the-token-endpoint option.

dns_discovery: Option<DnsDiscovery>

DNS-based dynamic upstream discovery (DW-042): when present, a background task resolves hostname via DNS and updates the endpoint set live as records change. The endpoints field becomes the initial/fallback set. Absent (the default): endpoints remain static (the current behavior — no change).

peak_ewma: Option<PeakEwmaConfig>

Peak-EWMA tuning (DW-090): only meaningful when load_balancer: peak_ewma. Absent (the default) uses the built-in defaults (10 s decay tau, 250 ms initial cost). Ignored for the other algorithms.

locality: Option<UpstreamLocality>

DW-094 (Ent): locality-aware routing and data residency. When present, the balancer filters or prefers endpoints by region/zone before applying the configured load_balancer algorithm. Ent-only: rejected at validation when the ent cargo feature is off.

pq: bool

DW-105: opt in to post-quantum hybrid key exchange (X25519+ML-KEM) for this upstream’s TLS connections. When true, the X25519+ML-KEM hybrid kx group is prepended to the rustls client config’s kx group list, PREFERRING the hybrid group while keeping the classical X25519 fallback for non-PQ upstreams. Compiled into every build (no cargo feature). EXPERIMENTAL: the rustls PQ API is not yet stable. Only meaningful for the TLS protocols (https, http2); validation rejects pq: true on an http1 upstream (no TLS is negotiated). Rejected when combined with FIPS mode (ML-KEM is not on the FIPS-validated list for aws-lc-rs).

cert_pinning: Option<CertPinningConfig>

DW-109 / SEC-04: upstream TLS certificate pinning by SPKI SHA-256 hash. When present, the gateway’s outbound TLS client installs a custom certificate verifier that extracts the peer cert’s SubjectPublicKeyInfo, computes its SHA-256, and compares against the configured pins. A mismatch rejects the connection (fail-closed: no fallback to CA-based verification). Compiled into every build (no cargo feature). Only meaningful for the TLS protocols (https, http2); validation rejects it on an http1 upstream.

mtls: Option<UpstreamMtls>

SEC-03: upstream mTLS client certificates. When present, the gateway presents this client certificate to the upstream during the TLS handshake (in addition to verifying the upstream’s server cert against trusted_ca_file or the public roots). Required for upstreams that demand client authentication (banking/payment APIs, mesh-internal services). Only meaningful for the TLS protocols (https, http2); validation rejects it on an http1 upstream.

pool: Option<UpstreamPoolConfig>

DP-03: hyper connection-pool and HTTP/2 tuning for this upstream’s outbound client. Absent (the default): every knob falls back to hyper-util’s built-in defaults (the prior behavior — only the pool timer was wired). When present, the configured knobs are applied to the per-upstream hyper-util legacy client builder; omitted sub-fields keep their hyper defaults. The pool timer is ALWAYS installed (it is required for idle-timeout eviction to fire), so this block only needs to carry the knobs an operator wants to change. Meaningful for every protocol: http1/https connections reuse the pool’s idle-timeout and max-idle-per-host knobs, while http2 connections additionally honor the keep-alive and concurrent-streams knobs.

Trait Implementations

impl Clone for Upstream

fn clone(&self) -> Upstream

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Upstream

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Upstream

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for Upstream

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl PartialEq for Upstream

fn eq(&self, other: &Upstream) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Upstream

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Upstream