Skip to main content

matier_pool/
lib.rs

1//! `matier-pool`: per-origin connection pooling for Matier (PLAN ยง6).
2//!
3//! * **Origin map**: a [`papaya`] lock-free hash map `OriginKey -> Arc<OriginPool>`. Lookups are
4//!   read-mostly (one insert per origin ever), papaya reads take no lock and never write shared
5//!   cache lines beyond the epoch guard, and the lookup is allocation-free (borrowed key, FxHash).
6//! * **HTTP/1**: LIFO idle stack behind a short `parking_lot::Mutex` (push/pop only, never held
7//!   across an await), a connection count, and a FIFO waiter queue (slab-backed linked list, O(1)
8//!   cancel) with direct handoff of released connections (or of a freed dial slot) to the oldest
9//!   waiter. The liveness probe runs at checkout; the idle timeout is checked lazily.
10//! * **HTTP/2**: an `arc_swap` snapshot of handles, power-of-two-choices on `in_flight`,
11//!   `try_reserve`, coalesced background dials, and zero-config load-based autoscaling ([`scale`]).
12//!
13//! The protocol of an origin is learned from the first connection (ALPN / prior knowledge) and
14//! cached; concurrent first requests wait for that one connection instead of dialing in parallel.
15
16mod origin;
17pub mod scale;
18mod waiters;
19
20use std::borrow::Borrow;
21use std::future::Future;
22use std::hash::{BuildHasherDefault, Hash, Hasher};
23use std::sync::Arc;
24use std::time::Duration;
25
26use futures_util::future::Either;
27use matier_core::{Body, Error, ErrorKind, Observer, OriginKey, Protocol, Result, Scheme};
28use matier_transport::h1::{H1Config, Release};
29use matier_transport::h2::H2Config;
30use matier_transport::{ConnectConfig, Incoming};
31use rustc_hash::FxHasher;
32
33use origin::{Lease, OriginPool};
34
35/// Pool limits and timeouts.
36#[derive(Clone, Debug)]
37pub struct PoolConfig {
38    /// Idle HTTP/1 connections kept per origin (default 256, the same as `max_conns_per_origin`, so a burst
39    /// does not close connections it will want again; `idle_timeout` closes the unused ones). Each idle
40    /// connection holds a file descriptor: lower this for clients that talk to many origins.
41    pub max_idle_per_origin: usize,
42    /// Idle HTTP/1 connections older than this are discarded at checkout, and HTTP/2 connections without
43    /// streams for this long are closed (default 90 s).
44    pub idle_timeout: Duration,
45    /// Connections are retired once they are this old, so traffic follows DNS and load-balancer changes
46    /// (default `None`: no limit). HTTP/1 connections are closed when they are next returned or checked out;
47    /// an HTTP/2 connection stops taking new streams after its replacement is up and closes once its
48    /// in-flight requests finish.
49    pub max_connection_lifetime: Option<Duration>,
50    /// HTTP/1: maximum connections (in use + idle + dialing) per origin (default 256).
51    pub max_conns_per_origin: usize,
52    /// Streams per HTTP/2 connection (default 128, or less when the server's `MAX_CONCURRENT_STREAMS` is lower).
53    /// Requests beyond it go to another connection, which the pool dials if needed.
54    pub h2_target_streams_per_conn: usize,
55    /// HTTP/2 connections kept per origin: dialed eagerly once the origin is known to speak h2 and never
56    /// scaled below (default 1). Leave it alone: the pool adds connections under load by itself.
57    pub h2_min_conns_per_origin: usize,
58    /// HTTP/2 autoscaling ceiling per origin (default: `std::thread::available_parallelism()`; one
59    /// connection is one actor task, so more connections than cores cannot add parallelism). Autoscaling
60    /// also stays within the tokio runtime's worker count (unless `h2_min_conns_per_origin` is higher). Set equal to
61    /// `h2_min_conns_per_origin` to pin the connection count. Replacing a connection past
62    /// `max_connection_lifetime` may exceed it by one for a moment. See [`scale`] for the policy.
63    pub h2_max_conns_per_origin: usize,
64    /// HTTP/2 scale-up thresholds (defaults: the constants in [`scale`]).
65    pub h2_scale: scale::ScaleThresholds,
66    /// Maximum time a request waits for a connection or stream slot (default 30 s; `None` waits forever).
67    /// Failure is `PoolTimeout` with `Recovery::Unprocessed`.
68    pub checkout_timeout: Option<Duration>,
69    /// An HTTP/2 connection whose peer advertises `SETTINGS_MAX_CONCURRENT_STREAMS = 0` is retired after
70    /// this long (default 10 s). Such a connection never counts as capacity and never triggers scale-up.
71    pub h2_zero_capacity_drain: Duration,
72}
73
74impl Default for PoolConfig {
75    fn default() -> Self {
76        Self {
77            max_idle_per_origin: 256,
78            idle_timeout: Duration::from_secs(90),
79            max_connection_lifetime: None,
80            max_conns_per_origin: 256,
81            h2_target_streams_per_conn: 128,
82            h2_min_conns_per_origin: 1,
83            h2_max_conns_per_origin: scale::default_h2_max_conns(),
84            h2_scale: scale::ScaleThresholds::default(),
85            checkout_timeout: Some(Duration::from_secs(30)),
86            h2_zero_capacity_drain: Duration::from_secs(10),
87        }
88    }
89}
90
91pub(crate) struct Shared {
92    pub(crate) cfg: PoolConfig,
93    pub(crate) connect: ConnectConfig,
94    pub(crate) h1: Arc<H1Config>,
95    pub(crate) h2: H2Config,
96    pub(crate) obs: Arc<dyn Observer>,
97}
98
99/// Snapshot of one origin's pool, for diagnostics and tests.
100#[derive(Clone, Debug, Default, PartialEq, Eq)]
101pub struct OriginStats {
102    /// Learned protocol (`None` until the first connection).
103    pub protocol: Option<Protocol>,
104    /// HTTP/1: connections in use + idle + dialing.
105    pub h1_total: usize,
106    /// HTTP/1: idle connections.
107    pub h1_idle: usize,
108    /// HTTP/1: queued waiters.
109    pub h1_waiters: usize,
110    /// HTTP/2: live connections (including draining ones).
111    pub h2_conns: usize,
112    /// HTTP/2: connections marked draining (not selectable; closing once idle).
113    pub h2_draining: usize,
114}
115
116// --- allocation-free map lookup ---------------------------------------------------------------
117
118trait KeyParts {
119    fn parts(&self) -> (Scheme, &str, u16);
120}
121struct Key(OriginKey);
122impl KeyParts for Key {
123    fn parts(&self) -> (Scheme, &str, u16) {
124        (self.0.scheme, &self.0.host, self.0.port)
125    }
126}
127struct Probe<'a>(Scheme, &'a str, u16);
128impl KeyParts for Probe<'_> {
129    fn parts(&self) -> (Scheme, &str, u16) {
130        (self.0, self.1, self.2)
131    }
132}
133impl<'a> Borrow<dyn KeyParts + 'a> for Key {
134    fn borrow(&self) -> &(dyn KeyParts + 'a) {
135        self
136    }
137}
138impl Hash for dyn KeyParts + '_ {
139    fn hash<H: Hasher>(&self, state: &mut H) {
140        let (s, h, p) = self.parts();
141        (s as u8).hash(state);
142        h.hash(state);
143        p.hash(state);
144    }
145}
146impl PartialEq for dyn KeyParts + '_ {
147    fn eq(&self, other: &Self) -> bool {
148        self.parts() == other.parts()
149    }
150}
151impl Eq for dyn KeyParts + '_ {}
152impl Hash for Key {
153    fn hash<H: Hasher>(&self, state: &mut H) {
154        <dyn KeyParts as Hash>::hash(self, state);
155    }
156}
157impl PartialEq for Key {
158    fn eq(&self, other: &Self) -> bool {
159        self.parts() == other.parts()
160    }
161}
162impl Eq for Key {}
163
164struct PoolInner {
165    map: papaya::HashMap<Key, Arc<OriginPool>, BuildHasherDefault<FxHasher>>,
166    shared: Arc<Shared>,
167}
168
169type MapGuard<'g> = papaya::HashMapRef<
170    'g,
171    Key,
172    Arc<OriginPool>,
173    BuildHasherDefault<FxHasher>,
174    papaya::LocalGuard<'g>,
175>;
176
177impl PoolInner {
178    /// Allocation-free lookup of an existing origin; `None` for anything unusual or unknown.
179    fn lookup<'g>(&self, map: &'g MapGuard<'g>, uri: &http::Uri) -> Option<&'g Arc<OriginPool>> {
180        let (scheme, host) = (uri.scheme_str()?, uri.host()?);
181        let sch = if scheme.eq_ignore_ascii_case("http") {
182            Scheme::Http
183        } else if scheme.eq_ignore_ascii_case("https") {
184            Scheme::Https
185        } else {
186            return None;
187        };
188        if host.bytes().any(|b| b.is_ascii_uppercase()) {
189            return None;
190        }
191        let port = uri.port_u16().unwrap_or_else(|| sch.default_port());
192        let probe = Probe(sch, host, port);
193        map.get(&probe as &dyn KeyParts)
194    }
195
196    fn origin_pool(&self, uri: &http::Uri) -> Result<Arc<OriginPool>> {
197        let map = self.map.pin();
198        // Fast path: no allocation. Falls back to the full (allocating) parse for anything unusual.
199        if let Some(p) = self.lookup(&map, uri) {
200            return Ok(Arc::clone(p));
201        }
202        let key = Key(OriginKey::from_uri(uri)?);
203        if let Some(p) = map.get(&key as &dyn KeyParts) {
204            return Ok(Arc::clone(p));
205        }
206        let created = OriginPool::new(key.0.clone(), Arc::clone(&self.shared));
207        let p = map.get_or_insert(key, created);
208        Ok(Arc::clone(p))
209    }
210}
211
212/// The connection pool. Cheap to clone.
213#[derive(Clone)]
214pub struct Pool {
215    inner: Arc<PoolInner>,
216}
217
218impl std::fmt::Debug for Pool {
219    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
220        f.debug_struct("Pool").finish_non_exhaustive()
221    }
222}
223
224impl Pool {
225    /// Creates an empty pool.
226    #[must_use]
227    pub fn new(
228        cfg: PoolConfig,
229        connect: ConnectConfig,
230        h1: H1Config,
231        h2: H2Config,
232        obs: Arc<dyn Observer>,
233    ) -> Self {
234        Self {
235            inner: Arc::new(PoolInner {
236                map: papaya::HashMap::with_hasher(BuildHasherDefault::default()),
237                shared: Arc::new(Shared {
238                    cfg,
239                    connect,
240                    h1: Arc::new(h1),
241                    h2,
242                    obs,
243                }),
244            }),
245        }
246    }
247
248    /// Sends `req` on a pooled connection (dialing if needed) and returns the response once its
249    /// head is available. The returned body returns the connection to the pool when it completes.
250    ///
251    /// A request that fails on a reused HTTP/1 connection before any response byte (stale
252    /// keep-alive race) or with `Recovery::Unprocessed` is retried once on a fresh connection if
253    /// its body is replayable (`Empty`/`Full`) and the method is idempotent (or the error is
254    /// `Unprocessed`).
255    ///
256    /// # Errors
257    /// Any transport/protocol error, `PoolTimeout` after `checkout_timeout`, `InvalidRequest` for
258    /// an unusable URI.
259    pub fn send(
260        &self,
261        req: http::Request<Body>,
262    ) -> impl Future<Output = Result<http::Response<Incoming>>> + Send + use<> {
263        // HTTP/2 fastest path: borrow the origin and the connection from the map/snapshot guards (no
264        // `Arc<OriginPool>` or handle clone) and hand the request straight to the actor.
265        {
266            let map = self.inner.map.pin();
267            if let Some(op) = self.inner.lookup(&map, req.uri())
268                && op.is_h2()
269            {
270                let snap = op.h2_snapshot();
271                if let Some((handle, slot)) = op.h2_pick_in(&snap) {
272                    return Either::Right(Either::Left(handle.send(slot, req)));
273                }
274            }
275        }
276        let op = match self.inner.origin_pool(req.uri()) {
277            Ok(op) => op,
278            Err(e) => return Either::Left(std::future::ready(Err(e))),
279        };
280        // HTTP/2 hot path: the lease is taken synchronously and the request is moved into the actor's
281        // inbox immediately; the returned `ResponseFuture` is a small `'static` future (no Box).
282        match op.try_fast(false) {
283            Some(Lease::H2(handle, slot)) => Either::Right(Either::Left(handle.send(slot, req))),
284            lease => Either::Right(Either::Right(send_on(op, req, lease))),
285        }
286    }
287
288    /// Diagnostics for the origin of `uri`.
289    #[must_use]
290    pub fn stats(&self, uri: &http::Uri) -> Option<OriginStats> {
291        let p = self.inner.origin_pool(uri).ok()?;
292        Some(p.stats())
293    }
294}
295
296#[allow(
297    clippy::manual_async_fn,
298    reason = "async fn would store `req` twice (future size budget)"
299)]
300/// General path (HTTP/1, slow acquisition, retries). An `async move` block rather than an
301/// `async fn` so `req` is stored once in the future (async-fn parameters are copied into locals).
302fn send_on(
303    op: Arc<OriginPool>,
304    mut req: http::Request<Body>,
305    mut lease: Option<Lease>,
306) -> impl Future<Output = Result<http::Response<Incoming>>> + Send {
307    async move {
308        let replayable = !matches!(req.body(), Body::Stream(_));
309        let idempotent = matier_transport::h1::is_idempotent(req.method());
310        let mut fresh = false;
311        let mut retried = false;
312        loop {
313            let l = match lease.take() {
314                Some(l) => l,
315                None => match op.try_fast(fresh) {
316                    Some(l) => l,
317                    None => op.acquire_slow(fresh).await?,
318                },
319            };
320            let result = match l {
321                Lease::H1(conn) => {
322                    conn.send_mut(&mut req, Arc::clone(&op) as Arc<dyn Release>)
323                        .await
324                }
325                // HTTP/2 consumes the request, so it cannot be retried here (needs a clone).
326                Lease::H2(handle, slot) => {
327                    return handle.send(slot, req).await;
328                }
329            };
330            match result {
331                Ok(resp) => return Ok(resp),
332                Err(e) if !retried && replayable => {
333                    let stale = matier_transport::h1::is_stale_keepalive(&e);
334                    let unprocessed = e.recovery() == matier_core::Recovery::Unprocessed;
335                    if unprocessed || (stale && idempotent) {
336                        retried = true;
337                        fresh = stale;
338                        continue;
339                    }
340                    return Err(e);
341                }
342                Err(e) => return Err(e),
343            }
344        }
345    }
346}
347
348pub(crate) fn dial_error(kind: ErrorKind, msg: String) -> Error {
349    Error::with_source(kind, matier_core::Recovery::Unprocessed, msg)
350}