tokio_quiche/http3/driver/
hooks.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 quiche::h3;
28use std::future::Future;
29
30use super::H3Command;
31use super::H3ConnectionResult;
32use super::H3Driver;
33use super::H3Event;
34use crate::http3::settings::Http3Settings;
35use crate::quic::HandshakeInfo;
36use crate::quic::QuicheConnection;
37
38/// A HEADERS frame received from the [`h3::Connection`], to be processed by
39/// the [DriverHooks].
40pub(crate) struct InboundHeaders {
41    pub(crate) stream_id: u64,
42    pub(crate) headers: Vec<h3::Header>,
43    pub(crate) has_body: bool,
44}
45
46/// Private trait to customize [H3Driver] for server or client operations.
47///
48/// Wherever endpoint-specific logic is required, a hook should be created in
49/// this trait and this hook then called in the appropriate [H3Driver] code.
50/// The hook can store its own data inside the [H3Driver] struct.
51#[allow(private_interfaces, unused)]
52pub trait DriverHooks: Sized + Send + 'static {
53    /// The type of [`H3Event`]s emitted by an [H3Driver] using these hooks.
54    /// The concrete type is expected to wrap [`H3Event`].
55    type Event: From<H3Event> + Send;
56    /// The type of [`H3Command`]s accepted by an [H3Driver] using these hooks.
57    /// The concrete type is expected to wrap [`H3Command`].
58    type Command: From<H3Command> + Send;
59
60    /// Initializes the storage for these hooks.
61    fn new(settings: &Http3Settings) -> Self;
62
63    /// Called in `ApplicationOverQuic::on_conn_established` after [H3Driver]
64    /// has been initialized. Used to verify connection settings and set up
65    /// post-accept state like timeouts.
66    fn conn_established(
67        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
68        handshake_info: &HandshakeInfo,
69    ) -> H3ConnectionResult<()>;
70
71    /// Processes any received [`h3::Event::Headers`]. There is no default
72    /// processing of HEADERS frames in [H3Driver].
73    fn headers_received(
74        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
75        headers: InboundHeaders,
76    ) -> H3ConnectionResult<()>;
77
78    /// Processes any command received from the
79    /// [`H3Controller`](super::H3Controller). May use
80    /// `H3Driver::handle_core_command` to handle regular [`H3Command`]s.
81    fn conn_command(
82        driver: &mut H3Driver<Self>, qconn: &mut QuicheConnection,
83        cmd: Self::Command,
84    ) -> H3ConnectionResult<()>;
85
86    /// Determines whether the hook's `wait_for_action` future will be polled
87    /// as part of `ApplicationOverQuic::wait_for_data`. Defaults to `false` and
88    /// must be overridden if `wait_for_action` is overridden.
89    fn has_wait_action(driver: &mut H3Driver<Self>) -> bool {
90        false
91    }
92
93    /// Returns a future that will be polled in
94    /// `ApplicationOverQuic::wait_for_data`, along with the other input
95    /// sources for the [H3Driver]. Note that the future will be dropped
96    /// before it resolves if another input is available first.
97    fn wait_for_action(
98        &mut self, qconn: &mut QuicheConnection,
99    ) -> impl Future<Output = H3ConnectionResult<()>> + Send {
100        std::future::pending()
101    }
102}
tokio_quiche/http3/driver/hooks.rs

tokio_quiche/http3/driver/
hooks.rs
