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}