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