Skip to main content

net_io/
limits.rs

1//! Every bound net-io enforces, in one value.
2
3use std::time::Duration;
4
5use crate::addr::PrefixPolicy;
6use crate::driver::DriverKind;
7use crate::error::{ConfigReason, NetError};
8use crate::info::Lane;
9
10/// Lanes that can hold a connection reservation (0 to 7).
11const RESERVED_LANES: usize = 8;
12
13/// A minimum transfer rate, checked per direction while that direction is active.
14///
15/// # Examples
16///
17/// ```
18/// use std::time::Duration;
19/// let rate = net_io::MinRate::new(512, Duration::from_secs(10));
20/// assert_eq!(rate.grace, Duration::from_secs(5));
21/// assert!(net_io::MinRate::off().is_off());
22/// ```
23#[derive(Clone, Copy, Debug, PartialEq, Eq)]
24pub struct MinRate {
25    /// Bytes per second the peer must reach over the window.
26    pub bytes_per_sec: u32,
27    /// The sliding window.
28    pub window: Duration,
29    /// How long after a direction becomes active the check starts.
30    pub grace: Duration,
31    /// How often the rate is checked.
32    pub check: Duration,
33}
34
35impl MinRate {
36    /// No minimum rate.
37    #[must_use]
38    pub const fn off() -> MinRate {
39        MinRate {
40            bytes_per_sec: 0,
41            window: Duration::from_secs(10),
42            grace: Duration::from_secs(5),
43            check: Duration::from_secs(1),
44        }
45    }
46
47    /// `bytes_per_sec` over `window`, after a 5 s grace, checked every second.
48    #[must_use]
49    pub const fn new(bytes_per_sec: u32, window: Duration) -> MinRate {
50        MinRate {
51            bytes_per_sec,
52            window,
53            grace: Duration::from_secs(5),
54            check: Duration::from_secs(1),
55        }
56    }
57
58    /// Whether the rate check is off.
59    #[must_use]
60    pub const fn is_off(&self) -> bool {
61        self.bytes_per_sec == 0
62    }
63}
64
65/// Adaptive deadlines: past `high` of `max_connections`, the handshake and idle
66/// deadlines of new and waiting connections are multiplied by `factor`, down to 1 s,
67/// until the count falls below `low`. No cost below the threshold beyond one check
68/// per connection opened or closed.
69///
70/// ```
71/// let p = net_io::Pressure::default();
72/// assert!(p.high > p.low);
73/// ```
74#[derive(Clone, Copy, Debug, PartialEq)]
75pub struct Pressure {
76    /// Fraction of `max_connections` above which deadlines shrink.
77    pub high: f32,
78    /// Fraction below which they return to normal.
79    pub low: f32,
80    /// The multiplier applied to handshake and idle timeouts.
81    pub factor: f32,
82}
83
84impl Default for Pressure {
85    fn default() -> Pressure {
86        Pressure {
87            high: 0.8,
88            low: 0.6,
89            factor: 0.25,
90        }
91    }
92}
93
94/// A buffer size class: a power of two from 1 KiB to 1 MiB.
95///
96/// ```
97/// use net_io::SizeClass;
98/// assert_eq!(SizeClass::MEDIUM.bytes(), 16 * 1024);
99/// assert!(SizeClass::new(3000).is_err());
100/// assert_eq!(SizeClass::new(2048).unwrap().bytes(), 2048);
101/// ```
102#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
103pub struct SizeClass(u32);
104
105impl SizeClass {
106    /// 4 KiB.
107    pub const SMALL: SizeClass = SizeClass(4 * 1024);
108    /// 16 KiB.
109    pub const MEDIUM: SizeClass = SizeClass(16 * 1024);
110    /// 64 KiB.
111    pub const LARGE: SizeClass = SizeClass(64 * 1024);
112
113    /// A class of `bytes`.
114    ///
115    /// # Errors
116    ///
117    /// `InvalidConfig { field: "size_class" }` unless `bytes` is a power of two from 1 KiB to 1 MiB.
118    pub const fn new(bytes: u32) -> Result<SizeClass, NetError> {
119        if !bytes.is_power_of_two() {
120            return Err(NetError::InvalidConfig {
121                field: "size_class",
122                reason: ConfigReason::Inconsistent,
123            });
124        }
125        if bytes < 1024 {
126            return Err(NetError::InvalidConfig {
127                field: "size_class",
128                reason: ConfigReason::TooSmall { min: 1024 },
129            });
130        }
131        if bytes > 1024 * 1024 {
132            return Err(NetError::InvalidConfig {
133                field: "size_class",
134                reason: ConfigReason::TooLarge { max: 1024 * 1024 },
135            });
136        }
137        Ok(SizeClass(bytes))
138    }
139
140    /// The size in bytes.
141    #[must_use]
142    pub const fn bytes(self) -> u32 {
143        self.0
144    }
145}
146
147/// Every bound net-io enforces. Unset values take the defaults of the driver
148/// that runs the connection.
149///
150/// # Examples
151///
152/// ```
153/// use net_io::{DriverKind, Limits, MinRate};
154/// use std::time::Duration;
155///
156/// let limits = Limits::builder()
157///     .max_connections(20_000)
158///     .idle_timeout(Duration::from_secs(15))
159///     .min_rate(MinRate::new(512, Duration::from_secs(10)))
160///     .build()?;
161/// assert_eq!(limits.max_connections(), Some(20_000));
162/// assert_eq!(limits.read_timeout(), None);
163/// assert_eq!(limits.resolve(DriverKind::Blocking).read_timeout(), Some(Duration::from_secs(30)));
164/// # Ok::<(), net_io::NetError>(())
165/// ```
166#[non_exhaustive]
167#[derive(Clone, Debug, Default, PartialEq)]
168pub struct Limits {
169    max_connections: Option<u32>,
170    max_per_listener: Option<u32>,
171    max_per_source: Option<(u32, PrefixPolicy)>,
172    backlog: Option<u32>,
173    accept_batch: Option<u16>,
174    handshake_timeout: Option<Duration>,
175    idle_timeout: Option<Duration>,
176    read_timeout: Option<Duration>,
177    write_timeout: Option<Duration>,
178    park_timeout: Option<Duration>,
179    min_rate: Option<MinRate>,
180    proxy_header_max: Option<u16>,
181    read_class: Option<(SizeClass, SizeClass)>,
182    output_budget: Option<u32>,
183    completion_queue: Option<u32>,
184    buffer_budget: Option<u64>,
185    drain_timeout: Option<Duration>,
186    first_request_grace: Option<Duration>,
187    graceful_linger: Option<(Duration, u32)>,
188    denial_linger: Option<Duration>,
189    denial_linger_max: Option<u32>,
190    refusal_bytes_max: Option<u16>,
191    tick: Option<Duration>,
192    pressure: Option<Pressure>,
193    lane_reserve: [Option<u32>; RESERVED_LANES],
194}
195
196/// The resolved values a running connection uses.
197#[derive(Clone, Copy, Debug, PartialEq)]
198pub(crate) struct Effective {
199    pub max_connections: u32,
200    pub max_per_listener: u32,
201    pub max_per_source: u32,
202    pub source_policy: PrefixPolicy,
203    pub backlog: u32,
204    pub accept_batch: u16,
205    pub handshake_timeout: Duration,
206    pub idle_timeout: Duration,
207    pub read_timeout: Duration,
208    pub write_timeout: Duration,
209    pub park_timeout: Duration,
210    pub min_rate: MinRate,
211    pub proxy_header_max: u16,
212    pub read_class: SizeClass,
213    pub read_class_max: SizeClass,
214    pub output_budget: u32,
215    pub completion_queue: u32,
216    pub buffer_budget: u64,
217    pub drain_timeout: Duration,
218    /// How long a drain lets a connection that has sent nothing yet bring its first
219    /// request before it counts as idle.
220    pub first_request_grace: Duration,
221    pub graceful_linger: Duration,
222    pub graceful_linger_bytes: u32,
223    pub denial_linger: Duration,
224    /// Soft closes (denial lingers and `close_after_flush`) at once, server-wide.
225    pub denial_linger_max: u32,
226    pub refusal_bytes_max: u16,
227    pub tick: Duration,
228    pub pressure: Option<Pressure>,
229    /// Slots each of the most important lanes keeps free from the less important.
230    pub lane_reserve: [u32; RESERVED_LANES],
231}
232
233/// The default cap on soft closes: a sixteenth of the connection cap, at least 1.
234fn soft_close_cap(max_connections: u32) -> u32 {
235    (max_connections / 16).max(1)
236}
237
238impl Effective {
239    /// The slots the lanes more important than `lane` keep free.
240    pub(crate) fn reserved_above(&self, lane: Lane) -> u32 {
241        self.lane_reserve
242            .iter()
243            .take(usize::from(lane.0))
244            .fold(0u32, |sum, r| sum.saturating_add(*r))
245    }
246
247    /// The defaults of `driver` (blocking, or the reactor).
248    pub(crate) fn defaults(driver: DriverKind) -> Effective {
249        let blocking = driver.resolve() == DriverKind::Blocking;
250        let max_connections = if blocking { 128 } else { 10_000 };
251        Effective {
252            max_connections,
253            max_per_listener: max_connections,
254            max_per_source: if blocking { 16 } else { 256 },
255            source_policy: PrefixPolicy::DEFAULT,
256            backlog: 1024,
257            accept_batch: if blocking { 16 } else { 64 },
258            handshake_timeout: Duration::from_secs(10),
259            idle_timeout: Duration::from_secs(if blocking { 5 } else { 60 }),
260            read_timeout: Duration::from_secs(30),
261            write_timeout: Duration::from_secs(30),
262            park_timeout: Duration::from_secs(30),
263            min_rate: MinRate::new(256, Duration::from_secs(10)),
264            proxy_header_max: 1024,
265            read_class: SizeClass::MEDIUM,
266            read_class_max: SizeClass::LARGE,
267            output_budget: 64 * 1024,
268            completion_queue: if blocking { 1 } else { 1024 },
269            buffer_budget: if blocking { 64 << 20 } else { 512 << 20 },
270            drain_timeout: Duration::from_secs(30),
271            first_request_grace: Duration::from_secs(1),
272            graceful_linger: Duration::from_secs(2),
273            graceful_linger_bytes: 64 * 1024,
274            denial_linger: Duration::from_millis(100),
275            denial_linger_max: soft_close_cap(max_connections),
276            refusal_bytes_max: 512,
277            tick: Duration::from_millis(if blocking { 10 } else { 1 }),
278            pressure: None,
279            lane_reserve: [0; RESERVED_LANES],
280        }
281    }
282}
283
284impl Limits {
285    /// A builder with every value unset.
286    ///
287    /// ```
288    /// let limits = net_io::Limits::builder().max_connections(100).build()?;
289    /// assert_eq!(limits.max_per_source(), None);
290    /// # Ok::<(), net_io::NetError>(())
291    /// ```
292    pub fn builder() -> LimitsBuilder {
293        LimitsBuilder::default()
294    }
295
296    /// Every value set to the reactor's defaults.
297    ///
298    /// ```
299    /// assert_eq!(net_io::Limits::reactor_defaults().max_connections(), Some(10_000));
300    /// ```
301    #[must_use]
302    pub fn reactor_defaults() -> Limits {
303        Limits::from_effective(&Effective::defaults(DriverKind::Reactor))
304    }
305
306    /// Every value set to the blocking driver's defaults.
307    ///
308    /// ```
309    /// assert_eq!(net_io::Limits::blocking_defaults().idle_timeout(), Some(std::time::Duration::from_secs(5)));
310    /// ```
311    #[must_use]
312    pub fn blocking_defaults() -> Limits {
313        Limits::from_effective(&Effective::defaults(DriverKind::Blocking))
314    }
315
316    /// A builder starting from these values.
317    ///
318    /// Every value carried over counts as set, so lowering `max_connections`
319    /// below a carried-over `max_per_listener` fails validation. Start from
320    /// [`Limits::builder`] to let dependent values follow `max_connections`.
321    ///
322    /// ```
323    /// let limits = net_io::Limits::blocking_defaults().to_builder().max_connections(256).build()?;
324    /// assert_eq!(limits.max_connections(), Some(256));
325    /// # Ok::<(), net_io::NetError>(())
326    /// ```
327    pub fn to_builder(&self) -> LimitsBuilder {
328        LimitsBuilder {
329            limits: self.clone(),
330            bad_lane: false,
331        }
332    }
333
334    /// These limits with unset values filled from `driver`'s defaults.
335    ///
336    /// ```
337    /// let limits = net_io::Limits::builder().max_connections(10).build()?;
338    /// let resolved = limits.resolve(net_io::DriverKind::Blocking);
339    /// assert_eq!(resolved.max_per_source().map(|(n, _)| n), Some(10));
340    /// # Ok::<(), net_io::NetError>(())
341    /// ```
342    #[must_use]
343    pub fn resolve(&self, driver: DriverKind) -> Limits {
344        let mut out = Limits::from_effective(&self.effective(driver));
345        out.pressure = self.pressure;
346        out.lane_reserve = self.lane_reserve;
347        out
348    }
349
350    /// Checks the values, with unset ones taken from the blocking driver's
351    /// defaults, against each other, the worker count, and the process's
352    /// descriptor limit. `ServerBuilder::build` runs the same checks with the
353    /// defaults of the driver it resolved.
354    ///
355    /// # Errors
356    ///
357    /// `InvalidConfig { field, reason }` for the first rule broken.
358    ///
359    /// ```
360    /// let limits = net_io::Limits::builder().max_connections(1_000_000).build()?;
361    /// assert!(limits.validate(4, Some(1024)).is_err());
362    /// # Ok::<(), net_io::NetError>(())
363    /// ```
364    pub fn validate(&self, workers: u16, descriptor_limit: Option<u64>) -> Result<(), NetError> {
365        self.validate_for(DriverKind::Blocking, workers, descriptor_limit)
366    }
367
368    /// As `validate`, with unset values from `driver`'s defaults: a reactor's
369    /// buffer budget is not the blocking pool's.
370    pub(crate) fn validate_for(
371        &self,
372        driver: DriverKind,
373        workers: u16,
374        descriptor_limit: Option<u64>,
375    ) -> Result<(), NetError> {
376        // Rules that need only the values themselves.
377        LimitsBuilder {
378            limits: self.clone(),
379            bad_lane: false,
380        }
381        .check()?;
382        let e = self.effective(driver);
383        let need_budget = u64::from(workers)
384            .saturating_mul(u64::from(e.read_class_max.bytes()))
385            .saturating_mul(2);
386        if e.buffer_budget < need_budget {
387            return Err(invalid(
388                "buffer_budget",
389                ConfigReason::BudgetBelowWorkers { need: need_budget },
390            ));
391        }
392        if let Some(have) = descriptor_limit {
393            let need = descriptors_needed(e.max_connections, workers);
394            if need > have {
395                return Err(invalid(
396                    "max_connections",
397                    ConfigReason::DescriptorLimit { have, need },
398                ));
399            }
400        }
401        Ok(())
402    }
403
404    /// The resolved values for `driver`.
405    pub(crate) fn effective(&self, driver: DriverKind) -> Effective {
406        let d = Effective::defaults(driver);
407        let max_connections = self.max_connections.unwrap_or(d.max_connections);
408        let (max_per_source, source_policy) = self
409            .max_per_source
410            .unwrap_or((d.max_per_source.min(max_connections), d.source_policy));
411        let (read_class, read_class_max) =
412            self.read_class.unwrap_or((d.read_class, d.read_class_max));
413        let (graceful_linger, graceful_linger_bytes) = self
414            .graceful_linger
415            .unwrap_or((d.graceful_linger, d.graceful_linger_bytes));
416        Effective {
417            max_connections,
418            max_per_listener: self.max_per_listener.unwrap_or(max_connections),
419            max_per_source,
420            source_policy,
421            backlog: self.backlog.unwrap_or(d.backlog),
422            accept_batch: self.accept_batch.unwrap_or(d.accept_batch),
423            handshake_timeout: self.handshake_timeout.unwrap_or(d.handshake_timeout),
424            idle_timeout: self.idle_timeout.unwrap_or(d.idle_timeout),
425            read_timeout: self.read_timeout.unwrap_or(d.read_timeout),
426            write_timeout: self.write_timeout.unwrap_or(d.write_timeout),
427            park_timeout: self.park_timeout.unwrap_or(d.park_timeout),
428            min_rate: self.min_rate.unwrap_or(d.min_rate),
429            proxy_header_max: self.proxy_header_max.unwrap_or(d.proxy_header_max),
430            read_class,
431            read_class_max,
432            output_budget: self.output_budget.unwrap_or(d.output_budget),
433            completion_queue: self.completion_queue.unwrap_or(d.completion_queue),
434            buffer_budget: self.buffer_budget.unwrap_or(d.buffer_budget),
435            drain_timeout: self.drain_timeout.unwrap_or(d.drain_timeout),
436            first_request_grace: self.first_request_grace.unwrap_or(d.first_request_grace),
437            graceful_linger,
438            graceful_linger_bytes,
439            denial_linger: self.denial_linger.unwrap_or(d.denial_linger),
440            denial_linger_max: self
441                .denial_linger_max
442                .unwrap_or_else(|| soft_close_cap(max_connections)),
443            refusal_bytes_max: self.refusal_bytes_max.unwrap_or(d.refusal_bytes_max),
444            tick: self.tick.unwrap_or(d.tick),
445            pressure: self.pressure,
446            lane_reserve: self.lane_reserve.map(|v| v.unwrap_or(0)),
447        }
448    }
449
450    /// Values from `other` where it sets them, otherwise from `self` (listener overrides).
451    pub(crate) fn overlay(&self, other: &Limits) -> Limits {
452        macro_rules! pick {
453            ($($f:ident),*) => { Limits { $($f: other.$f.or(self.$f),)* lane_reserve: {
454                let mut r = self.lane_reserve;
455                for (i, v) in other.lane_reserve.iter().enumerate() { if v.is_some() { r[i] = *v; } }
456                r
457            } } };
458        }
459        pick!(
460            max_connections,
461            max_per_listener,
462            max_per_source,
463            backlog,
464            accept_batch,
465            handshake_timeout,
466            idle_timeout,
467            read_timeout,
468            write_timeout,
469            park_timeout,
470            min_rate,
471            proxy_header_max,
472            read_class,
473            output_budget,
474            completion_queue,
475            buffer_budget,
476            drain_timeout,
477            first_request_grace,
478            graceful_linger,
479            denial_linger,
480            denial_linger_max,
481            refusal_bytes_max,
482            tick,
483            pressure
484        )
485    }
486
487    fn from_effective(e: &Effective) -> Limits {
488        Limits {
489            max_connections: Some(e.max_connections),
490            max_per_listener: Some(e.max_per_listener),
491            max_per_source: Some((e.max_per_source, e.source_policy)),
492            backlog: Some(e.backlog),
493            accept_batch: Some(e.accept_batch),
494            handshake_timeout: Some(e.handshake_timeout),
495            idle_timeout: Some(e.idle_timeout),
496            read_timeout: Some(e.read_timeout),
497            write_timeout: Some(e.write_timeout),
498            park_timeout: Some(e.park_timeout),
499            min_rate: Some(e.min_rate),
500            proxy_header_max: Some(e.proxy_header_max),
501            read_class: Some((e.read_class, e.read_class_max)),
502            output_budget: Some(e.output_budget),
503            completion_queue: Some(e.completion_queue),
504            buffer_budget: Some(e.buffer_budget),
505            drain_timeout: Some(e.drain_timeout),
506            first_request_grace: Some(e.first_request_grace),
507            graceful_linger: Some((e.graceful_linger, e.graceful_linger_bytes)),
508            denial_linger: Some(e.denial_linger),
509            denial_linger_max: Some(e.denial_linger_max),
510            refusal_bytes_max: Some(e.refusal_bytes_max),
511            tick: Some(e.tick),
512            pressure: None,
513            lane_reserve: [None; RESERVED_LANES],
514        }
515    }
516
517    /// The global connection cap.
518    #[must_use]
519    pub fn max_connections(&self) -> Option<u32> {
520        self.max_connections
521    }
522    /// The per-listener connection cap.
523    #[must_use]
524    pub fn max_per_listener(&self) -> Option<u32> {
525        self.max_per_listener
526    }
527    /// The per-source concurrency cap and how sources are grouped. Each listener
528    /// applies its own value to its own connections. Every open connection counts,
529    /// including one finishing a graceful close, so a client at the cap that
530    /// reconnects at once can be refused until its last connection is closed.
531    #[must_use]
532    pub fn max_per_source(&self) -> Option<(u32, PrefixPolicy)> {
533        self.max_per_source
534    }
535    /// The listen backlog.
536    #[must_use]
537    pub fn backlog(&self) -> Option<u32> {
538        self.backlog
539    }
540    /// Connections accepted per wake-up.
541    #[must_use]
542    pub fn accept_batch(&self) -> Option<u16> {
543        self.accept_batch
544    }
545    /// Time for the PROXY header and TLS handshake together.
546    #[must_use]
547    pub fn handshake_timeout(&self) -> Option<Duration> {
548        self.handshake_timeout
549    }
550    /// Time to wait for the next exchange.
551    #[must_use]
552    pub fn idle_timeout(&self) -> Option<Duration> {
553        self.idle_timeout
554    }
555    /// Time to wait for bytes during an exchange.
556    #[must_use]
557    pub fn read_timeout(&self) -> Option<Duration> {
558        self.read_timeout
559    }
560    /// Time to wait for the peer to take bytes.
561    #[must_use]
562    pub fn write_timeout(&self) -> Option<Duration> {
563        self.write_timeout
564    }
565    /// Time a parked connection may wait for its completion.
566    #[must_use]
567    pub fn park_timeout(&self) -> Option<Duration> {
568        self.park_timeout
569    }
570    /// The minimum transfer rate.
571    #[must_use]
572    pub fn min_rate(&self) -> Option<MinRate> {
573        self.min_rate
574    }
575    /// The PROXY v2 address-and-TLV cap.
576    #[must_use]
577    pub fn proxy_header_max(&self) -> Option<u16> {
578        self.proxy_header_max
579    }
580    /// The initial and maximum read buffer class.
581    #[must_use]
582    pub fn read_class(&self) -> Option<(SizeClass, SizeClass)> {
583        self.read_class
584    }
585    /// Pool memory a connection's output may hold.
586    #[must_use]
587    pub fn output_budget(&self) -> Option<u32> {
588        self.output_budget
589    }
590    /// A worker's completion queue length.
591    #[must_use]
592    pub fn completion_queue(&self) -> Option<u32> {
593        self.completion_queue
594    }
595    /// Total bytes of buffers all workers may allocate.
596    ///
597    /// Each worker's pool keeps at most the budget divided by the workers in its
598    /// free lists and frees what is released above that, and a pool that needs a
599    /// buffer of one size with the budget spent frees the buffers it keeps of other
600    /// sizes first, so the budget comes back after a burst.
601    ///
602    /// On the reactor a TLS connection takes its two buffers (the largest read class
603    /// in, 64 KiB out) only when its first bytes arrive, and the connections whose
604    /// handshake has not finished may hold at most a quarter of the budget, divided
605    /// by the workers, on each worker (at least one handshake each). A connection
606    /// whose handshake would take buffers above that is closed with
607    /// `Limit(BufferBudget)`; plaintext connections keep the rest.
608    #[must_use]
609    pub fn buffer_budget(&self) -> Option<u64> {
610        self.buffer_budget
611    }
612    /// The drain deadline.
613    #[must_use]
614    pub fn drain_timeout(&self) -> Option<Duration> {
615        self.drain_timeout
616    }
617    /// How long a drain waits for the first request of a connection that has sent
618    /// nothing yet.
619    #[must_use]
620    pub fn first_request_grace(&self) -> Option<Duration> {
621        self.first_request_grace
622    }
623    /// The graceful-close linger: time and bytes read and discarded.
624    #[must_use]
625    pub fn graceful_linger(&self) -> Option<(Duration, u32)> {
626        self.graceful_linger
627    }
628    /// How long a connection that was sent a denial lingers before it closes.
629    #[must_use]
630    pub fn denial_linger(&self) -> Option<Duration> {
631        self.denial_linger
632    }
633    /// How many connections may close softly (linger after a denial, or
634    /// `close_after_flush`) at once, server-wide.
635    #[must_use]
636    pub fn denial_linger_max(&self) -> Option<u32> {
637        self.denial_linger_max
638    }
639    /// The largest refusal reply.
640    #[must_use]
641    pub fn refusal_bytes_max(&self) -> Option<u16> {
642        self.refusal_bytes_max
643    }
644    /// The timer resolution.
645    #[must_use]
646    pub fn tick(&self) -> Option<Duration> {
647        self.tick
648    }
649    /// Adaptive deadlines under pressure.
650    #[must_use]
651    pub fn pressure(&self) -> Option<Pressure> {
652        self.pressure
653    }
654    /// The connection slots reserved for `lane` (lanes 0 to 7).
655    #[must_use]
656    pub fn lane_reserve(&self, lane: Lane) -> Option<u32> {
657        self.lane_reserve
658            .get(usize::from(lane.0))
659            .copied()
660            .flatten()
661    }
662}
663
664/// Descriptors a configuration needs: connections, two wake descriptors per
665/// worker, and a fixed reserve for listeners and the spare descriptor.
666pub(crate) fn descriptors_needed(max_connections: u32, workers: u16) -> u64 {
667    u64::from(max_connections) + 2 * u64::from(workers) + 32
668}
669
670fn invalid(field: &'static str, reason: ConfigReason) -> NetError {
671    NetError::InvalidConfig { field, reason }
672}
673
674/// Builds [`Limits`]; every setter is optional.
675///
676/// ```
677/// use net_io::{ConfigReason, Limits, NetError};
678/// let err = Limits::builder().max_connections(100).max_per_listener(200).build().unwrap_err();
679/// assert!(matches!(err, NetError::InvalidConfig { field: "max_per_listener", reason: ConfigReason::AboveGlobal }));
680/// assert!(Limits::builder().max_connections(100).build().is_ok());
681/// ```
682#[must_use]
683#[derive(Clone, Debug, Default)]
684pub struct LimitsBuilder {
685    limits: Limits,
686    /// A `lane_reserve` for a lane that does not exist, refused by `build`.
687    bad_lane: bool,
688}
689
690macro_rules! setter {
691    ($(#[$m:meta])* $name:ident, $t:ty) => {
692        $(#[$m])*
693        pub fn $name(mut self, value: $t) -> Self {
694            self.limits.$name = Some(value);
695            self
696        }
697    };
698}
699
700/// The most connections one server holds: the source tables are sized from it.
701pub(crate) const MAX_CONNECTIONS: u32 = 1 << 20;
702
703impl LimitsBuilder {
704    setter!(
705        /// The global connection cap.
706        max_connections,
707        u32
708    );
709    setter!(
710        /// The per-listener connection cap.
711        max_per_listener,
712        u32
713    );
714    setter!(
715        /// The listen backlog.
716        backlog,
717        u32
718    );
719    setter!(
720        /// Connections accepted per wake-up.
721        accept_batch,
722        u16
723    );
724    setter!(
725        /// Time for the PROXY header and TLS handshake together.
726        handshake_timeout,
727        Duration
728    );
729    setter!(
730        /// Time to wait for the next exchange.
731        idle_timeout,
732        Duration
733    );
734    setter!(
735        /// Time to wait for bytes during an exchange.
736        read_timeout,
737        Duration
738    );
739    setter!(
740        /// Time to wait for the peer to take bytes.
741        write_timeout,
742        Duration
743    );
744    setter!(
745        /// Time a parked connection may wait for its completion.
746        park_timeout,
747        Duration
748    );
749    setter!(
750        /// The minimum transfer rate ([`MinRate::off`] to disable).
751        min_rate,
752        MinRate
753    );
754    setter!(
755        /// Pool memory a connection's output may hold.
756        output_budget,
757        u32
758    );
759    setter!(
760        /// Total bytes of buffers all workers may allocate. A quarter of it, shared
761        /// among the workers, is the most unfinished TLS handshakes may hold on the
762        /// reactor; see [`Limits::buffer_budget`].
763        buffer_budget,
764        u64
765    );
766    setter!(
767        /// The drain deadline.
768        drain_timeout,
769        Duration
770    );
771    setter!(
772        /// The largest refusal reply (at most 512).
773        refusal_bytes_max,
774        u16
775    );
776    setter!(
777        /// The timer resolution (1 ms to 100 ms).
778        tick,
779        Duration
780    );
781    setter!(
782        /// Adaptive deadlines under pressure.
783        pressure,
784        Pressure
785    );
786
787    /// The per-source concurrency cap and how sources are grouped.
788    pub fn max_per_source(mut self, n: u32, policy: PrefixPolicy) -> Self {
789        self.limits.max_per_source = Some((n, policy));
790        self
791    }
792
793    /// The PROXY v2 address-and-TLV cap (up to 65,519).
794    pub fn proxy_header_max(mut self, v2_body_bytes: u16) -> Self {
795        self.limits.proxy_header_max = Some(v2_body_bytes);
796        self
797    }
798
799    /// The initial read buffer class and the largest a session may grow it to.
800    pub fn read_class(mut self, initial: SizeClass, max: SizeClass) -> Self {
801        self.limits.read_class = Some((initial, max));
802        self
803    }
804
805    /// A worker's completion queue length, rounded up to a power of two.
806    pub fn completion_queue(mut self, n: u32) -> Self {
807        self.limits.completion_queue = Some(n);
808        self
809    }
810
811    /// How long a drain waits, from a connection's accept, for the first request of
812    /// a connection that has sent nothing yet before it counts the connection idle
813    /// and closes it. A client that connected just before the drain and writes its
814    /// request right after is answered instead of finding the connection closed.
815    /// Default 1 s; the drain's deadline still bounds it; zero closes such a
816    /// connection at once, as before 0.8.
817    pub fn first_request_grace(mut self, time: Duration) -> Self {
818        self.limits.first_request_grace = Some(time);
819        self
820    }
821
822    /// The graceful-close linger: time and bytes read and discarded.
823    pub fn graceful_linger(mut self, time: Duration, bytes: u32) -> Self {
824        self.limits.graceful_linger = Some((time, bytes));
825        self
826    }
827
828    /// How long a connection that was sent a denial (a `Session::on_denied` reply,
829    /// or a `Refusal::WithBytes` after a PROXY header) lingers before it closes:
830    /// FIN after the denial, then reads are discarded until the peer closes or this
831    /// passes, so the peer reads the denial instead of a reset. Default 100 ms; zero
832    /// closes with a reset at once, as before 0.8. A kill ends the linger.
833    pub fn denial_linger(mut self, time: Duration) -> Self {
834        self.limits.denial_linger = Some(time);
835        self
836    }
837
838    /// How many connections may close softly at once, server-wide: lingering after a
839    /// denial, or flushing and lingering after `ServerHandle::close_after_flush`. Past
840    /// it a denial closes with a reset at once and a `close_after_flush` acts as a
841    /// `kill`, so a storm of denials costs at most this many slots for at most the
842    /// linger each. Default: a sixteenth of `max_connections` (at least 1); zero
843    /// turns soft closes off. Read from the server's limits, not a listener's.
844    pub fn denial_linger_max(mut self, n: u32) -> Self {
845        self.limits.denial_linger_max = Some(n);
846        self
847    }
848
849    /// Connection slots reserved for `lane` (lanes 0 to 7; applied from `0.6.0`).
850    pub fn lane_reserve(mut self, lane: Lane, slots: u32) -> Self {
851        match self.limits.lane_reserve.get_mut(usize::from(lane.0)) {
852            Some(slot) => *slot = Some(slots),
853            // Rejected by `build` (field "lane_reserve").
854            None => self.bad_lane = true,
855        }
856        self
857    }
858
859    /// Checks the values that were set and returns the limits.
860    ///
861    /// # Errors
862    ///
863    /// `InvalidConfig { field, reason }` for the first rule broken, in the order
864    /// documented in `docs/API.md`.
865    pub fn build(self) -> Result<Limits, NetError> {
866        self.check()?;
867        let mut limits = self.limits;
868        if let Some(n) = limits.completion_queue {
869            limits.completion_queue = Some(n.next_power_of_two());
870        }
871        Ok(limits)
872    }
873
874    fn check(&self) -> Result<(), NetError> {
875        /// A timeout over a year is refused (in seconds): `Instant + Duration` panics
876        /// on overflow, and "no limit" is not a limit a peer should be able to hold.
877        const TOO_LONG: ConfigReason = ConfigReason::TooLarge {
878            max: crate::time::LONGEST.as_secs(),
879        };
880        let l = &self.limits;
881        // Zero where zero is meaningless.
882        let zeros: [(&'static str, bool); 6] = [
883            ("max_connections", l.max_connections == Some(0)),
884            ("backlog", l.backlog == Some(0)),
885            ("accept_batch", l.accept_batch == Some(0)),
886            ("max_per_source", matches!(l.max_per_source, Some((0, _)))),
887            ("completion_queue", l.completion_queue == Some(0)),
888            ("output_budget", l.output_budget == Some(0)),
889        ];
890        for (field, zero) in zeros {
891            if zero {
892                return Err(invalid(field, ConfigReason::Zero));
893            }
894        }
895        if let Some(max) = l.max_connections {
896            if l.max_per_listener.is_some_and(|n| n > max) {
897                return Err(invalid("max_per_listener", ConfigReason::AboveGlobal));
898            }
899            if l.max_per_source.is_some_and(|(n, _)| n > max) {
900                return Err(invalid("max_per_source", ConfigReason::AboveGlobal));
901            }
902        }
903        if let Some(tick) = l.tick {
904            if tick < Duration::from_millis(1) {
905                return Err(invalid("tick", ConfigReason::TooSmall { min: 1 }));
906            }
907            if tick > Duration::from_millis(100) {
908                return Err(invalid("tick", ConfigReason::TooLarge { max: 100 }));
909            }
910        }
911        let tick = l.tick.unwrap_or(Duration::from_millis(1));
912        let timeouts: [(&'static str, Option<Duration>); 6] = [
913            ("handshake_timeout", l.handshake_timeout),
914            ("idle_timeout", l.idle_timeout),
915            ("read_timeout", l.read_timeout),
916            ("write_timeout", l.write_timeout),
917            ("park_timeout", l.park_timeout),
918            ("drain_timeout", l.drain_timeout),
919        ];
920        for (field, value) in timeouts {
921            if value.is_some_and(|d| d < tick) {
922                return Err(invalid(field, ConfigReason::BelowTick));
923            }
924            if value.is_some_and(|d| d > crate::time::LONGEST) {
925                return Err(invalid(field, TOO_LONG));
926            }
927        }
928        let long = |d: Duration| d > crate::time::LONGEST;
929        if l.min_rate
930            .is_some_and(|r| long(r.grace) || long(r.window) || long(r.check))
931        {
932            return Err(invalid("min_rate", TOO_LONG));
933        }
934        if l.graceful_linger.is_some_and(|(d, _)| long(d)) {
935            return Err(invalid("graceful_linger", TOO_LONG));
936        }
937        if l.first_request_grace.is_some_and(long) {
938            return Err(invalid("first_request_grace", TOO_LONG));
939        }
940        if l.denial_linger.is_some_and(long) {
941            return Err(invalid("denial_linger", TOO_LONG));
942        }
943        if l.max_connections.is_some_and(|n| n > MAX_CONNECTIONS) {
944            return Err(invalid(
945                "max_connections",
946                ConfigReason::TooLarge {
947                    max: u64::from(MAX_CONNECTIONS),
948                },
949            ));
950        }
951        if let Some(rate) = l.min_rate {
952            if !rate.is_off() {
953                if rate.check.is_zero() || rate.grace.is_zero() {
954                    return Err(invalid("min_rate", ConfigReason::Zero));
955                }
956                if rate.window < rate.check {
957                    return Err(invalid("min_rate", ConfigReason::WindowBelowCheck));
958                }
959            }
960        }
961        if let Some((initial, max)) = l.read_class {
962            if max < initial {
963                return Err(invalid("read_class", ConfigReason::Inconsistent));
964            }
965        }
966        if l.refusal_bytes_max.is_some_and(|n| n > 512) {
967            return Err(invalid(
968                "refusal_bytes_max",
969                ConfigReason::TooLarge { max: 512 },
970            ));
971        }
972        if l.proxy_header_max.is_some_and(|n| n > 65_519) {
973            return Err(invalid(
974                "proxy_header_max",
975                ConfigReason::TooLarge { max: 65_519 },
976            ));
977        }
978        if l.completion_queue.is_some_and(|n| n > 1 << 20) {
979            return Err(invalid(
980                "completion_queue",
981                ConfigReason::TooLarge { max: 1 << 20 },
982            ));
983        }
984        if let Some(p) = l.pressure {
985            let factor_ok = p.factor > 0.0 && p.factor <= 1.0;
986            let ordered = p.high.partial_cmp(&p.low) == Some(std::cmp::Ordering::Greater);
987            if !ordered
988                || !factor_ok
989                || !(0.0..=1.0).contains(&p.high)
990                || !(0.0..=1.0).contains(&p.low)
991            {
992                return Err(invalid("pressure", ConfigReason::Inconsistent));
993            }
994        }
995        if self.bad_lane {
996            return Err(invalid("lane_reserve", ConfigReason::TooLarge { max: 7 }));
997        }
998        let reserved: u64 = l.lane_reserve.iter().flatten().map(|n| u64::from(*n)).sum();
999        if let Some(max) = l.max_connections {
1000            if reserved > u64::from(max) {
1001                return Err(invalid("lane_reserve", ConfigReason::AboveGlobal));
1002            }
1003        }
1004        Ok(())
1005    }
1006}
1007
1008/// The process's open-descriptor limit (`RLIMIT_NOFILE`, soft) on Unix: what
1009/// `ServerBuilder::build` checks a global cap against. `None` where it is unlimited,
1010/// and on Windows, where socket handles do not come from a small table. Use it to
1011/// place a soft cap of your own under the one net-io would pick.
1012///
1013/// ```
1014/// let cap = net_io::descriptor_limit().map_or(10_000, |n| n.saturating_sub(64));
1015/// assert!(cap > 0);
1016/// ```
1017#[must_use]
1018pub fn descriptor_limit() -> Option<u64> {
1019    crate::sys::descriptor_limit()
1020}
1021
1022#[cfg(test)]
1023mod tests {
1024    use super::*;
1025
1026    #[test]
1027    fn test_unset_values_take_driver_defaults() {
1028        let l = Limits::builder().build().unwrap();
1029        assert_eq!(
1030            l.effective(DriverKind::Blocking).idle_timeout,
1031            Duration::from_secs(5)
1032        );
1033        assert_eq!(
1034            l.effective(DriverKind::Reactor).idle_timeout,
1035            Duration::from_secs(60)
1036        );
1037    }
1038
1039    #[test]
1040    fn test_dependent_defaults_follow_max_connections() {
1041        let l = Limits::builder().max_connections(10).build().unwrap();
1042        let e = l.effective(DriverKind::Reactor);
1043        assert_eq!(e.max_per_listener, 10);
1044        assert_eq!(e.max_per_source, 10);
1045    }
1046
1047    #[test]
1048    fn test_zero_values_rejected() {
1049        for b in [
1050            Limits::builder().max_connections(0),
1051            Limits::builder().backlog(0),
1052            Limits::builder().accept_batch(0),
1053            Limits::builder().max_per_source(0, PrefixPolicy::DEFAULT),
1054            Limits::builder().completion_queue(0),
1055            Limits::builder().output_budget(0),
1056        ] {
1057            assert!(matches!(
1058                b.build(),
1059                Err(NetError::InvalidConfig {
1060                    reason: ConfigReason::Zero,
1061                    ..
1062                })
1063            ));
1064        }
1065    }
1066
1067    #[test]
1068    fn test_timeout_below_tick_rejected() {
1069        let err = Limits::builder()
1070            .tick(Duration::from_millis(100))
1071            .read_timeout(Duration::from_millis(50))
1072            .build()
1073            .unwrap_err();
1074        assert!(matches!(
1075            err,
1076            NetError::InvalidConfig {
1077                field: "read_timeout",
1078                reason: ConfigReason::BelowTick
1079            }
1080        ));
1081    }
1082
1083    /// "No limit" spelled `Duration::MAX` is refused at build instead of panicking
1084    /// on the first deadline.
1085    #[test]
1086    fn test_timeouts_over_a_year_and_huge_caps_rejected() {
1087        for field in ["idle_timeout", "read_timeout", "drain_timeout"] {
1088            let b = Limits::builder();
1089            let b = match field {
1090                "idle_timeout" => b.idle_timeout(Duration::MAX),
1091                "read_timeout" => b.read_timeout(Duration::from_secs(400 * 86_400)),
1092                _ => b.drain_timeout(Duration::MAX),
1093            };
1094            let err = b.build().unwrap_err();
1095            assert!(
1096                matches!(err, NetError::InvalidConfig { field: f, reason: ConfigReason::TooLarge { .. } } if f == field),
1097                "{err:?}"
1098            );
1099        }
1100        assert!(
1101            Limits::builder()
1102                .idle_timeout(Duration::from_secs(365 * 86_400))
1103                .build()
1104                .is_ok()
1105        );
1106        let err = Limits::builder()
1107            .max_connections(u32::MAX)
1108            .build()
1109            .unwrap_err();
1110        assert!(matches!(
1111            err,
1112            NetError::InvalidConfig {
1113                field: "max_connections",
1114                reason: ConfigReason::TooLarge { .. }
1115            }
1116        ));
1117    }
1118
1119    #[test]
1120    fn test_min_rate_window_below_check_rejected() {
1121        let rate = MinRate {
1122            bytes_per_sec: 10,
1123            window: Duration::from_millis(500),
1124            grace: Duration::from_secs(1),
1125            check: Duration::from_secs(1),
1126        };
1127        assert!(matches!(
1128            Limits::builder().min_rate(rate).build(),
1129            Err(NetError::InvalidConfig {
1130                reason: ConfigReason::WindowBelowCheck,
1131                ..
1132            })
1133        ));
1134        assert!(Limits::builder().min_rate(MinRate::off()).build().is_ok());
1135    }
1136
1137    #[test]
1138    fn test_bounds_too_large() {
1139        assert!(Limits::builder().refusal_bytes_max(513).build().is_err());
1140        assert!(Limits::builder().refusal_bytes_max(512).build().is_ok());
1141        assert!(Limits::builder().proxy_header_max(65_520).build().is_err());
1142        assert!(
1143            Limits::builder()
1144                .completion_queue((1 << 20) + 1)
1145                .build()
1146                .is_err()
1147        );
1148    }
1149
1150    #[test]
1151    fn test_completion_queue_rounded_to_power_of_two() {
1152        let l = Limits::builder().completion_queue(1000).build().unwrap();
1153        assert_eq!(l.completion_queue(), Some(1024));
1154    }
1155
1156    #[test]
1157    fn test_pressure_and_lane_reserve_validation() {
1158        let bad = Pressure {
1159            high: 0.5,
1160            low: 0.6,
1161            factor: 0.5,
1162        };
1163        assert!(Limits::builder().pressure(bad).build().is_err());
1164        assert!(Limits::builder().lane_reserve(Lane(8), 1).build().is_err());
1165        // A later valid lane 7 does not hide the invalid one.
1166        assert!(
1167            Limits::builder()
1168                .lane_reserve(Lane(8), 1)
1169                .lane_reserve(Lane(7), 1)
1170                .build()
1171                .is_err()
1172        );
1173        assert!(
1174            Limits::builder()
1175                .max_connections(10)
1176                .lane_reserve(Lane(0), 6)
1177                .lane_reserve(Lane(1), 5)
1178                .build()
1179                .is_err()
1180        );
1181    }
1182
1183    #[test]
1184    fn test_validate_descriptor_limit_and_budget() {
1185        let l = Limits::builder().max_connections(1000).build().unwrap();
1186        assert!(matches!(
1187            l.validate(4, Some(500)),
1188            Err(NetError::InvalidConfig {
1189                reason: ConfigReason::DescriptorLimit { have: 500, .. },
1190                ..
1191            })
1192        ));
1193        assert!(l.validate(4, Some(100_000)).is_ok());
1194        let small = Limits::builder().buffer_budget(1024).build().unwrap();
1195        assert!(matches!(
1196            small.validate(4, None),
1197            Err(NetError::InvalidConfig {
1198                reason: ConfigReason::BudgetBelowWorkers { .. },
1199                ..
1200            })
1201        ));
1202    }
1203
1204    #[test]
1205    fn test_overlay_takes_listener_values() {
1206        let base = Limits::builder()
1207            .max_connections(100)
1208            .idle_timeout(Duration::from_secs(9))
1209            .build()
1210            .unwrap();
1211        let over = Limits::builder()
1212            .idle_timeout(Duration::from_secs(1))
1213            .build()
1214            .unwrap();
1215        let merged = base.overlay(&over);
1216        assert_eq!(merged.max_connections(), Some(100));
1217        assert_eq!(merged.idle_timeout(), Some(Duration::from_secs(1)));
1218    }
1219
1220    #[test]
1221    fn test_resolve_sets_every_value() {
1222        let r = Limits::default().resolve(DriverKind::Blocking);
1223        assert!(
1224            r.max_connections().is_some() && r.tick().is_some() && r.graceful_linger().is_some()
1225        );
1226    }
1227}