Expand description
Connection pool subsystem.
Provides slot-based concurrency limiting for HTTP connections, both globally and per-origin. Actual connection reuse is handled by hyper; this module controls how many concurrent requests may be in flight.
§Concurrency model
eggfetch’s pool enforces logical request concurrency — the number of concurrent requests the application may have in flight. This is distinct from physical connection counts and, under HTTP/2, from per-connection stream concurrency:
-
Logical request concurrency: Controlled by
max_connectionsandmax_connections_per_hostin this pool. A single semaphore permit corresponds to one logical request. -
Physical connection count: Owned by hyper’s internal connection pool. eggfetch cannot observe or control this directly. Under HTTP/1.1, one connection carries one request at a time. Under HTTP/2, one connection carries many multiplexed streams.
-
Per-origin HTTP/2 stream concurrency: hyper/h2 respects the server’s
SETTINGS_MAX_CONCURRENT_STREAMSadvertisement and its own internal limits. eggfetch does not expose or override these. The logical request limit acts as an upper bound on concurrent streams because each in-flight request holds a pool permit. -
Per-connection stream limit: The h2 library enforces a default of 100 concurrent streams per connection, or whatever the server advertises via
SETTINGS_MAX_CONCURRENT_STREAMS. This is transparent to eggfetch — hyper handles stream multiplexing within a connection automatically.
Under HTTP/2, multiple logical requests may share a single TCP connection (multiplexed streams). The pool’s per-origin limit still applies: it bounds the number of concurrent requests, not the number of connections. If the h2 connection’s stream limit is reached, hyper internally queues streams until a slot opens, which may cause pool acquisition to wait.
§HTTP/3 and QUIC
When the http3 feature is enabled and HttpVersionPolicy::Http3Only
is selected, requests bypass the hyper transport and are sent over QUIC
via Quinn. These requests still acquire pool permits for concurrency
limiting, but the underlying QUIC connection lifecycle is managed
independently by the H3 connector.
- Logical request concurrency: Same as HTTP/1.1 and HTTP/2 — one pool permit per in-flight request.
- QUIC connection caching: The H3 connector maintains a per-origin cache of QUIC connections. Idle connections are reused for subsequent requests to the same origin.
- Per-connection stream concurrency: Quinn enforces a maximum of 100 concurrent bidirectional streams per QUIC connection by default. This is independent of the pool’s logical permit limit.
§Origin keying
Per-origin limits are keyed by (scheme, host, port), where the port
uses the scheme’s default if not explicitly provided:
http://example.com:80shares a limit withhttp://example.combecause the default port forhttpis 80.http://example.comandhttps://example.comare distinct origins and have independent per-origin limits.http://example.com:8080is a distinct origin fromhttp://example.com.
When a proxy is involved, the pool key extends to
(proxy_origin, destination_origin, tunnel_mode). This means:
- Direct and proxied requests to the same destination have independent concurrency slots.
- Different proxies sharing the same destination get independent slots.
- HTTP forwarding and HTTPS CONNECT tunneling through the same proxy are keyed separately.
Structs§
- Pool
- Connection pool that limits concurrent requests.
- Pool
Config - Configuration for the connection pool.
- Pool
Guard - RAII guard representing an acquired pool slot.
- Pool
Metrics - Observable metrics for the connection pool.