tokio_quiche/settings/
quic.rs

1// Copyright (C) 2025, Cloudflare, Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright notice,
9//       this list of conditions and the following disclaimer.
10//
11//     * Redistributions in binary form must reproduce the above copyright
12//       notice, this list of conditions and the following disclaimer in the
13//       documentation and/or other materials provided with the distribution.
14//
15// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
16// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
17// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
19// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
27use foundations::settings::settings;
28use serde_with::serde_as;
29use serde_with::DurationMilliSeconds;
30use std::time::Duration;
31
32/// QUIC configuration parameters.
33#[serde_as]
34#[settings]
35pub struct QuicSettings {
36    /// Configures the list of supported application protocols. Defaults to
37    /// `[b"h3"]`.
38    #[serde(skip, default = "QuicSettings::default_alpn")]
39    pub alpn: Vec<Vec<u8>>,
40
41    /// Configures whether to enable DATAGRAM frame support. H3 connections
42    /// copy this setting from the underlying QUIC connection.
43    ///
44    /// Defaults to `true`.
45    #[serde(default = "QuicSettings::default_enable_dgram")]
46    pub enable_dgram: bool,
47
48    /// Max queue length for received DATAGRAM frames. Defaults to `2^16`.
49    #[serde(default = "QuicSettings::default_dgram_max_queue_len")]
50    pub dgram_recv_max_queue_len: usize,
51
52    /// Max queue length for sending DATAGRAM frames. Defaults to `2^16`.
53    #[serde(default = "QuicSettings::default_dgram_max_queue_len")]
54    pub dgram_send_max_queue_len: usize,
55
56    /// Sets the `initial_max_data` transport parameter. Defaults to 10 MB.
57    #[serde(default = "QuicSettings::default_initial_max_data")]
58    pub initial_max_data: u64,
59
60    /// Sets the `initial_max_stream_data_bidi_local` transport parameter.
61    /// Defaults to 1 MB.
62    #[serde(default = "QuicSettings::default_initial_max_stream_data")]
63    pub initial_max_stream_data_bidi_local: u64,
64
65    /// Sets the `initial_max_stream_data_bidi_remote` transport parameter.
66    /// Defaults to 1 MB.
67    #[serde(default = "QuicSettings::default_initial_max_stream_data")]
68    pub initial_max_stream_data_bidi_remote: u64,
69
70    /// Sets the `initial_max_stream_data_uni` transport parameter.
71    /// Defaults to 1 MB.
72    #[serde(default = "QuicSettings::default_initial_max_stream_data")]
73    pub initial_max_stream_data_uni: u64,
74
75    /// Sets the `initial_max_streams_bidi` transport parameter.
76    /// Defaults to `100`.
77    #[serde(default = "QuicSettings::default_initial_max_streams")]
78    pub initial_max_streams_bidi: u64,
79
80    /// Sets the `initial_max_streams_uni` transport parameter.
81    /// Defaults to `100`.
82    #[serde(default = "QuicSettings::default_initial_max_streams")]
83    pub initial_max_streams_uni: u64,
84
85    /// Configures the max idle timeout of the connection in milliseconds. The
86    /// real idle timeout is the minimum of this and the peer's
87    /// `max_idle_timeout`.
88    ///
89    /// Defaults to 56 seconds.
90    #[serde(
91        rename = "max_idle_timeout_ms",
92        default = "QuicSettings::default_max_idle_timeout"
93    )]
94    #[serde_as(as = "Option<DurationMilliSeconds>")]
95    pub max_idle_timeout: Option<Duration>,
96
97    /// Configures whether the local endpoint supports active connection
98    /// migration. Defaults to `true` (meaning disabled).
99    #[serde(default = "QuicSettings::default_disable_active_migration")]
100    pub disable_active_migration: bool,
101
102    /// Sets the maximum incoming UDP payload size. Defaults to 1350 bytes.
103    #[serde(default = "QuicSettings::default_max_recv_udp_payload_size")]
104    pub max_recv_udp_payload_size: usize,
105
106    /// Sets the maximum outgoing UDP payload size. Defaults to 1350 bytes.
107    #[serde(default = "QuicSettings::default_max_send_udp_payload_size")]
108    pub max_send_udp_payload_size: usize,
109
110    /// Whether to validate client IPs in QUIC initials.
111    ///
112    /// If set to `true`, any received QUIC initial will immediately spawn a
113    /// connection and start crypto operations for the handshake. Otherwise,
114    /// the client is asked to execute a stateless retry first (the default).
115    pub disable_client_ip_validation: bool,
116
117    /// Path to a file in which TLS secrets will be logged in
118    /// [SSLKEYLOGFILE format](https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html).
119    pub keylog_file: Option<String>,
120
121    /// Path to a directory where QLOG files will be saved.
122    pub qlog_dir: Option<String>,
123
124    /// Congestion control algorithm to use.
125    ///
126    /// For available values, see
127    /// [`CongestionControlAlgorithm`](quiche::CongestionControlAlgorithm).
128    /// Defaults to `cubic`.
129    #[serde(default = "QuicSettings::default_cc_algorithm")]
130    pub cc_algorithm: String,
131
132    /// Whether to use HyStart++ (only with `cubic` and `reno` CC). Defaults to
133    /// `true`.
134    #[serde(default = "QuicSettings::default_enable_hystart")]
135    pub enable_hystart: bool,
136
137    /// Optionally enables pacing for outgoing packets.
138    ///
139    /// Note: this also requires pacing-compatible
140    /// [`SocketCapabilities`](crate::socket::SocketCapabilities).
141    pub enable_pacing: bool,
142
143    /// Optionally enables expensive versions of the
144    /// `accepted_initial_quic_packet_count`
145    /// and `rejected_initial_quic_packet_count` metrics.
146    ///
147    /// The expensive versions add a label for the peer IP subnet (`/24` for
148    /// IPv4, `/32` for IPv6). They thus generate many more time series if
149    /// peers are arbitrary eyeballs from the global Internet.
150    pub enable_expensive_packet_count_metrics: bool,
151
152    /// Forwards [`quiche`] logs into the logging system currently used by
153    /// [`foundations`]. Defaults to `false`.
154    ///
155    /// # Warning
156    /// This should **only be used for local debugging**. `quiche` can emit lots
157    /// (and lots, and lots) of logs (the TRACE level emits a log record for
158    /// every packet and frame) and you can very easily overwhelm your
159    /// logging pipeline.
160    pub capture_quiche_logs: bool,
161
162    /// A timeout for the QUIC handshake, in milliseconds. Disabled by default.
163    #[serde(rename = "handshake_timeout_ms")]
164    #[serde_as(as = "Option<DurationMilliSeconds>")]
165    pub handshake_timeout: Option<Duration>,
166
167    /// The maximum number of newly-created connections that will be queued for
168    /// the application to receive. Not applicable to client-side usage.
169    ///
170    /// Defaults to 1024 connections.
171    #[serde(default = "QuicSettings::default_listen_backlog")]
172    pub listen_backlog: usize,
173}
174
175impl QuicSettings {
176    #[inline]
177    fn default_alpn() -> Vec<Vec<u8>> {
178        quiche::h3::APPLICATION_PROTOCOL
179            .iter()
180            .map(|v| v.to_vec())
181            .collect()
182    }
183
184    #[inline]
185    fn default_enable_dgram() -> bool {
186        true
187    }
188
189    #[inline]
190    fn default_dgram_max_queue_len() -> usize {
191        65536
192    }
193
194    #[inline]
195    fn default_initial_max_data() -> u64 {
196        10_000_000
197    }
198
199    #[inline]
200    fn default_initial_max_stream_data() -> u64 {
201        1_000_000
202    }
203
204    #[inline]
205    fn default_initial_max_streams() -> u64 {
206        100
207    }
208
209    #[inline]
210    fn default_max_idle_timeout() -> Option<Duration> {
211        Some(Duration::from_secs(56))
212    }
213
214    #[inline]
215    fn default_max_recv_udp_payload_size() -> usize {
216        1350
217    }
218
219    #[inline]
220    fn default_max_send_udp_payload_size() -> usize {
221        1350
222    }
223
224    #[inline]
225    fn default_disable_active_migration() -> bool {
226        true
227    }
228
229    #[inline]
230    fn default_cc_algorithm() -> String {
231        "cubic".to_string()
232    }
233
234    #[inline]
235    fn default_enable_hystart() -> bool {
236        true
237    }
238
239    #[inline]
240    fn default_listen_backlog() -> usize {
241        // Given a worst-case 1 minute handshake timeout and up to 4096 concurrent
242        // handshakes, we will dequeue at least 70 connections per second.
243        // This means this backlog size limits the queueing latency to
244        // ~15s.
245        1024
246    }
247}
248
249#[cfg(test)]
250mod test {
251    use super::QuicSettings;
252    use std::time::Duration;
253
254    #[test]
255    fn timeouts_parse_as_milliseconds() {
256        let quic = serde_json::from_str::<QuicSettings>(
257            r#"{ "handshake_timeout_ms": 5000, "max_idle_timeout_ms": 7000 }"#,
258        )
259        .unwrap();
260
261        assert_eq!(quic.handshake_timeout.unwrap(), Duration::from_secs(5));
262        assert_eq!(quic.max_idle_timeout.unwrap(), Duration::from_secs(7));
263    }
264}
tokio_quiche/settings/quic.rs

tokio_quiche/settings/
quic.rs
