Struct UpstreamRegistry 

pub struct UpstreamRegistry { /* private fields */ }

Registry of per-upstream pooled clients, built from one published snapshot. Rebuild (and drop the old registry) on snapshot swap; in-flight requests keep their old pools until their handles are dropped.

Implementations

impl UpstreamRegistry

pub fn from_snapshot(snapshot: &Snapshot) -> Self

Build from a snapshot, verifying upstream TLS certificates against the Mozilla webpki root set — except upstreams that configure trusted_ca_file, which verify against their own bundle (#121).

pub fn from_snapshot_with_previous( snapshot: &Snapshot, previous: &UpstreamRegistry, ) -> Self

Build from a snapshot, carrying over per-upstream load-balancer state from previous (in-flight counters, WRR phase, slow-start clocks for unchanged endpoint addresses). This is the reload path: weight and endpoint changes take effect without a restart, and in-flight requests holding old handles are unaffected.

pub fn from_snapshot_with_events( snapshot: &Snapshot, events: Option<&Emitter>, ) -> Self

from_snapshot with the dataplane’s event emitter attached (DW-044): breaker transitions and endpoint ejection/recovery in this registry’s state machines emit onto the bus. Distinct constructors rather than a changed signature so the many event-agnostic call sites (tests, tooling) stay untouched.

pub fn from_snapshot_with_previous_and_events( snapshot: &Snapshot, previous: &UpstreamRegistry, events: Option<&Emitter>, ) -> Self

from_snapshot_with_previous with the dataplane’s event emitter attached (DW-044); the dataplane’s reload path.

pub fn with_root_certificates( snapshot: &Snapshot, extra_roots: &[CertificateDer<'_>], ) -> Result<Self, UpstreamError>

Build from a snapshot with EXTRA trusted root certificates (e.g. a private CA signing upstream certificates), added on top of the webpki roots. Fails if any extra root is malformed, so operators see the bad certificate at registry build time rather than as a mysterious handshake failure later.

pub fn with_root_certificates_and_previous( snapshot: &Snapshot, extra_roots: &[CertificateDer<'_>], previous: Option<&UpstreamRegistry>, ) -> Result<Self, UpstreamError>

with_root_certificates with optional balancer-state carry-over from a previous registry build (see UpstreamRegistry::from_snapshot_with_previous).

Per-upstream trusted_ca_file (#121): when set, that upstream’s connector trusts the file’s bundle INSTEAD of the webpki+extras store — a private-CA upstream must not implicitly keep public-root trust. Config-driven bundles that fail to load at build time do NOT fail the build (the config was file-validated at publish, so this is a torn state — the bundle was replaced/unlinked underneath the gateway); the upstream FAILS CLOSED with an empty root store and a loud error log, so no traffic is ever sent under trust the operator did not configure. Programmatic extra_roots keep the immediate-Err contract above.

pub fn with_root_certificates_previous_and_events( snapshot: &Snapshot, extra_roots: &[CertificateDer<'_>], previous: Option<&UpstreamRegistry>, events: Option<&Emitter>, ) -> Result<Self, UpstreamError>

with_root_certificates_and_previous with the dataplane’s event emitter (DW-044); the single build path behind every constructor.

pub fn split_for(&self, service: &str) -> Option<Arc<ServiceSplit>>

The compiled split for a service (DW-040), when it has one.

pub fn get(&self, name: &str) -> Option<Arc<UpstreamHandle>>

Handle for the named upstream, or None if the snapshot has no such upstream.

pub fn names(&self) -> Vec<&str>

Names of all upstreams in this registry.

pub fn set_locality_context(&self, ctx: LocalityContext)

DW-094 (Ent): set the edge’s locality context on every upstream’s load balancer in this registry. Called by the dataplane at startup and on refresh to propagate the edge’s region/zone.

pub fn with_rebuilt_split_from_pairs( &self, service: &str, pairs: &[(String, u64)], ) -> Option<UpstreamRegistry>

DW-091: rebuild the split for service from explicit (upstream_name, weight) pairs. Returns a new registry with the replacement split; the handles are shared (Arc bump). The total weight MUST stay constant (the caller enforces this); changing the total would reshuffle every session’s branch (the DW-040 invariant).

pub fn pre_warm(&self)

SCALE-10 (#189): pre-warm connection pools for upstreams that configure pool.pre_warm. For each upstream with a non-zero pre_warm value, spawns a background task that sends lightweight HEAD requests to each endpoint to establish pre_warm connections in the pool. This removes cold-start latency spikes after reloads and upgrade hand-offs. Failures are logged and silently ignored (pre-warming is best-effort; a failed pre-warm does not affect the upstream’s availability).

Trait Implementations

impl Default for UpstreamRegistry

fn default() -> UpstreamRegistry

Returns the “default value” for a type.