Struct UpstreamPool 

pub struct UpstreamPool { /* private fields */ }

Upstream pool managing multiple backend servers

Implementations

impl UpstreamPool

pub async fn new(config: UpstreamConfig) -> ZentinelResult<Self>

Create new upstream pool from configuration

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

How often this pool’s discovery source should be re-resolved, if at all.

pub async fn refreshed(&self) -> Option<UpstreamPool>

Re-resolve discovery and, when the target set has changed, build the pool that should replace this one.

Returns None when there is nothing to do — no discovery source, the source failed, or it resolved to the same targets the pool already has. Callers install the returned pool in place of this one; the two share their circuit breakers and statistics, so a backend that was failing before the refresh is still failing after it.

Errors

Never fails: a discovery source that cannot be reached leaves the pool serving its current targets rather than emptying it.

pub async fn select_peer_with_metadata( &self, context: Option<&RequestContext>, ) -> ZentinelResult<(HttpPeer, HashMap<String, String>)>

Select next upstream peer with selection metadata

Returns the selected peer along with optional metadata from the load balancer. The metadata can contain sticky session information that should be passed to the response filter.

pub async fn select_peer( &self, context: Option<&RequestContext>, ) -> ZentinelResult<HttpPeer>

Select next upstream peer

pub async fn report_result(&self, target: &str, success: bool)

Report connection result for a target

On failure, the circuit breaker records the failure but the load balancer health status is only updated when the circuit breaker transitions to Open. This prevents a single connection error (e.g., a stale pooled connection reset) from permanently removing a target from the healthy pool.

pub async fn report_result_with_latency( &self, target: &str, success: bool, latency: Option<Duration>, )

Report request result with latency for adaptive load balancing

This method passes latency information to the load balancer for adaptive weight adjustment. It updates circuit breakers and health status. On failure, health is only marked down when the circuit breaker transitions to Open, preventing stale connection resets from permanently removing targets.

pub fn stats(&self) -> &PoolStats

Get pool statistics

pub fn id(&self) -> &UpstreamId

Get pool ID

pub async fn circuit_breaker_state( &self, target: &str, ) -> Option<CircuitBreakerState>

Get target count Circuit-breaker state for a target, or None when the pool has no breaker for that address — which for a discovery-backed pool means the target is not currently in the resolved set.

pub fn sticky_signing_key(&self) -> Option<[u8; 32]>

The key used to sign sticky-session affinity cookies, when this upstream uses sticky load balancing.

Exposed so tests can assert it survives a pool rebuild; rotating it would invalidate every cookie already issued.

pub fn target_addresses(&self) -> Vec<String>

Addresses of the pool’s current targets, in selection order.

pub fn target_count(&self) -> usize

pub fn pool_config(&self) -> PoolConfigSnapshot

Get pool configuration (for metrics/debugging)

pub async fn has_healthy_targets(&self) -> bool

Check if the pool has any healthy targets.

Returns true if at least one target is healthy, false if all targets are unhealthy.

pub async fn select_shadow_target( &self, context: Option<&RequestContext>, ) -> ZentinelResult<ShadowTarget>

Select a target for shadow traffic (returns URL components)

This is a simplified selection method for shadow requests that don’t need full HttpPeer setup. Returns the target URL scheme, address, and port.

pub fn is_tls_enabled(&self) -> bool

Check if TLS is enabled for this upstream

pub fn active_request_count(&self) -> u64

Get the number of currently active (in-flight) requests for this pool.

Used by the drain tracker to determine when a pool has been fully drained after removal from config.

pub fn increment_active(&self)

Increment the active request counter. Called when a request is assigned to this pool.

pub fn decrement_active(&self)

Decrement the active request counter. Called when a request completes (success or failure).

pub async fn shutdown(&self)

Shutdown the pool

Note: Pingora manages connection pooling internally, so we just log stats.