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    ///
58    /// Together with [`Self::max_idle_connections`] this resolves to one
59    /// effective per-host cap
60    /// (`max_idle_connections_per_host.or(max_idle_connections)`) shared by
61    /// every persistent Hyper client family.
62    pub max_idle_connections_per_host: Option<usize>,
63    /// Duration after which idle connections are closed (physical).
64    ///
65    /// When set, every persistent Hyper client also receives the pool timer
66    /// Hyper requires for background idle eviction.
67    pub keepalive_expiry: Option<Duration>,
68}
69
70impl Limits {
71    /// Effective global logical-request limit (new name wins).
72    #[must_use]
73    pub fn effective_max_in_flight(&self) -> Option<usize> {
74        self.max_in_flight_requests.or(self.max_connections)
75    }
76
77    /// Effective per-origin logical-request limit (new name wins).
78    #[must_use]
79    pub fn effective_max_in_flight_per_origin(&self) -> Option<usize> {
80        self.max_in_flight_requests_per_origin
81            .or(self.max_connections_per_host)
82    }
83}
84
85impl Limits {
86    /// Create HTTPX-compatible limits.
87    ///
88    /// HTTPX 0.28.1 defaults to 100 total connections with a 5-second
89    /// keepalive expiry. Per-host idle connections default to 20. No
90    /// per-host concurrency limit is set.
91    ///
92    /// # Examples
93    ///
94    /// ```
95    /// use eggfetch_core::Limits;
96    ///
97    /// let limits = Limits::compat();
98    /// assert_eq!(limits.max_connections, Some(100));
99    /// assert!(limits.max_connections_per_host.is_none());
100    /// assert_eq!(limits.max_idle_connections, Some(20));
101    /// assert_eq!(limits.max_idle_connections_per_host, Some(20));
102    /// assert_eq!(limits.keepalive_expiry, Some(std::time::Duration::from_secs(5)));
103    /// ```
104    #[must_use]
105    pub fn compat() -> Self {
106        Self {
107            max_connections: Some(100),
108            max_connections_per_host: None,
109            max_in_flight_requests: None,
110            max_in_flight_requests_per_origin: None,
111            max_idle_connections: Some(20),
112            max_idle_connections_per_host: Some(20),
113            keepalive_expiry: Some(Duration::from_secs(5)),
114        }
115    }
116
117    /// Create unlimited defaults (all `None`).
118    ///
119    /// No concurrency limits or idle connection caps are applied. Idle
120    /// connections are never proactively closed.
121    ///
122    /// # Examples
123    ///
124    /// ```
125    /// use eggfetch_core::Limits;
126    ///
127    /// let limits = Limits::native();
128    /// assert!(limits.max_connections.is_none());
129    /// assert!(limits.max_connections_per_host.is_none());
130    /// assert!(limits.max_idle_connections.is_none());
131    /// assert!(limits.max_idle_connections_per_host.is_none());
132    /// assert!(limits.keepalive_expiry.is_none());
133    /// ```
134    #[must_use]
135    pub fn native() -> Self {
136        Self::default()
137    }
138}
139
140impl From<Limits> for PoolConfig {
141    fn from(limits: Limits) -> Self {
142        Self {
143            max_connections: limits.max_connections,
144            max_connections_per_host: limits.max_connections_per_host,
145            max_in_flight_requests: limits.max_in_flight_requests,
146            max_in_flight_requests_per_origin: limits.max_in_flight_requests_per_origin,
147            max_idle_connections: limits.max_idle_connections,
148            max_idle_connections_per_host: limits.max_idle_connections_per_host,
149            idle_timeout: limits.keepalive_expiry,
150        }
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use super::*;
157
158    #[test]
159    fn default_limits_are_all_none() {
160        let limits = Limits::default();
161        assert!(limits.max_connections.is_none());
162        assert!(limits.max_connections_per_host.is_none());
163        assert!(limits.max_in_flight_requests.is_none());
164        assert!(limits.max_in_flight_requests_per_origin.is_none());
165        assert!(limits.max_idle_connections.is_none());
166        assert!(limits.max_idle_connections_per_host.is_none());
167        assert!(limits.keepalive_expiry.is_none());
168    }
169
170    #[test]
171    fn compat_limits_match_httpx() {
172        let limits = Limits::compat();
173        assert_eq!(limits.max_connections, Some(100));
174        assert!(limits.max_connections_per_host.is_none());
175        assert_eq!(limits.max_idle_connections, Some(20));
176        assert_eq!(limits.max_idle_connections_per_host, Some(20));
177        assert_eq!(limits.keepalive_expiry, Some(Duration::from_secs(5)));
178    }
179
180    #[test]
181    fn native_limits_are_unlimited() {
182        let limits = Limits::native();
183        assert_eq!(limits, Limits::default());
184    }
185
186    #[test]
187    fn limits_into_pool_config() {
188        let limits = Limits::compat();
189        let config: PoolConfig = limits.into();
190        assert_eq!(config.max_connections, Some(100));
191        assert!(config.max_connections_per_host.is_none());
192        assert_eq!(config.max_idle_connections, Some(20));
193        assert_eq!(config.max_idle_connections_per_host, Some(20));
194        assert_eq!(config.idle_timeout, Some(Duration::from_secs(5)));
195    }
196
197    #[test]
198    fn native_limits_into_pool_config() {
199        let limits = Limits::native();
200        let config: PoolConfig = limits.into();
201        assert_eq!(config.max_connections, None);
202        assert_eq!(config.max_connections_per_host, None);
203        assert_eq!(config.max_in_flight_requests, None);
204        assert_eq!(config.max_in_flight_requests_per_origin, None);
205        assert_eq!(config.max_idle_connections, None);
206        assert_eq!(config.max_idle_connections_per_host, None);
207        assert_eq!(config.idle_timeout, None);
208    }
209
210    #[test]
211    fn new_names_win_over_aliases() {
212        let limits = Limits {
213            max_connections: Some(10),
214            max_in_flight_requests: Some(7),
215            max_connections_per_host: Some(5),
216            max_in_flight_requests_per_origin: Some(3),
217            ..Limits::default()
218        };
219        assert_eq!(limits.effective_max_in_flight(), Some(7));
220        assert_eq!(limits.effective_max_in_flight_per_origin(), Some(3));
221        let config: PoolConfig = limits.into();
222        assert_eq!(config.effective_max_in_flight(), Some(7));
223        assert_eq!(config.effective_max_in_flight_per_origin(), Some(3));
224    }
225
226    #[test]
227    fn aliases_apply_when_new_names_absent() {
228        let limits = Limits {
229            max_connections: Some(11),
230            max_connections_per_host: Some(4),
231            ..Limits::default()
232        };
233        assert_eq!(limits.effective_max_in_flight(), Some(11));
234        assert_eq!(limits.effective_max_in_flight_per_origin(), Some(4));
235    }
236}