tokio_quiche/http3/
settings.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 std::future::poll_fn;
28use std::task::Context;
29use std::task::Poll;
30use std::time::Duration;
31
32use crate::http3::driver::H3ConnectionError;
33use crate::quic::QuicheConnection;
34
35use foundations::telemetry::log;
36use tokio_util::time::delay_queue::DelayQueue;
37use tokio_util::time::delay_queue::{
38    self,
39};
40
41/// Unified configuration parameters for
42/// [H3Driver](crate::http3::driver::H3Driver)s.
43#[derive(Default, Clone, Debug)]
44pub struct Http3Settings {
45    /// Maximum number of requests a
46    /// [ServerH3Driver](crate::http3::driver::ServerH3Driver) allows per
47    /// connection.
48    pub max_requests_per_connection: Option<u64>,
49    /// Maximum size of a single HEADERS frame, in bytes.
50    pub max_header_list_size: Option<u64>,
51    /// Maximum value the QPACK encoder is permitted to set for the dynamic
52    /// table capcity. See <https://www.rfc-editor.org/rfc/rfc9204.html#name-maximum-dynamic-table-capac>
53    pub qpack_max_table_capacity: Option<u64>,
54    /// Upper bound on the number of streams that can be blocked on the QPACK
55    /// decoder. See <https://www.rfc-editor.org/rfc/rfc9204.html#name-blocked-streams>
56    pub qpack_blocked_streams: Option<u64>,
57    /// Timeout between starting the QUIC handshake and receiving the first
58    /// request on a connection. Only applicable to
59    /// [ServerH3Driver](crate::http3::driver::ServerH3Driver).
60    pub post_accept_timeout: Option<Duration>,
61}
62
63impl From<&Http3Settings> for quiche::h3::Config {
64    fn from(value: &Http3Settings) -> Self {
65        let mut config = Self::new().unwrap();
66
67        if let Some(v) = value.max_header_list_size {
68            config.set_max_field_section_size(v);
69        }
70        if let Some(v) = value.qpack_max_table_capacity {
71            config.set_qpack_max_table_capacity(v);
72        }
73        if let Some(v) = value.qpack_blocked_streams {
74            config.set_qpack_blocked_streams(v);
75        }
76
77        config
78    }
79}
80
81/// Opaque handle to an entry in [`Http3Timeouts`].
82pub(crate) struct TimeoutKey(delay_queue::Key);
83
84pub(crate) struct Http3SettingsEnforcer {
85    limits: Http3Limits,
86    timeouts: Http3Timeouts,
87}
88
89impl From<&Http3Settings> for Http3SettingsEnforcer {
90    fn from(value: &Http3Settings) -> Self {
91        Self {
92            limits: Http3Limits {
93                max_requests_per_connection: value.max_requests_per_connection,
94            },
95            timeouts: Http3Timeouts {
96                post_accept_timeout: value.post_accept_timeout,
97                delay_queue: DelayQueue::new(),
98            },
99        }
100    }
101}
102
103impl Http3SettingsEnforcer {
104    /// Returns a boolean indicating whether or not the connection should be
105    /// closed due to a violation of the request count limit.
106    pub fn enforce_requests_limit(&self, request_count: u64) -> bool {
107        if let Some(limit) = self.limits.max_requests_per_connection {
108            return request_count >= limit;
109        }
110
111        false
112    }
113
114    /// Returns the configured post-accept timeout.
115    pub fn post_accept_timeout(&self) -> Option<Duration> {
116        self.timeouts.post_accept_timeout
117    }
118
119    /// Registers a timeout of `typ` in this [Http3SettingsEnforcer].
120    pub fn add_timeout(
121        &mut self, typ: Http3TimeoutType, duration: Duration,
122    ) -> TimeoutKey {
123        let key = self.timeouts.delay_queue.insert(typ, duration);
124        TimeoutKey(key)
125    }
126
127    /// Checks whether the [Http3SettingsEnforcer] has any pending timeouts.
128    /// This should be used to selectively poll `enforce_timeouts`.
129    pub fn has_pending_timeouts(&self) -> bool {
130        !self.timeouts.delay_queue.is_empty()
131    }
132
133    /// Checks which timeouts have expired.
134    fn poll_timeouts(&mut self, cx: &mut Context) -> Poll<TimeoutCheckResult> {
135        let mut changed = false;
136        let mut result = TimeoutCheckResult::default();
137
138        while let Poll::Ready(Some(exp)) =
139            self.timeouts.delay_queue.poll_expired(cx)
140        {
141            changed |= result.set_expired(exp.into_inner());
142        }
143
144        if changed {
145            return Poll::Ready(result);
146        }
147        Poll::Pending
148    }
149
150    /// Waits for at least one registered timeout to expire.
151    ///
152    /// This function will automatically call `close()` on the underlying
153    /// [quiche::Connection].
154    pub async fn enforce_timeouts(
155        &mut self, qconn: &mut QuicheConnection,
156    ) -> Result<(), H3ConnectionError> {
157        let result = poll_fn(|cx| self.poll_timeouts(cx)).await;
158
159        if result.connection_timed_out {
160            log::debug!("connection timed out due to post-accept-timeout"; "scid" => ?qconn.source_id());
161            qconn.close(true, quiche::h3::WireErrorCode::NoError as u64, &[])?;
162        }
163
164        Ok(())
165    }
166
167    /// Cancels a timeout that was previously registered with `add_timeout`.
168    pub fn cancel_timeout(&mut self, key: TimeoutKey) {
169        self.timeouts.delay_queue.remove(&key.0);
170    }
171}
172
173// TODO(rmehra): explore if these should really be Options, or if we
174// should enforce sane defaults
175struct Http3Limits {
176    max_requests_per_connection: Option<u64>,
177}
178
179struct Http3Timeouts {
180    post_accept_timeout: Option<Duration>,
181    delay_queue: DelayQueue<Http3TimeoutType>,
182}
183
184#[derive(Clone, Copy, Debug)]
185pub(crate) enum Http3TimeoutType {
186    PostAccept,
187}
188
189#[derive(Default, Eq, PartialEq)]
190struct TimeoutCheckResult {
191    connection_timed_out: bool,
192}
193
194impl TimeoutCheckResult {
195    fn set_expired(&mut self, typ: Http3TimeoutType) -> bool {
196        use Http3TimeoutType::*;
197        let field = match typ {
198            PostAccept => &mut self.connection_timed_out,
199        };
200
201        *field = true;
202        true
203    }
204}
tokio_quiche/http3/settings.rs

tokio_quiche/http3/
settings.rs
