tokio_quiche/settings/
mod.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
27//! Configuration for QUIC connections.
28
29mod config;
30mod hooks;
31mod quic;
32mod tls;
33
34pub(crate) use self::config::*;
35
36pub use self::hooks::*;
37pub use self::quic::*;
38pub use self::tls::*;
39
40/// Combined configuration parameters required to establish a QUIC connection.
41///
42/// [`ConnectionParams`] aggregates the parameters required for all QUIC
43/// connections, regardless of whether it's a client- or server-side connection.
44/// To construct them, either `ConnectionParams::new_server` or
45/// `ConnectionParams::new_client` must be used. The parameters can be modified
46/// freely after construction.
47#[derive(Default)]
48#[non_exhaustive] // force use of constructor functions
49pub struct ConnectionParams<'a> {
50    /// QUIC connection settings.
51    pub settings: QuicSettings,
52    /// Optional TLS credentials to authenticate with.
53    pub tls_cert: Option<TlsCertificatePaths<'a>>,
54    /// Hooks to use for the connection.
55    pub hooks: Hooks,
56    /// Expose a per-connection DSCP handle for server connections.
57    ///
58    /// The handle initially omits per-packet marking, so packets inherit the
59    /// UDP socket's TOS/TClass until the application selects a value. Only
60    /// Linux UDP sockets support marking; client connections ignore this
61    /// setting.
62    pub enable_per_connection_dscp: bool,
63    /// Set the session to attempt resumption.
64    pub session: Option<Vec<u8>>,
65    /// Custom destination connection ID to use for client connections.
66    ///
67    /// Be aware that [RFC 9000] places requirements for unpredictability and
68    /// length on the client DCID field. Setting this field is dangerous if
69    /// these requirements are not satisfied.
70    ///
71    /// Has no effect on server-side [`ConnectionParams`].
72    ///
73    /// [RFC 9000]: <https://datatracker.ietf.org/doc/html/rfc9000#section-7.2-3>
74    #[cfg(feature = "custom-client-dcid")]
75    pub dcid: Option<quiche::ConnectionId<'static>>,
76}
77
78impl core::fmt::Debug for ConnectionParams<'_> {
79    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
80        // Avoid printing 'session' since it contains connection secrets.
81        let mut s = f.debug_struct("ConnectionParams");
82        s.field("settings", &self.settings)
83            .field("tls_cert", &self.tls_cert)
84            .field("hooks", &self.hooks)
85            .field(
86                "enable_per_connection_dscp",
87                &self.enable_per_connection_dscp,
88            );
89
90        #[cfg(feature = "custom-client-dcid")]
91        s.field("dcid", &self.dcid);
92
93        s.finish()
94    }
95}
96
97impl<'a> ConnectionParams<'a> {
98    /// Creates [`ConnectionParams`] for a QUIC server.
99    /// Servers should always specify TLS credentials.
100    #[inline]
101    pub fn new_server(
102        settings: QuicSettings, tls_cert: TlsCertificatePaths<'a>, hooks: Hooks,
103    ) -> Self {
104        Self {
105            settings,
106            tls_cert: Some(tls_cert),
107            hooks,
108            enable_per_connection_dscp: false,
109            session: None,
110            #[cfg(feature = "custom-client-dcid")]
111            dcid: None,
112        }
113    }
114
115    /// Creates [`ConnectionParams`] for a QUIC client.
116    /// Clients may enable mTLS by specifying TLS credentials.
117    #[inline]
118    pub fn new_client(
119        settings: QuicSettings, tls_cert: Option<TlsCertificatePaths<'a>>,
120        hooks: Hooks,
121    ) -> Self {
122        Self {
123            settings,
124            tls_cert,
125            hooks,
126            enable_per_connection_dscp: false,
127            session: None,
128            #[cfg(feature = "custom-client-dcid")]
129            dcid: None,
130        }
131    }
132}
tokio_quiche/settings/mod.rs

tokio_quiche/settings/
mod.rs
