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