s2n_quic/server/builder.rs
1// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4use crate::{
5 provider::*,
6 server::{DefaultProviders, Server, ServerProviders},
7};
8
9/// A builder for configuring [`Server`] providers
10#[derive(Debug)]
11pub struct Builder<Providers>(pub(crate) Providers);
12
13impl Default for Builder<DefaultProviders> {
14 fn default() -> Self {
15 Self(Default::default())
16 }
17}
18
19impl<Providers: ServerProviders> Builder<Providers> {
20 impl_provider_method!(
21 /// Sets the connection ID provider for the [`Server`]
22 ///
23 /// # Examples
24 ///
25 /// Uses the default connection ID provider with the default configuration.
26 ///
27 /// ```rust,no_run
28 /// # use std::{error::Error, time::Duration};
29 /// use s2n_quic::{Server, provider::connection_id};
30 /// #
31 /// # #[tokio::main]
32 /// # async fn main() -> Result<(), Box<dyn Error>> {
33 /// let server = Server::builder()
34 /// .with_connection_id(connection_id::Default::default())?
35 /// .start()?;
36 /// #
37 /// # Ok(())
38 /// # }
39 /// ```
40 ///
41 /// Sets a custom connection ID provider for the server
42 ///
43 /// ```rust,no_run
44 /// # use std::{error::Error, time::Duration};
45 /// use s2n_quic::{Server, provider::connection_id};
46 /// use rand::prelude::*;
47 /// #
48 /// # #[tokio::main]
49 /// # async fn main() -> Result<(), Box<dyn Error>> {
50 /// struct MyConnectionIdFormat;
51 ///
52 /// impl connection_id::Generator for MyConnectionIdFormat {
53 /// fn generate(&mut self, _conn_info: &connection_id::ConnectionInfo) -> connection_id::LocalId {
54 /// let mut id = [0u8; 16];
55 /// rand::thread_rng().fill_bytes(&mut id);
56 /// connection_id::LocalId::try_from_bytes(&id[..]).unwrap()
57 /// }
58 /// }
59 ///
60 /// impl connection_id::Validator for MyConnectionIdFormat {
61 /// fn validate(&self, _conn_info: &connection_id::ConnectionInfo, packet: &[u8]) -> Option<usize> {
62 /// // this connection id format is always 16 bytes
63 /// Some(16)
64 /// }
65 /// }
66 ///
67 /// let server = Server::builder()
68 /// .with_connection_id(MyConnectionIdFormat)?
69 /// .start()?;
70 /// #
71 /// # Ok(())
72 /// # }
73 /// ```
74 with_connection_id,
75 connection_id,
76 ServerProviders
77 );
78
79 impl_provider_method!(
80 /// Sets the stateless reset token provider for the [`Server`]
81 ///
82 /// # Examples
83 ///
84 /// Sets a custom stateless reset token provider for the server
85 ///
86 /// ```rust,ignore
87 /// # use std::error::Error;
88 /// use s2n_quic::Server;
89 /// #
90 /// # #[tokio::main]
91 /// # async fn main() -> Result<(), Box<dyn Error>> {
92 /// let server = Server::builder()
93 /// .with_stateless_reset_token(MyStatelessResetTokenGenerator::new())?
94 /// .start()?;
95 /// #
96 /// # Ok(())
97 /// # }
98 /// ```
99 with_stateless_reset_token,
100 stateless_reset_token,
101 ServerProviders
102 );
103
104 impl_provider_method!(
105 /// Sets the limits provider for the [`Server`]
106 ///
107 /// # Examples
108 ///
109 /// Sets the max idle time, while inheriting the remaining default limits
110 ///
111 /// ```rust,no_run
112 /// # use std::{error::Error, time::Duration};
113 /// use s2n_quic::{Server, provider::limits};
114 /// #
115 /// # #[tokio::main]
116 /// # async fn main() -> Result<(), Box<dyn Error>> {
117 /// let server = Server::builder()
118 /// .with_limits(limits::Limits::new().with_max_idle_timeout(Duration::from_secs(40))?)?
119 /// .start()?;
120 /// #
121 /// # Ok(())
122 /// # }
123 /// ```
124 with_limits,
125 limits,
126 ServerProviders
127 );
128
129 impl_provider_method!(
130 /// Sets the endpoint limits provider for the [`Server`]
131 ///
132 /// # Examples
133 ///
134 /// Sets the max inflight handshakes for an endpoint, while inheriting the remaining default limits
135 ///
136 /// ```rust,no_run
137 /// # use std::{error::Error, time::Duration};
138 /// use s2n_quic::{Server, provider::endpoint_limits};
139 ///
140 /// # #[tokio::main]
141 /// # async fn main() -> Result<(), Box<dyn Error>> {
142 /// let server = Server::builder()
143 /// .with_endpoint_limits(
144 /// endpoint_limits::Default::builder()
145 /// .with_inflight_handshake_limit(100)?
146 /// .build()?,
147 /// )?
148 /// .start()?;
149 /// #
150 /// # Ok(())
151 /// # }
152 /// ```
153 with_endpoint_limits,
154 endpoint_limits,
155 ServerProviders
156 );
157
158 impl_provider_method!(
159 /// Sets the path specific mtu config provider for the [`Server`]
160 ///
161 /// # Examples
162 ///
163 /// Set custom MTU values to use per path, while inheriting the remaining default
164 /// config
165 ///
166 /// ```rust,no_run
167 /// # use std::{error::Error, time::Duration};
168 /// use s2n_quic::{Server, provider::mtu};
169 ///
170 /// # #[tokio::main]
171 /// # async fn main() -> Result<(), Box<dyn Error>> {
172 ///
173 /// struct MyMtuProvider(mtu::Config);
174 ///
175 /// impl mtu::Endpoint for MyMtuProvider {
176 /// fn on_path(
177 /// &mut self,
178 /// info: &mtu::PathInfo,
179 /// endpoint_mtu_config: mtu::Config,
180 /// ) -> Option<mtu::Config> {
181 /// Some(self.0)
182 /// }
183 /// }
184 /// let mtu = MyMtuProvider(mtu::Config::builder().build().unwrap());
185 ///
186 /// let server = Server::builder()
187 /// .with_mtu(mtu)?
188 /// .start()?;
189 /// #
190 /// # Ok(())
191 /// # }
192 /// ```
193 with_mtu,
194 mtu,
195 ServerProviders
196 );
197
198 impl_provider_method!(
199 /// Sets the event provider for the [`Server`]
200 ///
201 /// # Examples
202 ///
203 /// Sets a custom event subscriber for the server
204 ///
205 /// ```rust,ignore
206 /// # use std::{error::Error, time::Duration};
207 /// use s2n_quic::Server;
208 /// #
209 /// # #[tokio::main]
210 /// # async fn main() -> Result<(), Box<dyn Error>> {
211 /// let server = Server::builder()
212 /// .with_event(MyEventLogger::new())?
213 /// .start()?;
214 /// #
215 /// # Ok(())
216 /// # }
217 /// ```
218 with_event,
219 event,
220 ServerProviders
221 );
222
223 impl_provider_method!(
224 /// Sets the token provider for the [`Server`]
225 ///
226 /// # Examples
227 ///
228 /// Sets a custom token provider for the server
229 ///
230 /// ```rust,ignore
231 /// # use std::{error::Error, time::Duration};
232 /// use s2n_quic::Server;
233 /// #
234 /// # #[tokio::main]
235 /// # async fn main() -> Result<(), Box<dyn Error>> {
236 /// let server = Server::builder()
237 /// .with_address_token(MyTokenProvider::new())?
238 /// .start()?;
239 /// #
240 /// # Ok(())
241 /// # }
242 /// ```
243 with_address_token,
244 address_token,
245 ServerProviders
246 );
247
248 impl_provider_method!(
249 /// Sets the IO provider for the [`Server`]
250 ///
251 /// # Examples
252 ///
253 /// Starts listening on [`127.0.0.1:443`](https://127.0.0.1)
254 ///
255 /// ```rust,no_run
256 /// # use std::error::Error;
257 /// use s2n_quic::Server;
258 /// #
259 /// # #[tokio::main]
260 /// # async fn main() -> Result<(), Box<dyn Error>> {
261 /// let server = Server::builder()
262 /// .with_io("127.0.0.1:443")?
263 /// .start()?;
264 /// #
265 /// # Ok(())
266 /// # }
267 /// ```
268 ///
269 /// Configures a socket with the provided `Builder`
270 ///
271 /// ```rust,no_run
272 /// # use std::error::Error;
273 /// use s2n_quic::{Server, provider::io::tokio::Builder as IoBuilder};
274 /// use std::net::ToSocketAddrs;
275 /// #
276 /// # #[tokio::main]
277 /// # async fn main() -> Result<(), Box<dyn Error>> {
278 /// let addr = "127.0.0.1:443".to_socket_addrs()?.next().unwrap();
279 ///
280 /// let io = IoBuilder::default()
281 /// .with_receive_address(addr)?
282 /// .build()?;
283 ///
284 /// let server = Server::builder()
285 /// .with_io(io)?
286 /// .start()?;
287 /// #
288 /// # Ok(())
289 /// # }
290 /// ```
291 with_io,
292 io,
293 ServerProviders
294 );
295
296 impl_provider_method!(
297 /// Sets the TLS provider for the [`Server`]
298 ///
299 /// # Examples
300 ///
301 /// The default TLS provider and configuration will be used with the
302 /// path to the private key.
303 ///
304 /// ```rust,no_run
305 /// # use std::{error::Error, path::Path};
306 /// # use s2n_quic::Server;
307 /// #
308 /// # #[tokio::main]
309 /// # async fn main() -> Result<(), Box<dyn Error>> {
310 /// let server = Server::builder()
311 /// .with_tls((Path::new("./certs/cert.pem"), Path::new("./certs/key.pem")))?
312 /// .start()?;
313 /// #
314 /// # Ok(())
315 /// # }
316 /// ```
317 ///
318 /// Sets the TLS provider to a TLS server builder
319 ///
320 /// ```rust,ignore
321 /// # use std::{error::Error, path::Path};
322 /// # use s2n_quic::Server;
323 /// #
324 /// # #[tokio::main]
325 /// # async fn main() -> Result<(), Box<dyn Error>> {
326 /// let tls = s2n_tls::Server::builder()
327 /// .with_certificate(Path::new("./certs/cert.pem"), Path::new("./certs/key.pem"))?
328 /// .with_security_policy(s2n::tls::security_policy::S2N_20190802)?;
329 ///
330 /// let server = Server::builder()
331 /// .with_tls(tls)?
332 /// .start()?;
333 /// #
334 /// # Ok(())
335 /// # }
336 /// ```
337 with_tls,
338 tls,
339 ServerProviders
340 );
341
342 #[cfg(any(test, feature = "unstable-provider-packet-interceptor"))]
343 impl_provider_method!(
344 /// Sets the packet interceptor provider for the [`Server`]
345 with_packet_interceptor,
346 packet_interceptor,
347 ServerProviders
348 );
349
350 #[cfg(any(test, feature = "unstable-provider-random"))]
351 impl_provider_method!(
352 /// Sets the random provider for the [`Server`]
353 with_random,
354 random,
355 ServerProviders
356 );
357
358 #[cfg(feature = "unstable-provider-datagram")]
359 impl_provider_method!(
360 /// Sets the datagram provider for the [`Server`]
361 with_datagram,
362 datagram,
363 ServerProviders
364 );
365
366 #[cfg(any(test, feature = "unstable-provider-dc"))]
367 impl_provider_method!(
368 /// Sets the dc provider for the [`Server`]
369 with_dc,
370 dc,
371 ServerProviders
372 );
373
374 impl_provider_method!(
375 /// Sets the congestion controller provider for the [`Server`]
376 with_congestion_controller,
377 congestion_controller,
378 ServerProviders
379 );
380
381 /// Starts the [`Server`] with the configured providers
382 ///
383 /// # Examples
384 ///
385 /// ```rust,no_run
386 /// # use std::{error::Error, path::Path};
387 /// # use s2n_quic::Server;
388 /// #
389 /// # #[tokio::main]
390 /// # async fn main() -> Result<(), Box<dyn Error>> {
391 /// let server = Server::builder()
392 /// .with_tls((Path::new("./certs/cert.pem"), Path::new("./certs/key.pem")))?
393 /// .with_io("127.0.0.1:443")?
394 /// .start()?;
395 /// #
396 /// # Ok(())
397 /// # }
398 /// ```
399 pub fn start(self) -> Result<Server, StartError> {
400 self.0.build().start()
401 }
402}