Skip to main content

tokio_quiche/http3/driver/
server.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::ops::Deref;
28use std::sync::Arc;
29
30use tokio::sync::mpsc;
31
32use super::datagram;
33use super::datagram::PendingDgramBuffer;
34use super::DgramFlowId;
35use super::DriverHooks;
36use super::H3Command;
37use super::H3ConnectionError;
38use super::H3ConnectionResult;
39use super::H3Controller;
40use super::H3Driver;
41use super::H3Event;
42use super::InboundFrame;
43use super::InboundHeaders;
44use super::IncomingH3Headers;
45use super::StreamCtx;
46use super::STREAM_CAPACITY;
47use crate::http3::settings::Http3Settings;
48use crate::http3::settings::Http3SettingsEnforcer;
49use crate::http3::settings::Http3TimeoutType;
50use crate::http3::settings::TimeoutKey;
51use crate::quic::HandshakeInfo;
52use crate::quic::QuicCommand;
53use crate::quic::QuicheConnection;
54
55/// An [H3Driver] for a server-side HTTP/3 connection. See [H3Driver] for
56/// details. Emits [`ServerH3Event`]s and expects [`ServerH3Command`]s for
57/// control.
58pub type ServerH3Driver = H3Driver<ServerHooks>;
59/// The [H3Controller] type paired with [ServerH3Driver]. See [H3Controller] for
60/// details.
61pub type ServerH3Controller = H3Controller<ServerHooks>;
62/// Receives [`ServerH3Event`]s from a [ServerH3Driver]. This is the control
63/// stream which describes what is happening on the connection, but does not
64/// transfer data.
65pub type ServerEventStream = mpsc::UnboundedReceiver<ServerH3Event>;
66
67#[derive(Clone, Debug)]
68pub struct RawPriorityValue(Vec<u8>);
69
70impl From<Vec<u8>> for RawPriorityValue {
71    fn from(value: Vec<u8>) -> Self {
72        RawPriorityValue(value)
73    }
74}
75
76impl Deref for RawPriorityValue {
77    type Target = [u8];
78
79    fn deref(&self) -> &Self::Target {
80        &self.0
81    }
82}
83
84/// The request was received during early data (0-RTT).
85#[derive(Clone, Debug)]
86pub struct IsInEarlyData(bool);
87
88impl IsInEarlyData {
89    fn new(is_in_early_data: bool) -> Self {
90        IsInEarlyData(is_in_early_data)
91    }
92}
93
94impl Deref for IsInEarlyData {
95    type Target = bool;
96
97    fn deref(&self) -> &Self::Target {
98        &self.0
99    }
100}
101
102/// Events produced by [ServerH3Driver].
103#[derive(Debug)]
104pub enum ServerH3Event {
105    Core(H3Event),
106
107    Headers {
108        incoming_headers: IncomingH3Headers,
109        /// The latest PRIORITY_UPDATE frame value, if any.
110        priority: Option<RawPriorityValue>,
111        is_in_early_data: IsInEarlyData,
112    },
113}
114
115impl From<H3Event> for ServerH3Event {
116    fn from(ev: H3Event) -> Self {
117        match ev {
118            H3Event::IncomingHeaders(incoming_headers) => {
119                // Server `incoming_headers` are exclusively created in
120                // `ServerHooks::handle_request`, which correctly serializes the
121                // `RawPriorityValue` and `IsInEarlyData` values.
122                //
123                // `H3Driver::process_read_event` implements this behavior.
124                Self::Headers {
125                    incoming_headers,
126                    priority: None,
127                    is_in_early_data: IsInEarlyData::new(false),
128                }
129            },
130            _ => Self::Core(ev),
131        }
132    }
133}
134
135/// Commands accepted by [ServerH3Driver].
136#[derive(Debug)]
137pub enum ServerH3Command {
138    Core(H3Command),
139}
140
141impl From<H3Command> for ServerH3Command {
142    fn from(cmd: H3Command) -> Self {
143        Self::Core(cmd)
144    }
145}
146
147impl From<QuicCommand> for ServerH3Command {
148    fn from(cmd: QuicCommand) -> Self {
149        Self::Core(H3Command::QuicCmd(cmd))
150    }
151}
152
153// Quiche urgency is an 8-bit space. Internally, quiche reserves 0 for HTTP/3
154// control streams and request are shifted up by 124. Any value in that range is
155// suitable here.
156const PRE_HEADERS_BOOSTED_PRIORITY_URGENCY: u8 = 64;
157// Non-incremental streams are served in stream ID order, matching the client
158// FIFO expectation.
159const PRE_HEADERS_BOOSTED_PRIORITY_INCREMENTAL: bool = false;
160
161pub struct ServerHooks {
162    /// Helper to enforce limits and timeouts on an HTTP/3 connection.
163    settings_enforcer: Http3SettingsEnforcer,
164    /// Tracks the number of requests that have been handled by this driver.
165    requests: u64,
166
167    /// Handle to the post-accept timeout entry. If present, the server must
168    /// receive a HEADERS frame before this timeout.
169    post_accept_timeout: Option<TimeoutKey>,
170    /// Whether the extended CONNECT protocol is enabled. When disabled,
171    /// skip DATAGRAM flow creation for `:protocol` requests.
172    extended_connect_enabled: bool,
173    /// Datagrams received before the corresponding CONNECT request has been
174    /// processed. Bounded by [`datagram::PENDING_DGRAM_CAPACITY`].
175    pending_dgrams: PendingDgramBuffer,
176}
177
178impl ServerHooks {
179    /// Handles a new request, creating a stream context, checking for a
180    /// potential DATAGRAM flow (CONNECT-{UDP,IP}) and sending a relevant
181    /// [`H3Event`] to the [ServerH3Controller] for application-level
182    /// processing.
183    fn handle_request(
184        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
185        headers: InboundHeaders,
186    ) -> H3ConnectionResult<()> {
187        let InboundHeaders {
188            stream_id,
189            headers,
190            has_body,
191        } = headers;
192
193        // Multiple HEADERS frames can be received on a single stream, but only
194        // the first one is an actual request. For now ignore any additional
195        // HEADERS (e.g. "trailers").
196        if driver.stream_map.contains_key(&stream_id) {
197            return Ok(());
198        }
199
200        let (mut stream_ctx, send, recv) = StreamCtx::new(
201            stream_id,
202            STREAM_CAPACITY,
203            driver.ready_stream_sender.clone(),
204        );
205
206        // Create the datagram flow immediately on request receipt so that
207        // any early datagrams buffered in `pending_dgrams` can be flushed.
208        // Only do this when extended CONNECT is enabled; otherwise the
209        // `:protocol` pseudo-header should not trigger flow creation.
210        //
211        // TODO: Longer term it would be ideal if we waited until the
212        // app *accepts* the request before we create the flow channels.
213        let dgram_flow = if driver.hooks.extended_connect_enabled {
214            if let Some(flow_id) =
215                datagram::extract_quarter_stream_id(stream_id, &headers)
216            {
217                stream_ctx.associated_dgram_flow_id = Some(flow_id);
218                Some(driver.establish_flow(qconn, stream_id, flow_id)?)
219            } else {
220                None
221            }
222        } else {
223            None
224        };
225        // Flush any pending datagrams that arrived before the CONNECT
226        // request was processed.
227        if let Some(flow_id) = stream_ctx.associated_dgram_flow_id {
228            if let Some(flow) = driver.flow_map.get_mut(&flow_id) {
229                driver.hooks.pending_dgrams.flush_to_flow(flow_id, flow);
230            }
231        }
232
233        let latest_priority_update: Option<RawPriorityValue> = driver
234            .conn_mut()?
235            .take_last_priority_update(stream_id)
236            .ok()
237            .map(|v| v.into());
238
239        // Boost the priority of the stream until we write response headers via
240        // process_write_frame(), which will set the desired priority. Since it
241        // will get set later, just swallow any error here.
242        qconn
243            .stream_priority(
244                stream_id,
245                PRE_HEADERS_BOOSTED_PRIORITY_URGENCY,
246                PRE_HEADERS_BOOSTED_PRIORITY_INCREMENTAL,
247            )
248            .ok();
249
250        let headers = IncomingH3Headers {
251            stream_id,
252            headers,
253            send,
254            recv,
255            read_fin: !has_body,
256            h3_audit_stats: Arc::clone(&stream_ctx.audit_stats),
257            dgram_flow,
258        };
259
260        stream_ctx.wait_for_recv();
261        driver.insert_stream(stream_id, stream_ctx);
262
263        // A STOP_SENDING received before HEADERS had no stream context for
264        // the writable pass to update. Handle it now that the context exists,
265        // before the Headers event gives the application a response sender.
266        //
267        // This ensures the sender is already closed if the peer canceled.
268        driver.process_writable_stream(qconn, stream_id)?;
269
270        driver
271            .h3_event_sender
272            .send(ServerH3Event::Headers {
273                incoming_headers: headers,
274                priority: latest_priority_update,
275                is_in_early_data: IsInEarlyData::new(qconn.is_in_early_data()),
276            })
277            .map_err(|_| H3ConnectionError::ControllerWentAway)?;
278        driver.hooks.requests += 1;
279
280        Ok(())
281    }
282
283    #[cfg(test)]
284    /// Returns a mutable reference to the pending datagram buffer.
285    pub(crate) fn pending_dgrams_mut(&mut self) -> &mut PendingDgramBuffer {
286        &mut self.pending_dgrams
287    }
288}
289
290#[allow(private_interfaces)]
291impl DriverHooks for ServerHooks {
292    type Command = ServerH3Command;
293    type Event = ServerH3Event;
294
295    fn new(settings: &Http3Settings) -> Self {
296        Self {
297            settings_enforcer: settings.into(),
298            requests: 0,
299            post_accept_timeout: None,
300            extended_connect_enabled: settings.enable_extended_connect,
301            pending_dgrams: PendingDgramBuffer::new(),
302        }
303    }
304
305    fn conn_established(
306        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
307        handshake_info: &HandshakeInfo,
308    ) -> H3ConnectionResult<()> {
309        assert!(
310            qconn.is_server(),
311            "ServerH3Driver requires a server-side QUIC connection"
312        );
313
314        if let Some(post_accept_timeout) =
315            driver.hooks.settings_enforcer.post_accept_timeout()
316        {
317            let remaining = post_accept_timeout
318                .checked_sub(handshake_info.elapsed())
319                .ok_or(H3ConnectionError::PostAcceptTimeout)?;
320
321            let key = driver
322                .hooks
323                .settings_enforcer
324                .add_timeout(Http3TimeoutType::PostAccept, remaining);
325            driver.hooks.post_accept_timeout = Some(key);
326        }
327
328        Ok(())
329    }
330
331    fn headers_received(
332        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
333        headers: InboundHeaders,
334    ) -> H3ConnectionResult<()> {
335        if driver
336            .hooks
337            .settings_enforcer
338            .enforce_requests_limit(driver.hooks.requests)
339        {
340            let _ =
341                qconn.close(true, quiche::h3::WireErrorCode::NoError as u64, &[]);
342            return Ok(());
343        }
344
345        if let Some(timeout) = driver.hooks.post_accept_timeout.take() {
346            // We've seen the first Headers event for the connection,
347            // so we can abort the post-accept timeout
348            driver.hooks.settings_enforcer.cancel_timeout(timeout);
349        }
350
351        Self::handle_request(driver, qconn, headers)
352    }
353
354    fn stream_recv_closed(_driver: &mut H3Driver<Self>, _stream_id: u64) {}
355
356    fn stream_closed(driver: &mut H3Driver<Self>, stream_id: u64) {
357        let _ = driver
358            .h3_event_sender
359            .send(H3Event::StreamClosed { stream_id }.into());
360    }
361
362    /// Server-side datagram receive logic:
363    ///
364    /// * If a [`FlowCtx`] already exists for `flow_id` (the CONNECT request has
365    ///   been processed), deliver the datagram immediately.
366    /// * Otherwise, buffer the datagram in `pending_dgrams` up to
367    ///   [`PENDING_DGRAM_CAPACITY`].
368    fn handle_incoming_dgram(
369        driver: &mut H3Driver<Self>, flow_id: DgramFlowId, dgram: InboundFrame,
370    ) {
371        // When extended CONNECT is disabled, no DATAGRAM flows can be
372        // established, so silently drop.
373        if !driver.hooks.extended_connect_enabled {
374            return;
375        }
376
377        // Flow already established.
378        if let Some(flow) = driver.get_flow(flow_id) {
379            flow.send_best_effort(dgram);
380            return;
381        }
382
383        // Buffer while awaiting the CONNECT request.
384        driver.hooks.pending_dgrams.push(flow_id, dgram);
385    }
386
387    fn expire_pending_dgrams(&mut self) {
388        self.pending_dgrams.expire();
389    }
390
391    fn conn_command(
392        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
393        cmd: Self::Command,
394    ) -> H3ConnectionResult<()> {
395        let ServerH3Command::Core(cmd) = cmd;
396        driver.handle_core_command(qconn, cmd)
397    }
398
399    fn has_wait_action(driver: &mut H3Driver<Self>) -> bool {
400        driver.hooks.settings_enforcer.has_pending_timeouts()
401    }
402
403    async fn wait_for_action(
404        &mut self, qconn: &mut QuicheConnection,
405    ) -> H3ConnectionResult<()> {
406        self.settings_enforcer.enforce_timeouts(qconn).await?;
407        Err(H3ConnectionError::PostAcceptTimeout)
408    }
409}