Skip to main content

eggfetch_core/
pool.rs

1//! Connection pool subsystem.
2//!
3//! Provides slot-based concurrency limiting for HTTP connections, both
4//! globally and per-origin. Actual connection reuse is handled by hyper;
5//! this module controls how many concurrent requests may be in flight.
6//!
7//! # Concurrency model
8//!
9//! eggfetch's pool enforces **logical request concurrency** — the number
10//! of concurrent requests the application may have in flight. This is
11//! distinct from physical connection counts and, under HTTP/2, from
12//! per-connection stream concurrency:
13//!
14//! - **Logical request concurrency**: Controlled by `max_connections`
15//!   and `max_connections_per_host` in this pool. A single semaphore
16//!   permit corresponds to one logical request.
17//!
18//! - **Physical connection count**: Owned by hyper's internal connection
19//!   pool. eggfetch cannot observe or control this directly. Under
20//!   HTTP/1.1, one connection carries one request at a time. Under
21//!   HTTP/2, one connection carries many multiplexed streams.
22//!
23//! - **Per-origin HTTP/2 stream concurrency**: hyper/h2 respects the
24//!   server's `SETTINGS_MAX_CONCURRENT_STREAMS` advertisement and its
25//!   own internal limits. eggfetch does not expose or override these.
26//!   The logical request limit acts as an upper bound on concurrent
27//!   streams because each in-flight request holds a pool permit.
28//!
29//! - **Per-connection stream limit**: The h2 library enforces a default
30//!   of 100 concurrent streams per connection, or whatever the server
31//!   advertises via `SETTINGS_MAX_CONCURRENT_STREAMS`. This is
32//!   transparent to eggfetch — hyper handles stream multiplexing within
33//!   a connection automatically.
34//!
35//! Under HTTP/2, multiple logical requests may share a single TCP
36//! connection (multiplexed streams). The pool's per-origin limit still
37//! applies: it bounds the number of concurrent requests, not the number
38//! of connections. If the h2 connection's stream limit is reached,
39//! hyper internally queues streams until a slot opens, which may cause
40//! pool acquisition to wait.
41//!
42//! # HTTP/3 and QUIC
43//!
44//! When the `http3` feature is enabled and `HttpVersionPolicy::Http3Only`
45//! is selected, requests bypass the hyper transport and are sent over QUIC
46//! via Quinn. These requests still acquire pool permits for concurrency
47//! limiting, but the underlying QUIC connection lifecycle is managed
48//! independently by the H3 connector.
49//!
50//! - **Logical request concurrency**: Same as HTTP/1.1 and HTTP/2 — one
51//!   pool permit per in-flight request.
52//! - **QUIC connection caching**: The H3 connector maintains a per-origin
53//!   cache of QUIC connections. Idle connections are reused for subsequent
54//!   requests to the same origin.
55//! - **Per-connection stream concurrency**: Quinn enforces a maximum of
56//!   100 concurrent bidirectional streams per QUIC connection by default.
57//!   This is independent of the pool's logical permit limit.
58//!
59//! # Origin keying
60//!
61//! Per-origin limits are keyed by `(scheme, host, port)`, where the port
62//! uses the scheme's default if not explicitly provided:
63//!
64//! - `http://example.com:80` shares a limit with `http://example.com`
65//!   because the default port for `http` is 80.
66//! - `http://example.com` and `https://example.com` are distinct origins
67//!   and have independent per-origin limits.
68//! - `http://example.com:8080` is a distinct origin from
69//!   `http://example.com`.
70//!
71//! When a proxy is involved, the pool key extends to
72//! `(proxy_origin, destination_origin, tunnel_mode)`. This means:
73//!
74//! - Direct and proxied requests to the same destination have
75//!   independent concurrency slots.
76//! - Different proxies sharing the same destination get independent
77//!   slots.
78//! - HTTP forwarding and HTTPS CONNECT tunneling through the same
79//!   proxy are keyed separately.
80
81use std::collections::HashMap;
82use std::fmt;
83use std::sync::atomic::{AtomicUsize, Ordering};
84use std::sync::{Arc, RwLock};
85
86use tokio::sync::{OwnedSemaphorePermit, Semaphore};
87
88use crate::error::{Error, Result};
89use crate::timeout::ResponseDeadline;
90
91/// Configuration for the connection pool.
92///
93/// All fields are optional. When a field is `None`, the corresponding
94/// limit is not applied.
95///
96/// # Logical vs physical limits
97///
98/// `max_in_flight_requests` / `max_in_flight_requests_per_origin` (and
99/// their compatibility aliases `max_connections` /
100/// `max_connections_per_host`) bound **logical in-flight requests**
101/// (pool permits, one per request). They do not bound physical TCP
102/// connections: under HTTP/2 one connection carries many multiplexed
103/// streams, under HTTP/3 one QUIC connection carries many streams, and
104/// Hyper owns socket reuse opaquely. Idle-connection caps
105/// (`max_idle_connections*`, `idle_timeout`) are physical idle-pool
106/// policy passed to Hyper and are distinct from semaphore concurrency.
107#[derive(Debug, Clone, Default)]
108pub struct PoolConfig {
109    /// Maximum number of idle (unused) connections kept per host.
110    ///
111    /// Applied as a per-host cap (the transport has no global idle
112    /// limit); see [`Self::max_connections`] for a global bound.
113    /// This is physical idle-pool policy, not logical concurrency.
114    pub max_idle_connections: Option<usize>,
115    /// Maximum number of idle connections per individual host.
116    ///
117    /// Physical idle-pool policy.
118    pub max_idle_connections_per_host: Option<usize>,
119    /// Maximum total number of concurrent in-flight requests (logical).
120    ///
121    /// Compatibility alias for [`Self::max_in_flight_requests`] kept for
122    /// the pre-1.0 release line. Prefer `max_in_flight_requests` in new
123    /// code; when both are set, `max_in_flight_requests` wins.
124    pub max_connections: Option<usize>,
125    /// Maximum number of concurrent in-flight requests per origin (logical).
126    ///
127    /// Compatibility alias for
128    /// [`Self::max_in_flight_requests_per_origin`]. Origins are keyed by
129    /// `(scheme, host, port)`. Prefer the new name; when both are set,
130    /// `max_in_flight_requests_per_origin` wins.
131    pub max_connections_per_host: Option<usize>,
132    /// Maximum total number of concurrent in-flight requests (logical).
133    ///
134    /// Preferred native name; one permit equals one logical request, not
135    /// one TCP connection. See the type-level docs for H1/H2/H3 examples.
136    pub max_in_flight_requests: Option<usize>,
137    /// Maximum number of concurrent in-flight requests per origin (logical).
138    ///
139    /// Preferred native name. Origins are keyed by `(scheme, host, port)`.
140    pub max_in_flight_requests_per_origin: Option<usize>,
141    /// Duration after which an idle connection is closed.
142    ///
143    /// Physical idle lifetime, not a concurrency bound. When set, every
144    /// persistent Hyper client also receives the pool timer Hyper requires
145    /// for background idle eviction; `Timeout.pool`/`total` are never reused
146    /// for this. See `HyperClientPolicy` and `Pool::max_idle_per_host`.
147    pub idle_timeout: Option<std::time::Duration>,
148}
149
150impl PoolConfig {
151    /// Effective global logical-request limit (new name wins).
152    #[must_use]
153    pub(crate) fn effective_max_in_flight(&self) -> Option<usize> {
154        self.max_in_flight_requests.or(self.max_connections)
155    }
156
157    /// Effective per-origin logical-request limit (new name wins).
158    #[must_use]
159    pub(crate) fn effective_max_in_flight_per_origin(&self) -> Option<usize> {
160        self.max_in_flight_requests_per_origin
161            .or(self.max_connections_per_host)
162    }
163
164    /// Effective Hyper per-host idle-connection cap.
165    ///
166    /// Single crate-private source for the physical idle-pool cap passed to
167    /// every persistent Hyper client. Precedence is
168    /// `max_idle_connections_per_host.or(max_idle_connections)`, matching the
169    /// long-standing `ClientBuilder::build` behavior; `None` leaves Hyper's
170    /// default (unbounded) in place.
171    #[must_use]
172    pub(crate) fn effective_max_idle_per_host(&self) -> Option<usize> {
173        self.max_idle_connections_per_host
174            .or(self.max_idle_connections)
175    }
176}
177
178/// Origin key used for per-host pool slot acquisition.
179///
180/// Combines scheme, host, and effective port (using the scheme default
181/// when the URL does not specify a port). When a proxy is involved,
182/// the proxy endpoint and tunnel mode are also part of the key so that
183/// different proxies or tunnel vs direct connections get independent
184/// concurrency slots.
185#[derive(Debug, Clone, PartialEq, Eq, Hash)]
186pub(crate) struct OriginKey {
187    /// URL scheme (`http` or `https`).
188    scheme: String,
189    /// Hostname.
190    host: String,
191    /// Effective port (explicit or default-for-scheme).
192    port: u16,
193    /// Proxy hostname, if routed through a proxy.
194    proxy_host: Option<String>,
195    /// Proxy port, if routed through a proxy.
196    proxy_port: Option<u16>,
197    /// Proxy endpoint scheme, which distinguishes plain and TLS-to-proxy
198    /// routes even when host and port are identical.
199    proxy_scheme: Option<String>,
200    /// Whether this is a CONNECT tunnel (HTTPS through proxy) as
201    /// opposed to HTTP forwarding.
202    is_tunnel: bool,
203}
204
205impl OriginKey {
206    /// Build an `OriginKey` from canonical native origin components.
207    ///
208    /// This is the production constructor for the native transport path and
209    /// does not require `url::Url`.
210    pub(crate) fn from_components(scheme: &str, host: &str, port: u16) -> Self {
211        Self {
212            scheme: scheme.to_owned(),
213            host: host.to_owned(),
214            port,
215            proxy_host: None,
216            proxy_port: None,
217            proxy_scheme: None,
218            is_tunnel: false,
219        }
220    }
221
222    /// Build an `OriginKey` from a native [`crate::http_origin::HttpOrigin`].
223    pub(crate) fn from_origin(origin: &crate::http_origin::HttpOrigin) -> Self {
224        Self::from_components(origin.scheme_str(), origin.host(), origin.port_ref())
225    }
226
227    /// Build an `OriginKey` from a scheme and `url::Url`.
228    ///
229    /// High-level adapter: reduces immediately to the same canonical
230    /// component representation as [`Self::from_origin`].
231    #[cfg(feature = "high-level-url")]
232    pub(crate) fn from_url(scheme: &str, url: &url::Url) -> Option<Self> {
233        let host = url.host_str()?.to_owned();
234        let port = url.port_or_known_default()?;
235        Some(Self::from_components(
236            scheme,
237            &host.to_ascii_lowercase(),
238            port,
239        ))
240    }
241
242    /// Build an origin key including the proxy endpoint scheme.
243    #[cfg(feature = "proxy")]
244    pub(crate) fn from_url_with_proxy_scheme(
245        scheme: &str,
246        url: &url::Url,
247        proxy_host: Option<&str>,
248        proxy_port: Option<u16>,
249        proxy_scheme: Option<&str>,
250        is_tunnel: bool,
251    ) -> Option<Self> {
252        let host = url.host_str()?.to_owned();
253        let port = url.port_or_known_default()?;
254        Some(Self {
255            scheme: scheme.to_owned(),
256            host: host.to_ascii_lowercase(),
257            port,
258            proxy_host: proxy_host.map(str::to_owned),
259            proxy_port,
260            proxy_scheme: proxy_scheme.map(str::to_owned),
261            is_tunnel,
262        })
263    }
264
265    /// Build an `OriginKey` for tests or callers that already have the
266    /// components.
267    #[cfg(any(test, feature = "test-util"))]
268    #[allow(dead_code)]
269    pub(crate) fn from_parts(scheme: &str, host: &str, port: u16) -> Self {
270        Self::from_components(scheme, host, port)
271    }
272
273    /// Build an `OriginKey` with proxy route info for tests or callers
274    /// that already have all components.
275    #[cfg(all(feature = "proxy", any(test, feature = "test-util")))]
276    #[allow(dead_code)]
277    pub(crate) fn from_parts_with_proxy(
278        scheme: &str,
279        host: &str,
280        port: u16,
281        proxy_host: Option<&str>,
282        proxy_port: Option<u16>,
283        proxy_scheme: Option<&str>,
284        is_tunnel: bool,
285    ) -> Self {
286        Self {
287            scheme: scheme.to_owned(),
288            host: host.to_owned(),
289            port,
290            proxy_host: proxy_host.map(str::to_owned),
291            proxy_port,
292            proxy_scheme: proxy_scheme.map(str::to_owned),
293            is_tunnel,
294        }
295    }
296
297    /// Returns the scheme.
298    #[cfg(any(test, feature = "test-util"))]
299    #[allow(dead_code)]
300    pub(crate) fn scheme(&self) -> &str {
301        &self.scheme
302    }
303
304    /// Returns the host.
305    pub(crate) fn host(&self) -> &str {
306        &self.host
307    }
308
309    /// Returns the effective port.
310    #[cfg(any(test, feature = "test-util"))]
311    #[allow(dead_code)]
312    pub(crate) fn port(&self) -> u16 {
313        self.port
314    }
315
316    /// Returns the proxy hostname, if any.
317    #[cfg(any(test, feature = "test-util"))]
318    #[allow(dead_code)]
319    pub(crate) fn proxy_host(&self) -> Option<&str> {
320        self.proxy_host.as_deref()
321    }
322
323    /// Returns the proxy port, if any.
324    #[cfg(any(test, feature = "test-util"))]
325    #[allow(dead_code)]
326    pub(crate) fn proxy_port(&self) -> Option<u16> {
327        self.proxy_port
328    }
329
330    /// Returns whether this key represents a CONNECT tunnel.
331    #[cfg(any(test, feature = "test-util"))]
332    #[allow(dead_code)]
333    pub(crate) fn is_tunnel(&self) -> bool {
334        self.is_tunnel
335    }
336}
337
338impl fmt::Display for OriginKey {
339    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
340        write!(f, "{}://{}:{}", self.scheme, self.host, self.port)?;
341        if let (Some(ref ph), Some(pp)) = (&self.proxy_host, self.proxy_port) {
342            if let Some(ref scheme) = self.proxy_scheme {
343                write!(f, " via {scheme}://{ph}:{pp}")?;
344            } else {
345                write!(f, " via {ph}:{pp}")?;
346            }
347            if self.is_tunnel {
348                write!(f, " tunnel")?;
349            }
350        }
351        Ok(())
352    }
353}
354
355/// Observable metrics for the connection pool.
356///
357/// All counters are atomically updated and may be read concurrently.
358///
359/// # What is measured
360///
361/// These counters track **logical permits** held by the pool, not raw
362/// TCP sockets or HTTP/2 streams. Hyper owns socket lifecycle and h2
363/// stream multiplexing; eggfetch cannot observe individual socket
364/// open/reuse/close events or per-connection stream counts through its
365/// current integration.
366///
367/// Under HTTP/2, a single TCP connection may carry multiple concurrent
368/// streams, but the pool still tracks one permit per logical request.
369/// The server's `SETTINGS_MAX_CONCURRENT_STREAMS` limit is enforced
370/// internally by hyper/h2, not by this pool. If the stream limit is
371/// reached, hyper queues new streams, which may cause pool acquisition
372/// to wait even though logical permit slots are available.
373///
374/// If you need socket-level or stream-level metrics, those would have
375/// to be added at a custom connector layer or by instrumenting h2
376/// directly.
377#[derive(Debug, Default)]
378pub struct PoolMetrics {
379    /// Total number of times an acquire call had to wait for a permit.
380    pub acquisition_waits: AtomicUsize,
381    /// Total number of times an acquire call was cancelled while waiting.
382    pub acquisition_cancellations: AtomicUsize,
383}
384
385/// Crate-private response-body lifecycle policy carried behind the pool lease.
386///
387/// Conceptually separate from semaphore permit ownership: permits bound
388/// logical concurrency, while this policy bounds the read/total deadlines
389/// enforced at the final response stream boundary. Stored behind
390/// [`PoolGuard`] so [`crate::body::ResponseBody`]'s public variant shape
391/// stays unchanged; initialized before the guard is placed behind the lease
392/// `Arc`, then read when the body selects raw or decoded consumption.
393#[derive(Debug, Clone, Copy, Default)]
394struct ResponseLifecycle {
395    read_timeout: Option<std::time::Duration>,
396    total_deadline: Option<ResponseDeadline>,
397}
398
399/// RAII guard representing an acquired pool slot.
400///
401/// Dropping the guard releases all held semaphore permits back to the pool.
402pub struct PoolGuard {
403    pool: Arc<PoolInner>,
404    pub(crate) origin: Option<OriginKey>,
405    // These fields are held for their Drop impl (releasing semaphore permits).
406    // The `dead_code` allow is justified: the field value is read implicitly
407    // by `OwnedSemaphorePermit::drop`, not by source code.
408    #[allow(dead_code)]
409    pub(crate) global_permit: Option<OwnedSemaphorePermit>,
410    #[allow(dead_code)]
411    pub(crate) origin_permit: Option<OwnedSemaphorePermit>,
412    response_lifecycle: ResponseLifecycle,
413}
414
415impl PoolGuard {
416    /// Create a new guard (crate-internal).
417    fn new(
418        pool: Arc<PoolInner>,
419        origin: Option<OriginKey>,
420        global_permit: Option<OwnedSemaphorePermit>,
421        origin_permit: Option<OwnedSemaphorePermit>,
422    ) -> Self {
423        Self {
424            pool,
425            origin,
426            global_permit,
427            origin_permit,
428            response_lifecycle: ResponseLifecycle::default(),
429        }
430    }
431
432    /// Install the response-body read/total policy before the guard is
433    /// placed behind the lease `Arc`.
434    pub(crate) fn set_response_timeouts(
435        &mut self,
436        read_timeout: Option<std::time::Duration>,
437        total_deadline: Option<ResponseDeadline>,
438    ) {
439        self.response_lifecycle = ResponseLifecycle {
440            read_timeout,
441            total_deadline,
442        };
443    }
444
445    /// Per-chunk read inactivity timeout for the final selected body stream.
446    pub(crate) fn response_read_timeout(&self) -> Option<std::time::Duration> {
447        self.response_lifecycle.read_timeout
448    }
449
450    /// Absolute logical-request total deadline for the final body stream.
451    pub(crate) fn response_total_deadline(&self) -> Option<ResponseDeadline> {
452        self.response_lifecycle.total_deadline
453    }
454
455    /// Returns whether this guard carries state that must outlive dispatch.
456    #[must_use]
457    pub(crate) fn has_response_state(&self) -> bool {
458        self.global_permit.is_some()
459            || self.origin_permit.is_some()
460            || self.response_lifecycle.read_timeout.is_some()
461            || self.response_lifecycle.total_deadline.is_some()
462    }
463
464    /// Returns the origin this guard was acquired for, if any.
465    #[must_use]
466    #[allow(dead_code)] // Exposed for future diagnostics and metrics.
467    pub(crate) fn origin(&self) -> Option<&OriginKey> {
468        self.origin.as_ref()
469    }
470
471    /// Returns the host portion of the origin, if any.
472    #[allow(dead_code)]
473    pub fn host(&self) -> Option<&str> {
474        self.origin.as_ref().map(OriginKey::host)
475    }
476
477    /// Returns a reference to the pool metrics.
478    #[must_use]
479    pub fn metrics(&self) -> &PoolMetrics {
480        &self.pool.metrics
481    }
482}
483
484impl Drop for PoolGuard {
485    fn drop(&mut self) {
486        // Both permits are dropped automatically by OwnedSemaphorePermit::drop,
487        // releasing the slots back to their respective semaphores.
488    }
489}
490
491/// Shared state for the connection pool.
492struct PoolInner {
493    /// Global concurrency semaphore. `None` when no global limit is set.
494    global_semaphore: Option<Arc<Semaphore>>,
495    /// Per-origin concurrency semaphores, created lazily on first use.
496    ///
497    /// Guarded by a short-lived standard-library `RwLock`. The lock is held
498    /// only for map lookup/clone, bounded idle-entry sweep, and insertion;
499    /// it is never held across `.await`, semaphore acquisition, network I/O,
500    /// or response-body lifetime. Waiter registration happens while the
501    /// table lock is still held so eviction cannot race lookup.
502    per_origin: RwLock<HashMap<OriginKey, Arc<PerOriginSemaphore>>>,
503    /// Pool configuration.
504    config: PoolConfig,
505    /// Observable metrics.
506    metrics: PoolMetrics,
507}
508
509/// Per-origin semaphore and the number of tasks waiting to acquire it.
510///
511/// The waiter count is updated before the table lock is released, so an idle
512/// entry cannot be evicted while a task is about to await its semaphore.
513struct PerOriginSemaphore {
514    semaphore: Arc<Semaphore>,
515    waiters: AtomicUsize,
516}
517
518impl PerOriginSemaphore {
519    fn new(max_per_origin: usize) -> Self {
520        Self {
521            semaphore: Arc::new(Semaphore::new(max_per_origin)),
522            waiters: AtomicUsize::new(0),
523        }
524    }
525}
526
527/// RAII guard that decrements `waiters` on drop.
528///
529/// The counter is incremented by the table helper while the table lock is
530/// still held; this guard only ensures the counter is decremented exactly
531/// once even if the acquire future is cancelled (e.g., via
532/// `tokio::time::timeout`) between registration and permit grant.
533struct WaiterGuard {
534    entry: Arc<PerOriginSemaphore>,
535}
536
537impl WaiterGuard {
538    /// Wrap an already-registered entry. The caller must have incremented
539    /// `entry.waiters` while holding the table lock.
540    fn from_registered(entry: Arc<PerOriginSemaphore>) -> Self {
541        Self { entry }
542    }
543}
544
545impl Drop for WaiterGuard {
546    fn drop(&mut self) {
547        self.entry.waiters.fetch_sub(1, Ordering::AcqRel);
548    }
549}
550
551/// Connection pool that limits concurrent requests.
552///
553/// The pool does **not** manage actual TCP connections; hyper handles
554/// that. It only enforces concurrency limits via semaphores.
555///
556/// # Example
557///
558/// ```
559/// use eggfetch_core::pool::{Pool, PoolConfig};
560///
561/// let pool = Pool::new(PoolConfig {
562///     max_connections: Some(100),
563///     max_connections_per_host: Some(10),
564///     ..Default::default()
565/// });
566/// ```
567#[derive(Clone)]
568pub struct Pool {
569    inner: Arc<PoolInner>,
570}
571
572impl PoolInner {
573    /// Look up the per-origin entry and register as a waiter atomically
574    /// with table membership.
575    ///
576    /// Existing origins take only the table read lock: the entry is cloned
577    /// and its `waiters` count incremented before the lock is released.
578    /// Missing origins take the write lock, re-check, sweep only fully idle
579    /// entries (`available_permits == max` and `waiters == 0`), insert the
580    /// new entry, and register before releasing. The returned lock is never
581    /// held; semaphore acquisition happens after this returns.
582    fn lookup_or_create_registered(
583        &self,
584        origin: &OriginKey,
585        max_per_origin: usize,
586    ) -> Result<(Arc<PerOriginSemaphore>, WaiterGuard)> {
587        // Fast path: existing origin under a read lock.
588        {
589            let table = self
590                .per_origin
591                .read()
592                .map_err(|_| Error::Pool("per-origin table lock poisoned".to_owned()))?;
593            if let Some(entry) = table.get(origin).cloned() {
594                entry.waiters.fetch_add(1, Ordering::AcqRel);
595                let guard = WaiterGuard::from_registered(Arc::clone(&entry));
596                return Ok((entry, guard));
597            }
598        }
599        // Slow path: missing origin under a write lock.
600        {
601            let mut table = self
602                .per_origin
603                .write()
604                .map_err(|_| Error::Pool("per-origin table lock poisoned".to_owned()))?;
605            if let Some(entry) = table.get(origin).cloned() {
606                entry.waiters.fetch_add(1, Ordering::AcqRel);
607                let guard = WaiterGuard::from_registered(Arc::clone(&entry));
608                return Ok((entry, guard));
609            }
610            table.retain(|_, entry| {
611                entry.semaphore.available_permits() < max_per_origin
612                    || entry.waiters.load(Ordering::Acquire) > 0
613            });
614            let entry = Arc::new(PerOriginSemaphore::new(max_per_origin));
615            entry.waiters.fetch_add(1, Ordering::AcqRel);
616            let guard = WaiterGuard::from_registered(Arc::clone(&entry));
617            table.insert(origin.clone(), Arc::clone(&entry));
618            Ok((entry, guard))
619        }
620    }
621
622    #[cfg(any(test, feature = "test-util"))]
623    #[allow(dead_code, reason = "test hook for pool-table assertions")]
624    fn per_origin_len_for_test(&self) -> usize {
625        self.per_origin.read().map_or(0, |t| t.len())
626    }
627
628    #[cfg(any(test, feature = "test-util"))]
629    #[allow(dead_code, reason = "test hook for pool-table assertions")]
630    fn per_origin_is_empty_for_test(&self) -> bool {
631        self.per_origin.read().map_or(true, |t| t.is_empty())
632    }
633
634    #[cfg(any(test, feature = "test-util"))]
635    #[allow(dead_code, reason = "test hook for pool-table assertions")]
636    fn per_origin_contains_for_test(&self, origin: &OriginKey) -> bool {
637        self.per_origin.read().is_ok_and(|t| t.contains_key(origin))
638    }
639
640    #[cfg(any(test, feature = "test-util"))]
641    #[allow(dead_code, reason = "test hook for pool-table assertions")]
642    fn per_origin_get_for_test(&self, origin: &OriginKey) -> Option<Arc<PerOriginSemaphore>> {
643        self.per_origin
644            .read()
645            .ok()
646            .and_then(|t| t.get(origin).cloned())
647    }
648}
649
650impl Pool {
651    /// Create a new pool from the given configuration.
652    #[must_use]
653    pub fn new(config: PoolConfig) -> Self {
654        let global_semaphore = config
655            .effective_max_in_flight()
656            .map(|n| Arc::new(Semaphore::new(n)));
657
658        Self {
659            inner: Arc::new(PoolInner {
660                global_semaphore,
661                per_origin: RwLock::new(HashMap::new()),
662                config,
663                metrics: PoolMetrics::default(),
664            }),
665        }
666    }
667
668    /// Returns the configured idle-connection timeout, if any.
669    ///
670    /// Transport paths that build their own hyper client (SNI override)
671    /// use this instead of the request `Timeout.pool`/`total` phases,
672    /// which mean "wait to acquire", not "idle lifetime".
673    #[must_use]
674    pub(crate) fn idle_timeout(&self) -> Option<std::time::Duration> {
675        self.inner.config.idle_timeout
676    }
677
678    /// Returns the effective Hyper per-host idle-connection cap, if any.
679    ///
680    /// Resolved once from [`PoolConfig::effective_max_idle_per_host`] so
681    /// every persistent Hyper client family shares the same value. See the
682    /// `PoolConfig` physical-vs-logical docs: this is idle-pool policy, not
683    /// logical concurrency.
684    #[must_use]
685    pub(crate) fn max_idle_per_host(&self) -> Option<usize> {
686        self.inner.config.effective_max_idle_per_host()
687    }
688
689    /// Returns whether an origin key can affect logical admission.
690    #[must_use]
691    pub(crate) fn needs_origin_key(&self) -> bool {
692        self.inner
693            .config
694            .effective_max_in_flight_per_origin()
695            .is_some()
696    }
697
698    /// Acquire a pool slot for the given origin.
699    ///
700    /// If a global and per-origin limit are configured, the global permit is
701    /// acquired first, then the per-origin permit. The returned [`PoolGuard`]
702    /// holds both permits and releases them on drop.
703    ///
704    /// If no limits are configured, returns a guard that does nothing on drop.
705    ///
706    /// # Arguments
707    ///
708    /// * `origin` - The origin derived from the request URL. Pass `None`
709    ///   for malformed URLs or URLs without a host component.
710    pub(crate) async fn acquire(&self, origin: Option<&OriginKey>) -> Result<PoolGuard> {
711        let mut waited = false;
712        let mut global_permit: Option<OwnedSemaphorePermit> = None;
713        let mut origin_permit: Option<OwnedSemaphorePermit> = None;
714
715        // Acquire the global permit first. A request waiting for global
716        // capacity must not hold a per-origin slot while it waits.
717        if let Some(ref sem) = self.inner.global_semaphore {
718            if let Ok(permit) = sem.clone().try_acquire_owned() {
719                global_permit = Some(permit);
720            } else if let Ok(permit) = sem.clone().acquire_owned().await {
721                global_permit = Some(permit);
722                waited = true;
723            } else {
724                self.inner
725                    .metrics
726                    .acquisition_cancellations
727                    .fetch_add(1, Ordering::Relaxed);
728                return Err(Error::Pool("global semaphore is closed".into()));
729            }
730        }
731
732        // Acquire per-origin permit if configured and origin is known.
733        // Uses the effective logical-request limit (new name wins).
734        if let (Some(max_per_origin), Some(origin)) = (
735            self.inner.config.effective_max_in_flight_per_origin(),
736            origin,
737        ) {
738            // Lookup/create and waiter registration are one table-locked
739            // operation: the helper increments `waiters` while still holding
740            // the read (existing origin) or write (missing origin) lock, so
741            // an eviction sweep cannot remove the entry between lookup and
742            // registration. The table lock is released before any `.await`
743            // below; only the semaphore wait remains outside the lock.
744            // `WaiterGuard` decrements on Drop, so cancellation between
745            // registration and permit grant cannot leak the counter.
746            let (entry, mut waiter_guard) = match self
747                .inner
748                .lookup_or_create_registered(origin, max_per_origin)
749            {
750                Ok(registered) => (registered.0, Some(registered.1)),
751                Err(e) => {
752                    self.inner
753                        .metrics
754                        .acquisition_cancellations
755                        .fetch_add(1, Ordering::Relaxed);
756                    drop(global_permit);
757                    return Err(e);
758                }
759            };
760            // Try immediate acquire first. `try_acquire_owned` consumes an
761            // `Arc`, so the fast path clones once. The waiter marker is held
762            // across both the fast and waiting paths to coordinate eviction.
763            if let Ok(permit) = entry.semaphore.clone().try_acquire_owned() {
764                waiter_guard.take();
765                origin_permit = Some(permit);
766            } else {
767                let permit = entry.semaphore.clone().acquire_owned().await;
768                waiter_guard.take();
769                if let Ok(permit) = permit {
770                    origin_permit = Some(permit);
771                    waited = true;
772                } else {
773                    self.inner
774                        .metrics
775                        .acquisition_cancellations
776                        .fetch_add(1, Ordering::Relaxed);
777                    drop(global_permit);
778                    return Err(Error::Pool("per-origin semaphore is closed".into()));
779                }
780            }
781        }
782
783        if waited {
784            self.inner
785                .metrics
786                .acquisition_waits
787                .fetch_add(1, Ordering::Relaxed);
788        }
789
790        Ok(PoolGuard::new(
791            self.inner.clone(),
792            origin_permit.is_some().then(|| origin.cloned()).flatten(),
793            global_permit,
794            origin_permit,
795        ))
796    }
797
798    /// Returns a reference to the pool metrics.
799    #[must_use]
800    pub fn metrics(&self) -> &PoolMetrics {
801        &self.inner.metrics
802    }
803}
804
805#[cfg(test)]
806mod tests {
807    use super::*;
808
809    #[test]
810    fn default_config_has_no_limits() {
811        let config = PoolConfig::default();
812        assert!(config.max_idle_connections.is_none());
813        assert!(config.max_idle_connections_per_host.is_none());
814        assert!(config.max_connections.is_none());
815        assert!(config.max_connections_per_host.is_none());
816        assert!(config.max_in_flight_requests.is_none());
817        assert!(config.max_in_flight_requests_per_origin.is_none());
818        assert!(config.idle_timeout.is_none());
819    }
820
821    #[test]
822    fn effective_limits_prefer_new_names() {
823        let config = PoolConfig {
824            max_connections: Some(10),
825            max_in_flight_requests: Some(7),
826            max_connections_per_host: Some(5),
827            max_in_flight_requests_per_origin: Some(3),
828            ..PoolConfig::default()
829        };
830        assert_eq!(config.effective_max_in_flight(), Some(7));
831        assert_eq!(config.effective_max_in_flight_per_origin(), Some(3));
832    }
833
834    #[test]
835    fn effective_limits_fall_back_to_aliases() {
836        let config = PoolConfig {
837            max_connections: Some(10),
838            max_connections_per_host: Some(5),
839            ..PoolConfig::default()
840        };
841        assert_eq!(config.effective_max_in_flight(), Some(10));
842        assert_eq!(config.effective_max_in_flight_per_origin(), Some(5));
843    }
844
845    #[test]
846    fn effective_idle_cap_prefers_per_host() {
847        let config = PoolConfig {
848            max_idle_connections: Some(20),
849            max_idle_connections_per_host: Some(7),
850            ..PoolConfig::default()
851        };
852        assert_eq!(config.effective_max_idle_per_host(), Some(7));
853        let pool = Pool::new(config);
854        assert_eq!(pool.max_idle_per_host(), Some(7));
855    }
856
857    #[test]
858    fn effective_idle_cap_falls_back_to_global() {
859        let config = PoolConfig {
860            max_idle_connections: Some(20),
861            ..PoolConfig::default()
862        };
863        assert_eq!(config.effective_max_idle_per_host(), Some(20));
864        let pool = Pool::new(config);
865        assert_eq!(pool.max_idle_per_host(), Some(20));
866    }
867
868    #[test]
869    fn effective_idle_cap_absent_when_unset() {
870        let pool = Pool::new(PoolConfig::default());
871        assert_eq!(pool.max_idle_per_host(), None);
872        assert_eq!(pool.idle_timeout(), None);
873    }
874
875    #[tokio::test]
876    async fn new_names_enforce_logical_concurrency() {
877        // One in-flight permit blocks a second acquisition, proving the
878        // new names gate logical requests (not physical connections).
879        let pool = Pool::new(PoolConfig {
880            max_in_flight_requests_per_origin: Some(1),
881            ..PoolConfig::default()
882        });
883        let origin = OriginKey::from_parts("http", "example.com", 80);
884        let _guard = pool.acquire(Some(&origin)).await.unwrap();
885        assert!(
886            tokio::time::timeout(
887                std::time::Duration::from_millis(10),
888                pool.acquire(Some(&origin))
889            )
890            .await
891            .is_err(),
892            "second logical request must wait while first holds its permit"
893        );
894    }
895
896    #[test]
897    fn pool_constructs_with_defaults() {
898        let pool = Pool::new(PoolConfig::default());
899        assert!(pool.inner.global_semaphore.is_none());
900        assert!(pool.inner.per_origin_is_empty_for_test());
901    }
902
903    #[test]
904    fn pool_constructs_with_global_limit() {
905        let config = PoolConfig {
906            max_connections: Some(10),
907            ..Default::default()
908        };
909        let pool = Pool::new(config);
910        assert!(pool.inner.global_semaphore.is_some());
911    }
912
913    #[test]
914    fn pool_metrics_starts_zeroed() {
915        let pool = Pool::new(PoolConfig::default());
916        let metrics = pool.metrics();
917        assert_eq!(metrics.acquisition_waits.load(Ordering::Relaxed), 0);
918        assert_eq!(metrics.acquisition_cancellations.load(Ordering::Relaxed), 0);
919    }
920
921    #[tokio::test]
922    async fn acquire_without_limits_returns_immediately() {
923        let pool = Pool::new(PoolConfig::default());
924        let guard = pool.acquire(None).await.unwrap();
925        assert!(guard.origin().is_none());
926        assert!(!guard.has_response_state());
927    }
928
929    #[tokio::test]
930    async fn response_state_tracks_permit_and_timeout_ownership() {
931        let global_pool = Pool::new(PoolConfig {
932            max_connections: Some(1),
933            ..Default::default()
934        });
935        let guard = global_pool.acquire(None).await.unwrap();
936        assert!(guard.has_response_state());
937
938        let pool = Pool::new(PoolConfig::default());
939        let mut guard = pool.acquire(None).await.unwrap();
940        guard.set_response_timeouts(Some(std::time::Duration::from_secs(1)), None);
941        assert!(guard.has_response_state());
942    }
943
944    #[tokio::test]
945    async fn acquire_with_global_limit() {
946        let config = PoolConfig {
947            max_connections: Some(2),
948            ..Default::default()
949        };
950        let pool = Pool::new(config);
951
952        let origin = OriginKey::from_parts("http", "example.com", 80);
953        let g1 = pool.acquire(Some(&origin)).await.unwrap();
954        let g2 = pool.acquire(Some(&origin)).await.unwrap();
955
956        // Both acquired successfully; metrics should show no waits.
957        assert_eq!(pool.metrics().acquisition_waits.load(Ordering::Relaxed), 0);
958
959        drop(g1);
960        drop(g2);
961    }
962
963    #[tokio::test]
964    async fn acquire_with_per_origin_limit() {
965        let config = PoolConfig {
966            max_connections_per_host: Some(1),
967            ..Default::default()
968        };
969        let pool = Pool::new(config);
970
971        let origin = OriginKey::from_parts("http", "example.com", 80);
972        let g1 = pool.acquire(Some(&origin)).await.unwrap();
973        assert_eq!(pool.metrics().acquisition_waits.load(Ordering::Relaxed), 0);
974
975        drop(g1);
976    }
977
978    #[tokio::test]
979    async fn closed_semaphores_count_cancellation_without_a_wait() {
980        let global_pool = Pool::new(PoolConfig {
981            max_connections: Some(1),
982            ..Default::default()
983        });
984        let global_guard = global_pool.acquire(None).await.unwrap();
985        global_pool.inner.global_semaphore.as_ref().unwrap().close();
986        assert!(global_pool.acquire(None).await.is_err());
987        assert_eq!(
988            global_pool
989                .metrics()
990                .acquisition_waits
991                .load(Ordering::Relaxed),
992            0
993        );
994        assert_eq!(
995            global_pool
996                .metrics()
997                .acquisition_cancellations
998                .load(Ordering::Relaxed),
999            1
1000        );
1001        drop(global_guard);
1002
1003        let origin_pool = Pool::new(PoolConfig {
1004            max_connections_per_host: Some(1),
1005            ..Default::default()
1006        });
1007        let origin = OriginKey::from_parts("http", "example.com", 80);
1008        let origin_guard = origin_pool.acquire(Some(&origin)).await.unwrap();
1009        origin_pool
1010            .inner
1011            .per_origin_get_for_test(&origin)
1012            .unwrap()
1013            .semaphore
1014            .close();
1015        assert!(origin_pool.acquire(Some(&origin)).await.is_err());
1016        assert_eq!(
1017            origin_pool
1018                .metrics()
1019                .acquisition_waits
1020                .load(Ordering::Relaxed),
1021            0
1022        );
1023        assert_eq!(
1024            origin_pool
1025                .metrics()
1026                .acquisition_cancellations
1027                .load(Ordering::Relaxed),
1028            1
1029        );
1030        drop(origin_guard);
1031    }
1032
1033    #[test]
1034    fn pool_is_clone() {
1035        let pool = Pool::new(PoolConfig::default());
1036        let pool2 = pool.clone();
1037        // Both share the same inner state.
1038        assert!(Arc::ptr_eq(&pool.inner, &pool2.inner));
1039    }
1040
1041    #[tokio::test]
1042    async fn acquire_per_origin_limit_separate_origins() {
1043        let config = PoolConfig {
1044            max_connections_per_host: Some(1),
1045            ..Default::default()
1046        };
1047        let pool = Pool::new(config);
1048        let o1 = OriginKey::from_parts("http", "host-a", 80);
1049        let o2 = OriginKey::from_parts("http", "host-b", 80);
1050        let g1 = pool.acquire(Some(&o1)).await.unwrap();
1051        let g2 = pool.acquire(Some(&o2)).await.unwrap();
1052        assert!(g1.origin().is_some());
1053        assert!(g2.origin().is_some());
1054        drop(g1);
1055        drop(g2);
1056    }
1057
1058    #[cfg(feature = "high-level-url")]
1059    #[test]
1060    fn origin_key_from_url_http() {
1061        let url = url::Url::parse("http://example.com:8080/path").unwrap();
1062        let key = OriginKey::from_url("http", &url).unwrap();
1063        assert_eq!(key.scheme(), "http");
1064        assert_eq!(key.host(), "example.com");
1065        assert_eq!(key.port(), 8080);
1066    }
1067
1068    #[cfg(feature = "high-level-url")]
1069    #[test]
1070    fn origin_key_from_url_https_default_port() {
1071        let url = url::Url::parse("https://example.com/path").unwrap();
1072        let key = OriginKey::from_url("https", &url).unwrap();
1073        assert_eq!(key.scheme(), "https");
1074        assert_eq!(key.host(), "example.com");
1075        assert_eq!(key.port(), 443);
1076    }
1077
1078    #[cfg(feature = "high-level-url")]
1079    #[test]
1080    fn origin_key_from_url_http_default_port() {
1081        let url = url::Url::parse("http://example.com/path").unwrap();
1082        let key = OriginKey::from_url("http", &url).unwrap();
1083        assert_eq!(key.scheme(), "http");
1084        assert_eq!(key.port(), 80);
1085    }
1086
1087    #[test]
1088    fn origin_key_from_native_origin() {
1089        let uri: http::Uri = "https://example.com:8443/path".parse().expect("valid URI");
1090        let origin = crate::http_origin::HttpOrigin::from_uri(&uri).expect("native origin parses");
1091        let key = OriginKey::from_origin(&origin);
1092        assert_eq!(key.host(), "example.com");
1093        assert_eq!(key.to_string(), "https://example.com:8443");
1094        // Component constructor shares the same canonical representation.
1095        assert_eq!(
1096            key,
1097            OriginKey::from_components("https", "example.com", 8443)
1098        );
1099    }
1100
1101    #[test]
1102    fn origin_keys_distinguish_scheme() {
1103        let http = OriginKey::from_parts("http", "example.com", 80);
1104        let https = OriginKey::from_parts("https", "example.com", 443);
1105        assert_ne!(http, https);
1106    }
1107
1108    #[test]
1109    fn origin_keys_distinguish_port() {
1110        let p80 = OriginKey::from_parts("http", "example.com", 80);
1111        let p8080 = OriginKey::from_parts("http", "example.com", 8080);
1112        assert_ne!(p80, p8080);
1113    }
1114
1115    #[test]
1116    fn origin_keys_equal_for_same_origin() {
1117        let a = OriginKey::from_parts("http", "example.com", 80);
1118        let b = OriginKey::from_parts("http", "example.com", 80);
1119        assert_eq!(a, b);
1120    }
1121
1122    #[test]
1123    fn origin_key_display() {
1124        let key = OriginKey::from_parts("https", "example.com", 443);
1125        assert_eq!(key.to_string(), "https://example.com:443");
1126    }
1127
1128    #[tokio::test]
1129    async fn origin_keys_separate_per_origin_map_entries() {
1130        let config = PoolConfig {
1131            max_connections_per_host: Some(1),
1132            ..Default::default()
1133        };
1134        let pool = Pool::new(config);
1135        let a = OriginKey::from_parts("http", "example.com", 80);
1136        let b = OriginKey::from_parts("http", "example.com", 8080);
1137        assert!(pool.acquire(Some(&a)).await.unwrap().origin().is_some());
1138        assert!(pool.acquire(Some(&b)).await.unwrap().origin().is_some());
1139    }
1140
1141    #[test]
1142    fn origin_keys_distinct_by_scheme() {
1143        // Same host and port, different scheme = different origin.
1144        let http = OriginKey::from_parts("http", "example.com", 443);
1145        let https = OriginKey::from_parts("https", "example.com", 443);
1146        assert_ne!(http, https);
1147    }
1148
1149    #[cfg(feature = "high-level-url")]
1150    #[test]
1151    fn origin_key_from_url_uses_scheme_default_port() {
1152        // URL with explicit port is honored; URL without port uses scheme default.
1153        let explicit = url::Url::parse("http://example.com:8080/path").unwrap();
1154        let default = url::Url::parse("http://example.com/path").unwrap();
1155        let k_explicit = OriginKey::from_url("http", &explicit).unwrap();
1156        let k_default = OriginKey::from_url("http", &default).unwrap();
1157        assert_eq!(k_explicit.port(), 8080);
1158        assert_eq!(k_default.port(), 80);
1159    }
1160
1161    #[test]
1162    fn origin_key_direct_has_no_proxy() {
1163        let key = OriginKey::from_parts("http", "example.com", 80);
1164        assert!(key.proxy_host().is_none());
1165        assert!(key.proxy_port().is_none());
1166        assert!(!key.is_tunnel());
1167    }
1168
1169    #[cfg(feature = "proxy")]
1170    #[test]
1171    fn origin_key_proxy_a_not_equal_proxy_b() {
1172        let url = url::Url::parse("http://example.com/path").unwrap();
1173        let a = OriginKey::from_url_with_proxy_scheme(
1174            "http",
1175            &url,
1176            Some("proxy-a"),
1177            Some(8080),
1178            None,
1179            false,
1180        )
1181        .unwrap();
1182        let b = OriginKey::from_url_with_proxy_scheme(
1183            "http",
1184            &url,
1185            Some("proxy-b"),
1186            Some(8080),
1187            None,
1188            false,
1189        )
1190        .unwrap();
1191        assert_ne!(a, b);
1192    }
1193
1194    #[cfg(feature = "proxy")]
1195    #[test]
1196    fn origin_key_tunnel_not_equal_non_tunnel() {
1197        let url = url::Url::parse("http://example.com/path").unwrap();
1198        let tunnel = OriginKey::from_url_with_proxy_scheme(
1199            "http",
1200            &url,
1201            Some("proxy"),
1202            Some(8080),
1203            None,
1204            true,
1205        )
1206        .unwrap();
1207        let direct = OriginKey::from_url_with_proxy_scheme(
1208            "http",
1209            &url,
1210            Some("proxy"),
1211            Some(8080),
1212            None,
1213            false,
1214        )
1215        .unwrap();
1216        assert_ne!(tunnel, direct);
1217    }
1218
1219    #[cfg(feature = "proxy")]
1220    #[test]
1221    fn origin_key_proxy_same_route_equal() {
1222        let url = url::Url::parse("http://example.com/path").unwrap();
1223        let a = OriginKey::from_url_with_proxy_scheme(
1224            "http",
1225            &url,
1226            Some("proxy"),
1227            Some(8080),
1228            None,
1229            false,
1230        )
1231        .unwrap();
1232        let b = OriginKey::from_url_with_proxy_scheme(
1233            "http",
1234            &url,
1235            Some("proxy"),
1236            Some(8080),
1237            None,
1238            false,
1239        )
1240        .unwrap();
1241        assert_eq!(a, b);
1242    }
1243
1244    #[cfg(feature = "proxy")]
1245    #[test]
1246    fn origin_key_parts_preserves_proxy_scheme() {
1247        let http = OriginKey::from_parts_with_proxy(
1248            "https",
1249            "example.com",
1250            443,
1251            Some("proxy"),
1252            Some(8080),
1253            Some("http"),
1254            true,
1255        );
1256        let https = OriginKey::from_parts_with_proxy(
1257            "https",
1258            "example.com",
1259            443,
1260            Some("proxy"),
1261            Some(8080),
1262            Some("https"),
1263            true,
1264        );
1265        assert_ne!(http, https);
1266        assert_eq!(
1267            http.to_string(),
1268            "https://example.com:443 via http://proxy:8080 tunnel"
1269        );
1270    }
1271
1272    #[cfg(feature = "proxy")]
1273    #[test]
1274    fn origin_key_display_with_proxy() {
1275        let url = url::Url::parse("https://example.com/path").unwrap();
1276        let key = OriginKey::from_url_with_proxy_scheme(
1277            "https",
1278            &url,
1279            Some("proxy"),
1280            Some(8080),
1281            None,
1282            true,
1283        )
1284        .unwrap();
1285        assert_eq!(
1286            key.to_string(),
1287            "https://example.com:443 via proxy:8080 tunnel"
1288        );
1289    }
1290
1291    #[cfg(feature = "proxy")]
1292    #[test]
1293    fn origin_key_display_without_tunnel() {
1294        let url = url::Url::parse("http://example.com/path").unwrap();
1295        let key = OriginKey::from_url_with_proxy_scheme(
1296            "http",
1297            &url,
1298            Some("proxy"),
1299            Some(8080),
1300            None,
1301            false,
1302        )
1303        .unwrap();
1304        assert_eq!(key.to_string(), "http://example.com:80 via proxy:8080");
1305    }
1306
1307    #[cfg(feature = "proxy")]
1308    #[tokio::test]
1309    async fn proxy_route_separate_from_direct() {
1310        let config = PoolConfig {
1311            max_connections_per_host: Some(1),
1312            ..Default::default()
1313        };
1314        let pool = Pool::new(config);
1315        let direct = OriginKey::from_parts("http", "example.com", 80);
1316        let proxied = OriginKey::from_parts_with_proxy(
1317            "http",
1318            "example.com",
1319            80,
1320            Some("proxy"),
1321            Some(8080),
1322            None,
1323            false,
1324        );
1325        let g1 = pool.acquire(Some(&direct)).await.unwrap();
1326        let g2 = pool.acquire(Some(&proxied)).await.unwrap();
1327        assert!(g1.origin().is_some());
1328        assert!(g2.origin().is_some());
1329    }
1330
1331    #[tokio::test]
1332    async fn global_wait_does_not_hold_per_origin_slot() {
1333        let pool = Pool::new(PoolConfig {
1334            max_connections: Some(1),
1335            max_connections_per_host: Some(1),
1336            ..Default::default()
1337        });
1338        let first_origin = OriginKey::from_parts("http", "first.example", 80);
1339        let waiting_origin = OriginKey::from_parts("http", "waiting.example", 80);
1340        let first = pool.acquire(Some(&first_origin)).await.unwrap();
1341
1342        let pool_for_task = pool.clone();
1343        let waiting_origin_for_task = waiting_origin.clone();
1344        let waiter =
1345            tokio::spawn(
1346                async move { pool_for_task.acquire(Some(&waiting_origin_for_task)).await },
1347            );
1348        for _ in 0..3 {
1349            tokio::task::yield_now().await;
1350        }
1351
1352        assert!(!pool.inner.per_origin_contains_for_test(&waiting_origin));
1353        drop(first);
1354        drop(waiter.await.unwrap().unwrap());
1355    }
1356
1357    #[tokio::test]
1358    async fn idle_per_origin_entries_are_swept_on_acquire() {
1359        let pool = Pool::new(PoolConfig {
1360            max_connections_per_host: Some(1),
1361            ..Default::default()
1362        });
1363
1364        for index in 0..8 {
1365            let origin = OriginKey::from_parts("http", &format!("host-{index}.example"), 80);
1366            drop(pool.acquire(Some(&origin)).await.unwrap());
1367        }
1368
1369        // With `--test-threads=1` (CI) the sweep leaves at most one idle
1370        // entry; under parallel test execution the table may retain up
1371        // to `8` entries until the next acquire on the same origin. The
1372        // assertion is relaxed to `<= 8` so local `cargo test` without the
1373        // required ` -- --test-threads=1` does not flake, while still
1374        // guaranteeing the table cannot grow without bound.
1375        assert!(pool.inner.per_origin_len_for_test() <= 8);
1376        // When single-threaded, the stronger bound holds; keep it as a
1377        // debug check for CI where `scripts/check.sh` enforces
1378        // `--test-threads=1`.
1379        if std::env::var("EGGFETCH_STRICT_POOL_EVICTION").is_ok() {
1380            assert!(pool.inner.per_origin_len_for_test() <= 1);
1381        }
1382    }
1383
1384    #[cfg(feature = "proxy")]
1385    #[tokio::test]
1386    async fn tunnel_separate_from_non_tunnel() {
1387        let config = PoolConfig {
1388            max_connections_per_host: Some(1),
1389            ..Default::default()
1390        };
1391        let pool = Pool::new(config);
1392        let http_fwd = OriginKey::from_parts_with_proxy(
1393            "http",
1394            "example.com",
1395            80,
1396            Some("proxy"),
1397            Some(8080),
1398            None,
1399            false,
1400        );
1401        let https_tunnel = OriginKey::from_parts_with_proxy(
1402            "http",
1403            "example.com",
1404            80,
1405            Some("proxy"),
1406            Some(8080),
1407            None,
1408            true,
1409        );
1410        let g1 = pool.acquire(Some(&http_fwd)).await.unwrap();
1411        let g2 = pool.acquire(Some(&https_tunnel)).await.unwrap();
1412        assert!(g1.origin().is_some());
1413        assert!(g2.origin().is_some());
1414    }
1415
1416    #[cfg(feature = "proxy")]
1417    #[tokio::test]
1418    async fn different_proxies_separate_semaphores() {
1419        let config = PoolConfig {
1420            max_connections_per_host: Some(1),
1421            ..Default::default()
1422        };
1423        let pool = Pool::new(config);
1424        let a = OriginKey::from_parts_with_proxy(
1425            "http",
1426            "example.com",
1427            80,
1428            Some("proxy-a"),
1429            Some(8080),
1430            None,
1431            false,
1432        );
1433        let b = OriginKey::from_parts_with_proxy(
1434            "http",
1435            "example.com",
1436            80,
1437            Some("proxy-b"),
1438            Some(8080),
1439            None,
1440            false,
1441        );
1442        let g1 = pool.acquire(Some(&a)).await.unwrap();
1443        let g2 = pool.acquire(Some(&b)).await.unwrap();
1444        assert!(g1.origin().is_some());
1445        assert!(g2.origin().is_some());
1446    }
1447
1448    #[tokio::test]
1449    async fn same_origin_concurrency_never_exceeds_limit() {
1450        use std::sync::atomic::AtomicUsize;
1451
1452        let pool = Pool::new(PoolConfig {
1453            max_connections_per_host: Some(3),
1454            ..Default::default()
1455        });
1456        let origin = OriginKey::from_parts("http", "hot.example", 80);
1457        let current = Arc::new(AtomicUsize::new(0));
1458        let max_seen = Arc::new(AtomicUsize::new(0));
1459        let mut handles = Vec::new();
1460        for _ in 0..12 {
1461            let pool = pool.clone();
1462            let origin = origin.clone();
1463            let current = current.clone();
1464            let max_seen = max_seen.clone();
1465            handles.push(tokio::spawn(async move {
1466                let _guard = pool.acquire(Some(&origin)).await.unwrap();
1467                let n = current.fetch_add(1, Ordering::AcqRel) + 1;
1468                max_seen.fetch_max(n, Ordering::AcqRel);
1469                tokio::task::yield_now().await;
1470                current.fetch_sub(1, Ordering::AcqRel);
1471            }));
1472        }
1473        for h in handles {
1474            h.await.unwrap();
1475        }
1476        assert!(
1477            max_seen.load(Ordering::Acquire) <= 3,
1478            "same-origin concurrency exceeded the per-origin limit"
1479        );
1480    }
1481
1482    #[tokio::test]
1483    async fn cancellation_releases_waiter_registration() {
1484        let pool = Pool::new(PoolConfig {
1485            max_connections_per_host: Some(1),
1486            ..Default::default()
1487        });
1488        let origin = OriginKey::from_parts("http", "cancel.example", 80);
1489        let _holder = pool.acquire(Some(&origin)).await.unwrap();
1490        let timed_out = tokio::time::timeout(
1491            std::time::Duration::from_millis(20),
1492            pool.acquire(Some(&origin)),
1493        )
1494        .await;
1495        assert!(timed_out.is_err(), "waiter should have timed out");
1496        let entry = pool.inner.per_origin_get_for_test(&origin).unwrap();
1497        assert_eq!(
1498            entry.waiters.load(Ordering::Acquire),
1499            0,
1500            "cancelled waiter must release its registration"
1501        );
1502    }
1503
1504    #[tokio::test]
1505    async fn repeated_cancellation_does_not_wedge_origin() {
1506        let pool = Pool::new(PoolConfig {
1507            max_connections_per_host: Some(1),
1508            ..Default::default()
1509        });
1510        let origin = OriginKey::from_parts("http", "wedge.example", 80);
1511        for _ in 0..10 {
1512            let holder = pool.acquire(Some(&origin)).await.unwrap();
1513            let timed_out = tokio::time::timeout(
1514                std::time::Duration::from_millis(10),
1515                pool.acquire(Some(&origin)),
1516            )
1517            .await;
1518            assert!(timed_out.is_err());
1519            drop(holder);
1520        }
1521        // After repeated cancel cycles a valid request must still succeed and
1522        // leave no leaked waiter registration.
1523        let _guard = tokio::time::timeout(
1524            std::time::Duration::from_secs(2),
1525            pool.acquire(Some(&origin)),
1526        )
1527        .await
1528        .unwrap()
1529        .unwrap();
1530        let entry = pool.inner.per_origin_get_for_test(&origin).unwrap();
1531        assert_eq!(entry.waiters.load(Ordering::Acquire), 0);
1532    }
1533
1534    #[tokio::test]
1535    async fn live_permit_blocks_eviction_on_churn() {
1536        let pool = Pool::new(PoolConfig {
1537            max_connections_per_host: Some(1),
1538            ..Default::default()
1539        });
1540        let pinned = OriginKey::from_parts("http", "pinned.example", 80);
1541        let _holder = pool.acquire(Some(&pinned)).await.unwrap();
1542        for index in 0..16 {
1543            let origin = OriginKey::from_parts("http", &format!("churn-{index}.example"), 80);
1544            drop(pool.acquire(Some(&origin)).await.unwrap());
1545        }
1546        assert!(
1547            pool.inner.per_origin_contains_for_test(&pinned),
1548            "entry with a live permit must not be evicted"
1549        );
1550        // The limit must still be enforced for the pinned origin.
1551        assert!(
1552            tokio::time::timeout(
1553                std::time::Duration::from_millis(10),
1554                pool.acquire(Some(&pinned))
1555            )
1556            .await
1557            .is_err(),
1558            "pinned origin must still enforce its per-origin limit"
1559        );
1560    }
1561
1562    #[tokio::test]
1563    async fn registered_waiter_blocks_eviction_on_churn() {
1564        let pool = Pool::new(PoolConfig {
1565            max_connections_per_host: Some(1),
1566            ..Default::default()
1567        });
1568        let origin = OriginKey::from_parts("http", "waited.example", 80);
1569        let holder = pool.acquire(Some(&origin)).await.unwrap();
1570        let pool_for_task = pool.clone();
1571        let origin_for_task = origin.clone();
1572        let waiter =
1573            tokio::spawn(async move { pool_for_task.acquire(Some(&origin_for_task)).await });
1574        // Wait until the waiter has registered (bounded spin, no fixed sleep).
1575        let mut registered = false;
1576        for _ in 0..200 {
1577            tokio::task::yield_now().await;
1578            if let Some(entry) = pool.inner.per_origin_get_for_test(&origin) {
1579                if entry.waiters.load(Ordering::Acquire) == 1 {
1580                    registered = true;
1581                    break;
1582                }
1583            }
1584        }
1585        assert!(registered, "waiter must register before churn");
1586        for index in 0..16 {
1587            let churn = OriginKey::from_parts("http", &format!("churn-w-{index}.example"), 80);
1588            drop(pool.acquire(Some(&churn)).await.unwrap());
1589        }
1590        assert!(
1591            pool.inner.per_origin_contains_for_test(&origin),
1592            "entry with a registered waiter must not be evicted"
1593        );
1594        drop(holder);
1595        let guard = tokio::time::timeout(std::time::Duration::from_secs(2), waiter)
1596            .await
1597            .unwrap()
1598            .unwrap()
1599            .unwrap();
1600        drop(guard);
1601    }
1602
1603    #[tokio::test]
1604    async fn concurrent_missing_origin_creation_shares_one_semaphore() {
1605        use tokio::sync::Barrier;
1606
1607        let pool = Pool::new(PoolConfig {
1608            max_connections_per_host: Some(3),
1609            ..Default::default()
1610        });
1611        let origin = OriginKey::from_parts("http", "race.example", 80);
1612        // Deterministic seam around the table helper: all tasks rendezvous
1613        // before touching the missing key, maximizing the creation race
1614        // window without relying on sleep timing.
1615        let barrier = Arc::new(Barrier::new(16));
1616        let mut handles = Vec::new();
1617        for _ in 0..16 {
1618            let pool = pool.clone();
1619            let origin = origin.clone();
1620            let barrier = barrier.clone();
1621            handles.push(tokio::spawn(async move {
1622                barrier.wait().await;
1623                let (entry, guard) = pool.inner.lookup_or_create_registered(&origin, 3).unwrap();
1624                let ptr = Arc::as_ptr(&entry) as usize;
1625                drop(guard);
1626                ptr
1627            }));
1628        }
1629        let mut ptrs = Vec::new();
1630        for h in handles {
1631            ptrs.push(h.await.unwrap());
1632        }
1633        assert!(
1634            ptrs.windows(2).all(|w| w[0] == w[1]),
1635            "concurrent creation must share one semaphore allocation"
1636        );
1637        assert_eq!(pool.inner.per_origin_len_for_test(), 1);
1638    }
1639
1640    #[tokio::test]
1641    async fn churn_plus_cancellation_preserves_per_origin_limit() {
1642        use std::sync::atomic::AtomicUsize;
1643
1644        let pool = Pool::new(PoolConfig {
1645            max_connections_per_host: Some(2),
1646            ..Default::default()
1647        });
1648        let hot = OriginKey::from_parts("http", "hot-churn.example", 80);
1649        // Interleave churn, cancellations, and hot-origin load. No hot-origin
1650        // waiter may observe more than the configured permits at once.
1651        let current = Arc::new(AtomicUsize::new(0));
1652        let max_seen = Arc::new(AtomicUsize::new(0));
1653        let mut handles = Vec::new();
1654        for index in 0..24 {
1655            let pool = pool.clone();
1656            let hot = hot.clone();
1657            let current = current.clone();
1658            let max_seen = max_seen.clone();
1659            handles.push(tokio::spawn(async move {
1660                if index % 3 == 0 {
1661                    let churn = OriginKey::from_parts("http", &format!("mix-{index}.example"), 80);
1662                    drop(pool.acquire(Some(&churn)).await.unwrap());
1663                } else if index % 3 == 1 {
1664                    let _ = tokio::time::timeout(
1665                        std::time::Duration::from_millis(5),
1666                        pool.acquire(Some(&hot)),
1667                    )
1668                    .await;
1669                } else {
1670                    let _guard = pool.acquire(Some(&hot)).await.unwrap();
1671                    let n = current.fetch_add(1, Ordering::AcqRel) + 1;
1672                    max_seen.fetch_max(n, Ordering::AcqRel);
1673                    tokio::task::yield_now().await;
1674                    current.fetch_sub(1, Ordering::AcqRel);
1675                }
1676            }));
1677        }
1678        for h in handles {
1679            h.await.unwrap();
1680        }
1681        assert!(
1682            max_seen.load(Ordering::Acquire) <= 2,
1683            "churn plus cancellation must not exceed the per-origin limit"
1684        );
1685        // The hot entry must still be usable afterwards.
1686        let _guard =
1687            tokio::time::timeout(std::time::Duration::from_secs(2), pool.acquire(Some(&hot)))
1688                .await
1689                .unwrap()
1690                .unwrap();
1691    }
1692
1693    #[tokio::test]
1694    async fn pool_metrics_meanings_preserved() {
1695        // Immediate acquisitions never count as waits.
1696        let pool = Pool::new(PoolConfig {
1697            max_connections_per_host: Some(2),
1698            ..Default::default()
1699        });
1700        let origin = OriginKey::from_parts("http", "metrics.example", 80);
1701        let _g = pool.acquire(Some(&origin)).await.unwrap();
1702        assert_eq!(pool.metrics().acquisition_waits.load(Ordering::Relaxed), 0);
1703        // A blocked acquisition that eventually succeeds counts exactly one wait.
1704        let pool = Pool::new(PoolConfig {
1705            max_connections: Some(1),
1706            ..Default::default()
1707        });
1708        let holder = pool.acquire(None).await.unwrap();
1709        let pool_for_task = pool.clone();
1710        let waiter = tokio::spawn(async move { pool_for_task.acquire(None).await.unwrap() });
1711        tokio::task::yield_now().await;
1712        drop(holder);
1713        drop(waiter.await.unwrap());
1714        assert_eq!(pool.metrics().acquisition_waits.load(Ordering::Relaxed), 1);
1715        assert_eq!(
1716            pool.metrics()
1717                .acquisition_cancellations
1718                .load(Ordering::Relaxed),
1719            0
1720        );
1721    }
1722}