Skip to main content

eggfetch_core/
limits.rs

1//! Resource limits for the connection pool.
2//!
3//! Distinguishes between logical request concurrency (pool permits)
4//! and physical connection behavior (hyper's internal pool).
5
6use std::time::Duration;
7
8use crate::pool::PoolConfig;
9
10/// Resource limits for the connection pool.
11///
12/// Distinguishes between logical request concurrency (pool permits,
13/// one per in-flight request) and physical connection behavior
14/// (Hyper's internal idle pool).
15///
16/// # Logical vs physical
17///
18/// - `max_in_flight_requests` / `max_in_flight_requests_per_origin` bound
19///   logical requests. Under H1 one request usually owns its connection
20///   slot; under H2/H3 many requests multiplex over one connection/QUIC
21///   session while each still holds a permit.
22/// - `max_idle_connections*` / `keepalive_expiry` are physical idle-pool
23///   policy passed to Hyper, not concurrency bounds.
24///
25/// `max_connections` / `max_connections_per_host` are compatibility
26/// aliases for the pre-1.0 line (same semantics as the new names; the
27/// HTTPX facade keeps `Limits(max_connections=...)` unchanged). When both
28/// alias and new name are set, the new name wins.
29#[derive(Debug, Clone, Default, PartialEq)]
30pub struct Limits {
31    /// Maximum concurrent logical requests (pool permits).
32    ///
33    /// Compatibility alias for `max_in_flight_requests`. Maps to pool
34    /// `max_connections`.
35    pub max_connections: Option<usize>,
36    /// Maximum concurrent logical requests per origin.
37    ///
38    /// Compatibility alias for `max_in_flight_requests_per_origin`. Maps
39    /// to pool `max_connections_per_host`.
40    pub max_connections_per_host: Option<usize>,
41    /// Maximum concurrent in-flight requests (logical, preferred name).
42    ///
43    /// One permit per request, not one TCP connection. H1/H2/H3 examples:
44    /// H1 serializes one request per connection; H2 multiplexes many
45    /// streams over one TCP connection up to the server's
46    /// `SETTINGS_MAX_CONCURRENT_STREAMS`; H3 multiplexes over QUIC with
47    /// bidi streams derived from the per-origin limit.
48    pub max_in_flight_requests: Option<usize>,
49    /// Maximum concurrent in-flight requests per origin (logical,
50    /// preferred name).
51    pub max_in_flight_requests_per_origin: Option<usize>,
52    /// Maximum number of idle (kept-alive) connections.
53    /// Maps to hyper's pool idle connection limit (physical).
54    pub max_idle_connections: Option<usize>,
55    /// Maximum number of idle connections per host (physical).
56    /// Maps to hyper's pool per-host idle limit.
57    pub max_idle_connections_per_host: Option<usize>,
58    /// Duration after which idle connections are closed (physical).
59    pub keepalive_expiry: Option<Duration>,
60}
61
62impl Limits {
63    /// Effective global logical-request limit (new name wins).
64    #[must_use]
65    pub fn effective_max_in_flight(&self) -> Option<usize> {
66        self.max_in_flight_requests.or(self.max_connections)
67    }
68
69    /// Effective per-origin logical-request limit (new name wins).
70    #[must_use]
71    pub fn effective_max_in_flight_per_origin(&self) -> Option<usize> {
72        self.max_in_flight_requests_per_origin
73            .or(self.max_connections_per_host)
74    }
75}
76
77impl Limits {
78    /// Create HTTPX-compatible limits.
79    ///
80    /// HTTPX 0.28.1 defaults to 100 total connections with a 5-second
81    /// keepalive expiry. Per-host idle connections default to 20. No
82    /// per-host concurrency limit is set.
83    ///
84    /// # Examples
85    ///
86    /// ```
87    /// use eggfetch_core::Limits;
88    ///
89    /// let limits = Limits::compat();
90    /// assert_eq!(limits.max_connections, Some(100));
91    /// assert!(limits.max_connections_per_host.is_none());
92    /// assert_eq!(limits.max_idle_connections, Some(20));
93    /// assert_eq!(limits.max_idle_connections_per_host, Some(20));
94    /// assert_eq!(limits.keepalive_expiry, Some(std::time::Duration::from_secs(5)));
95    /// ```
96    #[must_use]
97    pub fn compat() -> Self {
98        Self {
99            max_connections: Some(100),
100            max_connections_per_host: None,
101            max_in_flight_requests: None,
102            max_in_flight_requests_per_origin: None,
103            max_idle_connections: Some(20),
104            max_idle_connections_per_host: Some(20),
105            keepalive_expiry: Some(Duration::from_secs(5)),
106        }
107    }
108
109    /// Create unlimited defaults (all `None`).
110    ///
111    /// No concurrency limits or idle connection caps are applied. Idle
112    /// connections are never proactively closed.
113    ///
114    /// # Examples
115    ///
116    /// ```
117    /// use eggfetch_core::Limits;
118    ///
119    /// let limits = Limits::native();
120    /// assert!(limits.max_connections.is_none());
121    /// assert!(limits.max_connections_per_host.is_none());
122    /// assert!(limits.max_idle_connections.is_none());
123    /// assert!(limits.max_idle_connections_per_host.is_none());
124    /// assert!(limits.keepalive_expiry.is_none());
125    /// ```
126    #[must_use]
127    pub fn native() -> Self {
128        Self::default()
129    }
130}
131
132impl From<Limits> for PoolConfig {
133    fn from(limits: Limits) -> Self {
134        Self {
135            max_connections: limits.max_connections,
136            max_connections_per_host: limits.max_connections_per_host,
137            max_in_flight_requests: limits.max_in_flight_requests,
138            max_in_flight_requests_per_origin: limits.max_in_flight_requests_per_origin,
139            max_idle_connections: limits.max_idle_connections,
140            max_idle_connections_per_host: limits.max_idle_connections_per_host,
141            idle_timeout: limits.keepalive_expiry,
142        }
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    #[test]
151    fn default_limits_are_all_none() {
152        let limits = Limits::default();
153        assert!(limits.max_connections.is_none());
154        assert!(limits.max_connections_per_host.is_none());
155        assert!(limits.max_in_flight_requests.is_none());
156        assert!(limits.max_in_flight_requests_per_origin.is_none());
157        assert!(limits.max_idle_connections.is_none());
158        assert!(limits.max_idle_connections_per_host.is_none());
159        assert!(limits.keepalive_expiry.is_none());
160    }
161
162    #[test]
163    fn compat_limits_match_httpx() {
164        let limits = Limits::compat();
165        assert_eq!(limits.max_connections, Some(100));
166        assert!(limits.max_connections_per_host.is_none());
167        assert_eq!(limits.max_idle_connections, Some(20));
168        assert_eq!(limits.max_idle_connections_per_host, Some(20));
169        assert_eq!(limits.keepalive_expiry, Some(Duration::from_secs(5)));
170    }
171
172    #[test]
173    fn native_limits_are_unlimited() {
174        let limits = Limits::native();
175        assert_eq!(limits, Limits::default());
176    }
177
178    #[test]
179    fn limits_into_pool_config() {
180        let limits = Limits::compat();
181        let config: PoolConfig = limits.into();
182        assert_eq!(config.max_connections, Some(100));
183        assert!(config.max_connections_per_host.is_none());
184        assert_eq!(config.max_idle_connections, Some(20));
185        assert_eq!(config.max_idle_connections_per_host, Some(20));
186        assert_eq!(config.idle_timeout, Some(Duration::from_secs(5)));
187    }
188
189    #[test]
190    fn native_limits_into_pool_config() {
191        let limits = Limits::native();
192        let config: PoolConfig = limits.into();
193        assert_eq!(config.max_connections, None);
194        assert_eq!(config.max_connections_per_host, None);
195        assert_eq!(config.max_in_flight_requests, None);
196        assert_eq!(config.max_in_flight_requests_per_origin, None);
197        assert_eq!(config.max_idle_connections, None);
198        assert_eq!(config.max_idle_connections_per_host, None);
199        assert_eq!(config.idle_timeout, None);
200    }
201
202    #[test]
203    fn new_names_win_over_aliases() {
204        let limits = Limits {
205            max_connections: Some(10),
206            max_in_flight_requests: Some(7),
207            max_connections_per_host: Some(5),
208            max_in_flight_requests_per_origin: Some(3),
209            ..Limits::default()
210        };
211        assert_eq!(limits.effective_max_in_flight(), Some(7));
212        assert_eq!(limits.effective_max_in_flight_per_origin(), Some(3));
213        let config: PoolConfig = limits.into();
214        assert_eq!(config.effective_max_in_flight(), Some(7));
215        assert_eq!(config.effective_max_in_flight_per_origin(), Some(3));
216    }
217
218    #[test]
219    fn aliases_apply_when_new_names_absent() {
220        let limits = Limits {
221            max_connections: Some(11),
222            max_connections_per_host: Some(4),
223            ..Limits::default()
224        };
225        assert_eq!(limits.effective_max_in_flight(), Some(11));
226        assert_eq!(limits.effective_max_in_flight_per_origin(), Some(4));
227    }
228}