Struct UpstreamHandle 

pub struct UpstreamHandle { /* private fields */ }

A send-capable handle to one configured upstream: a dedicated pooled hyper client plus observability. Cheap to share via Arc from the UpstreamRegistry.

Implementations

impl UpstreamHandle

pub fn name(&self) -> &str

Upstream name this handle serves.

pub fn cap(&self) -> u32

Effective connection cap (explicit or default, minimum 1).

pub fn connect_timeout(&self) -> Duration

Effective connect timeout (explicit or default).

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

Effective happy-eyeballs delay (DW-030); None = racing disabled.

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

Per-attempt read timeout (timeouts.read_ms), if configured.

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

Response-body inactivity timeout (timeouts.write_ms), if configured.

pub fn retry_params(&self) -> &RetryParams

Resolved retry parameters (DW-014). attempts == 0 = retries off.

pub fn hedge_params(&self) -> &HedgeParams

Resolved hedge parameters (DW-063).

pub fn retry_budget(&self) -> &Arc<RetryBudget>

This upstream’s rolling-window retry budget (DW-014).

pub fn max_pending(&self) -> u32

Effective pending cap (DW-015); 0 = unbounded queueing.

pub fn breaker(&self) -> &Arc<Breaker>

This upstream’s circuit breaker state (DW-015). Always present; consult UpstreamHandle::breaker_params first — a None there means the breaker is disabled and the state object is dormant.

pub fn breaker_params(&self) -> Option<&BreakerParams>

Resolved breaker parameters (DW-015); None = breaker disabled.

pub fn connections_opened(&self) -> u64

Total connections established since the handle was built.

pub fn requests_sent(&self) -> u64

Total requests sent through the pool.

pub fn scheme(&self) -> &str

Effective scheme this upstream dials (“http” or “https”).

pub fn lb(&self) -> &Arc<UpstreamLb>

This upstream’s load balancer (endpoint set, algorithm, in-flight counters). Exposed for the TLS-passthrough path (which picks an endpoint the same way) and for tests.

pub fn hash_on(&self) -> Option<&HashOn>

DP-07 (#236): the hash-key source for this upstream’s consistent-hash load balancer (ip_hash or maglev). None means the client IP is used (the default).

pub fn set_locality_context(&self, ctx: LocalityContext)

DW-094 (Ent): set the edge’s locality context on this upstream’s load balancer. Called by the dataplane at startup to propagate the edge’s region/zone (from env vars or edge labels) to every upstream’s balancer.

pub fn tls_roots(&self) -> Option<&RootCertStore>

The trust roots this upstream’s TLS connections verify against (#121): None for plaintext http1 upstreams, the configured trusted_ca_file bundle when set, else the webpki public set. Active https health probes clone this so a probe and a proxied request can never disagree about who to trust.

pub fn h3_handle(&self) -> Option<&Arc<H3UpstreamHandle>>

DW-108: the H3/QUIC upstream transport, when this upstream is protocol: h3 AND the h3 cargo feature is enabled. The QUIC active health probe reuses its TLS client config (trust roots + h3 ALPN) so a probe and a proxied request trust the same roots. None for non-H3 upstreams or when the feature is off.

pub fn protocol(&self) -> UpstreamProtocol

The configured upstream protocol (DW-108). H3 selects the QUIC transport; the other variants use the TCP/TLS pooled client.

pub async fn send<B>( &self, req: Request<B>, ) -> Result<Response<UpstreamBody>, UpstreamError>

where B: Body<Data = Bytes> + Send + 'static, B::Error: Into<Box<dyn Error + Send + Sync>>,

Send a request through this upstream’s pool without a hash key (algorithms other than ip_hash ignore the key anyway).

pub async fn send_with_hash_key<B>( &self, req: Request<B>, hash_key: Option<&str>, ) -> Result<Response<UpstreamBody>, UpstreamError>

where B: Body<Data = Bytes> + Send + 'static, B::Error: Into<Box<dyn Error + Send + Sync>>,

Send a request through this upstream’s pool, dispatching via the upstream’s load balancer (DW-011). hash_key is the client IP as a string (used by ip_hash; ignored by the other algorithms). The picked endpoint’s address:port becomes both the dialed URI’s authority and the outbound Host header (replacing whatever the caller set); the path and query are preserved verbatim. The picked endpoint’s in-flight counter is held for the request/response-header exchange (documented approximation: released when headers resolve, not when the streaming body completes). The response body streams (wrapped in UpstreamBody for the DW-014 write-timeout / mid-body health reporting knobs; the wrapper is a frame-for-frame passthrough when both are unset), so proxying (DW-009) can forward it without buffering.

pub async fn send_with_hash_key_observed<B>( &self, req: Request<B>, hash_key: Option<&str>, picked: &mut Option<String>, ) -> Result<Response<UpstreamBody>, UpstreamError>

where B: Body<Data = Bytes> + Send + 'static, B::Error: Into<Box<dyn Error + Send + Sync>>,

UpstreamHandle::send_with_hash_key with observability (DW-021): the load-balancer pick runs under an upstream_pick span (child of the caller’s upstream_attempt span) and the picked endpoint’s address:port is written to picked when a dispatch resolved (left None on the NoEndpoints guard), so the proxy can attribute the attempt in its access log and the upstream_attempts_total metric.

Trait Implementations

impl Debug for UpstreamHandle

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

Formats the value using the given formatter.