pingora-pool

Active contributors: davis, ewang, andrew

Purpose

Generic, async-aware connection pool. Used by the HTTP connector in pingora-core to keep upstream TCP/TLS connections alive between requests. Tracks idle connections, reaps stale ones, and counts unexpected-data events that signal a broken upstream.

Directory layout

pingora-pool/src/
├── lib.rs               ConnectionPool — top-level pool API
├── connection.rs        ConnectionMeta, idle tracking, the actual pool storage
└── lru.rs               Sharded LRU used internally

Key abstractions

Type	File	What it is
ConnectionPool	pingora-pool/src/lib.rs	The pool, generic over the connection ID and value
ConnectionMeta	pingora-pool/src/connection.rs	Per-connection metadata (group, last used)
Group	pingora-pool/src/connection.rs	A pool of connections sharing a peer key

How it works

graph TD
    proxy[Proxy needs upstream connection]
    pool[ConnectionPool::get<br/>by peer key]
    found{In pool?}
    fresh[Open new TCP/TLS]
    use[Use connection]
    idle[ConnectionPool::release]
    reap[Background reaper]

    proxy --> pool --> found
    found -->|yes| use
    found -->|no| fresh --> use
    use --> idle --> reap
    reap -->|stale| close[Close]
    reap -->|fresh| pool

A connection is registered with the pool with a peer hash (the key for that backend's group) and a uniqueness token. When checked out, the pool returns the most recently released matching connection. Idle connections are reaped in a background task on a configurable timeout.

The unexpected data counter (added in ea9d9ec, Mar 2026) is bumped when the pool checks an idle connection and finds the socket has bytes that shouldn't be there — usually a broken h2 stream or a confused upstream. Watch this in production via the Prometheus integration.

The "max reuse count" (added in 0.8.0) caps how many times a single downstream connection can be reused, useful for forcing periodic reconnection to refresh balancing decisions or pick up new TLS settings.

Integration points

• Consumed by pingora-core/src/connectors/http/ (HTTP connector).
• Also used internally by HTTP/2's stream pool.

Entry points for modification

• Connection metadata fields → connection.rs.
• Custom reaping logic → connection.rs. The current reaper is straightforward time-based.
• New per-pool metrics → expose accessors on ConnectionPool, then wire them into the metrics layer in the user's binary.

Key source files

File	Purpose
pingora-pool/src/lib.rs	Public ConnectionPool API
pingora-pool/src/connection.rs	Pool storage, group bookkeeping, unexpected-data counter
pingora-pool/src/lru.rs	Sharded LRU used by the pool