weida_core/limits.rs
1//! Resource limits.
2//!
3//! Master doc §50: no internal queue may be unbounded, and every allocation
4//! that a remote peer can influence must have a defensive ceiling. Each field
5//! below names the remote-controlled quantity it bounds.
6//!
7//! **`Limits` is a per-connection profile.** Every field applies to one
8//! connection — which is what a runtime holding one profile per connection
9//! tier will need
10//! (`docs/decisions/0002-control-and-bulk-separation.md` §6.4). Numbers that
11//! belong to a runtime rather than to a connection — how many connections a
12//! binding accepts, how many one peer may hold, how deep an endpoint's queue
13//! is, how many resolved addresses a dial tries — live on `RuntimeConfig`
14//! instead, so that no profile can carry a value nothing reads.
15
16use std::time::Duration;
17
18/// Resource limits applied to one connection.
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub struct Limits {
21 /// Largest frame header this side will accept, in bytes. Checked against
22 /// the preamble length *before* any allocation.
23 pub max_header_bytes: u64,
24 /// QUIC concurrent inbound unidirectional streams. Bounds the number of
25 /// live per-stream parse tasks for one-way transfers.
26 pub max_concurrent_uni_streams: u32,
27 /// QUIC concurrent inbound bidirectional streams; bounds live request
28 /// exchanges per connection and, with `max_header_bytes`, worst-case
29 /// header memory.
30 pub max_concurrent_bidi_streams: u32,
31 /// QUIC per-stream receive window in bytes. Bounds buffered payload for one
32 /// transfer and provides backpressure to the sender.
33 pub stream_receive_window: u64,
34 /// QUIC per-connection receive window in bytes.
35 pub connection_receive_window: u64,
36 /// QUIC keep-alive interval. Sent by the dialling side only, so a binding's
37 /// value is not used.
38 pub keep_alive: Duration,
39 /// QUIC idle timeout, applied in both directions.
40 pub idle_timeout: Duration,
41 /// How long to wait for the peer HELLO before closing the connection with
42 /// `NEGOTIATION_FAILED`, in milliseconds.
43 pub hello_timeout_ms: u64,
44 /// Subscription filters one peer connection may hold at once, summed over
45 /// every path. Exceeding it closes the connection with `LIMIT_EXCEEDED`:
46 /// SUBSCRIBE has no stream to answer with an ERROR frame.
47 pub max_subscriptions: usize,
48 /// Payload bytes a publisher may hold queued for one subscriber. A message
49 /// that does not fit is dropped for that subscriber and counted; the
50 /// publisher never blocks on a slow consumer.
51 pub subscriber_buffer_bytes: usize,
52 /// Producer scopes — paths and topics — a receiver tracks per connection
53 /// for gap detection or reassembly, when `PerProducer` ordering is
54 /// negotiated. The peer chooses the scope names, so the table needs a
55 /// ceiling; at the cap a new scope is simply not tracked, no gap is
56 /// reported for it and nothing is held back for it.
57 pub max_sequence_scopes: usize,
58 /// Transfers a receiver may hold back at once, summed over scopes, when
59 /// `PerProducer(reassemble)` ordering is negotiated. A held transfer is
60 /// an unread stream, so the bytes it pins are quinn's — up to
61 /// `stream_receive_window` for it and `connection_receive_window` for the
62 /// hold as a whole. At the cap the oldest held transfer is released out
63 /// of order with its gap reported, never held in a growing buffer.
64 pub max_reorder_hold: usize,
65 /// Live transfers on one **local** connection, where the OS connection
66 /// *is* the stream and there is no multiplexing
67 /// ([decisions/0010](../../../docs/decisions/0010-local-transport.md)
68 /// §4.2). Windows caps named-pipe instances at 1-255, which is the
69 /// tightest platform limit and therefore the one the default respects;
70 /// an `open` at the cap waits for a live transfer to end, exactly as a
71 /// QUIC `open` waits on the peer's stream budget, rather than refusing.
72 /// A peer configured with zero can therefore open nothing and waits
73 /// until its caller's deadline, exactly as one granted no QUIC streams.
74 pub max_local_streams: usize,
75 /// Connections a subscriber parks toward a peer it dialled, so that peer
76 /// can open a stream back
77 /// ([decisions/0012](../../../docs/decisions/0012-local-connection-grouping.md)
78 /// §4.4). An accepted socket cannot be dialled, so fan-out over a local
79 /// socket transport rides connections the subscriber opened and left
80 /// waiting; each is a file descriptor held for a copy that may never
81 /// come, and each counts against `max_local_streams` on both sides. A
82 /// publisher that finds none parked drops that copy and counts it, the
83 /// same answer fan-out already gives an exhausted subscriber budget. Zero
84 /// disables the pool, which makes a subscription over such a transport an
85 /// error at subscribe time rather than a silence.
86 pub max_parked_reverse: usize,
87
88 /// Identities a receiver remembers per connection for `Bounded`
89 /// deduplication. The window bounds how long an identity is kept, not
90 /// how many arrive within it, so the count needs its own ceiling; at the
91 /// cap the oldest entry is evicted, which costs suppression rather than
92 /// memory.
93 pub max_dedup_entries: usize,
94
95 /// Bytes of a peer's QUIC datagrams buffered unread per connection,
96 /// oldest dropped first. **Zero turns flows off**: the connection then
97 /// advertises neither capability code `1` nor `max_datagram_frame_size`,
98 /// buffers nothing and runs no datagram reader
99 /// ([decisions/0034](../../../docs/decisions/0034-late-is-lost.md) §4.5).
100 /// [`DEFAULT_DATAGRAM_RECEIVE_BYTES`] is the documented value for turning
101 /// them on.
102 pub datagram_receive_bytes: usize,
103 /// Bytes of datagrams queued for sending per connection on QUIC, and per
104 /// flow on a local transport; beyond it the oldest queued one is
105 /// discarded. Bounds what this side holds for a peer that reads slowly.
106 pub datagram_send_bytes: usize,
107 /// Inbound flows one connection may hold live. Each is a FLOW stream the
108 /// peer opened and a ring this side keeps; a FLOW beyond it is stopped
109 /// with `LIMIT_EXCEEDED`.
110 pub max_flows: usize,
111 /// Unread datagram bytes held per inbound flow; a consumer that falls
112 /// behind loses its oldest datagrams, counted per flow.
113 pub flow_queue_bytes: usize,
114 /// Bytes of datagrams held per connection for flow ids with no live flow
115 /// yet — a datagram can overtake its FLOW header — and the one place a
116 /// peer can make this side hold datagrams it never registered.
117 pub flow_early_bytes: usize,
118 /// How long a datagram waits in that ring for its FLOW header before it
119 /// is dropped and counted.
120 pub flow_early_hold: Duration,
121
122 /// The congestion controller of this profile's QUIC connections. Not a
123 /// bound, but a per-connection choice, which is why it lives here: a
124 /// bulk profile that shares a bottleneck with media may want a different
125 /// controller than a media profile
126 /// ([decisions/0034](../../../docs/decisions/0034-late-is-lost.md) §6).
127 pub congestion: Congestion,
128}
129
130/// A QUIC congestion controller, as `quinn` implements them.
131#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
132pub enum Congestion {
133 /// CUBIC (RFC 9438), `quinn`'s default: loss-based.
134 #[default]
135 Cubic,
136 /// NewReno (RFC 9002 §7): loss-based, the conservative baseline.
137 NewReno,
138 /// BBR: model-based, reacts to delay rather than waiting for loss.
139 /// `quinn` marks its implementation experimental.
140 Bbr,
141}
142
143/// The documented `Limits::datagram_receive_bytes` for a profile that
144/// enables datagram flows: 64 KiB, about fifty full datagrams.
145pub const DEFAULT_DATAGRAM_RECEIVE_BYTES: usize = 65_536;
146
147impl Limits {
148 /// Worst-case header memory a single hostile connection can pin, in bytes.
149 ///
150 /// Both stream budgets count: a peer may open its full uni *and* bidi
151 /// allowance, and every accepted stream starts with one header.
152 pub const fn worst_case_header_memory(&self) -> u64 {
153 self.max_header_bytes
154 * (self.max_concurrent_uni_streams as u64 + self.max_concurrent_bidi_streams as u64)
155 }
156}
157
158impl Default for Limits {
159 fn default() -> Self {
160 Limits {
161 max_header_bytes: 16 * 1024,
162 max_concurrent_uni_streams: 2048,
163 max_concurrent_bidi_streams: 1024,
164 stream_receive_window: 1024 * 1024,
165 connection_receive_window: 16 * 1024 * 1024,
166 keep_alive: Duration::from_secs(10),
167 idle_timeout: Duration::from_secs(30),
168 hello_timeout_ms: 10_000,
169 max_subscriptions: 256,
170 subscriber_buffer_bytes: 8 * 1024 * 1024,
171 max_sequence_scopes: 1024,
172 max_reorder_hold: 256,
173 max_local_streams: 255,
174 max_parked_reverse: 8,
175
176 max_dedup_entries: 4096,
177 datagram_receive_bytes: 0,
178 datagram_send_bytes: 65_536,
179 max_flows: 64,
180 flow_queue_bytes: 16_384,
181 flow_early_bytes: 4_096,
182 flow_early_hold: Duration::from_secs(1),
183 congestion: Congestion::Cubic,
184 }
185 }
186}
187
188#[cfg(test)]
189mod tests {
190 use super::*;
191
192 #[test]
193 fn defaults_match_the_protocol_document() {
194 let l = Limits::default();
195 assert_eq!(l.max_header_bytes, 16384);
196 assert_eq!(l.max_concurrent_uni_streams, 2048);
197 assert_eq!(l.max_concurrent_bidi_streams, 1024);
198 assert_eq!(l.stream_receive_window, 1 << 20);
199 assert_eq!(l.connection_receive_window, 16 << 20);
200 assert_eq!(l.keep_alive, Duration::from_secs(10));
201 assert_eq!(l.idle_timeout, Duration::from_secs(30));
202 assert_eq!(l.hello_timeout_ms, 10_000);
203 assert_eq!(l.max_subscriptions, 256);
204 assert_eq!(l.subscriber_buffer_bytes, 8 << 20);
205 assert_eq!(l.max_sequence_scopes, 1024);
206 assert_eq!(l.max_reorder_hold, 256);
207 assert_eq!(l.max_local_streams, 255);
208 assert_eq!(l.max_parked_reverse, 8);
209 assert_eq!(l.max_dedup_entries, 4096);
210 assert_eq!(l.datagram_receive_bytes, 0);
211 assert_eq!(DEFAULT_DATAGRAM_RECEIVE_BYTES, 64 << 10);
212 assert_eq!(l.datagram_send_bytes, 64 << 10);
213 assert_eq!(l.max_flows, 64);
214 assert_eq!(l.flow_queue_bytes, 16 << 10);
215 assert_eq!(l.flow_early_bytes, 4 << 10);
216 assert_eq!(l.flow_early_hold, Duration::from_secs(1));
217 assert_eq!(l.congestion, Congestion::Cubic);
218 }
219
220 #[test]
221 fn worst_case_header_memory_is_48_mib() {
222 assert_eq!(Limits::default().worst_case_header_memory(), 48 << 20);
223 }
224}