Skip to main content

Module pool

Module pool 

Source
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_connections and max_connections_per_host in 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_STREAMS advertisement 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:80 shares a limit with http://example.com because the default port for http is 80.
  • http://example.com and https://example.com are distinct origins and have independent per-origin limits.
  • http://example.com:8080 is a distinct origin from http://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.
PoolConfig
Configuration for the connection pool.
PoolGuard
RAII guard representing an acquired pool slot.
PoolMetrics
Observable metrics for the connection pool.