Struct ConnectionPoolOptions 

#[non_exhaustive]
pub struct ConnectionPoolOptions {
    pub connection_idle_timeout: ConnectionIdleTimeout,
    pub max_connections: usize,
    pub multiple_pools: Option<(usize, PoolSelection)>,
    pub connection_lifetime: ConnectionLifetime,
}

Configuration options for HTTP connection pooling.

Controls connection pool behavior including connection lifetime and limits. Connection pooling improves performance by reusing established connections rather than creating new ones for each request.

Defaults

Option	Default
connection_idle_timeout	60 seconds
max_connections	usize::MAX (unlimited)
multiple_pools	None (single pool)
connection_lifetime	no maximum lifetime

Connection Handling

The connection pool automatically manages connection lifecycle and reuses established connections to improve performance. However, connections that end without proper graceful shutdown may result in the next request failing.

When such failures occur, the problematic connection is discarded and subsequent requests will establish a new healthy connection. The pool implements various strategies to minimize the impact of connection failures, but applications should be prepared to handle occasional connection-related errors through appropriate resilience mechanisms.

Server-Side Connection Closure

A server may decide to close the connection at any time, even when HTTP/2 keep-alive pings are being sent. Whether pings prevent server-side closure depends on the server implementation: some servers treat HTTP/2 pings as active traffic and reset their idle timers, while others ignore pings entirely and close the connection based on their own idle timeout policy.

For servers that do not treat HTTP/2 pings as active traffic, consider periodically sending real HTTP requests (e.g., lightweight health-check or no-op requests) to force the server to recognize the connection as active and keep it open.

Keep-Alive Pings

HTTP/2 keep-alive pings can be sent for both active and idle connections. This behavior is controlled by ConnectionKeepAlive:

• ConnectionKeepAlive::active_connections sends pings only on connections that are actively handling requests.
• ConnectionKeepAlive::active_and_idle_connections sends pings on all connections, including idle ones sitting in the pool.

Pool Idle Timeout

Independently of keep-alive pings, the underlying HTTP client (hyper) will close connections that have been idle in the pool for longer than the configured connection_idle_timeout. The default is 60 seconds. Pass None to keep connections in the pool indefinitely, relying solely on the server or keep-alive probes to determine when a connection is closed.

Connection Lifetime

Independently of idle eviction, connection_lifetime caps the total wall-clock age of a pooled connection. After serving a response, a connection older than the configured lifetime is dropped instead of being returned to the pool, forcing the next request to establish a fresh connection. This is useful for picking up DNS changes, load-balancer rotations, or refreshed credentials within a bounded window. By default no maximum lifetime is enforced.

For per-connection customization (e.g. adding jitter so that pools created via multiple_pools don’t all recycle at the same instant), use ConnectionLifetime::per_connection.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

connection_idle_timeout: ConnectionIdleTimeout

How long idle pooled connections are kept before eviction.

max_connections: usize

Maximum number of idle connections per host.

multiple_pools: Option<(usize, PoolSelection)>

Optional multi-pool configuration as (count, selection_strategy).

None means a single pool is used.

connection_lifetime: ConnectionLifetime

Maximum wall-clock lifetime policy for pooled connections.

Implementations

impl ConnectionPoolOptions

pub fn connection_idle_timeout( self, timeout: impl Into<Option<Duration>>, ) -> ConnectionPoolOptions

Caps how long an idle connection stays in the pool before being evicted.

Pass None to disable idle eviction (connections live until the server or a keep-alive probe closes them). Defaults to 60 seconds.

use std::time::Duration;

use fetch_options::ConnectionPoolOptions;

let options =
    ConnectionPoolOptions::default().connection_idle_timeout(Duration::from_secs(300));

pub fn max_connections(self, max: usize) -> ConnectionPoolOptions

Sets the maximum number of idle connections per host in the pool.

This controls how many idle connections can be kept open for each host. By default, this value is set to usize::MAX, meaning no limit on idle connections.

pub fn connection_lifetime( self, lifetime: ConnectionLifetime, ) -> ConnectionPoolOptions

Caps the total wall-clock lifetime of a pooled connection.

Unlike connection_idle_timeout (which only bounds idle time), this bounds the time since the connection was established. After serving a response, a connection older than the configured cap is dropped instead of being returned to the pool — useful for picking up DNS changes, load-balancer rotations, or refreshed credentials within a bounded window.

Use ConnectionLifetime::fixed for a constant cap, ConnectionLifetime::per_connection for per-connection customization (e.g. jitter), or ConnectionLifetime::unlimited (the default) to disable lifetime-based recycling.

use std::time::Duration;

use fetch_options::{ConnectionLifetime, ConnectionPoolOptions};

let options = ConnectionPoolOptions::default()
    .connection_lifetime(ConnectionLifetime::fixed(Duration::from_secs(300)));

pub fn multiple_pools( self, count: usize, selection: PoolSelection, ) -> ConnectionPoolOptions

Configures multiple connection pools for high-throughput scenarios.

This creates count separate connection pools and distributes requests across them according to the specified selection strategy.

Passing count <= 1 disables multi-pool routing (equivalent to None).

When to Use

For most scenarios, multiple pools are not needed. A single HTTP/2 connection can handle many concurrent requests efficiently through multiplexing.

Only enable multiple pools if you have measured and confirmed that your client is being throttled by a single HTTP/2 connection. This can happen in very high-throughput scenarios where the connection’s stream limit becomes a bottleneck.

Trait Implementations

impl Clone for ConnectionPoolOptions

fn clone(&self) -> ConnectionPoolOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConnectionPoolOptions

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

Formats the value using the given formatter.

impl Default for ConnectionPoolOptions

fn default() -> ConnectionPoolOptions

Returns the “default value” for a type.