leyline_quiche/lib.rs
1// Copyright (C) 2018-2019, 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//! 🥧 Savoury implementation of the QUIC transport protocol and HTTP/3.
28//!
29//! [quiche] is an implementation of the QUIC transport protocol and HTTP/3 as
30//! specified by the [IETF]. It provides a low level API for processing QUIC
31//! packets and handling connection state. The application is responsible for
32//! providing I/O (e.g. sockets handling) as well as an event loop with support
33//! for timers.
34//!
35//! [quiche]: https://github.com/cloudflare/quiche/
36//! [ietf]: https://quicwg.org/
37//!
38//! ## Configuring connections
39//!
40//! The first step in establishing a QUIC connection using quiche is creating a
41//! [`Config`] object:
42//!
43//! ```
44//! let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
45//! config.set_application_protos(&[b"example-proto"]);
46//!
47//! // Additional configuration specific to application and use case...
48//! # Ok::<(), quiche::Error>(())
49//! ```
50//!
51//! The [`Config`] object controls important aspects of the QUIC connection such
52//! as QUIC version, ALPN IDs, flow control, congestion control, idle timeout
53//! and other properties or features.
54//!
55//! QUIC is a general-purpose transport protocol and there are several
56//! configuration properties where there is no reasonable default value. For
57//! example, the permitted number of concurrent streams of any particular type
58//! is dependent on the application running over QUIC, and other use-case
59//! specific concerns.
60//!
61//! quiche defaults several properties to zero, applications most likely need
62//! to set these to something else to satisfy their needs using the following:
63//!
64//! - [`set_initial_max_streams_bidi()`]
65//! - [`set_initial_max_streams_uni()`]
66//! - [`set_initial_max_data()`]
67//! - [`set_initial_max_stream_data_bidi_local()`]
68//! - [`set_initial_max_stream_data_bidi_remote()`]
69//! - [`set_initial_max_stream_data_uni()`]
70//!
71//! [`Config`] also holds TLS configuration. This can be changed by mutators on
72//! the an existing object, or by constructing a TLS context manually and
73//! creating a configuration using [`with_boring_ssl_ctx_builder()`].
74//!
75//! A configuration object can be shared among multiple connections.
76//!
77//! ### Connection setup
78//!
79//! On the client-side the [`connect()`] utility function can be used to create
80//! a new connection, while [`accept()`] is for servers:
81//!
82//! ```
83//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
84//! # let server_name = "quic.tech";
85//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
86//! # let peer = "127.0.0.1:1234".parse().unwrap();
87//! # let local = "127.0.0.1:4321".parse().unwrap();
88//! // Client connection.
89//! let conn =
90//! quiche::connect(Some(&server_name), &scid, local, peer, &mut config)?;
91//!
92//! // Server connection.
93//! # let peer = "127.0.0.1:1234".parse().unwrap();
94//! # let local = "127.0.0.1:4321".parse().unwrap();
95//! let conn = quiche::accept(&scid, None, local, peer, &mut config)?;
96//! # Ok::<(), quiche::Error>(())
97//! ```
98//!
99//! In both cases, the application is responsible for generating a new source
100//! connection ID that will be used to identify the new connection.
101//!
102//! The application also need to pass the address of the remote peer of the
103//! connection: in the case of a client that would be the address of the server
104//! it is trying to connect to, and for a server that is the address of the
105//! client that initiated the connection.
106//!
107//! ## Handling incoming packets
108//!
109//! Using the connection's [`recv()`] method the application can process
110//! incoming packets that belong to that connection from the network:
111//!
112//! ```no_run
113//! # let mut buf = [0; 512];
114//! # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
115//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
116//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
117//! # let peer = "127.0.0.1:1234".parse().unwrap();
118//! # let local = "127.0.0.1:4321".parse().unwrap();
119//! # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
120//! let to = socket.local_addr().unwrap();
121//!
122//! loop {
123//! let (read, from) = socket.recv_from(&mut buf).unwrap();
124//!
125//! let recv_info = quiche::RecvInfo { from, to };
126//!
127//! let read = match conn.recv(&mut buf[..read], recv_info) {
128//! Ok(v) => v,
129//!
130//! Err(quiche::Error::Done) => {
131//! // Done reading.
132//! break;
133//! },
134//!
135//! Err(e) => {
136//! // An error occurred, handle it.
137//! break;
138//! },
139//! };
140//! }
141//! # Ok::<(), quiche::Error>(())
142//! ```
143//!
144//! The application has to pass a [`RecvInfo`] structure in order to provide
145//! additional information about the received packet (such as the address it
146//! was received from).
147//!
148//! ## Generating outgoing packets
149//!
150//! Outgoing packet are generated using the connection's [`send()`] method
151//! instead:
152//!
153//! ```no_run
154//! # let mut out = [0; 512];
155//! # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
156//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
157//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
158//! # let peer = "127.0.0.1:1234".parse().unwrap();
159//! # let local = "127.0.0.1:4321".parse().unwrap();
160//! # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
161//! loop {
162//! let (write, send_info) = match conn.send(&mut out) {
163//! Ok(v) => v,
164//!
165//! Err(quiche::Error::Done) => {
166//! // Done writing.
167//! break;
168//! },
169//!
170//! Err(e) => {
171//! // An error occurred, handle it.
172//! break;
173//! },
174//! };
175//!
176//! socket.send_to(&out[..write], &send_info.to).unwrap();
177//! }
178//! # Ok::<(), quiche::Error>(())
179//! ```
180//!
181//! The application will be provided with a [`SendInfo`] structure providing
182//! additional information about the newly created packet (such as the address
183//! the packet should be sent to).
184//!
185//! When packets are sent, the application is responsible for maintaining a
186//! timer to react to time-based connection events. The timer expiration can be
187//! obtained using the connection's [`timeout()`] method.
188//!
189//! ```
190//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
191//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
192//! # let peer = "127.0.0.1:1234".parse().unwrap();
193//! # let local = "127.0.0.1:4321".parse().unwrap();
194//! # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
195//! let timeout = conn.timeout();
196//! # Ok::<(), quiche::Error>(())
197//! ```
198//!
199//! The application is responsible for providing a timer implementation, which
200//! can be specific to the operating system or networking framework used. When
201//! a timer expires, the connection's [`on_timeout()`] method should be called,
202//! after which additional packets might need to be sent on the network:
203//!
204//! ```no_run
205//! # let mut out = [0; 512];
206//! # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
207//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
208//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
209//! # let peer = "127.0.0.1:1234".parse().unwrap();
210//! # let local = "127.0.0.1:4321".parse().unwrap();
211//! # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
212//! // Timeout expired, handle it.
213//! conn.on_timeout();
214//!
215//! // Send more packets as needed after timeout.
216//! loop {
217//! let (write, send_info) = match conn.send(&mut out) {
218//! Ok(v) => v,
219//!
220//! Err(quiche::Error::Done) => {
221//! // Done writing.
222//! break;
223//! },
224//!
225//! Err(e) => {
226//! // An error occurred, handle it.
227//! break;
228//! },
229//! };
230//!
231//! socket.send_to(&out[..write], &send_info.to).unwrap();
232//! }
233//! # Ok::<(), quiche::Error>(())
234//! ```
235//!
236//! ### Pacing
237//!
238//! It is recommended that applications [pace] sending of outgoing packets to
239//! avoid creating packet bursts that could cause short-term congestion and
240//! losses in the network.
241//!
242//! quiche exposes pacing hints for outgoing packets through the [`at`] field
243//! of the [`SendInfo`] structure that is returned by the [`send()`] method.
244//! This field represents the time when a specific packet should be sent into
245//! the network.
246//!
247//! Applications can use these hints by artificially delaying the sending of
248//! packets through platform-specific mechanisms (such as the [`SO_TXTIME`]
249//! socket option on Linux), or custom methods (for example by using user-space
250//! timers).
251//!
252//! [pace]: https://datatracker.ietf.org/doc/html/rfc9002#section-7.7
253//! [`SO_TXTIME`]: https://man7.org/linux/man-pages/man8/tc-etf.8.html
254//!
255//! ## Sending and receiving stream data
256//!
257//! After some back and forth, the connection will complete its handshake and
258//! will be ready for sending or receiving application data.
259//!
260//! Data can be sent on a stream by using the [`stream_send()`] method:
261//!
262//! ```no_run
263//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
264//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
265//! # let peer = "127.0.0.1:1234".parse().unwrap();
266//! # let local = "127.0.0.1:4321".parse().unwrap();
267//! # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
268//! if conn.is_established() {
269//! // Handshake completed, send some data on stream 0.
270//! conn.stream_send(0, b"hello", true)?;
271//! }
272//! # Ok::<(), quiche::Error>(())
273//! ```
274//!
275//! The application can check whether there are any readable streams by using
276//! the connection's [`readable()`] method, which returns an iterator over all
277//! the streams that have outstanding data to read.
278//!
279//! The [`stream_recv()`] method can then be used to retrieve the application
280//! data from the readable stream:
281//!
282//! ```no_run
283//! # let mut buf = [0; 512];
284//! # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
285//! # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
286//! # let peer = "127.0.0.1:1234".parse().unwrap();
287//! # let local = "127.0.0.1:4321".parse().unwrap();
288//! # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
289//! if conn.is_established() {
290//! // Iterate over readable streams.
291//! for stream_id in conn.readable() {
292//! // Stream is readable, read until there's no more data.
293//! while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
294//! println!("Got {} bytes on stream {}", read, stream_id);
295//! }
296//! }
297//! }
298//! # Ok::<(), quiche::Error>(())
299//! ```
300//!
301//! ## HTTP/3
302//!
303//! The quiche [HTTP/3 module] provides a high level API for sending and
304//! receiving HTTP requests and responses on top of the QUIC transport protocol.
305//!
306//! [`Config`]: https://docs.quic.tech/quiche/struct.Config.html
307//! [`set_initial_max_streams_bidi()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_bidi
308//! [`set_initial_max_streams_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_streams_uni
309//! [`set_initial_max_data()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_data
310//! [`set_initial_max_stream_data_bidi_local()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_local
311//! [`set_initial_max_stream_data_bidi_remote()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_bidi_remote
312//! [`set_initial_max_stream_data_uni()`]: https://docs.rs/quiche/latest/quiche/struct.Config.html#method.set_initial_max_stream_data_uni
313//! [`with_boring_ssl_ctx_builder()`]: https://docs.quic.tech/quiche/struct.Config.html#method.with_boring_ssl_ctx_builder
314//! [`connect()`]: fn.connect.html
315//! [`accept()`]: fn.accept.html
316//! [`recv()`]: struct.Connection.html#method.recv
317//! [`RecvInfo`]: struct.RecvInfo.html
318//! [`send()`]: struct.Connection.html#method.send
319//! [`SendInfo`]: struct.SendInfo.html
320//! [`at`]: struct.SendInfo.html#structfield.at
321//! [`timeout()`]: struct.Connection.html#method.timeout
322//! [`on_timeout()`]: struct.Connection.html#method.on_timeout
323//! [`stream_send()`]: struct.Connection.html#method.stream_send
324//! [`readable()`]: struct.Connection.html#method.readable
325//! [`stream_recv()`]: struct.Connection.html#method.stream_recv
326//! [HTTP/3 module]: h3/index.html
327//!
328//! ## Congestion Control
329//!
330//! The quiche library provides a high-level API for configuring which
331//! congestion control algorithm to use throughout the QUIC connection.
332//!
333//! When a QUIC connection is created, the application can optionally choose
334//! which CC algorithm to use. See [`CongestionControlAlgorithm`] for currently
335//! available congestion control algorithms.
336//!
337//! For example:
338//!
339//! ```
340//! let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION).unwrap();
341//! config.set_cc_algorithm(quiche::CongestionControlAlgorithm::Reno);
342//! ```
343//!
344//! Alternatively, you can configure the congestion control algorithm to use
345//! by its name.
346//!
347//! ```
348//! let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION).unwrap();
349//! config.set_cc_algorithm_name("reno").unwrap();
350//! ```
351//!
352//! Note that the CC algorithm should be configured before calling [`connect()`]
353//! or [`accept()`]. Otherwise the connection will use a default CC algorithm.
354//!
355//! [`CongestionControlAlgorithm`]: enum.CongestionControlAlgorithm.html
356//!
357//! ## Feature flags
358//!
359//! quiche defines a number of [feature flags] to reduce the amount of compiled
360//! code and dependencies:
361//!
362//! * `boringssl-bssl-crate` (default): Use the BoringSSL library provided by
363//! the [leyline_bssl] crate.
364//!
365//! * `pkg-config-meta`: Generate pkg-config metadata file for libquiche.
366//!
367//! * `ffi`: Build and expose the FFI API.
368//!
369//! * `qlog`: Enable support for the [qlog] logging format.
370//!
371//! * `custom-client-dcid`: Allow clients to supply a custom DCID when
372//! initiating a connection. Dangerous if the DCID does not meet QUIC's
373//! unpredictability and length requirements.
374//!
375//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
376//! [leyline_bssl]: https://crates.io/crates/leyline_bssl
377//! [qlog]: https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-main-schema
378
379#![allow(clippy::upper_case_acronyms)]
380#![warn(unused_qualifications)]
381#![cfg_attr(docsrs, feature(doc_cfg))]
382
383#[macro_use]
384extern crate log;
385
386use std::cmp;
387
388use std::collections::VecDeque;
389
390use debug_panic::debug_panic;
391
392use std::net::SocketAddr;
393
394use std::str::FromStr;
395
396use std::sync::Arc;
397
398use std::time::Duration;
399use std::time::Instant;
400
401#[cfg(feature = "qlog")]
402use qlog::events::DataRecipient;
403#[cfg(feature = "qlog")]
404use qlog::events::Event;
405#[cfg(feature = "qlog")]
406use qlog::events::EventData;
407#[cfg(feature = "qlog")]
408use qlog::events::EventImportance;
409#[cfg(feature = "qlog")]
410use qlog::events::EventType;
411#[cfg(feature = "qlog")]
412use qlog::events::RawInfo;
413#[cfg(feature = "qlog")]
414use qlog::events::quic::DataMovedAdditionalInfo;
415#[cfg(feature = "qlog")]
416use qlog::events::quic::QuicEventType;
417#[cfg(feature = "qlog")]
418use qlog::events::quic::TransportInitiator;
419
420use smallvec::SmallVec;
421
422use crate::buffers::DefaultBufFactory;
423
424use crate::recovery::OnAckReceivedOutcome;
425use crate::recovery::OnLossDetectionTimeoutOutcome;
426use crate::recovery::RecoveryOps;
427use crate::recovery::ReleaseDecision;
428
429use crate::stream::RecvAction;
430use crate::stream::StreamPriorityKey;
431
432/// The current QUIC wire version.
433pub const PROTOCOL_VERSION: u32 = PROTOCOL_VERSION_V1;
434
435/// Supported QUIC versions.
436const PROTOCOL_VERSION_V1: u32 = 0x0000_0001;
437
438const PROTOCOL_VERSION_V2: u32 = 0x6b33_43cf;
439
440/// The maximum length of a connection ID.
441pub const MAX_CONN_ID_LEN: usize = packet::MAX_CID_LEN as usize;
442
443/// The minimum length of Initial packets sent by a client.
444pub const MIN_CLIENT_INITIAL_LEN: usize = 1200;
445
446const MAX_IPV6_INITIAL_LEN: usize = 1232;
447
448/// The default initial RTT.
449const DEFAULT_INITIAL_RTT: Duration = Duration::from_millis(333);
450
451const PAYLOAD_MIN_LEN: usize = 4;
452
453// PATH_CHALLENGE (9 bytes) + AEAD tag (16 bytes).
454const MIN_PROBING_SIZE: usize = 25;
455
456const MAX_AMPLIFICATION_FACTOR: usize = 3;
457
458// The maximum number of tracked packet number ranges that need to be acked.
459//
460// This represents more or less how many ack blocks can fit in a typical packet.
461const MAX_ACK_RANGES: usize = 68;
462
463// The highest possible stream ID allowed.
464const MAX_STREAM_ID: u64 = 1 << 60;
465
466// The default max_datagram_size used in congestion control.
467const MAX_SEND_UDP_PAYLOAD_SIZE: usize = 1200;
468
469// The default length of DATAGRAM queues.
470const DEFAULT_MAX_DGRAM_QUEUE_LEN: usize = 0;
471
472// The default length of PATH_CHALLENGE receive queue.
473const DEFAULT_MAX_PATH_CHALLENGE_RX_QUEUE_LEN: usize = 3;
474
475// The DATAGRAM standard recommends either none or 65536 as maximum DATAGRAM
476// frames size. We enforce the recommendation for forward compatibility.
477const MAX_DGRAM_FRAME_SIZE: u64 = 65536;
478
479// The length of the payload length field.
480const PAYLOAD_LENGTH_LEN: usize = 2;
481
482// The number of undecryptable that can be buffered.
483const MAX_UNDECRYPTABLE_PACKETS: usize = 10;
484
485const RESERVED_VERSION_MASK: u32 = 0xfafafafa;
486
487// The maximum size of the receiver connection flow control window.
488const MAX_CONNECTION_WINDOW: u64 = 24 * 1024 * 1024;
489
490// How much larger the connection flow control window need to be larger than
491// the stream flow control window.
492const CONNECTION_WINDOW_FACTOR: f64 = 1.5;
493
494// How many probing packet timeouts do we tolerate before considering the path
495// validation as failed.
496const MAX_PROBING_TIMEOUTS: usize = 3;
497
498// The default initial congestion window size in terms of packet count.
499const DEFAULT_INITIAL_CONGESTION_WINDOW_PACKETS: usize = 10;
500
501// The maximum data offset that can be stored in a crypto stream.
502const MAX_CRYPTO_STREAM_OFFSET: u64 = 1 << 16;
503
504// The send capacity factor.
505const TX_CAP_FACTOR: f64 = 1.0;
506
507/// Ancillary information about incoming packets.
508#[derive(Clone, Copy, Debug, PartialEq, Eq)]
509pub struct RecvInfo {
510 /// The remote address the packet was received from.
511 pub from: SocketAddr,
512
513 /// The local address the packet was received on.
514 pub to: SocketAddr,
515}
516
517/// Ancillary information about outgoing packets.
518#[derive(Clone, Copy, Debug, PartialEq, Eq)]
519pub struct SendInfo {
520 /// The local address the packet should be sent from.
521 pub from: SocketAddr,
522
523 /// The remote address the packet should be sent to.
524 pub to: SocketAddr,
525
526 /// The time to send the packet out.
527 ///
528 /// See [Pacing] for more details.
529 ///
530 /// [Pacing]: index.html#pacing
531 pub at: Instant,
532}
533
534/// The side of the stream to be shut down.
535///
536/// This should be used when calling [`stream_shutdown()`].
537///
538/// [`stream_shutdown()`]: struct.Connection.html#method.stream_shutdown
539#[repr(C)]
540#[derive(PartialEq, Eq)]
541pub enum Shutdown {
542 /// Stop receiving stream data.
543 Read = 0,
544
545 /// Stop sending stream data.
546 Write = 1,
547}
548
549/// Qlog logging level.
550#[repr(C)]
551#[cfg(feature = "qlog")]
552#[cfg_attr(docsrs, doc(cfg(feature = "qlog")))]
553pub enum QlogLevel {
554 /// Logs any events of Core importance.
555 Core = 0,
556
557 /// Logs any events of Core and Base importance.
558 Base = 1,
559
560 /// Logs any events of Core, Base and Extra importance
561 Extra = 2,
562}
563
564/// Stores configuration shared between multiple connections.
565pub struct Config {
566 local_transport_params: TransportParams,
567
568 version: u32,
569
570 tls_ctx: tls::Context,
571
572 application_protos: Vec<Vec<u8>>,
573
574 grease: bool,
575
576 cc_algorithm: CongestionControlAlgorithm,
577 custom_bbr_params: Option<BbrParams>,
578 initial_congestion_window_packets: usize,
579 enable_relaxed_loss_threshold: bool,
580 enable_cubic_idle_restart_fix: bool,
581 enable_send_streams_blocked: bool,
582
583 pmtud: bool,
584 pmtud_max_probes: u8,
585
586 hystart: bool,
587
588 pacing: bool,
589 /// Send rate limit in Mbps
590 max_pacing_rate: Option<u64>,
591
592 tx_cap_factor: f64,
593
594 dgram_recv_max_queue_len: usize,
595 dgram_send_max_queue_len: usize,
596
597 path_challenge_recv_max_queue_len: usize,
598
599 max_send_udp_payload_size: usize,
600
601 max_connection_window: u64,
602 max_stream_window: u64,
603
604 max_amplification_factor: usize,
605
606 disable_dcid_reuse: bool,
607
608 track_unknown_transport_params: Option<usize>,
609
610 initial_rtt: Duration,
611
612 transport_params_plan: Option<Vec<TransportParamEntry>>,
613
614 compatible_versions: Vec<u32>,
615
616 initial_datagram_size: Option<usize>,
617
618 initial_crypto_split: InitialCryptoSplit,
619}
620
621// See https://quicwg.org/base-drafts/rfc9000.html#section-15
622fn is_reserved_version(version: u32) -> bool {
623 version & RESERVED_VERSION_MASK == version
624}
625
626impl Config {
627 /// Creates a config object with the given version.
628 ///
629 /// ## Examples:
630 ///
631 /// ```
632 /// let config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
633 /// # Ok::<(), quiche::Error>(())
634 /// ```
635 pub fn new(version: u32) -> Result<Config> {
636 Self::with_tls_ctx(version, tls::Context::new()?)
637 }
638
639 /// Creates a config object with the given version and
640 /// [`SslContextBuilder`].
641 ///
642 /// This is useful for applications that wish to manually configure
643 /// [`SslContextBuilder`].
644 ///
645 /// [`SslContextBuilder`]: https://docs.rs/boring/latest/boring/ssl/struct.SslContextBuilder.html
646 #[cfg(feature = "boringssl-bssl-crate")]
647 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
648 pub fn with_boring_ssl_ctx_builder(
649 version: u32,
650 tls_ctx_builder: leyline_bssl::ssl::SslContextBuilder,
651 ) -> Result<Config> {
652 Self::with_tls_ctx(version, tls::Context::from_bssl(tls_ctx_builder)?)
653 }
654
655 fn with_tls_ctx(version: u32, tls_ctx: tls::Context) -> Result<Config> {
656 if !is_reserved_version(version) && !version_is_supported(version) {
657 return Err(Error::UnknownVersion);
658 }
659
660 Ok(Config {
661 local_transport_params: TransportParams::default(),
662 version,
663 tls_ctx,
664 application_protos: Vec::new(),
665 grease: true,
666 cc_algorithm: CongestionControlAlgorithm::CUBIC,
667 custom_bbr_params: None,
668 initial_congestion_window_packets: DEFAULT_INITIAL_CONGESTION_WINDOW_PACKETS,
669 enable_relaxed_loss_threshold: false,
670 enable_cubic_idle_restart_fix: true,
671 enable_send_streams_blocked: false,
672 pmtud: false,
673 pmtud_max_probes: pmtud::MAX_PROBES_DEFAULT,
674 hystart: true,
675 pacing: true,
676 max_pacing_rate: None,
677
678 tx_cap_factor: TX_CAP_FACTOR,
679
680 dgram_recv_max_queue_len: DEFAULT_MAX_DGRAM_QUEUE_LEN,
681 dgram_send_max_queue_len: DEFAULT_MAX_DGRAM_QUEUE_LEN,
682
683 path_challenge_recv_max_queue_len: DEFAULT_MAX_PATH_CHALLENGE_RX_QUEUE_LEN,
684
685 max_send_udp_payload_size: MAX_SEND_UDP_PAYLOAD_SIZE,
686
687 max_connection_window: MAX_CONNECTION_WINDOW,
688 max_stream_window: stream::MAX_STREAM_WINDOW,
689
690 max_amplification_factor: MAX_AMPLIFICATION_FACTOR,
691
692 disable_dcid_reuse: false,
693
694 track_unknown_transport_params: None,
695 initial_rtt: DEFAULT_INITIAL_RTT,
696 transport_params_plan: None,
697 compatible_versions: Vec::new(),
698 initial_datagram_size: None,
699 initial_crypto_split: InitialCryptoSplit::Fill,
700 })
701 }
702
703 /// Configures the given certificate chain.
704 ///
705 /// The content of `file` is parsed as a PEM-encoded leaf certificate,
706 /// followed by optional intermediate certificates.
707 ///
708 /// ## Examples:
709 ///
710 /// ```no_run
711 /// # let mut config = quiche::Config::new(0xbabababa)?;
712 /// config.load_cert_chain_from_pem_file("/path/to/cert.pem")?;
713 /// # Ok::<(), quiche::Error>(())
714 /// ```
715 pub fn load_cert_chain_from_pem_file(&mut self, file: &str) -> Result<()> {
716 self.tls_ctx.use_certificate_chain_file(file)
717 }
718
719 /// Configures the given private key.
720 ///
721 /// The content of `file` is parsed as a PEM-encoded private key.
722 ///
723 /// ## Examples:
724 ///
725 /// ```no_run
726 /// # let mut config = quiche::Config::new(0xbabababa)?;
727 /// config.load_priv_key_from_pem_file("/path/to/key.pem")?;
728 /// # Ok::<(), quiche::Error>(())
729 /// ```
730 pub fn load_priv_key_from_pem_file(&mut self, file: &str) -> Result<()> {
731 self.tls_ctx.use_privkey_file(file)
732 }
733
734 /// Specifies a file where trusted CA certificates are stored for the
735 /// purposes of certificate verification.
736 ///
737 /// The content of `file` is parsed as a PEM-encoded certificate chain.
738 ///
739 /// ## Examples:
740 ///
741 /// ```no_run
742 /// # let mut config = quiche::Config::new(0xbabababa)?;
743 /// config.load_verify_locations_from_file("/path/to/cert.pem")?;
744 /// # Ok::<(), quiche::Error>(())
745 /// ```
746 pub fn load_verify_locations_from_file(&mut self, file: &str) -> Result<()> {
747 self.tls_ctx.load_verify_locations_from_file(file)
748 }
749
750 /// Specifies a directory where trusted CA certificates are stored for the
751 /// purposes of certificate verification.
752 ///
753 /// The content of `dir` a set of PEM-encoded certificate chains.
754 ///
755 /// ## Examples:
756 ///
757 /// ```no_run
758 /// # let mut config = quiche::Config::new(0xbabababa)?;
759 /// config.load_verify_locations_from_directory("/path/to/certs")?;
760 /// # Ok::<(), quiche::Error>(())
761 /// ```
762 pub fn load_verify_locations_from_directory(&mut self, dir: &str) -> Result<()> {
763 self.tls_ctx.load_verify_locations_from_directory(dir)
764 }
765
766 /// Configures the TLS curve preference list.
767 ///
768 /// `curves` is a colon-separated list of curve (a.k.a. group) names, in
769 /// order of preference, e.g. `"X25519MLKEM768:X25519:P-256:P-384"`.
770 /// Corresponds to `SSL_CTX_set1_curves_list` (a.k.a.
771 /// `SSL_CTX_set1_groups_list`).
772 pub fn set_curves_list(&mut self, curves: &str) -> Result<()> {
773 self.tls_ctx.set_curves_list(curves)
774 }
775
776 /// Configures whether to verify the peer's certificate.
777 ///
778 /// This should usually be `true` for client-side connections and `false`
779 /// for server-side ones.
780 ///
781 /// Note that by default, no verification is performed.
782 ///
783 /// Also note that on the server-side, enabling verification of the peer
784 /// will trigger a certificate request and make authentication errors
785 /// fatal, but will still allow anonymous clients (i.e. clients that
786 /// don't present a certificate at all). Servers can check whether a
787 /// client presented a certificate by calling [`peer_cert()`] if they
788 /// need to.
789 ///
790 /// [`peer_cert()`]: struct.Connection.html#method.peer_cert
791 pub fn verify_peer(&mut self, verify: bool) {
792 self.tls_ctx.set_verify(verify);
793 }
794
795 /// Configures whether to do path MTU discovery.
796 ///
797 /// PMTUD-driven packet limit updates are reported to the application
798 /// through [`PathEvent::PmtuUpdated`].
799 ///
800 /// The default value is `false`.
801 pub fn discover_pmtu(&mut self, discover: bool) {
802 self.pmtud = discover;
803 }
804
805 /// Configures the maximum number of PMTUD probe attempts before treating
806 /// a probe size as failed.
807 ///
808 /// Defaults to 3 per [RFC 8899 Section 5.1.2](https://datatracker.ietf.org/doc/html/rfc8899#section-5.1.2).
809 /// If 0 is passed, the default value is used.
810 pub fn set_pmtud_max_probes(&mut self, max_probes: u8) {
811 self.pmtud_max_probes = max_probes;
812 }
813
814 /// Configures whether to send GREASE values.
815 ///
816 /// The default value is `true`.
817 pub fn grease(&mut self, grease: bool) {
818 self.grease = grease;
819 }
820
821 pub fn set_transport_params_plan(&mut self, plan: Vec<TransportParamEntry>) {
822 self.transport_params_plan = Some(plan);
823 }
824
825 pub fn set_compatible_versions(&mut self, versions: &[u32]) {
826 self.compatible_versions = versions
827 .iter()
828 .copied()
829 .filter(|version| version_is_supported(*version))
830 .collect();
831 }
832
833 pub fn set_initial_datagram_size(&mut self, size: usize) {
834 self.initial_datagram_size = Some(size.max(MIN_CLIENT_INITIAL_LEN));
835 }
836
837 pub fn set_initial_crypto_split(&mut self, split: InitialCryptoSplit) {
838 self.initial_crypto_split = split;
839 }
840
841 /// Enables logging of secrets.
842 ///
843 /// When logging is enabled, the [`set_keylog()`] method must be called on
844 /// the connection for its cryptographic secrets to be logged in the
845 /// [keylog] format to the specified writer.
846 ///
847 /// [`set_keylog()`]: struct.Connection.html#method.set_keylog
848 /// [keylog]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
849 pub fn log_keys(&mut self) {
850 self.tls_ctx.enable_keylog();
851 }
852
853 /// Configures the session ticket key material.
854 ///
855 /// On the server this key will be used to encrypt and decrypt session
856 /// tickets, used to perform session resumption without server-side state.
857 ///
858 /// By default a key is generated internally, and rotated regularly, so
859 /// applications don't need to call this unless they need to use a
860 /// specific key (e.g. in order to support resumption across multiple
861 /// servers), in which case the application is also responsible for
862 /// rotating the key to provide forward secrecy.
863 pub fn set_ticket_key(&mut self, key: &[u8]) -> Result<()> {
864 self.tls_ctx.set_ticket_key(key)
865 }
866
867 /// Enables sending or receiving early data.
868 pub fn enable_early_data(&mut self) {
869 self.tls_ctx.set_early_data_enabled(true);
870 }
871
872 /// Configures the list of supported application protocols.
873 ///
874 /// On the client this configures the list of protocols to send to the
875 /// server as part of the ALPN extension.
876 ///
877 /// On the server this configures the list of supported protocols to match
878 /// against the client-supplied list.
879 ///
880 /// Applications must set a value, but no default is provided.
881 ///
882 /// ## Examples:
883 ///
884 /// ```
885 /// # let mut config = quiche::Config::new(0xbabababa)?;
886 /// config.set_application_protos(&[b"http/1.1", b"http/0.9"]);
887 /// # Ok::<(), quiche::Error>(())
888 /// ```
889 pub fn set_application_protos(&mut self, protos_list: &[&[u8]]) -> Result<()> {
890 self.application_protos = protos_list.iter().map(|s| s.to_vec()).collect();
891
892 self.tls_ctx.set_alpn(protos_list)
893 }
894
895 /// Configures the list of supported application protocols using wire
896 /// format.
897 ///
898 /// The list of protocols `protos` must be a series of non-empty, 8-bit
899 /// length-prefixed strings.
900 ///
901 /// See [`set_application_protos`](Self::set_application_protos) for more
902 /// background about application protocols.
903 ///
904 /// ## Examples:
905 ///
906 /// ```
907 /// # let mut config = quiche::Config::new(0xbabababa)?;
908 /// config.set_application_protos_wire_format(b"\x08http/1.1\x08http/0.9")?;
909 /// # Ok::<(), quiche::Error>(())
910 /// ```
911 pub fn set_application_protos_wire_format(&mut self, protos: &[u8]) -> Result<()> {
912 let mut b = octets::Octets::with_slice(protos);
913
914 let mut protos_list = Vec::new();
915
916 while let Ok(proto) = b.get_bytes_with_u8_length() {
917 protos_list.push(proto.buf());
918 }
919
920 self.set_application_protos(&protos_list)
921 }
922
923 /// Sets the anti-amplification limit factor.
924 ///
925 /// The default value is `3`.
926 pub fn set_max_amplification_factor(&mut self, v: usize) {
927 self.max_amplification_factor = v;
928 }
929
930 /// Sets the send capacity factor.
931 ///
932 /// The default value is `1`.
933 pub fn set_send_capacity_factor(&mut self, v: f64) {
934 self.tx_cap_factor = v;
935 }
936
937 /// Sets the connection's initial RTT.
938 ///
939 /// The default value is `333`.
940 pub fn set_initial_rtt(&mut self, v: Duration) {
941 self.initial_rtt = v;
942 }
943
944 /// Sets the `max_idle_timeout` transport parameter, in milliseconds.
945 ///
946 /// The default value is infinite, that is, no timeout is used.
947 pub fn set_max_idle_timeout(&mut self, v: u64) {
948 self.local_transport_params.max_idle_timeout = cmp::min(v, octets::MAX_VAR_INT);
949 }
950
951 /// Sets the `max_udp_payload_size transport` parameter.
952 ///
953 /// The default value is `65527`.
954 pub fn set_max_recv_udp_payload_size(&mut self, v: usize) {
955 self.local_transport_params.max_udp_payload_size = cmp::min(v as u64, octets::MAX_VAR_INT);
956 }
957
958 /// Sets the maximum outgoing UDP payload size.
959 ///
960 /// The default and minimum value is `1200`.
961 pub fn set_max_send_udp_payload_size(&mut self, v: usize) {
962 self.max_send_udp_payload_size = cmp::max(v, MAX_SEND_UDP_PAYLOAD_SIZE);
963 }
964
965 /// Sets the `initial_max_data` transport parameter.
966 ///
967 /// When set to a non-zero value quiche will only allow at most `v` bytes of
968 /// incoming stream data to be buffered for the whole connection (that is,
969 /// data that is not yet read by the application) and will allow more data
970 /// to be received as the buffer is consumed by the application.
971 ///
972 /// When set to zero, either explicitly or via the default, quiche will not
973 /// give any flow control to the peer, preventing it from sending any stream
974 /// data.
975 ///
976 /// The default value is `0`.
977 pub fn set_initial_max_data(&mut self, v: u64) {
978 self.local_transport_params.initial_max_data = cmp::min(v, octets::MAX_VAR_INT);
979 }
980
981 /// Sets the `initial_max_stream_data_bidi_local` transport parameter.
982 ///
983 /// When set to a non-zero value quiche will only allow at most `v` bytes
984 /// of incoming stream data to be buffered for each locally-initiated
985 /// bidirectional stream (that is, data that is not yet read by the
986 /// application) and will allow more data to be received as the buffer is
987 /// consumed by the application.
988 ///
989 /// When set to zero, either explicitly or via the default, quiche will not
990 /// give any flow control to the peer, preventing it from sending any stream
991 /// data.
992 ///
993 /// The default value is `0`.
994 pub fn set_initial_max_stream_data_bidi_local(&mut self, v: u64) {
995 self.local_transport_params
996 .initial_max_stream_data_bidi_local = cmp::min(v, octets::MAX_VAR_INT);
997 }
998
999 /// Sets the `initial_max_stream_data_bidi_remote` transport parameter.
1000 ///
1001 /// When set to a non-zero value quiche will only allow at most `v` bytes
1002 /// of incoming stream data to be buffered for each remotely-initiated
1003 /// bidirectional stream (that is, data that is not yet read by the
1004 /// application) and will allow more data to be received as the buffer is
1005 /// consumed by the application.
1006 ///
1007 /// When set to zero, either explicitly or via the default, quiche will not
1008 /// give any flow control to the peer, preventing it from sending any stream
1009 /// data.
1010 ///
1011 /// The default value is `0`.
1012 pub fn set_initial_max_stream_data_bidi_remote(&mut self, v: u64) {
1013 self.local_transport_params
1014 .initial_max_stream_data_bidi_remote = cmp::min(v, octets::MAX_VAR_INT);
1015 }
1016
1017 /// Sets the `initial_max_stream_data_uni` transport parameter.
1018 ///
1019 /// When set to a non-zero value quiche will only allow at most `v` bytes
1020 /// of incoming stream data to be buffered for each unidirectional stream
1021 /// (that is, data that is not yet read by the application) and will allow
1022 /// more data to be received as the buffer is consumed by the application.
1023 ///
1024 /// When set to zero, either explicitly or via the default, quiche will not
1025 /// give any flow control to the peer, preventing it from sending any stream
1026 /// data.
1027 ///
1028 /// The default value is `0`.
1029 pub fn set_initial_max_stream_data_uni(&mut self, v: u64) {
1030 self.local_transport_params.initial_max_stream_data_uni = cmp::min(v, octets::MAX_VAR_INT);
1031 }
1032
1033 /// Sets the `initial_max_streams_bidi` transport parameter.
1034 ///
1035 /// When set to a non-zero value quiche will only allow `v` number of
1036 /// concurrent remotely-initiated bidirectional streams to be open at any
1037 /// given time and will increase the limit automatically as streams are
1038 /// completed.
1039 ///
1040 /// When set to zero, either explicitly or via the default, quiche will not
1041 /// not allow the peer to open any bidirectional streams.
1042 ///
1043 /// A bidirectional stream is considered completed when all incoming data
1044 /// has been read by the application (up to the `fin` offset) or the
1045 /// stream's read direction has been shutdown, and all outgoing data has
1046 /// been acked by the peer (up to the `fin` offset) or the stream's write
1047 /// direction has been shutdown.
1048 ///
1049 /// The default value is `0`.
1050 pub fn set_initial_max_streams_bidi(&mut self, v: u64) {
1051 self.local_transport_params.initial_max_streams_bidi = cmp::min(v, octets::MAX_VAR_INT);
1052 }
1053
1054 /// Sets the `initial_max_streams_uni` transport parameter.
1055 ///
1056 /// When set to a non-zero value quiche will only allow `v` number of
1057 /// concurrent remotely-initiated unidirectional streams to be open at any
1058 /// given time and will increase the limit automatically as streams are
1059 /// completed.
1060 ///
1061 /// When set to zero, either explicitly or via the default, quiche will not
1062 /// not allow the peer to open any unidirectional streams.
1063 ///
1064 /// A unidirectional stream is considered completed when all incoming data
1065 /// has been read by the application (up to the `fin` offset) or the
1066 /// stream's read direction has been shutdown.
1067 ///
1068 /// The default value is `0`.
1069 pub fn set_initial_max_streams_uni(&mut self, v: u64) {
1070 self.local_transport_params.initial_max_streams_uni = cmp::min(v, octets::MAX_VAR_INT);
1071 }
1072
1073 /// Sets the `ack_delay_exponent` transport parameter.
1074 ///
1075 /// Values above the RFC 9000 maximum of
1076 /// [`MAX_ACK_DELAY_EXPONENT`] (20) are clamped to that
1077 /// maximum.
1078 ///
1079 /// The default value is `3`.
1080 pub fn set_ack_delay_exponent(&mut self, v: u64) {
1081 self.local_transport_params.ack_delay_exponent = cmp::min(v, MAX_ACK_DELAY_EXPONENT);
1082 }
1083
1084 /// Sets the `max_ack_delay` transport parameter.
1085 ///
1086 /// The default value is `25`.
1087 pub fn set_max_ack_delay(&mut self, v: u64) {
1088 self.local_transport_params.max_ack_delay = cmp::min(v, octets::MAX_VAR_INT);
1089 }
1090
1091 /// Sets the `active_connection_id_limit` transport parameter.
1092 ///
1093 /// The default value is `2`. Lower values will be ignored.
1094 pub fn set_active_connection_id_limit(&mut self, v: u64) {
1095 if v >= 2 {
1096 self.local_transport_params.active_conn_id_limit = cmp::min(v, octets::MAX_VAR_INT);
1097 }
1098 }
1099
1100 /// Sets the `disable_active_migration` transport parameter.
1101 ///
1102 /// The default value is `false`.
1103 pub fn set_disable_active_migration(&mut self, v: bool) {
1104 self.local_transport_params.disable_active_migration = v;
1105 }
1106
1107 /// Sets the congestion control algorithm used.
1108 ///
1109 /// The default value is `CongestionControlAlgorithm::CUBIC`.
1110 pub fn set_cc_algorithm(&mut self, algo: CongestionControlAlgorithm) {
1111 self.cc_algorithm = algo;
1112 }
1113
1114 /// Sets custom BBR settings.
1115 ///
1116 /// This API is experimental and will be removed in the future.
1117 ///
1118 /// Currently this only applies if cc_algorithm is
1119 /// `CongestionControlAlgorithm::Bbr2Gcongestion` is set.
1120 ///
1121 /// The default value is `None`.
1122 #[cfg(feature = "internal")]
1123 #[doc(hidden)]
1124 pub fn set_custom_bbr_params(&mut self, custom_bbr_settings: BbrParams) {
1125 self.custom_bbr_params = Some(custom_bbr_settings);
1126 }
1127
1128 /// Sets the congestion control algorithm used by string.
1129 ///
1130 /// The default value is `cubic`. On error `Error::CongestionControl`
1131 /// will be returned.
1132 ///
1133 /// ## Examples:
1134 ///
1135 /// ```
1136 /// # let mut config = quiche::Config::new(0xbabababa)?;
1137 /// config.set_cc_algorithm_name("reno");
1138 /// # Ok::<(), quiche::Error>(())
1139 /// ```
1140 pub fn set_cc_algorithm_name(&mut self, name: &str) -> Result<()> {
1141 self.cc_algorithm = CongestionControlAlgorithm::from_str(name)?;
1142
1143 Ok(())
1144 }
1145
1146 /// Sets initial congestion window size in terms of packet count.
1147 ///
1148 /// The default value is 10.
1149 pub fn set_initial_congestion_window_packets(&mut self, packets: usize) {
1150 self.initial_congestion_window_packets = packets;
1151 }
1152
1153 /// Configure whether to enable relaxed loss detection on spurious loss.
1154 ///
1155 /// The default value is false.
1156 pub fn set_enable_relaxed_loss_threshold(&mut self, enable: bool) {
1157 self.enable_relaxed_loss_threshold = enable;
1158 }
1159
1160 /// Configure whether to enable the CUBIC idle restart fix.
1161 ///
1162 /// When enabled, the epoch shift on idle restart uses the later of
1163 /// the last ACK time and last send time, avoiding an inflated delta
1164 /// when bytes-in-flight transiently hits zero.
1165 ///
1166 /// The default value is `true`.
1167 pub fn set_enable_cubic_idle_restart_fix(&mut self, enable: bool) {
1168 self.enable_cubic_idle_restart_fix = enable;
1169 }
1170
1171 /// Configure whether to enable sending STREAMS_BLOCKED frames.
1172 ///
1173 /// STREAMS_BLOCKED frames are an optional advisory signal in the QUIC
1174 /// protocol which SHOULD be sent when the sender wishes to open a stream
1175 /// but is unable to do so due to the maximum stream limit set by its peer.
1176 ///
1177 /// The default value is false.
1178 pub fn set_enable_send_streams_blocked(&mut self, enable: bool) {
1179 self.enable_send_streams_blocked = enable;
1180 }
1181
1182 /// Configures whether to enable HyStart++.
1183 ///
1184 /// The default value is `true`.
1185 pub fn enable_hystart(&mut self, v: bool) {
1186 self.hystart = v;
1187 }
1188
1189 /// Configures whether to enable pacing.
1190 ///
1191 /// The default value is `true`.
1192 pub fn enable_pacing(&mut self, v: bool) {
1193 self.pacing = v;
1194 }
1195
1196 /// Sets the max value for pacing rate.
1197 ///
1198 /// By default pacing rate is not limited.
1199 pub fn set_max_pacing_rate(&mut self, v: u64) {
1200 self.max_pacing_rate = Some(v);
1201 }
1202
1203 /// Configures whether to enable receiving DATAGRAM frames.
1204 ///
1205 /// When enabled, the `max_datagram_frame_size` transport parameter is set
1206 /// to 65536 as recommended by draft-ietf-quic-datagram-01.
1207 ///
1208 /// The default is `false`.
1209 pub fn enable_dgram(&mut self, enabled: bool, recv_queue_len: usize, send_queue_len: usize) {
1210 self.local_transport_params.max_datagram_frame_size = if enabled {
1211 Some(MAX_DGRAM_FRAME_SIZE)
1212 } else {
1213 None
1214 };
1215 self.dgram_recv_max_queue_len = recv_queue_len;
1216 self.dgram_send_max_queue_len = send_queue_len;
1217 }
1218
1219 /// Configures the max number of queued received PATH_CHALLENGE frames.
1220 ///
1221 /// When an endpoint receives a PATH_CHALLENGE frame and the queue is full,
1222 /// the frame is discarded.
1223 ///
1224 /// The default is 3.
1225 pub fn set_path_challenge_recv_max_queue_len(&mut self, queue_len: usize) {
1226 self.path_challenge_recv_max_queue_len = queue_len;
1227 }
1228
1229 /// Sets the maximum size of the connection window.
1230 ///
1231 /// The default value is MAX_CONNECTION_WINDOW (24MBytes).
1232 pub fn set_max_connection_window(&mut self, v: u64) {
1233 self.max_connection_window = v;
1234 }
1235
1236 /// Sets the maximum size of the stream window.
1237 ///
1238 /// The default value is MAX_STREAM_WINDOW (16MBytes).
1239 pub fn set_max_stream_window(&mut self, v: u64) {
1240 self.max_stream_window = v;
1241 }
1242
1243 /// Sets the initial stateless reset token.
1244 ///
1245 /// This value is only advertised by servers. Setting a stateless retry
1246 /// token as a client has no effect on the connection.
1247 ///
1248 /// The default value is `None`.
1249 pub fn set_stateless_reset_token(&mut self, v: Option<u128>) {
1250 self.local_transport_params.stateless_reset_token = v;
1251 }
1252
1253 /// Sets whether the QUIC connection should avoid reusing DCIDs over
1254 /// different paths.
1255 ///
1256 /// When set to `true`, it ensures that a destination Connection ID is never
1257 /// reused on different paths. Such behaviour may lead to connection stall
1258 /// if the peer performs a non-voluntary migration (e.g., NAT rebinding) and
1259 /// does not provide additional destination Connection IDs to handle such
1260 /// event.
1261 ///
1262 /// The default value is `false`.
1263 pub fn set_disable_dcid_reuse(&mut self, v: bool) {
1264 self.disable_dcid_reuse = v;
1265 }
1266
1267 /// Enables tracking unknown transport parameters.
1268 ///
1269 /// Specify the maximum number of bytes used to track unknown transport
1270 /// parameters. The size includes the identifier and its value. If storing a
1271 /// transport parameter would cause the limit to be exceeded, it is quietly
1272 /// dropped.
1273 ///
1274 /// The default is that the feature is disabled.
1275 pub fn enable_track_unknown_transport_parameters(&mut self, size: usize) {
1276 self.track_unknown_transport_params = Some(size);
1277 }
1278
1279 /// Sets whether the initial max data value should be used as the initial
1280 /// flow control window.
1281 ///
1282 /// This is now always enabled and this method is a no-op. It will be
1283 /// removed in a future release.
1284 #[deprecated(note = "This is now always enabled. This method is a no-op.")]
1285 pub fn set_use_initial_max_data_as_flow_control_win(&mut self, _v: bool) {}
1286}
1287
1288/// Tracks the health of the tx_buffered value.
1289#[derive(Clone, Copy, Debug, Default, PartialEq)]
1290pub enum TxBufferTrackingState {
1291 /// The send buffer is in a good state
1292 #[default]
1293 Ok,
1294 /// The send buffer is in an inconsistent state, which could lead to
1295 /// connection stalls or excess buffering due to bugs we haven't
1296 /// tracked down yet.
1297 Inconsistent,
1298}
1299
1300/// Tracks if the connection hit the peer stream limit and which
1301/// STREAMS_BLOCKED frames have been sent.
1302#[derive(Default)]
1303struct StreamsBlockedState {
1304 /// The peer's max_streams limit at which we last became blocked on
1305 /// opening new local streams, if any.
1306 blocked_at: Option<u64>,
1307
1308 /// The stream limit sent on the most recently sent STREAMS_BLOCKED
1309 /// frame. If != to blocked_at, the connection has pending STREAMS_BLOCKED
1310 /// frames to send.
1311 blocked_sent: Option<u64>,
1312}
1313
1314impl StreamsBlockedState {
1315 /// Returns true if there is a STREAMS_BLOCKED frame that needs sending.
1316 fn has_pending_stream_blocked_frame(&self) -> bool {
1317 self.blocked_sent < self.blocked_at
1318 }
1319
1320 /// Update the stream blocked limit.
1321 fn update_at(&mut self, limit: u64) {
1322 self.blocked_at = self.blocked_at.max(Some(limit));
1323 }
1324
1325 /// Clear blocked_sent to force retransmission of the most recently sent
1326 /// STREAMS_BLOCKED frame.
1327 fn force_retransmit_sent_limit_eq(&mut self, limit: u64) {
1328 // Only clear blocked_sent if the lost frame had the most recently sent
1329 // limit.
1330 if self.blocked_sent == Some(limit) {
1331 self.blocked_sent = None;
1332 }
1333 }
1334}
1335
1336/// A QUIC connection.
1337pub struct Connection<F = DefaultBufFactory>
1338where
1339 F: BufFactory,
1340{
1341 /// QUIC wire version used for the connection.
1342 version: u32,
1343
1344 /// Connection Identifiers.
1345 ids: cid::ConnectionIdentifiers,
1346
1347 /// Unique opaque ID for the connection that can be used for logging.
1348 trace_id: String,
1349
1350 /// Packet number spaces.
1351 pkt_num_spaces: [packet::PktNumSpace; packet::Epoch::count()],
1352
1353 /// The crypto context.
1354 crypto_ctx: [packet::CryptoContext; packet::Epoch::count()],
1355
1356 /// Next packet number.
1357 next_pkt_num: u64,
1358
1359 // TODO
1360 // combine with `next_pkt_num`
1361 /// Track the packet skip context
1362 pkt_num_manager: packet::PktNumManager,
1363
1364 /// Peer's transport parameters.
1365 peer_transport_params: TransportParams,
1366
1367 /// If tracking unknown transport parameters from a peer, how much space to
1368 /// use in bytes.
1369 peer_transport_params_track_unknown: Option<usize>,
1370
1371 /// Local transport parameters.
1372 local_transport_params: TransportParams,
1373
1374 /// TLS handshake state.
1375 handshake: tls::Handshake,
1376
1377 /// Serialized TLS session buffer.
1378 ///
1379 /// This field is populated when a new session ticket is processed on the
1380 /// client. On the server this is empty.
1381 session: Option<Vec<u8>>,
1382
1383 /// The configuration for recovery.
1384 recovery_config: recovery::RecoveryConfig,
1385
1386 /// The path manager.
1387 paths: path::PathMap,
1388
1389 /// PATH_CHALLENGE receive queue max length.
1390 path_challenge_recv_max_queue_len: usize,
1391
1392 /// Total number of received PATH_CHALLENGE frames.
1393 path_challenge_rx_count: u64,
1394
1395 /// List of supported application protocols.
1396 application_protos: Vec<Vec<u8>>,
1397
1398 /// Total number of received packets.
1399 recv_count: usize,
1400
1401 /// Total number of sent packets.
1402 sent_count: usize,
1403
1404 /// Total number of lost packets.
1405 lost_count: usize,
1406
1407 /// Total number of lost packets that were later acked.
1408 spurious_lost_count: usize,
1409
1410 /// Total number of packets sent with data retransmitted.
1411 retrans_count: usize,
1412
1413 /// Total number of sent DATAGRAM frames.
1414 dgram_sent_count: usize,
1415
1416 /// Total number of received DATAGRAM frames.
1417 dgram_recv_count: usize,
1418
1419 /// Total number of bytes received from the peer.
1420 rx_data: u64,
1421
1422 /// Receiver flow controller.
1423 flow_control: flowcontrol::FlowControl,
1424
1425 /// Whether we send MAX_DATA frame.
1426 should_send_max_data: bool,
1427
1428 /// True if there is a pending MAX_STREAMS_BIDI frame to send.
1429 should_send_max_streams_bidi: bool,
1430
1431 /// True if there is a pending MAX_STREAMS_UNI frame to send.
1432 should_send_max_streams_uni: bool,
1433
1434 /// Number of stream data bytes that can be buffered.
1435 tx_cap: usize,
1436
1437 /// The send capacity factor.
1438 tx_cap_factor: f64,
1439
1440 /// Total number of bytes sent to the peer.
1441 tx_data: u64,
1442
1443 /// Peer's flow control limit for the connection.
1444 max_tx_data: u64,
1445
1446 /// Last tx_data before running a full send() loop.
1447 last_tx_data: u64,
1448
1449 /// Total number of bytes retransmitted over the connection.
1450 /// This counts only STREAM and CRYPTO data.
1451 stream_retrans_bytes: u64,
1452
1453 /// Total number of bytes sent over the connection.
1454 sent_bytes: u64,
1455
1456 /// Total number of bytes received over the connection.
1457 recv_bytes: u64,
1458
1459 /// Total number of bytes sent acked over the connection.
1460 acked_bytes: u64,
1461
1462 /// Total number of bytes sent lost over the connection.
1463 lost_bytes: u64,
1464
1465 /// Streams map, indexed by stream ID.
1466 pub(crate) streams: stream::StreamMap<F>,
1467
1468 /// Peer's original destination connection ID. Used by the client to
1469 /// validate the server's transport parameter.
1470 odcid: Option<ConnectionId<'static>>,
1471
1472 /// Peer's retry source connection ID. Used by the client during stateless
1473 /// retry to validate the server's transport parameter.
1474 rscid: Option<ConnectionId<'static>>,
1475
1476 /// Received address verification token.
1477 token: Option<Vec<u8>>,
1478
1479 /// Error code and reason to be sent to the peer in a CONNECTION_CLOSE
1480 /// frame.
1481 local_error: Option<ConnectionError>,
1482
1483 /// Error code and reason received from the peer in a CONNECTION_CLOSE
1484 /// frame.
1485 peer_error: Option<ConnectionError>,
1486
1487 /// The connection-level limit at which send blocking occurred.
1488 blocked_limit: Option<u64>,
1489
1490 /// Idle timeout expiration time.
1491 idle_timer: Option<Instant>,
1492
1493 /// Draining timeout expiration time.
1494 draining_timer: Option<Instant>,
1495
1496 /// List of raw packets that were received before they could be decrypted.
1497 undecryptable_pkts: VecDeque<(Vec<u8>, RecvInfo)>,
1498
1499 /// The negotiated ALPN protocol.
1500 alpn: Vec<u8>,
1501
1502 /// Whether this is a server-side connection.
1503 is_server: bool,
1504
1505 /// Whether the initial secrets have been derived.
1506 derived_initial_secrets: bool,
1507
1508 /// Whether a version negotiation packet has already been received. Only
1509 /// relevant for client connections.
1510 did_version_negotiation: bool,
1511
1512 /// Whether stateless retry has been performed.
1513 did_retry: bool,
1514
1515 /// Whether the peer already updated its connection ID.
1516 got_peer_conn_id: bool,
1517
1518 /// Whether the peer verified our initial address.
1519 peer_verified_initial_address: bool,
1520
1521 /// Whether the peer's transport parameters were parsed.
1522 parsed_peer_transport_params: bool,
1523
1524 /// Whether the connection handshake has been completed.
1525 handshake_completed: bool,
1526
1527 /// Whether the HANDSHAKE_DONE frame has been sent.
1528 handshake_done_sent: bool,
1529
1530 /// Whether the HANDSHAKE_DONE frame has been acked.
1531 handshake_done_acked: bool,
1532
1533 /// Whether the connection handshake has been confirmed.
1534 handshake_confirmed: bool,
1535
1536 /// Key phase bit used for outgoing protected packets.
1537 key_phase: bool,
1538
1539 /// Whether an ack-eliciting packet has been sent since last receiving a
1540 /// packet.
1541 ack_eliciting_sent: bool,
1542
1543 /// Whether the connection is closed.
1544 closed: bool,
1545
1546 /// Whether the connection was timed out.
1547 timed_out: bool,
1548
1549 /// Whether to send GREASE.
1550 grease: bool,
1551
1552 transport_params_plan: Option<Vec<TransportParamEntry>>,
1553
1554 compatible_versions: Vec<u32>,
1555
1556 did_compatible_version_negotiation: bool,
1557
1558 initial_datagram_size: Option<usize>,
1559
1560 initial_size_fallback: bool,
1561
1562 initial_crypto_split: InitialCryptoSplit,
1563
1564 initial_crypto_split_sent: bool,
1565
1566 frame_extensions: frame::Extensions,
1567
1568 /// Whether to send STREAMS_BLOCKED frames when bidi or uni stream quota
1569 /// exhausted.
1570 enable_send_streams_blocked: bool,
1571
1572 /// TLS keylog writer.
1573 keylog: Option<Box<dyn std::io::Write + Send + Sync>>,
1574
1575 #[cfg(feature = "qlog")]
1576 qlog: QlogInfo,
1577
1578 /// DATAGRAM queues.
1579 dgram_recv_queue: dgram::DatagramQueue<F>,
1580 dgram_send_queue: dgram::DatagramQueue<F>,
1581
1582 /// Whether to emit DATAGRAM frames in the next packet.
1583 emit_dgram: bool,
1584
1585 /// Whether the connection should prevent from reusing destination
1586 /// Connection IDs when the peer migrates.
1587 disable_dcid_reuse: bool,
1588
1589 /// The number of streams reset by local.
1590 reset_stream_local_count: u64,
1591
1592 /// The number of streams stopped by local.
1593 stopped_stream_local_count: u64,
1594
1595 /// The number of streams reset by remote.
1596 reset_stream_remote_count: u64,
1597
1598 /// The number of streams stopped by remote.
1599 stopped_stream_remote_count: u64,
1600
1601 /// The number of DATA_BLOCKED frames sent due to hitting the connection
1602 /// flow control limit.
1603 data_blocked_sent_count: u64,
1604
1605 /// The number of STREAM_DATA_BLOCKED frames sent due to a stream hitting
1606 /// the stream flow control limit.
1607 stream_data_blocked_sent_count: u64,
1608
1609 /// The number of DATA_BLOCKED frames received from the remote endpoint.
1610 data_blocked_recv_count: u64,
1611
1612 /// The number of STREAM_DATA_BLOCKED frames received from the remote
1613 /// endpoint.
1614 stream_data_blocked_recv_count: u64,
1615
1616 /// The number of STREAMS_BLOCKED frames received from the remote endpoint
1617 /// indicating the peer is blocked on opening new bidirectional streams.
1618 streams_blocked_bidi_recv_count: u64,
1619
1620 /// The number of STREAMS_BLOCKED frames received from the remote endpoint
1621 /// indicating the peer is blocked on opening new unidirectional streams.
1622 streams_blocked_uni_recv_count: u64,
1623
1624 /// The number of times send() was blocked because the anti-amplification
1625 /// budget (bytes received × max_amplification_factor) was exhausted.
1626 amplification_limited_count: u64,
1627
1628 /// Tracks if the connection hit the peer's bidi or uni stream limit, and if
1629 /// STREAMS_BLOCKED frames are pending transmission.
1630 streams_blocked_bidi_state: StreamsBlockedState,
1631 streams_blocked_uni_state: StreamsBlockedState,
1632
1633 /// The anti-amplification limit factor.
1634 max_amplification_factor: usize,
1635}
1636
1637/// Creates a new server-side connection.
1638///
1639/// The `scid` parameter represents the server's source connection ID, while
1640/// the optional `odcid` parameter represents the original destination ID the
1641/// client sent before a Retry packet (this is only required when using the
1642/// [`retry()`] function). See also the [`accept_with_retry()`] function for
1643/// more advanced retry cases.
1644///
1645/// [`retry()`]: fn.retry.html
1646///
1647/// ## Examples:
1648///
1649/// ```no_run
1650/// # let mut config = quiche::Config::new(0xbabababa)?;
1651/// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
1652/// # let local = "127.0.0.1:0".parse().unwrap();
1653/// # let peer = "127.0.0.1:1234".parse().unwrap();
1654/// let conn = quiche::accept(&scid, None, local, peer, &mut config)?;
1655/// # Ok::<(), quiche::Error>(())
1656/// ```
1657#[inline(always)]
1658pub fn accept(
1659 scid: &ConnectionId,
1660 odcid: Option<&ConnectionId>,
1661 local: SocketAddr,
1662 peer: SocketAddr,
1663 config: &mut Config,
1664) -> Result<Connection> {
1665 accept_with_buf_factory(scid, odcid, local, peer, config)
1666}
1667
1668/// Creates a server-side connection with custom buffer generation.
1669///
1670/// The buffers generated can be anything that can be dereferenced as a byte
1671/// slice. See [`accept`] and [`BufFactory`] for more information.
1672#[inline]
1673pub fn accept_with_buf_factory<F: BufFactory>(
1674 scid: &ConnectionId,
1675 odcid: Option<&ConnectionId>,
1676 local: SocketAddr,
1677 peer: SocketAddr,
1678 config: &mut Config,
1679) -> Result<Connection<F>> {
1680 // Connections with `odcid` historically used `scid` as the retry source
1681 // CID. Preserve this behavior for backwards compatibility.
1682 // `accept_with_retry` allows the SCIDs to be specified separately.
1683 let retry_cids = odcid.map(|odcid| RetryConnectionIds {
1684 original_destination_cid: odcid,
1685 retry_source_cid: scid,
1686 });
1687 Connection::new(scid, retry_cids, None, local, peer, config, true)
1688}
1689
1690/// A wrapper for connection IDs used in [`accept_with_retry`].
1691pub struct RetryConnectionIds<'a> {
1692 /// The DCID of the first Initial packet received by the server, which
1693 /// triggered the Retry packet.
1694 pub original_destination_cid: &'a ConnectionId<'a>,
1695 /// The SCID of the Retry packet sent by the server. This can be different
1696 /// from the new connection's SCID.
1697 pub retry_source_cid: &'a ConnectionId<'a>,
1698}
1699
1700/// Creates a new server-side connection after the client responded to a Retry
1701/// packet.
1702///
1703/// To generate a Retry packet in the first place, use the [`retry()`] function.
1704///
1705/// The `scid` parameter represents the server's source connection ID, which can
1706/// be freshly generated after the application has successfully verified the
1707/// Retry. `retry_cids` is used to tie the new connection to the Initial + Retry
1708/// exchange that preceded the connection's creation.
1709///
1710/// The DCID of the client's Initial packet is inherently untrusted data. It is
1711/// safe to use the DCID in the `retry_source_cid` field of the
1712/// `RetryConnectionIds` provided to this function. However, using the Initial's
1713/// DCID for the `scid` parameter carries risks. Applications are advised to
1714/// implement their own DCID validation steps before using the DCID in that
1715/// manner.
1716#[inline]
1717pub fn accept_with_retry<F: BufFactory>(
1718 scid: &ConnectionId,
1719 retry_cids: RetryConnectionIds,
1720 local: SocketAddr,
1721 peer: SocketAddr,
1722 config: &mut Config,
1723) -> Result<Connection<F>> {
1724 Connection::new(scid, Some(retry_cids), None, local, peer, config, true)
1725}
1726
1727/// Creates a new client-side connection.
1728///
1729/// The `scid` parameter is used as the connection's source connection ID,
1730/// while the optional `server_name` parameter is used to verify the peer's
1731/// certificate.
1732///
1733/// ## Examples:
1734///
1735/// ```no_run
1736/// # let mut config = quiche::Config::new(0xbabababa)?;
1737/// # let server_name = "quic.tech";
1738/// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
1739/// # let local = "127.0.0.1:4321".parse().unwrap();
1740/// # let peer = "127.0.0.1:1234".parse().unwrap();
1741/// let conn =
1742/// quiche::connect(Some(&server_name), &scid, local, peer, &mut config)?;
1743/// # Ok::<(), quiche::Error>(())
1744/// ```
1745#[inline]
1746pub fn connect(
1747 server_name: Option<&str>,
1748 scid: &ConnectionId,
1749 local: SocketAddr,
1750 peer: SocketAddr,
1751 config: &mut Config,
1752) -> Result<Connection> {
1753 let mut conn = Connection::new(scid, None, None, local, peer, config, false)?;
1754
1755 if let Some(server_name) = server_name {
1756 conn.handshake.set_host_name(server_name)?;
1757 }
1758
1759 Ok(conn)
1760}
1761
1762/// Creates a new client-side connection using the given DCID initially.
1763///
1764/// Be aware that [RFC 9000] places requirements for unpredictability and length
1765/// on the client DCID field. This function is dangerous if these requirements
1766/// are not satisfied.
1767///
1768/// The `scid` parameter is used as the connection's source connection ID, while
1769/// the optional `server_name` parameter is used to verify the peer's
1770/// certificate.
1771///
1772/// [RFC 9000]: <https://datatracker.ietf.org/doc/html/rfc9000#section-7.2-3>
1773pub fn connect_with_dcid(
1774 server_name: Option<&str>,
1775 scid: &ConnectionId,
1776 dcid: &ConnectionId,
1777 local: SocketAddr,
1778 peer: SocketAddr,
1779 config: &mut Config,
1780) -> Result<Connection> {
1781 let mut conn = Connection::new(scid, None, Some(dcid), local, peer, config, false)?;
1782
1783 if let Some(server_name) = server_name {
1784 conn.handshake.set_host_name(server_name)?;
1785 }
1786
1787 Ok(conn)
1788}
1789
1790/// Creates a new client-side connection, with a custom buffer generation
1791/// method.
1792///
1793/// The buffers generated can be anything that can be drereferenced as a byte
1794/// slice. See [`connect`] and [`BufFactory`] for more info.
1795#[inline]
1796pub fn connect_with_buffer_factory<F: BufFactory>(
1797 server_name: Option<&str>,
1798 scid: &ConnectionId,
1799 local: SocketAddr,
1800 peer: SocketAddr,
1801 config: &mut Config,
1802) -> Result<Connection<F>> {
1803 let mut conn = Connection::new(scid, None, None, local, peer, config, false)?;
1804
1805 if let Some(server_name) = server_name {
1806 conn.handshake.set_host_name(server_name)?;
1807 }
1808
1809 Ok(conn)
1810}
1811
1812/// Creates a new client-side connection, with a custom buffer generation
1813/// method using the given dcid initially.
1814/// Be aware the RFC places requirements for unpredictability and length
1815/// on the client DCID field.
1816/// [`RFC9000`]: https://datatracker.ietf.org/doc/html/rfc9000#section-7.2-3
1817///
1818/// The buffers generated can be anything that can be drereferenced as a byte
1819/// slice. See [`connect`] and [`BufFactory`] for more info.
1820#[cfg(feature = "custom-client-dcid")]
1821#[cfg_attr(docsrs, doc(cfg(feature = "custom-client-dcid")))]
1822pub fn connect_with_dcid_and_buffer_factory<F: BufFactory>(
1823 server_name: Option<&str>,
1824 scid: &ConnectionId,
1825 dcid: &ConnectionId,
1826 local: SocketAddr,
1827 peer: SocketAddr,
1828 config: &mut Config,
1829) -> Result<Connection<F>> {
1830 let mut conn = Connection::new(scid, None, Some(dcid), local, peer, config, false)?;
1831
1832 if let Some(server_name) = server_name {
1833 conn.handshake.set_host_name(server_name)?;
1834 }
1835
1836 Ok(conn)
1837}
1838
1839/// Writes a version negotiation packet.
1840///
1841/// The `scid` and `dcid` parameters are the source connection ID and the
1842/// destination connection ID extracted from the received client's Initial
1843/// packet that advertises an unsupported version.
1844///
1845/// ## Examples:
1846///
1847/// ```no_run
1848/// # let mut buf = [0; 512];
1849/// # let mut out = [0; 512];
1850/// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
1851/// let (len, src) = socket.recv_from(&mut buf).unwrap();
1852///
1853/// let hdr =
1854/// quiche::Header::from_slice(&mut buf[..len], quiche::MAX_CONN_ID_LEN)?;
1855///
1856/// if hdr.version != quiche::PROTOCOL_VERSION {
1857/// let len = quiche::negotiate_version(&hdr.scid, &hdr.dcid, &mut out)?;
1858/// socket.send_to(&out[..len], &src).unwrap();
1859/// }
1860/// # Ok::<(), quiche::Error>(())
1861/// ```
1862#[inline]
1863pub fn negotiate_version(
1864 scid: &ConnectionId,
1865 dcid: &ConnectionId,
1866 out: &mut [u8],
1867) -> Result<usize> {
1868 packet::negotiate_version(scid, dcid, out)
1869}
1870
1871/// Writes a stateless retry packet.
1872///
1873/// The `scid` and `dcid` parameters are the source connection ID and the
1874/// destination connection ID extracted from the received client's Initial
1875/// packet, while `new_scid` is the server's new source connection ID and
1876/// `token` is the address validation token the client needs to echo back.
1877///
1878/// The application is responsible for generating the address validation
1879/// token to be sent to the client, and verifying tokens sent back by the
1880/// client. The generated token should include the `dcid` parameter, such
1881/// that it can be later extracted from the token and passed to the
1882/// [`accept()`] function as its `odcid` parameter.
1883///
1884/// [`accept()`]: fn.accept.html
1885///
1886/// ## Examples:
1887///
1888/// ```no_run
1889/// # let mut config = quiche::Config::new(0xbabababa)?;
1890/// # let mut buf = [0; 512];
1891/// # let mut out = [0; 512];
1892/// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
1893/// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
1894/// # let local = socket.local_addr().unwrap();
1895/// # fn mint_token(hdr: &quiche::Header, src: &std::net::SocketAddr) -> Vec<u8> {
1896/// # vec![]
1897/// # }
1898/// # fn validate_token<'a>(src: &std::net::SocketAddr, token: &'a [u8]) -> Option<quiche::ConnectionId<'a>> {
1899/// # None
1900/// # }
1901/// let (len, peer) = socket.recv_from(&mut buf).unwrap();
1902///
1903/// let hdr = quiche::Header::from_slice(&mut buf[..len], quiche::MAX_CONN_ID_LEN)?;
1904///
1905/// let token = hdr.token.as_ref().unwrap();
1906///
1907/// // No token sent by client, create a new one.
1908/// if token.is_empty() {
1909/// let new_token = mint_token(&hdr, &peer);
1910///
1911/// let len = quiche::retry(
1912/// &hdr.scid, &hdr.dcid, &scid, &new_token, hdr.version, &mut out,
1913/// )?;
1914///
1915/// socket.send_to(&out[..len], &peer).unwrap();
1916/// return Ok(());
1917/// }
1918///
1919/// // Client sent token, validate it.
1920/// let odcid = validate_token(&peer, token);
1921///
1922/// if odcid.is_none() {
1923/// // Invalid address validation token.
1924/// return Ok(());
1925/// }
1926///
1927/// let conn = quiche::accept(&scid, odcid.as_ref(), local, peer, &mut config)?;
1928/// # Ok::<(), quiche::Error>(())
1929/// ```
1930#[inline]
1931pub fn retry(
1932 scid: &ConnectionId,
1933 dcid: &ConnectionId,
1934 new_scid: &ConnectionId,
1935 token: &[u8],
1936 version: u32,
1937 out: &mut [u8],
1938) -> Result<usize> {
1939 packet::retry(scid, dcid, new_scid, token, version, out)
1940}
1941
1942/// Returns true if the given protocol version is supported.
1943#[inline]
1944pub fn version_is_supported(version: u32) -> bool {
1945 matches!(version, PROTOCOL_VERSION_V1 | PROTOCOL_VERSION_V2)
1946}
1947
1948/// Pushes a frame to the output packet if there is enough space.
1949///
1950/// Returns `true` on success, `false` otherwise. In case of failure it means
1951/// there is no room to add the frame in the packet. You may retry to add the
1952/// frame later.
1953macro_rules! push_frame_to_pkt {
1954 ($out:expr, $frames:expr, $frame:expr, $left:expr) => {{
1955 if $frame.wire_len() <= $left {
1956 $left -= $frame.wire_len();
1957
1958 $frame.to_bytes(&mut $out)?;
1959
1960 $frames.push($frame);
1961
1962 true
1963 } else {
1964 false
1965 }
1966 }};
1967}
1968
1969/// Executes the provided body if the qlog feature is enabled, quiche has been
1970/// configured with a log writer, the event's importance is within the
1971/// configured level.
1972macro_rules! qlog_with_type {
1973 ($ty:expr, $qlog:expr, $qlog_streamer_ref:ident, $body:block) => {{
1974 #[cfg(feature = "qlog")]
1975 {
1976 if EventImportance::from($ty).is_contained_in(&$qlog.level) {
1977 if let Some($qlog_streamer_ref) = &mut $qlog.streamer {
1978 $body
1979 }
1980 }
1981 }
1982 }};
1983}
1984
1985#[cfg(feature = "qlog")]
1986const QLOG_PARAMS_SET: EventType = EventType::QuicEventType(QuicEventType::ParametersSet);
1987
1988#[cfg(feature = "qlog")]
1989const QLOG_PACKET_RX: EventType = EventType::QuicEventType(QuicEventType::PacketReceived);
1990
1991#[cfg(feature = "qlog")]
1992const QLOG_PACKET_TX: EventType = EventType::QuicEventType(QuicEventType::PacketSent);
1993
1994#[cfg(feature = "qlog")]
1995const QLOG_DATA_MV: EventType = EventType::QuicEventType(QuicEventType::StreamDataMoved);
1996
1997#[cfg(feature = "qlog")]
1998const QLOG_METRICS: EventType = EventType::QuicEventType(QuicEventType::RecoveryMetricsUpdated);
1999
2000#[cfg(feature = "qlog")]
2001const QLOG_CONNECTION_CLOSED: EventType = EventType::QuicEventType(QuicEventType::ConnectionClosed);
2002
2003#[cfg(feature = "qlog")]
2004struct QlogInfo {
2005 streamer: Option<qlog::streamer::QlogStreamer>,
2006 logged_peer_params: bool,
2007 level: EventImportance,
2008}
2009
2010#[cfg(feature = "qlog")]
2011impl Default for QlogInfo {
2012 fn default() -> Self {
2013 QlogInfo {
2014 streamer: None,
2015 logged_peer_params: false,
2016 level: EventImportance::Base,
2017 }
2018 }
2019}
2020
2021impl<F: BufFactory> Connection<F> {
2022 fn new(
2023 scid: &ConnectionId,
2024 retry_cids: Option<RetryConnectionIds>,
2025 client_dcid: Option<&ConnectionId>,
2026 local: SocketAddr,
2027 peer: SocketAddr,
2028 config: &mut Config,
2029 is_server: bool,
2030 ) -> Result<Connection<F>> {
2031 let tls = config.tls_ctx.new_handshake()?;
2032 Connection::with_tls(
2033 scid,
2034 retry_cids,
2035 client_dcid,
2036 local,
2037 peer,
2038 config,
2039 tls,
2040 is_server,
2041 )
2042 }
2043
2044 #[allow(clippy::too_many_arguments)]
2045 fn with_tls(
2046 scid: &ConnectionId,
2047 retry_cids: Option<RetryConnectionIds>,
2048 client_dcid: Option<&ConnectionId>,
2049 local: SocketAddr,
2050 peer: SocketAddr,
2051 config: &Config,
2052 tls: tls::Handshake,
2053 is_server: bool,
2054 ) -> Result<Connection<F>> {
2055 if retry_cids.is_some() && client_dcid.is_some() {
2056 // These are exclusive, the caller should only specify one or the
2057 // other.
2058 return Err(Error::InvalidDcidInitialization);
2059 }
2060 if let Some(client_dcid) = client_dcid {
2061 // The Minimum length is 8.
2062 // See https://datatracker.ietf.org/doc/html/rfc9000#section-7.2-3
2063 if client_dcid.to_vec().len() < 8 {
2064 return Err(Error::InvalidDcidInitialization);
2065 }
2066 }
2067
2068 let max_rx_data = config.local_transport_params.initial_max_data;
2069
2070 let scid_as_hex: Vec<String> = scid.iter().map(|b| format!("{b:02x}")).collect();
2071
2072 let reset_token = if is_server {
2073 config.local_transport_params.stateless_reset_token
2074 } else {
2075 None
2076 };
2077
2078 let recovery_config = recovery::RecoveryConfig::from_config(config);
2079
2080 let mut path = path::Path::new(
2081 local,
2082 peer,
2083 &recovery_config,
2084 config.path_challenge_recv_max_queue_len,
2085 true,
2086 Some(config),
2087 );
2088
2089 // If we sent a Retry assume the peer's address is verified.
2090 path.verified_peer_address = retry_cids.is_some();
2091 // Assume clients validate the server's address implicitly.
2092 path.peer_verified_local_address = is_server;
2093
2094 // Do not allocate more than the number of active CIDs.
2095 let paths = path::PathMap::new(
2096 path,
2097 config.local_transport_params.active_conn_id_limit as usize,
2098 is_server,
2099 );
2100
2101 let active_path_id = paths.get_active_path_id()?;
2102
2103 let ids = cid::ConnectionIdentifiers::new(
2104 config.local_transport_params.active_conn_id_limit as usize,
2105 scid,
2106 active_path_id,
2107 reset_token,
2108 );
2109
2110 let initial_flow_control_window = max_rx_data;
2111 let mut conn = Connection {
2112 version: config.version,
2113
2114 ids,
2115
2116 trace_id: scid_as_hex.join(""),
2117
2118 pkt_num_spaces: [
2119 packet::PktNumSpace::new(),
2120 packet::PktNumSpace::new(),
2121 packet::PktNumSpace::new(),
2122 ],
2123
2124 crypto_ctx: [
2125 packet::CryptoContext::new(),
2126 packet::CryptoContext::new(),
2127 packet::CryptoContext::new(),
2128 ],
2129
2130 next_pkt_num: 0,
2131
2132 pkt_num_manager: packet::PktNumManager::new(),
2133
2134 peer_transport_params: TransportParams::default(),
2135
2136 peer_transport_params_track_unknown: config.track_unknown_transport_params,
2137
2138 local_transport_params: config.local_transport_params.clone(),
2139
2140 handshake: tls,
2141
2142 session: None,
2143
2144 recovery_config,
2145
2146 paths,
2147 path_challenge_recv_max_queue_len: config.path_challenge_recv_max_queue_len,
2148 path_challenge_rx_count: 0,
2149
2150 application_protos: config.application_protos.clone(),
2151
2152 recv_count: 0,
2153 sent_count: 0,
2154 lost_count: 0,
2155 spurious_lost_count: 0,
2156 retrans_count: 0,
2157 dgram_sent_count: 0,
2158 dgram_recv_count: 0,
2159 sent_bytes: 0,
2160 recv_bytes: 0,
2161 acked_bytes: 0,
2162 lost_bytes: 0,
2163
2164 rx_data: 0,
2165 flow_control: flowcontrol::FlowControl::new(
2166 max_rx_data,
2167 initial_flow_control_window,
2168 config.max_connection_window,
2169 ),
2170 should_send_max_data: false,
2171 should_send_max_streams_bidi: false,
2172 should_send_max_streams_uni: false,
2173
2174 tx_cap: 0,
2175 tx_cap_factor: config.tx_cap_factor,
2176
2177 tx_data: 0,
2178 max_tx_data: 0,
2179 last_tx_data: 0,
2180
2181 stream_retrans_bytes: 0,
2182
2183 streams: stream::StreamMap::new(
2184 config.local_transport_params.initial_max_streams_bidi,
2185 config.local_transport_params.initial_max_streams_uni,
2186 config.max_stream_window,
2187 ),
2188
2189 odcid: None,
2190
2191 rscid: None,
2192
2193 token: None,
2194
2195 local_error: None,
2196
2197 peer_error: None,
2198
2199 blocked_limit: None,
2200
2201 idle_timer: None,
2202
2203 draining_timer: None,
2204
2205 undecryptable_pkts: VecDeque::new(),
2206
2207 alpn: Vec::new(),
2208
2209 is_server,
2210
2211 derived_initial_secrets: false,
2212
2213 did_version_negotiation: false,
2214
2215 did_retry: false,
2216
2217 got_peer_conn_id: false,
2218
2219 // Assume clients validate the server's address implicitly.
2220 peer_verified_initial_address: is_server,
2221
2222 parsed_peer_transport_params: false,
2223
2224 handshake_completed: false,
2225
2226 handshake_done_sent: false,
2227 handshake_done_acked: false,
2228
2229 handshake_confirmed: false,
2230
2231 key_phase: false,
2232
2233 ack_eliciting_sent: false,
2234
2235 closed: false,
2236
2237 timed_out: false,
2238
2239 grease: config.grease,
2240
2241 transport_params_plan: config.transport_params_plan.clone(),
2242
2243 compatible_versions: config.compatible_versions.clone(),
2244
2245 did_compatible_version_negotiation: false,
2246
2247 initial_datagram_size: config.initial_datagram_size,
2248
2249 initial_size_fallback: false,
2250
2251 initial_crypto_split: config.initial_crypto_split,
2252
2253 initial_crypto_split_sent: false,
2254
2255 frame_extensions: frame::Extensions::from_plan(config.transport_params_plan.as_deref()),
2256
2257 enable_send_streams_blocked: config.enable_send_streams_blocked,
2258
2259 keylog: None,
2260
2261 #[cfg(feature = "qlog")]
2262 qlog: Default::default(),
2263
2264 dgram_recv_queue: dgram::DatagramQueue::new(config.dgram_recv_max_queue_len),
2265
2266 dgram_send_queue: dgram::DatagramQueue::new(config.dgram_send_max_queue_len),
2267
2268 emit_dgram: true,
2269
2270 disable_dcid_reuse: config.disable_dcid_reuse,
2271
2272 reset_stream_local_count: 0,
2273 stopped_stream_local_count: 0,
2274 reset_stream_remote_count: 0,
2275 stopped_stream_remote_count: 0,
2276
2277 data_blocked_sent_count: 0,
2278 stream_data_blocked_sent_count: 0,
2279 data_blocked_recv_count: 0,
2280 stream_data_blocked_recv_count: 0,
2281
2282 streams_blocked_bidi_recv_count: 0,
2283 streams_blocked_uni_recv_count: 0,
2284
2285 amplification_limited_count: 0,
2286
2287 streams_blocked_bidi_state: Default::default(),
2288 streams_blocked_uni_state: Default::default(),
2289
2290 max_amplification_factor: config.max_amplification_factor,
2291 };
2292 if let Some(retry_cids) = retry_cids {
2293 conn.local_transport_params
2294 .original_destination_connection_id =
2295 Some(retry_cids.original_destination_cid.to_vec().into());
2296
2297 conn.local_transport_params.retry_source_connection_id =
2298 Some(retry_cids.retry_source_cid.to_vec().into());
2299
2300 conn.did_retry = true;
2301 }
2302
2303 conn.local_transport_params.initial_source_connection_id =
2304 Some(conn.ids.get_scid(0)?.cid.to_vec().into());
2305
2306 conn.handshake.init(is_server)?;
2307
2308 conn.handshake
2309 .use_legacy_codepoint(!version_is_supported(config.version));
2310
2311 conn.encode_transport_params()?;
2312
2313 if !is_server {
2314 let dcid = if let Some(client_dcid) = client_dcid {
2315 // We already had an dcid generated for us, use it.
2316 client_dcid.to_vec()
2317 } else {
2318 // Derive initial secrets for the client. We can do this here
2319 // because we already generated the random
2320 // destination connection ID.
2321 let mut dcid = [0; 16];
2322 rand::rand_bytes(&mut dcid[..]);
2323 dcid.to_vec()
2324 };
2325
2326 let (aead_open, aead_seal) =
2327 crypto::derive_initial_key_material(&dcid, conn.version, conn.is_server, false)?;
2328
2329 let reset_token = conn.peer_transport_params.stateless_reset_token;
2330 conn.set_initial_dcid(dcid.to_vec().into(), reset_token, active_path_id)?;
2331
2332 conn.crypto_ctx[packet::Epoch::Initial].crypto_open = Some(aead_open);
2333 conn.crypto_ctx[packet::Epoch::Initial].crypto_seal = Some(aead_seal);
2334
2335 conn.derived_initial_secrets = true;
2336 }
2337
2338 Ok(conn)
2339 }
2340
2341 /// Sets keylog output to the designated [`Writer`].
2342 ///
2343 /// This needs to be called as soon as the connection is created, to avoid
2344 /// missing some early logs.
2345 ///
2346 /// [`Writer`]: https://doc.rust-lang.org/std/io/trait.Write.html
2347 #[inline]
2348 pub fn set_keylog(&mut self, writer: Box<dyn std::io::Write + Send + Sync>) {
2349 self.keylog = Some(writer);
2350 }
2351
2352 /// Sets qlog output to the designated [`Writer`].
2353 ///
2354 /// Only events included in `QlogLevel::Base` are written. The serialization
2355 /// format is JSON-SEQ.
2356 ///
2357 /// This needs to be called as soon as the connection is created, to avoid
2358 /// missing some early logs.
2359 ///
2360 /// [`Writer`]: https://doc.rust-lang.org/std/io/trait.Write.html
2361 #[cfg(feature = "qlog")]
2362 #[cfg_attr(docsrs, doc(cfg(feature = "qlog")))]
2363 pub fn set_qlog(
2364 &mut self,
2365 writer: Box<dyn std::io::Write + Send + Sync>,
2366 title: String,
2367 description: String,
2368 ) {
2369 self.set_qlog_with_level(writer, title, description, QlogLevel::Base)
2370 }
2371
2372 /// Sets qlog output to the designated [`Writer`].
2373 ///
2374 /// Only qlog events included in the specified `QlogLevel` are written. The
2375 /// serialization format is JSON-SEQ.
2376 ///
2377 /// This needs to be called as soon as the connection is created, to avoid
2378 /// missing some early logs.
2379 ///
2380 /// [`Writer`]: https://doc.rust-lang.org/std/io/trait.Write.html
2381 #[cfg(feature = "qlog")]
2382 #[cfg_attr(docsrs, doc(cfg(feature = "qlog")))]
2383 pub fn set_qlog_with_level(
2384 &mut self,
2385 writer: Box<dyn std::io::Write + Send + Sync>,
2386 title: String,
2387 description: String,
2388 qlog_level: QlogLevel,
2389 ) {
2390 use qlog::CommonFields;
2391 use qlog::ReferenceTime;
2392 use qlog::events::HTTP3_URI;
2393 use qlog::events::QUIC_URI;
2394 use qlog::events::quic::TransportInitiator;
2395
2396 let vp = if self.is_server {
2397 qlog::VantagePointType::Server
2398 } else {
2399 qlog::VantagePointType::Client
2400 };
2401
2402 let level = match qlog_level {
2403 QlogLevel::Core => EventImportance::Core,
2404
2405 QlogLevel::Base => EventImportance::Base,
2406
2407 QlogLevel::Extra => EventImportance::Extra,
2408 };
2409
2410 self.qlog.level = level;
2411
2412 // Best effort to get Instant::now() and SystemTime::now() as closely
2413 // together as possible.
2414 let now = Instant::now();
2415 let now_wall_clock = std::time::SystemTime::now();
2416 let common_fields = CommonFields {
2417 reference_time: ReferenceTime::new_monotonic(Some(now_wall_clock)),
2418 ..Default::default()
2419 };
2420 let trace = qlog::TraceSeq::new(
2421 Some(title.to_string()),
2422 Some(description.to_string()),
2423 Some(common_fields),
2424 Some(qlog::VantagePoint {
2425 name: None,
2426 ty: vp,
2427 flow: None,
2428 }),
2429 vec![QUIC_URI.to_string(), HTTP3_URI.to_string()],
2430 );
2431
2432 let mut streamer = qlog::streamer::QlogStreamer::new(
2433 Some(title),
2434 Some(description),
2435 now,
2436 trace,
2437 self.qlog.level,
2438 qlog::streamer::EventTimePrecision::MicroSeconds,
2439 writer,
2440 );
2441
2442 streamer.start_log().ok();
2443
2444 let ev_data = self
2445 .local_transport_params
2446 .to_qlog(TransportInitiator::Local, self.handshake.cipher());
2447
2448 // This event occurs very early, so just mark the relative time as 0.0.
2449 streamer.add_event(Event::with_time(0.0, ev_data)).ok();
2450
2451 self.qlog.streamer = Some(streamer);
2452 }
2453
2454 /// Returns a mutable reference to the QlogStreamer, if it exists.
2455 #[cfg(feature = "qlog")]
2456 #[cfg_attr(docsrs, doc(cfg(feature = "qlog")))]
2457 pub fn qlog_streamer(&mut self) -> Option<&mut qlog::streamer::QlogStreamer> {
2458 self.qlog.streamer.as_mut()
2459 }
2460
2461 /// Configures the given session for resumption.
2462 ///
2463 /// On the client, this can be used to offer the given serialized session,
2464 /// as returned by [`session()`], for resumption.
2465 ///
2466 /// This must only be called immediately after creating a connection, that
2467 /// is, before any packet is sent or received.
2468 ///
2469 /// [`session()`]: struct.Connection.html#method.session
2470 #[inline]
2471 pub fn set_session(&mut self, session: &[u8]) -> Result<()> {
2472 let mut b = octets::Octets::with_slice(session);
2473
2474 let session_len = b.get_u64()? as usize;
2475 let session_bytes = b.get_bytes(session_len)?;
2476
2477 self.handshake.set_session(session_bytes.as_ref())?;
2478
2479 let raw_params_len = b.get_u64()? as usize;
2480 let raw_params_bytes = b.get_bytes(raw_params_len)?;
2481
2482 let peer_params = TransportParams::decode(
2483 raw_params_bytes.as_ref(),
2484 self.is_server,
2485 self.peer_transport_params_track_unknown,
2486 )?;
2487
2488 self.process_peer_transport_params(peer_params)?;
2489
2490 Ok(())
2491 }
2492
2493 /// Sets the `max_idle_timeout` transport parameter, in milliseconds.
2494 ///
2495 /// This must only be called immediately after creating a connection, that
2496 /// is, before any packet is sent or received.
2497 ///
2498 /// The default value is infinite, that is, no timeout is used unless
2499 /// already configured when creating the connection.
2500 pub fn set_max_idle_timeout(&mut self, v: u64) -> Result<()> {
2501 self.local_transport_params.max_idle_timeout = cmp::min(v, octets::MAX_VAR_INT);
2502
2503 self.encode_transport_params()
2504 }
2505
2506 /// Sets the congestion control algorithm used.
2507 ///
2508 /// This function can only be called inside one of BoringSSL's handshake
2509 /// callbacks, before any packet has been sent. Calling this function any
2510 /// other time will have no effect.
2511 ///
2512 /// See [`Config::set_cc_algorithm()`].
2513 ///
2514 /// [`Config::set_cc_algorithm()`]: struct.Config.html#method.set_cc_algorithm
2515 #[cfg(feature = "boringssl-bssl-crate")]
2516 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2517 pub fn set_cc_algorithm_in_handshake(
2518 ssl: &mut leyline_bssl::ssl::SslRef,
2519 algo: CongestionControlAlgorithm,
2520 ) -> Result<()> {
2521 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2522
2523 ex_data.recovery_config.cc_algorithm = algo;
2524
2525 Ok(())
2526 }
2527
2528 /// Sets custom BBR settings.
2529 ///
2530 /// This API is experimental and will be removed in the future.
2531 ///
2532 /// Currently this only applies if cc_algorithm is
2533 /// `CongestionControlAlgorithm::Bbr2Gcongestion` is set.
2534 ///
2535 /// This function can only be called inside one of BoringSSL's handshake
2536 /// callbacks, before any packet has been sent. Calling this function any
2537 /// other time will have no effect.
2538 ///
2539 /// See [`Config::set_custom_bbr_settings()`].
2540 ///
2541 /// [`Config::set_custom_bbr_settings()`]: struct.Config.html#method.set_custom_bbr_settings
2542 #[cfg(all(feature = "boringssl-bssl-crate", feature = "internal"))]
2543 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2544 #[doc(hidden)]
2545 pub fn set_custom_bbr_settings_in_handshake(
2546 ssl: &mut leyline_bssl::ssl::SslRef,
2547 custom_bbr_params: BbrParams,
2548 ) -> Result<()> {
2549 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2550
2551 ex_data.recovery_config.custom_bbr_params = Some(custom_bbr_params);
2552
2553 Ok(())
2554 }
2555
2556 /// Sets the congestion control algorithm used by string.
2557 ///
2558 /// This function can only be called inside one of BoringSSL's handshake
2559 /// callbacks, before any packet has been sent. Calling this function any
2560 /// other time will have no effect.
2561 ///
2562 /// See [`Config::set_cc_algorithm_name()`].
2563 ///
2564 /// [`Config::set_cc_algorithm_name()`]: struct.Config.html#method.set_cc_algorithm_name
2565 #[cfg(feature = "boringssl-bssl-crate")]
2566 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2567 pub fn set_cc_algorithm_name_in_handshake(
2568 ssl: &mut leyline_bssl::ssl::SslRef,
2569 name: &str,
2570 ) -> Result<()> {
2571 let cc_algo = CongestionControlAlgorithm::from_str(name)?;
2572 Self::set_cc_algorithm_in_handshake(ssl, cc_algo)
2573 }
2574
2575 /// Sets initial congestion window size in terms of packet count.
2576 ///
2577 /// This function can only be called inside one of BoringSSL's handshake
2578 /// callbacks, before any packet has been sent. Calling this function any
2579 /// other time will have no effect.
2580 ///
2581 /// See [`Config::set_initial_congestion_window_packets()`].
2582 ///
2583 /// [`Config::set_initial_congestion_window_packets()`]: struct.Config.html#method.set_initial_congestion_window_packets
2584 #[cfg(feature = "boringssl-bssl-crate")]
2585 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2586 pub fn set_initial_congestion_window_packets_in_handshake(
2587 ssl: &mut leyline_bssl::ssl::SslRef,
2588 packets: usize,
2589 ) -> Result<()> {
2590 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2591
2592 ex_data.recovery_config.initial_congestion_window_packets = packets;
2593
2594 Ok(())
2595 }
2596
2597 /// Configure whether to enable relaxed loss detection on spurious loss.
2598 ///
2599 /// This function can only be called inside one of BoringSSL's handshake
2600 /// callbacks, before any packet has been sent. Calling this function any
2601 /// other time will have no effect.
2602 ///
2603 /// See [`Config::set_enable_relaxed_loss_threshold()`].
2604 ///
2605 /// [`Config::set_enable_relaxed_loss_threshold()`]: struct.Config.html#method.set_enable_relaxed_loss_threshold
2606 #[cfg(feature = "boringssl-bssl-crate")]
2607 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2608 pub fn set_enable_relaxed_loss_threshold_in_handshake(
2609 ssl: &mut leyline_bssl::ssl::SslRef,
2610 enable: bool,
2611 ) -> Result<()> {
2612 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2613
2614 ex_data.recovery_config.enable_relaxed_loss_threshold = enable;
2615
2616 Ok(())
2617 }
2618
2619 /// Configure whether to enable the CUBIC idle restart fix.
2620 ///
2621 /// This function can only be called inside one of BoringSSL's handshake
2622 /// callbacks, before any packet has been sent. Calling this function any
2623 /// other time will have no effect.
2624 ///
2625 /// See [`Config::set_enable_cubic_idle_restart_fix()`].
2626 ///
2627 /// [`Config::set_enable_cubic_idle_restart_fix()`]: struct.Config.html#method.set_enable_cubic_idle_restart_fix
2628 #[cfg(feature = "boringssl-bssl-crate")]
2629 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2630 pub fn set_enable_cubic_idle_restart_fix_in_handshake(
2631 ssl: &mut leyline_bssl::ssl::SslRef,
2632 enable: bool,
2633 ) -> Result<()> {
2634 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2635
2636 ex_data.recovery_config.enable_cubic_idle_restart_fix = enable;
2637
2638 Ok(())
2639 }
2640
2641 /// Configures whether to enable HyStart++.
2642 ///
2643 /// This function can only be called inside one of BoringSSL's handshake
2644 /// callbacks, before any packet has been sent. Calling this function any
2645 /// other time will have no effect.
2646 ///
2647 /// See [`Config::enable_hystart()`].
2648 ///
2649 /// [`Config::enable_hystart()`]: struct.Config.html#method.enable_hystart
2650 #[cfg(feature = "boringssl-bssl-crate")]
2651 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2652 pub fn set_hystart_in_handshake(ssl: &mut leyline_bssl::ssl::SslRef, v: bool) -> Result<()> {
2653 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2654
2655 ex_data.recovery_config.hystart = v;
2656
2657 Ok(())
2658 }
2659
2660 /// Configures whether to enable pacing.
2661 ///
2662 /// This function can only be called inside one of BoringSSL's handshake
2663 /// callbacks, before any packet has been sent. Calling this function any
2664 /// other time will have no effect.
2665 ///
2666 /// See [`Config::enable_pacing()`].
2667 ///
2668 /// [`Config::enable_pacing()`]: struct.Config.html#method.enable_pacing
2669 #[cfg(feature = "boringssl-bssl-crate")]
2670 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2671 pub fn set_pacing_in_handshake(ssl: &mut leyline_bssl::ssl::SslRef, v: bool) -> Result<()> {
2672 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2673
2674 ex_data.recovery_config.pacing = v;
2675
2676 Ok(())
2677 }
2678
2679 /// Sets the max value for pacing rate.
2680 ///
2681 /// This function can only be called inside one of BoringSSL's handshake
2682 /// callbacks, before any packet has been sent. Calling this function any
2683 /// other time will have no effect.
2684 ///
2685 /// See [`Config::set_max_pacing_rate()`].
2686 ///
2687 /// [`Config::set_max_pacing_rate()`]: struct.Config.html#method.set_max_pacing_rate
2688 #[cfg(feature = "boringssl-bssl-crate")]
2689 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2690 pub fn set_max_pacing_rate_in_handshake(
2691 ssl: &mut leyline_bssl::ssl::SslRef,
2692 v: Option<u64>,
2693 ) -> Result<()> {
2694 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2695
2696 ex_data.recovery_config.max_pacing_rate = v;
2697
2698 Ok(())
2699 }
2700
2701 /// Sets the maximum outgoing UDP payload size.
2702 ///
2703 /// This function can only be called inside one of BoringSSL's handshake
2704 /// callbacks, before any packet has been sent. Calling this function any
2705 /// other time will have no effect.
2706 ///
2707 /// See [`Config::set_max_send_udp_payload_size()`].
2708 ///
2709 /// [`Config::set_max_send_udp_payload_size()`]: struct.Config.html#method.set_max_send_udp_payload_size
2710 #[cfg(feature = "boringssl-bssl-crate")]
2711 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2712 pub fn set_max_send_udp_payload_size_in_handshake(
2713 ssl: &mut leyline_bssl::ssl::SslRef,
2714 v: usize,
2715 ) -> Result<()> {
2716 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2717
2718 ex_data.recovery_config.max_send_udp_payload_size = v;
2719
2720 Ok(())
2721 }
2722
2723 /// Sets the send capacity factor.
2724 ///
2725 /// This function can only be called inside one of BoringSSL's handshake
2726 /// callbacks, before any packet has been sent. Calling this function any
2727 /// other time will have no effect.
2728 ///
2729 /// See [`Config::set_send_capacity_factor()`].
2730 ///
2731 /// [`Config::set_max_send_udp_payload_size()`]: struct.Config.html#method.set_send_capacity_factor
2732 #[cfg(feature = "boringssl-bssl-crate")]
2733 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2734 pub fn set_send_capacity_factor_in_handshake(
2735 ssl: &mut leyline_bssl::ssl::SslRef,
2736 v: f64,
2737 ) -> Result<()> {
2738 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2739
2740 ex_data.tx_cap_factor = v;
2741
2742 Ok(())
2743 }
2744
2745 /// Configures whether to do path MTU discovery.
2746 ///
2747 /// This function can only be called inside one of BoringSSL's handshake
2748 /// callbacks, before any packet has been sent. Calling this function any
2749 /// other time will have no effect.
2750 ///
2751 /// See [`Config::discover_pmtu()`].
2752 ///
2753 /// [`Config::discover_pmtu()`]: struct.Config.html#method.discover_pmtu
2754 #[cfg(feature = "boringssl-bssl-crate")]
2755 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2756 pub fn set_discover_pmtu_in_handshake(
2757 ssl: &mut leyline_bssl::ssl::SslRef,
2758 discover: bool,
2759 max_probes: u8,
2760 ) -> Result<()> {
2761 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2762
2763 ex_data.pmtud = Some((discover, max_probes));
2764
2765 Ok(())
2766 }
2767
2768 /// Sets the `max_idle_timeout` transport parameter, in milliseconds.
2769 ///
2770 /// This function can only be called inside one of BoringSSL's handshake
2771 /// callbacks, before any packet has been sent. Calling this function any
2772 /// other time will have no effect.
2773 ///
2774 /// See [`Config::set_max_idle_timeout()`].
2775 ///
2776 /// [`Config::set_max_idle_timeout()`]: struct.Config.html#method.set_max_idle_timeout
2777 #[cfg(feature = "boringssl-bssl-crate")]
2778 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2779 pub fn set_max_idle_timeout_in_handshake(
2780 ssl: &mut leyline_bssl::ssl::SslRef,
2781 v: u64,
2782 ) -> Result<()> {
2783 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2784
2785 ex_data.local_transport_params.max_idle_timeout = v;
2786
2787 Self::set_transport_parameters_in_hanshake(
2788 ex_data.local_transport_params.clone(),
2789 ex_data.is_server,
2790 ssl,
2791 )
2792 }
2793
2794 /// Sets the `initial_max_streams_bidi` transport parameter.
2795 ///
2796 /// This function can only be called inside one of BoringSSL's handshake
2797 /// callbacks, before any packet has been sent. Calling this function any
2798 /// other time will have no effect.
2799 ///
2800 /// See [`Config::set_initial_max_streams_bidi()`].
2801 ///
2802 /// [`Config::set_initial_max_streams_bidi()`]: struct.Config.html#method.set_initial_max_streams_bidi
2803 #[cfg(feature = "boringssl-bssl-crate")]
2804 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2805 pub fn set_initial_max_streams_bidi_in_handshake(
2806 ssl: &mut leyline_bssl::ssl::SslRef,
2807 v: u64,
2808 ) -> Result<()> {
2809 let ex_data = tls::ExData::from_ssl_ref(ssl).ok_or(Error::TlsFail)?;
2810
2811 ex_data.local_transport_params.initial_max_streams_bidi = v;
2812
2813 Self::set_transport_parameters_in_hanshake(
2814 ex_data.local_transport_params.clone(),
2815 ex_data.is_server,
2816 ssl,
2817 )
2818 }
2819
2820 #[cfg(feature = "boringssl-bssl-crate")]
2821 fn set_transport_parameters_in_hanshake(
2822 params: TransportParams,
2823 is_server: bool,
2824 ssl: &mut leyline_bssl::ssl::SslRef,
2825 ) -> Result<()> {
2826 use foreign_types_shared::ForeignTypeRef;
2827 use std::mem::ManuallyDrop;
2828
2829 // In order to apply the new parameter to the TLS state before TPs are
2830 // written into a TLS message, we need to re-encode all TPs immediately.
2831 //
2832 // Since we don't have direct access to the main `Connection` object, we
2833 // need to re-create the `Handshake` state from the `SslRef`.
2834 //
2835 // Wrap the temporary `Handshake` in `ManuallyDrop` because this is only
2836 // a borrowed view of `ssl`. The caller retains ownership of the
2837 // underlying BoringSSL object.
2838 let mut handshake =
2839 ManuallyDrop::new(unsafe { tls::Handshake::from_ptr(ssl.as_ptr() as _)? });
2840
2841 handshake.set_quic_transport_params(¶ms, is_server, None)
2842 }
2843
2844 /// Sets the `use_initial_max_data_as_flow_control_win` flag during SSL
2845 /// handshake.
2846 ///
2847 /// This is now always enabled and this method is a no-op. It will be
2848 /// removed in a future release.
2849 #[cfg(feature = "boringssl-bssl-crate")]
2850 #[cfg_attr(docsrs, doc(cfg(feature = "boringssl-bssl-crate")))]
2851 #[deprecated(note = "This is now always enabled. This method is a no-op.")]
2852 pub fn set_use_initial_max_data_as_flow_control_win_in_handshake(
2853 _ssl: &mut leyline_bssl::ssl::SslRef,
2854 ) -> Result<()> {
2855 Ok(())
2856 }
2857
2858 /// Processes QUIC packets received from the peer.
2859 ///
2860 /// On success the number of bytes processed from the input buffer is
2861 /// returned. On error the connection will be closed by calling [`close()`]
2862 /// with the appropriate error code.
2863 ///
2864 /// Coalesced packets will be processed as necessary.
2865 ///
2866 /// Note that the contents of the input buffer `buf` might be modified by
2867 /// this function due to, for example, in-place decryption.
2868 ///
2869 /// [`close()`]: struct.Connection.html#method.close
2870 ///
2871 /// ## Examples:
2872 ///
2873 /// ```no_run
2874 /// # let mut buf = [0; 512];
2875 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
2876 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
2877 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
2878 /// # let peer = "127.0.0.1:1234".parse().unwrap();
2879 /// # let local = socket.local_addr().unwrap();
2880 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
2881 /// loop {
2882 /// let (read, from) = socket.recv_from(&mut buf).unwrap();
2883 ///
2884 /// let recv_info = quiche::RecvInfo {
2885 /// from,
2886 /// to: local,
2887 /// };
2888 ///
2889 /// let read = match conn.recv(&mut buf[..read], recv_info) {
2890 /// Ok(v) => v,
2891 ///
2892 /// Err(e) => {
2893 /// // An error occurred, handle it.
2894 /// break;
2895 /// },
2896 /// };
2897 /// }
2898 /// # Ok::<(), quiche::Error>(())
2899 /// ```
2900 pub fn recv(&mut self, buf: &mut [u8], info: RecvInfo) -> Result<usize> {
2901 let len = buf.len();
2902
2903 if len == 0 {
2904 return Err(Error::BufferTooShort);
2905 }
2906
2907 let recv_pid = self.paths.path_id_from_addrs(&(info.to, info.from));
2908
2909 if let Some(recv_pid) = recv_pid {
2910 let recv_path = self.paths.get_mut(recv_pid)?;
2911
2912 // Keep track of how many bytes we received from the client, so we
2913 // can limit bytes sent back before address validation, to a
2914 // multiple of this. The limit needs to be increased early on, so
2915 // that if there is an error there is enough credit to send a
2916 // CONNECTION_CLOSE.
2917 //
2918 // It doesn't matter if the packets received were valid or not, we
2919 // only need to track the total amount of bytes received.
2920 //
2921 // Note that we also need to limit the number of bytes we sent on a
2922 // path if we are not the host that initiated its usage.
2923 if self.is_server && !recv_path.verified_peer_address {
2924 recv_path.max_send_bytes += len * self.max_amplification_factor;
2925 }
2926 } else if !self.is_server {
2927 // If a client receives packets from an unknown server address,
2928 // the client MUST discard these packets.
2929 trace!(
2930 "{} client received packet from unknown address {:?}, dropping",
2931 self.trace_id, info,
2932 );
2933
2934 return Ok(len);
2935 }
2936
2937 let mut done = 0;
2938 let mut left = len;
2939
2940 // Process coalesced packets.
2941 while left > 0 {
2942 let read = match self.recv_single(&mut buf[len - left..len], &info, recv_pid) {
2943 Ok(v) => v,
2944
2945 Err(Error::Done) => {
2946 // If the packet can't be processed or decrypted, check if
2947 // it's a stateless reset.
2948 if self.is_stateless_reset(&buf[len - left..len]) {
2949 trace!("{} packet is a stateless reset", self.trace_id);
2950
2951 self.mark_closed();
2952 }
2953
2954 left
2955 }
2956
2957 Err(e) => {
2958 // In case of error processing the incoming packet, close
2959 // the connection.
2960 self.close(false, e.to_wire(), b"").ok();
2961 return Err(e);
2962 }
2963 };
2964
2965 done += read;
2966 left -= read;
2967 }
2968
2969 // Even though the packet was previously "accepted", it
2970 // should be safe to forward the error, as it also comes
2971 // from the `recv()` method.
2972 self.process_undecrypted_0rtt_packets()?;
2973
2974 Ok(done)
2975 }
2976
2977 fn process_undecrypted_0rtt_packets(&mut self) -> Result<()> {
2978 // Process previously undecryptable 0-RTT packets if the decryption key
2979 // is now available.
2980 if self.crypto_ctx[packet::Epoch::Application]
2981 .crypto_0rtt_open
2982 .is_some()
2983 {
2984 while let Some((mut pkt, info)) = self.undecryptable_pkts.pop_front() {
2985 if let Err(e) = self.recv(&mut pkt, info) {
2986 self.undecryptable_pkts.clear();
2987
2988 return Err(e);
2989 }
2990 }
2991 }
2992 Ok(())
2993 }
2994
2995 /// Returns true if a QUIC packet is a stateless reset.
2996 fn is_stateless_reset(&self, buf: &[u8]) -> bool {
2997 // If the packet is too small, then we just throw it away.
2998 let buf_len = buf.len();
2999 if buf_len < 21 {
3000 return false;
3001 }
3002
3003 // TODO: we should iterate over all active destination connection IDs
3004 // and check against their reset token.
3005 match self.peer_transport_params.stateless_reset_token {
3006 Some(token) => {
3007 let token_len = 16;
3008
3009 crypto::verify_slices_are_equal(
3010 &token.to_be_bytes(),
3011 &buf[buf_len - token_len..buf_len],
3012 )
3013 .is_ok()
3014 }
3015
3016 None => false,
3017 }
3018 }
3019
3020 /// Processes a single QUIC packet received from the peer.
3021 ///
3022 /// On success the number of bytes processed from the input buffer is
3023 /// returned. When the [`Done`] error is returned, processing of the
3024 /// remainder of the incoming UDP datagram should be interrupted.
3025 ///
3026 /// Note that a server might observe a new 4-tuple, preventing to
3027 /// know in advance to which path the incoming packet belongs to (`recv_pid`
3028 /// is `None`). As a client, packets from unknown 4-tuple are dropped
3029 /// beforehand (see `recv()`).
3030 ///
3031 /// On error, an error other than [`Done`] is returned.
3032 ///
3033 /// [`Done`]: enum.Error.html#variant.Done
3034 fn recv_single(
3035 &mut self,
3036 buf: &mut [u8],
3037 info: &RecvInfo,
3038 recv_pid: Option<usize>,
3039 ) -> Result<usize> {
3040 let now = Instant::now();
3041
3042 if buf.is_empty() {
3043 return Err(Error::Done);
3044 }
3045
3046 if self.is_closed() || self.is_draining() {
3047 return Err(Error::Done);
3048 }
3049
3050 let is_closing = self.local_error.is_some();
3051
3052 if is_closing {
3053 return Err(Error::Done);
3054 }
3055
3056 let buf_len = buf.len();
3057
3058 let mut b = octets::OctetsMut::with_slice(buf);
3059
3060 let mut hdr = Header::from_bytes(&mut b, self.source_id().len())
3061 .map_err(|e| drop_pkt_on_err(e, self.recv_count, self.is_server, &self.trace_id))?;
3062
3063 if hdr.ty == Type::VersionNegotiation {
3064 // Version negotiation packets can only be sent by the server.
3065 if self.is_server {
3066 return Err(Error::Done);
3067 }
3068
3069 // Ignore duplicate version negotiation.
3070 if self.did_version_negotiation {
3071 return Err(Error::Done);
3072 }
3073
3074 // Ignore version negotiation if any other packet has already been
3075 // successfully processed.
3076 if self.recv_count > 0 {
3077 return Err(Error::Done);
3078 }
3079
3080 if hdr.dcid != self.source_id() {
3081 return Err(Error::Done);
3082 }
3083
3084 if hdr.scid != self.destination_id() {
3085 return Err(Error::Done);
3086 }
3087
3088 trace!("{} rx pkt {:?}", self.trace_id, hdr);
3089
3090 let versions = hdr.versions.ok_or(Error::Done)?;
3091
3092 // Ignore version negotiation if the version already selected is
3093 // listed.
3094 if versions.contains(&self.version) {
3095 return Err(Error::Done);
3096 }
3097
3098 let supported_versions = versions.iter().filter(|&&v| {
3099 version_is_supported(v)
3100 && (self.compatible_versions.is_empty()
3101 || self.compatible_versions.contains(&v))
3102 });
3103
3104 let mut found_version = false;
3105
3106 for &v in supported_versions {
3107 found_version = true;
3108
3109 // The final version takes precedence over draft ones.
3110 if v == PROTOCOL_VERSION_V1 {
3111 self.version = v;
3112 break;
3113 }
3114
3115 self.version = cmp::max(self.version, v);
3116 }
3117
3118 if !found_version {
3119 // We don't support any of the versions offered.
3120 //
3121 // While a man-in-the-middle attacker might be able to
3122 // inject a version negotiation packet that triggers this
3123 // failure, the window of opportunity is very small and
3124 // this error is quite useful for debugging, so don't just
3125 // ignore the packet.
3126 return Err(Error::UnknownVersion);
3127 }
3128
3129 self.did_version_negotiation = true;
3130
3131 // Derive Initial secrets based on the new version.
3132 let (aead_open, aead_seal) = crypto::derive_initial_key_material(
3133 &self.destination_id(),
3134 self.version,
3135 self.is_server,
3136 true,
3137 )?;
3138
3139 // Reset connection state to force sending another Initial packet.
3140 self.drop_epoch_state(packet::Epoch::Initial, now);
3141 self.got_peer_conn_id = false;
3142 self.handshake.clear()?;
3143
3144 self.crypto_ctx[packet::Epoch::Initial].crypto_open = Some(aead_open);
3145 self.crypto_ctx[packet::Epoch::Initial].crypto_seal = Some(aead_seal);
3146
3147 self.handshake
3148 .use_legacy_codepoint(!version_is_supported(self.version));
3149
3150 // Encode transport parameters again, as the new version might be
3151 // using a different format.
3152 self.encode_transport_params()?;
3153
3154 return Err(Error::Done);
3155 }
3156
3157 if hdr.ty == Type::Retry {
3158 // Retry packets can only be sent by the server.
3159 if self.is_server {
3160 return Err(Error::Done);
3161 }
3162
3163 // Ignore duplicate retry.
3164 if self.did_retry {
3165 return Err(Error::Done);
3166 }
3167
3168 // Check if Retry packet is valid.
3169 if packet::verify_retry_integrity(&b, &self.destination_id(), self.version).is_err() {
3170 return Err(Error::Done);
3171 }
3172
3173 trace!("{} rx pkt {:?}", self.trace_id, hdr);
3174
3175 self.token = hdr.token;
3176 self.did_retry = true;
3177
3178 // Remember peer's new connection ID.
3179 self.odcid = Some(self.destination_id().into_owned());
3180
3181 self.set_initial_dcid(hdr.scid.clone(), None, self.paths.get_active_path_id()?)?;
3182
3183 self.rscid = Some(self.destination_id().into_owned());
3184
3185 // Derive Initial secrets using the new connection ID.
3186 let (aead_open, aead_seal) =
3187 crypto::derive_initial_key_material(&hdr.scid, self.version, self.is_server, true)?;
3188
3189 // Reset connection state to force sending another Initial packet.
3190 self.drop_epoch_state(packet::Epoch::Initial, now);
3191 self.got_peer_conn_id = false;
3192 self.handshake.clear()?;
3193
3194 self.crypto_ctx[packet::Epoch::Initial].crypto_open = Some(aead_open);
3195 self.crypto_ctx[packet::Epoch::Initial].crypto_seal = Some(aead_seal);
3196
3197 return Err(Error::Done);
3198 }
3199
3200 if self.is_server && !self.did_version_negotiation {
3201 if !version_is_supported(hdr.version) {
3202 return Err(Error::UnknownVersion);
3203 }
3204
3205 self.version = hdr.version;
3206 self.did_version_negotiation = true;
3207
3208 self.handshake
3209 .use_legacy_codepoint(!version_is_supported(self.version));
3210
3211 // Encode transport parameters again, as the new version might be
3212 // using a different format.
3213 self.encode_transport_params()?;
3214 }
3215
3216 let mut compatible_switch = None;
3217
3218 if !self.is_server
3219 && !self.did_compatible_version_negotiation
3220 && self.crypto_ctx[packet::Epoch::Handshake]
3221 .crypto_open
3222 .is_none()
3223 && hdr.ty == Type::Initial
3224 && hdr.version != self.version
3225 && self.compatible_versions.contains(&hdr.version)
3226 {
3227 let initial_dcid = self
3228 .rscid
3229 .clone()
3230 .or_else(|| self.odcid.clone())
3231 .unwrap_or_else(|| self.destination_id().into_owned());
3232
3233 compatible_switch = Some(crypto::derive_initial_key_material(
3234 &initial_dcid,
3235 hdr.version,
3236 self.is_server,
3237 true,
3238 )?);
3239 }
3240
3241 if hdr.ty != Type::Short && hdr.version != self.version && compatible_switch.is_none() {
3242 // At this point version negotiation was already performed, so
3243 // ignore packets that don't match the connection's version.
3244 return Err(Error::Done);
3245 }
3246
3247 // Long header packets have an explicit payload length, but short
3248 // packets don't so just use the remaining capacity in the buffer.
3249 let payload_len = if hdr.ty == Type::Short {
3250 b.cap()
3251 } else {
3252 b.get_varint().map_err(|e| {
3253 drop_pkt_on_err(e.into(), self.recv_count, self.is_server, &self.trace_id)
3254 })? as usize
3255 };
3256
3257 // Make sure the buffer is same or larger than an explicit
3258 // payload length.
3259 if payload_len > b.cap() {
3260 return Err(drop_pkt_on_err(
3261 Error::InvalidPacket,
3262 self.recv_count,
3263 self.is_server,
3264 &self.trace_id,
3265 ));
3266 }
3267
3268 // Derive initial secrets on the server.
3269 if !self.derived_initial_secrets {
3270 let (aead_open, aead_seal) = crypto::derive_initial_key_material(
3271 &hdr.dcid,
3272 self.version,
3273 self.is_server,
3274 false,
3275 )?;
3276
3277 self.crypto_ctx[packet::Epoch::Initial].crypto_open = Some(aead_open);
3278 self.crypto_ctx[packet::Epoch::Initial].crypto_seal = Some(aead_seal);
3279
3280 self.derived_initial_secrets = true;
3281 }
3282
3283 // Select packet number space epoch based on the received packet's type.
3284 let epoch = hdr.ty.to_epoch()?;
3285
3286 // Select AEAD context used to open incoming packet.
3287 let aead = if let Some((open, _)) = compatible_switch.as_ref() {
3288 Some(open)
3289 } else if hdr.ty == Type::ZeroRTT {
3290 // Only use 0-RTT key if incoming packet is 0-RTT.
3291 self.crypto_ctx[epoch].crypto_0rtt_open.as_ref()
3292 } else {
3293 // Otherwise use the packet number space's main key.
3294 self.crypto_ctx[epoch].crypto_open.as_ref()
3295 };
3296
3297 // Finally, discard packet if no usable key is available.
3298 let mut aead = match aead {
3299 Some(v) => v,
3300
3301 None => {
3302 if hdr.ty == Type::ZeroRTT
3303 && self.undecryptable_pkts.len() < MAX_UNDECRYPTABLE_PACKETS
3304 && !self.is_established()
3305 {
3306 // Buffer 0-RTT packets when the required read key is not
3307 // available yet, and process them later.
3308 //
3309 // TODO: in the future we might want to buffer other types
3310 // of undecryptable packets as well.
3311 let pkt_len = b.off() + payload_len;
3312 let pkt = (b.buf()[..pkt_len]).to_vec();
3313
3314 self.undecryptable_pkts.push_back((pkt, *info));
3315 return Ok(pkt_len);
3316 }
3317
3318 let e = drop_pkt_on_err(
3319 Error::CryptoFail,
3320 self.recv_count,
3321 self.is_server,
3322 &self.trace_id,
3323 );
3324
3325 return Err(e);
3326 }
3327 };
3328
3329 let aead_tag_len = aead.alg().tag_len();
3330
3331 packet::decrypt_hdr(&mut b, &mut hdr, aead)
3332 .map_err(|e| drop_pkt_on_err(e, self.recv_count, self.is_server, &self.trace_id))?;
3333
3334 let pn = packet::decode_pkt_num(
3335 self.pkt_num_spaces[epoch].largest_rx_pkt_num,
3336 hdr.pkt_num,
3337 hdr.pkt_num_len,
3338 );
3339
3340 let pn_len = hdr.pkt_num_len;
3341
3342 trace!(
3343 "{} rx pkt {:?} len={} pn={} {}",
3344 self.trace_id,
3345 hdr,
3346 payload_len,
3347 pn,
3348 AddrTupleFmt(info.from, info.to)
3349 );
3350
3351 #[cfg(feature = "qlog")]
3352 let mut qlog_frames = vec![];
3353
3354 // Check for key update.
3355 let mut aead_next = None;
3356
3357 if self.handshake_confirmed && hdr.ty != Type::ZeroRTT && hdr.key_phase != self.key_phase {
3358 // Check if this packet arrived before key update.
3359 if let Some(key_update) = self.crypto_ctx[epoch]
3360 .key_update
3361 .as_ref()
3362 .and_then(|key_update| (pn < key_update.pn_on_update).then_some(key_update))
3363 {
3364 aead = &key_update.crypto_open;
3365 } else {
3366 trace!("{} peer-initiated key update", self.trace_id);
3367
3368 aead_next = Some((
3369 self.crypto_ctx[epoch]
3370 .crypto_open
3371 .as_ref()
3372 .unwrap()
3373 .derive_next_packet_key()?,
3374 self.crypto_ctx[epoch]
3375 .crypto_seal
3376 .as_ref()
3377 .unwrap()
3378 .derive_next_packet_key()?,
3379 ));
3380
3381 // `aead_next` is always `Some` at this point, so the
3382 // `unwrap()` will never fail.
3383 aead = &aead_next.as_ref().unwrap().0;
3384 }
3385 }
3386
3387 let mut payload = packet::decrypt_pkt(&mut b, pn, pn_len, payload_len, aead)
3388 .map_err(|e| drop_pkt_on_err(e, self.recv_count, self.is_server, &self.trace_id))?;
3389
3390 if let Some((aead_open, aead_seal)) = compatible_switch {
3391 self.version = hdr.version;
3392 self.did_compatible_version_negotiation = true;
3393
3394 self.crypto_ctx[packet::Epoch::Initial].crypto_open = Some(aead_open);
3395 self.crypto_ctx[packet::Epoch::Initial].crypto_seal = Some(aead_seal);
3396 self.crypto_ctx[packet::Epoch::Application].crypto_seal = None;
3397 }
3398
3399 if self.pkt_num_spaces[epoch].recv_pkt_num.contains(pn) {
3400 trace!("{} ignored duplicate packet {}", self.trace_id, pn);
3401 return Err(Error::Done);
3402 }
3403
3404 // Packets with no frames are invalid.
3405 if payload.cap() == 0 {
3406 return Err(Error::InvalidPacket);
3407 }
3408
3409 // Now that we decrypted the packet, let's see if we can map it to an
3410 // existing path.
3411 let recv_pid = if hdr.ty == Type::Short && self.got_peer_conn_id {
3412 let pkt_dcid = ConnectionId::from_ref(&hdr.dcid);
3413 self.get_or_create_recv_path_id(recv_pid, &pkt_dcid, buf_len, info)?
3414 } else {
3415 // During handshake, we are on the initial path.
3416 self.paths.get_active_path_id()?
3417 };
3418
3419 // The key update is verified once a packet is successfully decrypted
3420 // using the new keys.
3421 if let Some((open_next, seal_next)) = aead_next {
3422 if !self.crypto_ctx[epoch]
3423 .key_update
3424 .as_ref()
3425 .is_none_or(|prev| prev.update_acked)
3426 {
3427 // Peer has updated keys twice without awaiting confirmation.
3428 return Err(Error::KeyUpdate);
3429 }
3430
3431 trace!("{} key update verified", self.trace_id);
3432
3433 let _ = self.crypto_ctx[epoch].crypto_seal.replace(seal_next);
3434
3435 let open_prev = self.crypto_ctx[epoch]
3436 .crypto_open
3437 .replace(open_next)
3438 .unwrap();
3439
3440 let recv_path = self.paths.get_mut(recv_pid)?;
3441
3442 self.crypto_ctx[epoch].key_update = Some(packet::KeyUpdate {
3443 crypto_open: open_prev,
3444 pn_on_update: pn,
3445 update_acked: false,
3446 timer: now + (recv_path.recovery.pto() * 3),
3447 });
3448
3449 self.key_phase = !self.key_phase;
3450
3451 qlog_with_type!(QLOG_PACKET_RX, self.qlog, q, {
3452 let trigger = Some(qlog::events::quic::KeyUpdateOrRetiredTrigger::RemoteUpdate);
3453
3454 let ev_data_client = EventData::QuicKeyUpdated(qlog::events::quic::KeyUpdated {
3455 key_type: qlog::events::quic::KeyType::Client1RttSecret,
3456 trigger: trigger.clone(),
3457 ..Default::default()
3458 });
3459
3460 q.add_event_data_with_instant(ev_data_client, now).ok();
3461
3462 let ev_data_server = EventData::QuicKeyUpdated(qlog::events::quic::KeyUpdated {
3463 key_type: qlog::events::quic::KeyType::Server1RttSecret,
3464 trigger,
3465 ..Default::default()
3466 });
3467
3468 q.add_event_data_with_instant(ev_data_server, now).ok();
3469 });
3470 }
3471
3472 if !self.is_server && !self.got_peer_conn_id {
3473 if self.odcid.is_none() {
3474 self.odcid = Some(self.destination_id().into_owned());
3475 }
3476
3477 // Replace the randomly generated destination connection ID with
3478 // the one supplied by the server.
3479 self.set_initial_dcid(
3480 hdr.scid.clone(),
3481 self.peer_transport_params.stateless_reset_token,
3482 recv_pid,
3483 )?;
3484
3485 self.got_peer_conn_id = true;
3486 }
3487
3488 if self.is_server && !self.got_peer_conn_id {
3489 self.set_initial_dcid(hdr.scid.clone(), None, recv_pid)?;
3490
3491 if !self.did_retry {
3492 self.local_transport_params
3493 .original_destination_connection_id = Some(hdr.dcid.to_vec().into());
3494
3495 self.encode_transport_params()?;
3496 }
3497
3498 self.got_peer_conn_id = true;
3499 }
3500
3501 // To avoid sending an ACK in response to an ACK-only packet, we need
3502 // to keep track of whether this packet contains any frame other than
3503 // ACK and PADDING.
3504 let mut ack_elicited = false;
3505
3506 // Process packet payload. If a frame cannot be processed, store the
3507 // error and stop further packet processing.
3508 let mut frame_processing_err = None;
3509
3510 // To know if the peer migrated the connection, we need to keep track
3511 // whether this is a non-probing packet.
3512 let mut probing = true;
3513
3514 // Process packet payload.
3515 while payload.cap() > 0 {
3516 let frame = frame::Frame::from_bytes_with(&mut payload, hdr.ty, self.frame_extensions)?;
3517
3518 qlog_with_type!(QLOG_PACKET_RX, self.qlog, _q, {
3519 qlog_frames.push(frame.to_qlog());
3520 });
3521
3522 if frame.ack_eliciting() {
3523 ack_elicited = true;
3524 }
3525
3526 if !frame.probing() {
3527 probing = false;
3528 }
3529
3530 if let Err(e) = self.process_frame(frame, &hdr, recv_pid, epoch, now) {
3531 frame_processing_err = Some(e);
3532 break;
3533 }
3534 }
3535
3536 qlog_with_type!(QLOG_PACKET_RX, self.qlog, q, {
3537 let packet_size = b.len();
3538
3539 let qlog_pkt_hdr = qlog::events::quic::PacketHeader::with_type(
3540 hdr.ty.to_qlog(),
3541 Some(pn),
3542 Some(hdr.version),
3543 Some(&hdr.scid),
3544 Some(&hdr.dcid),
3545 );
3546
3547 let qlog_raw_info = RawInfo {
3548 length: Some(packet_size as u64),
3549 payload_length: Some(payload_len as u64),
3550 data: None,
3551 };
3552
3553 let ev_data = EventData::QuicPacketReceived(qlog::events::quic::PacketReceived {
3554 header: qlog_pkt_hdr,
3555 frames: Some(qlog_frames),
3556 raw: Some(qlog_raw_info),
3557 ..Default::default()
3558 });
3559
3560 q.add_event_data_with_instant(ev_data, now).ok();
3561 });
3562
3563 qlog_with_type!(QLOG_METRICS, self.qlog, q, {
3564 let recv_path = self.paths.get_mut(recv_pid)?;
3565 recv_path.recovery.maybe_qlog(q, now);
3566 });
3567
3568 if let Some(e) = frame_processing_err {
3569 // Any frame error is terminal, so now just return.
3570 return Err(e);
3571 }
3572
3573 // Only log the remote transport parameters once the connection is
3574 // established (i.e. after frames have been fully parsed) and only
3575 // once per connection.
3576 if self.is_established() {
3577 qlog_with_type!(QLOG_PARAMS_SET, self.qlog, q, {
3578 if !self.qlog.logged_peer_params {
3579 let ev_data = self
3580 .peer_transport_params
3581 .to_qlog(TransportInitiator::Remote, self.handshake.cipher());
3582
3583 q.add_event_data_with_instant(ev_data, now).ok();
3584
3585 self.qlog.logged_peer_params = true;
3586 }
3587 });
3588 }
3589
3590 // Process acked frames. Note that several packets from several paths
3591 // might have been acked by the received packet.
3592 let (paths, path_events) = self.paths.iter_mut_and_events();
3593 for (_, p) in paths {
3594 while let Some(acked) = p.recovery.next_acked_frame(epoch) {
3595 match acked {
3596 frame::Frame::Ping {
3597 mtu_probe: Some(mtu_probe),
3598 } => {
3599 trace!(
3600 "{} pmtud probe acked; probe size {:?}",
3601 self.trace_id, mtu_probe
3602 );
3603
3604 let local = p.local_addr();
3605 let peer = p.peer_addr();
3606 if let Some(pmtud) = p.pmtud.as_mut() {
3607 let old_pmtu = pmtud.get_current_mtu();
3608 let current_mtu = pmtud.successful_probe(mtu_probe);
3609 let new_pmtu = pmtud.get_current_mtu();
3610
3611 // Update the datagram size only after validating
3612 // the MTU.
3613 if let Some(current_mtu) = current_mtu {
3614 qlog_with_type!(
3615 EventType::QuicEventType(QuicEventType::MtuUpdated),
3616 self.qlog,
3617 q,
3618 {
3619 let pmtu_data = EventData::QuicMtuUpdated(
3620 qlog::events::quic::MtuUpdated {
3621 old: Some(p.recovery.max_datagram_size() as u32),
3622 new: current_mtu as u32,
3623 done: Some(true),
3624 },
3625 );
3626
3627 q.add_event_data_with_instant(pmtu_data, now).ok();
3628 }
3629 );
3630
3631 p.recovery.pmtud_update_max_datagram_size(current_mtu);
3632 }
3633
3634 if let Some(event) = path::pmtu_event(local, peer, old_pmtu, new_pmtu) {
3635 path_events.push_back(event);
3636 }
3637 }
3638 }
3639
3640 frame::Frame::ACK { ranges, .. } => {
3641 // Stop acknowledging packets less than or equal to the
3642 // largest acknowledged in the sent ACK frame that, in
3643 // turn, got acked.
3644 if let Some(largest_acked) = ranges.last() {
3645 self.pkt_num_spaces[epoch]
3646 .recv_pkt_need_ack
3647 .remove_until(largest_acked);
3648 }
3649 }
3650
3651 frame::Frame::CryptoHeader { offset, length } => {
3652 self.crypto_ctx[epoch]
3653 .crypto_stream
3654 .send
3655 .ack_and_drop(offset, length);
3656 }
3657
3658 frame::Frame::StreamHeader {
3659 stream_id,
3660 offset,
3661 length,
3662 ..
3663 } => {
3664 // Emit qlog before checking if the stream still exists.
3665 // The client does need to ACK frames that were received
3666 // after the client sends a ResetStream.
3667
3668 qlog_with_type!(QLOG_DATA_MV, self.qlog, q, {
3669 let ev_data = EventData::QuicStreamDataMoved(
3670 qlog::events::quic::StreamDataMoved {
3671 stream_id: Some(stream_id),
3672 offset: Some(offset),
3673 raw: Some(RawInfo {
3674 length: Some(length as u64),
3675 ..Default::default()
3676 }),
3677 from: Some(DataRecipient::Transport),
3678 to: Some(DataRecipient::Dropped),
3679 ..Default::default()
3680 },
3681 );
3682
3683 q.add_event_data_with_instant(ev_data, now).ok();
3684 });
3685
3686 let stream = match self.streams.get_mut(stream_id) {
3687 Some(v) => v,
3688
3689 None => continue,
3690 };
3691
3692 let dropped = stream.send.ack_and_drop(offset, length);
3693 let priority_key = Arc::clone(&stream.priority_key);
3694
3695 // Only collect the stream if it is complete and not
3696 // readable or writable.
3697 //
3698 // If it is readable, it will get collected when
3699 // stream_recv() is next used.
3700 //
3701 // If it is writable, it might mean that the stream
3702 // has been stopped by the peer (i.e. a STOP_SENDING
3703 // frame is received), in which case before collecting
3704 // the stream we will need to propagate the
3705 // `StreamStopped` error to the application. It will
3706 // instead get collected when one of stream_capacity(),
3707 // stream_writable(), stream_send(), ... is next called.
3708 //
3709 // Note that we can't use `is_writable()` here because
3710 // it returns false if the stream is stopped. Instead,
3711 // since the stream is marked as writable when a
3712 // STOP_SENDING frame is received, we check the writable
3713 // queue directly instead.
3714 let is_writable = priority_key.writable.is_linked() &&
3715 // Ensure that the stream is actually stopped.
3716 stream.send.is_stopped();
3717
3718 let is_complete = stream.is_complete();
3719 let is_readable = stream.is_readable();
3720
3721 if is_complete && !is_readable && !is_writable {
3722 let local = stream.local;
3723 self.streams.collect(stream_id, local);
3724 }
3725
3726 // Update `tx_buffered` for data dropped from stream
3727 // buffers, such as retransmission data acknowledged
3728 // before it could be resent.
3729 if dropped > 0 {
3730 self.streams.sub_tx_buffered(dropped);
3731 }
3732 }
3733
3734 frame::Frame::HandshakeDone => {
3735 // Explicitly set this to true, so that if the frame was
3736 // already scheduled for retransmission, it is aborted.
3737 self.handshake_done_sent = true;
3738
3739 self.handshake_done_acked = true;
3740 }
3741
3742 frame::Frame::ResetStream { stream_id, .. } => {
3743 let stream = match self.streams.get_mut(stream_id) {
3744 Some(v) => v,
3745
3746 None => continue,
3747 };
3748
3749 let priority_key = Arc::clone(&stream.priority_key);
3750
3751 // Only collect the stream if it is complete and not
3752 // readable or writable.
3753 //
3754 // If it is readable, it will get collected when
3755 // stream_recv() is next used.
3756 //
3757 // If it is writable, it might mean that the stream
3758 // has been stopped by the peer (i.e. a STOP_SENDING
3759 // frame is received), in which case before collecting
3760 // the stream we will need to propagate the
3761 // `StreamStopped` error to the application. It will
3762 // instead get collected when one of stream_capacity(),
3763 // stream_writable(), stream_send(), ... is next called.
3764 //
3765 // Note that we can't use `is_writable()` here because
3766 // it returns false if the stream is stopped. Instead,
3767 // since the stream is marked as writable when a
3768 // STOP_SENDING frame is received, we check the writable
3769 // queue directly instead.
3770 let is_writable = priority_key.writable.is_linked() &&
3771 // Ensure that the stream is actually stopped.
3772 stream.send.is_stopped();
3773
3774 let is_complete = stream.is_complete();
3775 let is_readable = stream.is_readable();
3776
3777 if is_complete && !is_readable && !is_writable {
3778 let local = stream.local;
3779 self.streams.collect(stream_id, local);
3780 }
3781 }
3782
3783 _ => (),
3784 }
3785 }
3786 }
3787
3788 // Now that we processed all the frames, if there is a path that has no
3789 // Destination CID, try to allocate one.
3790 let no_dcid = self
3791 .paths
3792 .iter_mut()
3793 .filter(|(_, p)| p.active_dcid_seq.is_none());
3794
3795 for (pid, p) in no_dcid {
3796 if self.ids.zero_length_dcid() {
3797 p.active_dcid_seq = Some(0);
3798 continue;
3799 }
3800
3801 let dcid_seq = match self.ids.lowest_available_dcid_seq() {
3802 Some(seq) => seq,
3803 None => break,
3804 };
3805
3806 self.ids.link_dcid_to_path_id(dcid_seq, pid)?;
3807
3808 p.active_dcid_seq = Some(dcid_seq);
3809 }
3810
3811 // We only record the time of arrival of the largest packet number
3812 // that still needs to be acked, to be used for ACK delay calculation.
3813 if self.pkt_num_spaces[epoch].recv_pkt_need_ack.last() < Some(pn) {
3814 self.pkt_num_spaces[epoch].largest_rx_pkt_time = now;
3815 }
3816
3817 self.pkt_num_spaces[epoch].recv_pkt_num.insert(pn);
3818
3819 self.pkt_num_spaces[epoch].recv_pkt_need_ack.push_item(pn);
3820
3821 self.pkt_num_spaces[epoch].ack_elicited =
3822 cmp::max(self.pkt_num_spaces[epoch].ack_elicited, ack_elicited);
3823
3824 self.pkt_num_spaces[epoch].largest_rx_pkt_num =
3825 cmp::max(self.pkt_num_spaces[epoch].largest_rx_pkt_num, pn);
3826
3827 if !probing {
3828 self.pkt_num_spaces[epoch].largest_rx_non_probing_pkt_num = cmp::max(
3829 self.pkt_num_spaces[epoch].largest_rx_non_probing_pkt_num,
3830 pn,
3831 );
3832
3833 // Did the peer migrated to another path?
3834 let active_path_id = self.paths.get_active_path_id()?;
3835
3836 if self.is_server
3837 && recv_pid != active_path_id
3838 && self.pkt_num_spaces[epoch].largest_rx_non_probing_pkt_num == pn
3839 {
3840 self.on_peer_migrated(recv_pid, self.disable_dcid_reuse, now)?;
3841 }
3842 }
3843
3844 if let Some(idle_timeout) = self.idle_timeout() {
3845 self.idle_timer = Some(now + idle_timeout);
3846 }
3847
3848 // Update send capacity.
3849 self.update_tx_cap();
3850
3851 self.recv_count += 1;
3852 self.paths.get_mut(recv_pid)?.recv_count += 1;
3853
3854 let read = b.off() + aead_tag_len;
3855
3856 self.recv_bytes += read as u64;
3857 self.paths.get_mut(recv_pid)?.recv_bytes += read as u64;
3858
3859 // An Handshake packet has been received from the client and has been
3860 // successfully processed, so we can drop the initial state and consider
3861 // the client's address to be verified.
3862 if self.is_server && hdr.ty == Type::Handshake {
3863 self.drop_epoch_state(packet::Epoch::Initial, now);
3864
3865 self.paths.get_mut(recv_pid)?.verified_peer_address = true;
3866 }
3867
3868 self.ack_eliciting_sent = false;
3869
3870 Ok(read)
3871 }
3872
3873 /// Writes a single QUIC packet to be sent to the peer.
3874 ///
3875 /// On success the number of bytes written to the output buffer is
3876 /// returned, or [`Done`] if there was nothing to write.
3877 ///
3878 /// The application should call `send()` multiple times until [`Done`] is
3879 /// returned, indicating that there are no more packets to send. It is
3880 /// recommended that `send()` be called in the following cases:
3881 ///
3882 /// * When the application receives QUIC packets from the peer (that is,
3883 /// any time [`recv()`] is also called).
3884 ///
3885 /// * When the connection timer expires (that is, any time [`on_timeout()`]
3886 /// is also called).
3887 ///
3888 /// * When the application sends data to the peer (for example, any time
3889 /// [`stream_send()`] or [`stream_shutdown()`] are called).
3890 ///
3891 /// * When the application receives data from the peer (for example any
3892 /// time [`stream_recv()`] is called).
3893 ///
3894 /// Once [`is_draining()`] returns `true`, it is no longer necessary to call
3895 /// `send()` and all calls will return [`Done`].
3896 ///
3897 /// [`Done`]: enum.Error.html#variant.Done
3898 /// [`recv()`]: struct.Connection.html#method.recv
3899 /// [`on_timeout()`]: struct.Connection.html#method.on_timeout
3900 /// [`stream_send()`]: struct.Connection.html#method.stream_send
3901 /// [`stream_shutdown()`]: struct.Connection.html#method.stream_shutdown
3902 /// [`stream_recv()`]: struct.Connection.html#method.stream_recv
3903 /// [`is_draining()`]: struct.Connection.html#method.is_draining
3904 ///
3905 /// ## Examples:
3906 ///
3907 /// ```no_run
3908 /// # let mut out = [0; 512];
3909 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
3910 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
3911 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
3912 /// # let peer = "127.0.0.1:1234".parse().unwrap();
3913 /// # let local = socket.local_addr().unwrap();
3914 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
3915 /// loop {
3916 /// let (write, send_info) = match conn.send(&mut out) {
3917 /// Ok(v) => v,
3918 ///
3919 /// Err(quiche::Error::Done) => {
3920 /// // Done writing.
3921 /// break;
3922 /// },
3923 ///
3924 /// Err(e) => {
3925 /// // An error occurred, handle it.
3926 /// break;
3927 /// },
3928 /// };
3929 ///
3930 /// socket.send_to(&out[..write], &send_info.to).unwrap();
3931 /// }
3932 /// # Ok::<(), quiche::Error>(())
3933 /// ```
3934 pub fn send(&mut self, out: &mut [u8]) -> Result<(usize, SendInfo)> {
3935 self.send_on_path(out, None, None)
3936 }
3937
3938 /// Writes a single QUIC packet to be sent to the peer from the specified
3939 /// local address `from` to the destination address `to`.
3940 ///
3941 /// The behavior of this method differs depending on the value of the `from`
3942 /// and `to` parameters:
3943 ///
3944 /// * If both are `Some`, then the method only consider the 4-tuple
3945 /// (`from`, `to`). Application can monitor the 4-tuple availability,
3946 /// either by monitoring [`path_event_next()`] events or by relying on
3947 /// the [`paths_iter()`] method. If the provided 4-tuple does not exist
3948 /// on the connection (anymore), it returns an [`InvalidState`].
3949 ///
3950 /// * If `from` is `Some` and `to` is `None`, then the method only
3951 /// considers sending packets on paths having `from` as local address.
3952 ///
3953 /// * If `to` is `Some` and `from` is `None`, then the method only
3954 /// considers sending packets on paths having `to` as peer address.
3955 ///
3956 /// * If both are `None`, all available paths are considered.
3957 ///
3958 /// On success the number of bytes written to the output buffer is
3959 /// returned, or [`Done`] if there was nothing to write.
3960 ///
3961 /// The application should call `send_on_path()` multiple times until
3962 /// [`Done`] is returned, indicating that there are no more packets to
3963 /// send. It is recommended that `send_on_path()` be called in the
3964 /// following cases:
3965 ///
3966 /// * When the application receives QUIC packets from the peer (that is,
3967 /// any time [`recv()`] is also called).
3968 ///
3969 /// * When the connection timer expires (that is, any time [`on_timeout()`]
3970 /// is also called).
3971 ///
3972 /// * When the application sends data to the peer (for examples, any time
3973 /// [`stream_send()`] or [`stream_shutdown()`] are called).
3974 ///
3975 /// * When the application receives data from the peer (for example any
3976 /// time [`stream_recv()`] is called).
3977 ///
3978 /// Once [`is_draining()`] returns `true`, it is no longer necessary to call
3979 /// `send_on_path()` and all calls will return [`Done`].
3980 ///
3981 /// [`Done`]: enum.Error.html#variant.Done
3982 /// [`InvalidState`]: enum.Error.html#InvalidState
3983 /// [`recv()`]: struct.Connection.html#method.recv
3984 /// [`on_timeout()`]: struct.Connection.html#method.on_timeout
3985 /// [`stream_send()`]: struct.Connection.html#method.stream_send
3986 /// [`stream_shutdown()`]: struct.Connection.html#method.stream_shutdown
3987 /// [`stream_recv()`]: struct.Connection.html#method.stream_recv
3988 /// [`path_event_next()`]: struct.Connection.html#method.path_event_next
3989 /// [`paths_iter()`]: struct.Connection.html#method.paths_iter
3990 /// [`is_draining()`]: struct.Connection.html#method.is_draining
3991 ///
3992 /// ## Examples:
3993 ///
3994 /// ```no_run
3995 /// # let mut out = [0; 512];
3996 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
3997 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
3998 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
3999 /// # let peer = "127.0.0.1:1234".parse().unwrap();
4000 /// # let local = socket.local_addr().unwrap();
4001 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
4002 /// loop {
4003 /// let (write, send_info) = match conn.send_on_path(&mut out, Some(local), Some(peer)) {
4004 /// Ok(v) => v,
4005 ///
4006 /// Err(quiche::Error::Done) => {
4007 /// // Done writing.
4008 /// break;
4009 /// },
4010 ///
4011 /// Err(e) => {
4012 /// // An error occurred, handle it.
4013 /// break;
4014 /// },
4015 /// };
4016 ///
4017 /// socket.send_to(&out[..write], &send_info.to).unwrap();
4018 /// }
4019 /// # Ok::<(), quiche::Error>(())
4020 /// ```
4021 pub fn send_on_path(
4022 &mut self,
4023 out: &mut [u8],
4024 from: Option<SocketAddr>,
4025 to: Option<SocketAddr>,
4026 ) -> Result<(usize, SendInfo)> {
4027 if out.is_empty() {
4028 return Err(Error::BufferTooShort);
4029 }
4030
4031 if self.is_closed() || self.is_draining() {
4032 return Err(Error::Done);
4033 }
4034
4035 let now = Instant::now();
4036
4037 if self.local_error.is_none() {
4038 self.do_handshake(now)?;
4039 }
4040
4041 // Forwarding the error value here could confuse
4042 // applications, as they may not expect getting a `recv()`
4043 // error when calling `send()`.
4044 //
4045 // We simply fall-through to sending packets, which should
4046 // take care of terminating the connection as needed.
4047 let _ = self.process_undecrypted_0rtt_packets();
4048
4049 // There's no point in trying to send a packet if the Initial secrets
4050 // have not been derived yet, so return early.
4051 if !self.derived_initial_secrets {
4052 return Err(Error::Done);
4053 }
4054
4055 let mut has_initial = false;
4056
4057 let mut done = 0;
4058
4059 // Limit output packet size to respect the sender and receiver's
4060 // maximum UDP payload size limit.
4061 let mut left = cmp::min(out.len(), self.max_send_udp_payload_size());
4062
4063 let send_pid = match (from, to) {
4064 (Some(f), Some(t)) => self
4065 .paths
4066 .path_id_from_addrs(&(f, t))
4067 .ok_or(Error::InvalidState)?,
4068
4069 _ => self.get_send_path_id(from, to)?,
4070 };
4071
4072 let send_path = self.paths.get_mut(send_pid)?;
4073
4074 // Increase the maximum datagram size for a PMTUD probe.
4075 if let Some(pmtud) = send_path.pmtud.as_mut() {
4076 if pmtud.should_probe() {
4077 let size = if self.handshake_confirmed || self.handshake_completed {
4078 pmtud.get_probe_size()
4079 } else {
4080 pmtud.get_current_mtu()
4081 };
4082
4083 send_path.recovery.pmtud_update_max_datagram_size(size);
4084
4085 left = cmp::min(out.len(), send_path.recovery.max_datagram_size());
4086 }
4087 }
4088
4089 // Limit data sent by the server based on the amount of data received
4090 // from the client before its address is validated.
4091 if !send_path.verified_peer_address && self.is_server {
4092 left = cmp::min(left, send_path.max_send_bytes);
4093 }
4094
4095 // Generate coalesced packets.
4096 while left > 0 {
4097 let split_sent = self.initial_crypto_split_sent;
4098 let (ty, written) =
4099 match self.send_single(&mut out[done..done + left], send_pid, has_initial, now) {
4100 Ok(v) => v,
4101
4102 Err(Error::BufferTooShort) | Err(Error::Done) => break,
4103
4104 Err(e) => return Err(e),
4105 };
4106
4107 done += written;
4108 left -= written;
4109
4110 match ty {
4111 Type::Initial => has_initial = true,
4112
4113 // No more packets can be coalesced after a 1-RTT.
4114 Type::Short => break,
4115
4116 _ => (),
4117 };
4118
4119 if !split_sent && self.initial_crypto_split_sent {
4120 break;
4121 }
4122
4123 // When sending multiple PTO probes, don't coalesce them together,
4124 // so they are sent on separate UDP datagrams.
4125 if let Ok(epoch) = ty.to_epoch() {
4126 if self.paths.get_mut(send_pid)?.recovery.loss_probes(epoch) > 0 {
4127 break;
4128 }
4129 }
4130
4131 // Don't coalesce packets that must go on different paths.
4132 if !(from.is_some() && to.is_some()) && self.get_send_path_id(from, to)? != send_pid {
4133 break;
4134 }
4135 }
4136
4137 if done == 0 {
4138 self.last_tx_data = self.tx_data;
4139
4140 return Err(Error::Done);
4141 }
4142
4143 let min_initial_len = self
4144 .client_initial_datagram_size()
4145 .unwrap_or(MIN_CLIENT_INITIAL_LEN);
4146
4147 if has_initial && left > 0 && done < min_initial_len {
4148 let pad_len = cmp::min(left, min_initial_len - done);
4149
4150 // Fill padding area with null bytes, to avoid leaking information
4151 // in case the application reuses the packet buffer.
4152 out[done..done + pad_len].fill(0);
4153
4154 done += pad_len;
4155 }
4156
4157 let send_path = self.paths.get(send_pid)?;
4158
4159 let info = SendInfo {
4160 from: send_path.local_addr(),
4161 to: send_path.peer_addr(),
4162
4163 at: send_path.recovery.get_packet_send_time(now),
4164 };
4165
4166 Ok((done, info))
4167 }
4168
4169 fn send_single(
4170 &mut self,
4171 out: &mut [u8],
4172 send_pid: usize,
4173 has_initial: bool,
4174 now: Instant,
4175 ) -> Result<(Type, usize)> {
4176 if out.is_empty() {
4177 return Err(Error::BufferTooShort);
4178 }
4179
4180 if self.is_draining() {
4181 return Err(Error::Done);
4182 }
4183
4184 let is_closing = self.local_error.is_some();
4185
4186 let out_len = out.len();
4187
4188 let mut b = octets::OctetsMut::with_slice(out);
4189
4190 let pkt_type = self.write_pkt_type(send_pid)?;
4191
4192 let pad_initial = pkt_type == Type::Initial
4193 && !self.is_server
4194 && self.client_initial_datagram_size().is_some()
4195 && self.crypto_ctx[packet::Epoch::Handshake]
4196 .crypto_seal
4197 .is_none();
4198
4199 let max_dgram_len = if !self.dgram_send_queue.is_empty() {
4200 self.dgram_max_writable_len()
4201 } else {
4202 None
4203 };
4204
4205 let epoch = pkt_type.to_epoch()?;
4206 let pkt_space = &mut self.pkt_num_spaces[epoch];
4207 let crypto_ctx = &mut self.crypto_ctx[epoch];
4208
4209 // Process lost frames. There might be several paths having lost frames.
4210 let (paths, path_events) = self.paths.iter_mut_and_events();
4211 for (_, p) in paths {
4212 while let Some(lost) = p.recovery.next_lost_frame(epoch) {
4213 match lost {
4214 frame::Frame::CryptoHeader { offset, length } => {
4215 crypto_ctx.crypto_stream.send.retransmit(offset, length);
4216
4217 self.stream_retrans_bytes += length as u64;
4218 p.stream_retrans_bytes += length as u64;
4219
4220 self.retrans_count += 1;
4221 p.retrans_count += 1;
4222 }
4223
4224 frame::Frame::StreamHeader {
4225 stream_id,
4226 offset,
4227 length,
4228 fin,
4229 } => {
4230 let stream = match self.streams.get_mut(stream_id) {
4231 // Only retransmit data if the stream is not closed
4232 // or stopped.
4233 Some(v) if !v.send.is_stopped() => v,
4234
4235 // Data on a closed stream will not be retransmitted
4236 // or acked after it is declared lost, so just drop
4237 // it.
4238 _ => {
4239 qlog_with_type!(QLOG_DATA_MV, self.qlog, q, {
4240 let ev_data = EventData::QuicStreamDataMoved(
4241 qlog::events::quic::StreamDataMoved {
4242 stream_id: Some(stream_id),
4243 offset: Some(offset),
4244 raw: Some(RawInfo {
4245 length: Some(length as u64),
4246 ..Default::default()
4247 }),
4248 from: Some(DataRecipient::Transport),
4249 to: Some(DataRecipient::Dropped),
4250 ..Default::default()
4251 },
4252 );
4253
4254 q.add_event_data_with_instant(ev_data, now).ok();
4255 });
4256
4257 continue;
4258 }
4259 };
4260
4261 let was_flushable = stream.is_flushable();
4262
4263 let empty_fin = length == 0 && fin;
4264
4265 let retransmitted = stream.send.retransmit(offset, length);
4266
4267 // If the stream is now flushable push it to the
4268 // flushable queue, but only if it wasn't already
4269 // queued.
4270 //
4271 // Consider the stream flushable also when we are
4272 // sending a zero-length frame that has the fin flag
4273 // set.
4274 if (stream.is_flushable() || empty_fin) && !was_flushable {
4275 let priority_key = Arc::clone(&stream.priority_key);
4276 self.streams.insert_flushable(&priority_key);
4277 }
4278
4279 // Update tx_buffered when data is marked for
4280 // retransmission (it was decremented when emitted).
4281 // Only increment by the actual amount retransmitted,
4282 // which may be less than `length` if some data was
4283 // already acked.
4284 self.streams.add_tx_buffered(retransmitted);
4285
4286 self.stream_retrans_bytes += length as u64;
4287 p.stream_retrans_bytes += length as u64;
4288
4289 self.retrans_count += 1;
4290 p.retrans_count += 1;
4291 }
4292
4293 frame::Frame::ACK { .. } => {
4294 pkt_space.ack_elicited = true;
4295 }
4296
4297 frame::Frame::ResetStream {
4298 stream_id,
4299 error_code,
4300 final_size,
4301 } => {
4302 self.streams.insert_reset(stream_id, error_code, final_size);
4303 }
4304
4305 frame::Frame::StopSending {
4306 stream_id,
4307 error_code,
4308 } =>
4309 // We only need to retransmit the STOP_SENDING frame if
4310 // the stream is still active and not FIN'd. Even if the
4311 // packet was lost, if the application has the final
4312 // size at this point there is no need to retransmit.
4313 {
4314 if let Some(stream) = self.streams.get(stream_id) {
4315 if !stream.recv.is_fin() {
4316 self.streams.insert_stopped(stream_id, error_code);
4317 }
4318 }
4319 }
4320
4321 // Retransmit HANDSHAKE_DONE only if it hasn't been acked at
4322 // least once already.
4323 frame::Frame::HandshakeDone => {
4324 if !self.handshake_done_acked {
4325 self.handshake_done_sent = false;
4326 }
4327 }
4328
4329 frame::Frame::MaxStreamData { stream_id, .. } => {
4330 if self.streams.get(stream_id).is_some() {
4331 self.streams.insert_almost_full(stream_id);
4332 }
4333 }
4334
4335 frame::Frame::MaxData { .. } => {
4336 self.should_send_max_data = true;
4337 }
4338
4339 frame::Frame::MaxStreamsUni { .. } => {
4340 self.should_send_max_streams_uni = true;
4341 }
4342
4343 frame::Frame::MaxStreamsBidi { .. } => {
4344 self.should_send_max_streams_bidi = true;
4345 }
4346
4347 // Retransmit STREAMS_BLOCKED frames if the frame with the
4348 // most recent limit is lost. These are informational
4349 // signals to the peer, reliably sending them
4350 // ensures the signal is used consistently and helps
4351 // debugging.
4352 frame::Frame::StreamsBlockedBidi { limit } => {
4353 self.streams_blocked_bidi_state
4354 .force_retransmit_sent_limit_eq(limit);
4355 }
4356
4357 frame::Frame::StreamsBlockedUni { limit } => {
4358 self.streams_blocked_uni_state
4359 .force_retransmit_sent_limit_eq(limit);
4360 }
4361
4362 frame::Frame::NewConnectionId { seq_num, .. } => {
4363 self.ids.mark_advertise_new_scid_seq(seq_num, true);
4364 }
4365
4366 frame::Frame::RetireConnectionId { seq_num } => {
4367 self.ids.mark_retire_dcid_seq(seq_num, true)?;
4368 }
4369
4370 frame::Frame::Ping { mtu_probe } => {
4371 // Ping frames are not retransmitted.
4372 if let Some(failed_probe) = mtu_probe {
4373 trace!("pmtud probe dropped: {failed_probe}");
4374
4375 let local = p.local_addr();
4376 let peer = p.peer_addr();
4377 if let Some(pmtud) = p.pmtud.as_mut() {
4378 let old_pmtu = pmtud.get_current_mtu();
4379 pmtud.failed_probe(failed_probe);
4380 let new_pmtu = pmtud.get_current_mtu();
4381
4382 if let Some(event) =
4383 path::pmtu_event(local, peer, old_pmtu, new_pmtu)
4384 {
4385 p.recovery.pmtud_update_max_datagram_size(new_pmtu);
4386 path_events.push_back(event);
4387 }
4388 }
4389 }
4390 }
4391
4392 // Sent as StreamHeader frames. Stream frames are never
4393 // generated by quiche.
4394 frame::Frame::Stream { .. } => {
4395 debug_panic!(
4396 "Unexpected frame lost: Stream. quiche should \
4397 have tracked retransmittable stream data as \
4398 StreamHeader frames."
4399 );
4400 }
4401
4402 // Sent as CryptoHeader frames. Crypto frames are never
4403 // generated by quiche.
4404 frame::Frame::Crypto { .. } => {
4405 debug_panic!(
4406 "Unexpected frame lost: Crypto. quiche should \
4407 have tracked retransmittable crypto data as \
4408 CryptoHeader frames."
4409 );
4410 }
4411
4412 // NewToken frames are never sent by quiche; they are not
4413 // implemented.
4414 frame::Frame::NewToken { .. } => {
4415 debug_panic!(
4416 "Unexpected frame lost: NewToken. quiche used to \
4417 not implement NewToken frames, retransmission of \
4418 these frames is not implemented."
4419 );
4420 }
4421
4422 // Data blocked frames are an optional advisory
4423 // signal. We choose to not retransmit them to
4424 // avoid unnecessary network usage.
4425 frame::Frame::DataBlocked { .. } | frame::Frame::StreamDataBlocked { .. } => (),
4426
4427 // Path challenge and response have their own
4428 // retry logic. They should not be retransmitted
4429 // normally since according to RFC 9000 Section
4430 // 8.2.2: "An endpoint MUST NOT send more than one
4431 // PATH_RESPONSE frame in response to one
4432 // PATH_CHALLENGE frame".
4433 frame::Frame::PathChallenge { .. } | frame::Frame::PathResponse { .. } => (),
4434
4435 // From RFC 9000 Section 13.3: CONNECTION_CLOSE
4436 // frames, are not sent again when packet loss is
4437 // detected. Resending these signals is described
4438 // in Section 10.
4439 frame::Frame::ConnectionClose { .. }
4440 | frame::Frame::ApplicationClose { .. } => (),
4441
4442 // Padding doesn't require retransmission.
4443 frame::Frame::Padding { .. } => (),
4444
4445 frame::Frame::DatagramHeader { .. } | frame::Frame::Datagram { .. } => {
4446 // Datagrams do not require retransmission. Just update
4447 // stats.
4448 p.dgram_lost_count = p.dgram_lost_count.saturating_add(1);
4449 } // IMPORTANT: Do not add an exhaustive catch
4450 // all. We want to add explicit handling for frame
4451 // types that can be safely ignored when lost.
4452 }
4453 }
4454 }
4455
4456 #[cfg(debug_assertions)]
4457 self.streams.debug_check_tx_buffered_consistency();
4458
4459 let is_app_limited = self.delivery_rate_check_if_app_limited();
4460 let n_paths = self.paths.len();
4461 let path = self.paths.get_mut(send_pid)?;
4462 let flow_control = &mut self.flow_control;
4463 let pkt_space = &mut self.pkt_num_spaces[epoch];
4464 let crypto_ctx = &mut self.crypto_ctx[epoch];
4465 let pkt_num_manager = &mut self.pkt_num_manager;
4466
4467 let mut left = if let Some(pmtud) = path.pmtud.as_mut() {
4468 // Limit output buffer size by estimated path MTU.
4469 cmp::min(pmtud.get_current_mtu(), b.cap())
4470 } else {
4471 b.cap()
4472 };
4473
4474 if pkt_num_manager.should_skip_pn(self.handshake_completed) {
4475 pkt_num_manager.set_skip_pn(Some(self.next_pkt_num));
4476 self.next_pkt_num += 1;
4477 };
4478 let pn = self.next_pkt_num;
4479
4480 let largest_acked_pkt = path.recovery.get_largest_acked_on_epoch(epoch).unwrap_or(0);
4481 let pn_len = packet::pkt_num_len(pn, largest_acked_pkt);
4482
4483 // The AEAD overhead at the current encryption level.
4484 let crypto_overhead = crypto_ctx.crypto_overhead().ok_or(Error::Done)?;
4485
4486 let dcid_seq = path.active_dcid_seq.ok_or(Error::OutOfIdentifiers)?;
4487
4488 let dcid = ConnectionId::from_ref(self.ids.get_dcid(dcid_seq)?.cid.as_ref());
4489
4490 let scid = if let Some(scid_seq) = path.active_scid_seq {
4491 ConnectionId::from_ref(self.ids.get_scid(scid_seq)?.cid.as_ref())
4492 } else if pkt_type == Type::Short {
4493 ConnectionId::default()
4494 } else {
4495 return Err(Error::InvalidState);
4496 };
4497
4498 let hdr = Header {
4499 ty: pkt_type,
4500
4501 version: self.version,
4502
4503 dcid,
4504 scid,
4505
4506 pkt_num: 0,
4507 pkt_num_len: pn_len,
4508
4509 // Only clone token for Initial packets, as other packets don't have
4510 // this field (Retry doesn't count, as it's not encoded as part of
4511 // this code path).
4512 token: if pkt_type == Type::Initial {
4513 self.token.clone()
4514 } else {
4515 None
4516 },
4517
4518 versions: None,
4519 key_phase: self.key_phase,
4520 };
4521
4522 hdr.to_bytes(&mut b)?;
4523
4524 let hdr_trace = if log::max_level() == log::LevelFilter::Trace {
4525 Some(format!("{hdr:?}"))
4526 } else {
4527 None
4528 };
4529
4530 let hdr_ty = hdr.ty;
4531
4532 #[cfg(feature = "qlog")]
4533 let qlog_pkt_hdr = self.qlog.streamer.as_ref().map(|_q| {
4534 qlog::events::quic::PacketHeader::with_type(
4535 hdr.ty.to_qlog(),
4536 Some(pn),
4537 Some(hdr.version),
4538 Some(&hdr.scid),
4539 Some(&hdr.dcid),
4540 )
4541 });
4542
4543 // Calculate the space required for the packet, including the header
4544 // the payload length, the packet number and the AEAD overhead.
4545 let mut overhead = b.off() + pn_len + crypto_overhead;
4546
4547 // We assume that the payload length, which is only present in long
4548 // header packets, can always be encoded with a 2-byte varint.
4549 if pkt_type != Type::Short {
4550 overhead += PAYLOAD_LENGTH_LEN;
4551 }
4552
4553 // Make sure we have enough space left for the packet overhead.
4554 match left.checked_sub(overhead) {
4555 Some(v) => left = v,
4556
4557 None => {
4558 // We can't send more because there isn't enough space available
4559 // in the output buffer.
4560 //
4561 // This usually happens when we try to send a new packet but
4562 // failed because cwnd is almost full. In such case app_limited
4563 // is set to false here to make cwnd grow when ACK is received.
4564 path.recovery.update_app_limited(false);
4565 return Err(Error::Done);
4566 }
4567 }
4568
4569 // Make sure there is enough space for the minimum payload length.
4570 if left < PAYLOAD_MIN_LEN {
4571 path.recovery.update_app_limited(false);
4572 return Err(Error::Done);
4573 }
4574
4575 let mut frames: SmallVec<[frame::Frame; 1]> = SmallVec::new();
4576
4577 let mut ack_eliciting = false;
4578 let mut in_flight = false;
4579 let mut is_pmtud_probe = false;
4580 let mut has_data = false;
4581 let mut stream_data_skipped = false;
4582
4583 // Whether a PING frame must explicitly elicit an ACK when no other
4584 // frame does so implicitly.
4585 let ack_elicit_required = path.recovery.should_elicit_ack(epoch);
4586
4587 let header_offset = b.off();
4588
4589 // Reserve space for payload length in advance. Since we don't yet know
4590 // what the final length will be, we reserve 2 bytes in all cases.
4591 //
4592 // Only long header packets have an explicit length field.
4593 if pkt_type != Type::Short {
4594 b.skip(PAYLOAD_LENGTH_LEN)?;
4595 }
4596
4597 packet::encode_pkt_num(pn, pn_len, &mut b)?;
4598
4599 let payload_offset = b.off();
4600
4601 let cwnd_available = path.recovery.cwnd_available().saturating_sub(overhead);
4602
4603 let left_before_packing_ack_frame = left;
4604
4605 // Create ACK frame.
4606 //
4607 // When we need to explicitly elicit an ACK via PING later, go ahead and
4608 // generate an ACK (if there's anything to ACK) since we're going to
4609 // send a packet with PING anyways, even if we haven't received anything
4610 // ACK eliciting.
4611 if pkt_space.recv_pkt_need_ack.len() > 0
4612 && (pkt_space.ack_elicited || ack_elicit_required)
4613 && (!is_closing
4614 || (pkt_type == Type::Handshake
4615 && self.local_error.as_ref().is_some_and(|le| le.is_app)))
4616 && path.active()
4617 {
4618 #[cfg(not(feature = "fuzzing"))]
4619 let ack_delay = pkt_space.largest_rx_pkt_time.elapsed();
4620
4621 #[cfg(not(feature = "fuzzing"))]
4622 let ack_delay = ack_delay.as_micros() as u64
4623 / 2_u64.pow(self.local_transport_params.ack_delay_exponent as u32);
4624
4625 // pseudo-random reproducible ack delays when fuzzing
4626 #[cfg(feature = "fuzzing")]
4627 let ack_delay = rand::rand_u8() as u64 + 1;
4628
4629 let frame = frame::Frame::ACK {
4630 ack_delay,
4631 ranges: pkt_space.recv_pkt_need_ack.clone(),
4632 ecn_counts: None, // sending ECN is not supported at this time
4633 };
4634
4635 // When a PING frame needs to be sent, avoid sending the ACK if
4636 // there is not enough cwnd available for both (note that PING
4637 // frames are always 1 byte, so we just need to check that the
4638 // ACK's length is lower than cwnd).
4639 if pkt_space.ack_elicited || frame.wire_len() < cwnd_available {
4640 // ACK-only packets are not congestion controlled so ACKs must
4641 // be bundled considering the buffer capacity only, and not the
4642 // available cwnd.
4643 if push_frame_to_pkt!(b, frames, frame, left) {
4644 pkt_space.ack_elicited = false;
4645 }
4646 }
4647 }
4648
4649 // Limit output packet size by congestion window size.
4650 left = cmp::min(
4651 left,
4652 // Bytes consumed by ACK frames.
4653 cwnd_available.saturating_sub(left_before_packing_ack_frame - left),
4654 );
4655
4656 let mut challenge_data = None;
4657
4658 if pkt_type == Type::Short {
4659 // Create PMTUD probe.
4660 //
4661 // A PMTUD probe must ignore `left`, which is already limited by the
4662 // current PMTU. The probe remains limited by the output buffer and
4663 // congestion window.
4664 //
4665 // Generate PMTUD probes only after handshake confirmation to avoid
4666 // interference from anti-amplification limits.
4667 if let Ok(active_path) = self.paths.get_active_mut() {
4668 let should_probe_pmtu = active_path.should_send_pmtu_probe(
4669 self.handshake_confirmed,
4670 self.handshake_completed,
4671 out_len,
4672 is_closing,
4673 frames.is_empty(),
4674 );
4675
4676 if should_probe_pmtu {
4677 if let Some(pmtud) = active_path.pmtud.as_mut() {
4678 let probe_size = pmtud.get_probe_size();
4679 trace!(
4680 "{} sending pmtud probe pmtu_probe={} estimated_pmtu={}",
4681 self.trace_id,
4682 probe_size,
4683 pmtud.get_current_mtu(),
4684 );
4685
4686 left = probe_size;
4687
4688 match left.checked_sub(overhead) {
4689 Some(v) => left = v,
4690
4691 None => {
4692 // We can't send more because there isn't enough
4693 // space available in the output buffer.
4694 //
4695 // The congestion window is nearly full. A new
4696 // packet does not fit.
4697 //
4698 // Clear the app-limited state so ACKs can grow
4699 // the congestion window.
4700 active_path.recovery.update_app_limited(false);
4701 return Err(Error::Done);
4702 }
4703 }
4704
4705 let frame = frame::Frame::Padding {
4706 len: probe_size - overhead - 1,
4707 };
4708
4709 if push_frame_to_pkt!(b, frames, frame, left) {
4710 let frame = frame::Frame::Ping {
4711 mtu_probe: Some(probe_size),
4712 };
4713
4714 if push_frame_to_pkt!(b, frames, frame, left) {
4715 ack_eliciting = true;
4716 in_flight = true;
4717 }
4718 }
4719
4720 // Reset probe flag after sending to prevent duplicate
4721 // probes in a single flight.
4722 pmtud.set_in_flight(true);
4723 is_pmtud_probe = true;
4724 }
4725 }
4726 }
4727
4728 let path = self.paths.get_mut(send_pid)?;
4729 // Create PATH_RESPONSE frame if needed.
4730 // We do not try to ensure that these are really sent.
4731 while let Some(challenge) = path.pop_received_challenge() {
4732 let frame = frame::Frame::PathResponse { data: challenge };
4733
4734 if push_frame_to_pkt!(b, frames, frame, left) {
4735 ack_eliciting = true;
4736 in_flight = true;
4737 } else {
4738 // If there are other pending PATH_RESPONSE, don't lose them
4739 // now.
4740 break;
4741 }
4742 }
4743
4744 // Create PATH_CHALLENGE frame if needed.
4745 if path.validation_requested() {
4746 // TODO: ensure that data is unique over paths.
4747 let data = rand::rand_u64().to_be_bytes();
4748
4749 let frame = frame::Frame::PathChallenge { data };
4750
4751 if push_frame_to_pkt!(b, frames, frame, left) {
4752 // Let's notify the path once we know the packet size.
4753 challenge_data = Some(data);
4754
4755 ack_eliciting = true;
4756 in_flight = true;
4757 }
4758 }
4759
4760 if let Some(key_update) = crypto_ctx.key_update.as_mut() {
4761 key_update.update_acked = true;
4762 }
4763 }
4764
4765 let path = self.paths.get_mut(send_pid)?;
4766
4767 if pkt_type == Type::Short && !is_closing {
4768 // Create NEW_CONNECTION_ID frames as needed.
4769 while let Some(seq_num) = self.ids.next_advertise_new_scid_seq() {
4770 let frame = self.ids.get_new_connection_id_frame_for(seq_num)?;
4771
4772 if push_frame_to_pkt!(b, frames, frame, left) {
4773 self.ids.mark_advertise_new_scid_seq(seq_num, false);
4774
4775 ack_eliciting = true;
4776 in_flight = true;
4777 } else {
4778 break;
4779 }
4780 }
4781 }
4782
4783 if pkt_type == Type::Short && !is_closing && path.active() {
4784 // Create HANDSHAKE_DONE frame.
4785 // self.should_send_handshake_done() but without the need to borrow
4786 if self.handshake_completed && !self.handshake_done_sent && self.is_server {
4787 let frame = frame::Frame::HandshakeDone;
4788
4789 if push_frame_to_pkt!(b, frames, frame, left) {
4790 self.handshake_done_sent = true;
4791
4792 ack_eliciting = true;
4793 in_flight = true;
4794 }
4795 }
4796
4797 // Create MAX_STREAMS_BIDI frame.
4798 if self.streams.should_update_max_streams_bidi() || self.should_send_max_streams_bidi {
4799 let frame = frame::Frame::MaxStreamsBidi {
4800 max: self.streams.max_streams_bidi_next(),
4801 };
4802
4803 if push_frame_to_pkt!(b, frames, frame, left) {
4804 self.streams.update_max_streams_bidi();
4805 self.should_send_max_streams_bidi = false;
4806
4807 ack_eliciting = true;
4808 in_flight = true;
4809 }
4810 }
4811
4812 // Create MAX_STREAMS_UNI frame.
4813 if self.streams.should_update_max_streams_uni() || self.should_send_max_streams_uni {
4814 let frame = frame::Frame::MaxStreamsUni {
4815 max: self.streams.max_streams_uni_next(),
4816 };
4817
4818 if push_frame_to_pkt!(b, frames, frame, left) {
4819 self.streams.update_max_streams_uni();
4820 self.should_send_max_streams_uni = false;
4821
4822 ack_eliciting = true;
4823 in_flight = true;
4824 }
4825 }
4826
4827 // Create DATA_BLOCKED frame.
4828 if let Some(limit) = self.blocked_limit {
4829 let frame = frame::Frame::DataBlocked { limit };
4830
4831 if push_frame_to_pkt!(b, frames, frame, left) {
4832 self.blocked_limit = None;
4833 self.data_blocked_sent_count = self.data_blocked_sent_count.saturating_add(1);
4834
4835 ack_eliciting = true;
4836 in_flight = true;
4837 }
4838 }
4839
4840 // Create STREAMS_BLOCKED (bidi) frame when the local endpoint has
4841 // exhausted the peer's bidirectional stream count limit.
4842 if self
4843 .streams_blocked_bidi_state
4844 .has_pending_stream_blocked_frame()
4845 {
4846 if let Some(limit) = self.streams_blocked_bidi_state.blocked_at {
4847 let frame = frame::Frame::StreamsBlockedBidi { limit };
4848
4849 if push_frame_to_pkt!(b, frames, frame, left) {
4850 // Record the limit we just notified the peer about so
4851 // that redundant frames for the same limit are
4852 // suppressed.
4853 self.streams_blocked_bidi_state.blocked_sent = Some(limit);
4854
4855 ack_eliciting = true;
4856 in_flight = true;
4857 }
4858 }
4859 }
4860
4861 // Create STREAMS_BLOCKED (uni) frame when the local endpoint has
4862 // exhausted the peer's unidirectional stream count limit.
4863 if self
4864 .streams_blocked_uni_state
4865 .has_pending_stream_blocked_frame()
4866 {
4867 if let Some(limit) = self.streams_blocked_uni_state.blocked_at {
4868 let frame = frame::Frame::StreamsBlockedUni { limit };
4869
4870 if push_frame_to_pkt!(b, frames, frame, left) {
4871 // Record the limit we just notified the peer about so
4872 // that redundant frames for the same limit are
4873 // suppressed.
4874 self.streams_blocked_uni_state.blocked_sent = Some(limit);
4875
4876 ack_eliciting = true;
4877 in_flight = true;
4878 }
4879 }
4880 }
4881
4882 // Create MAX_STREAM_DATA frames as needed.
4883 for stream_id in self.streams.almost_full() {
4884 let stream = match self.streams.get_mut(stream_id) {
4885 Some(v) => v,
4886
4887 None => {
4888 // The stream doesn't exist anymore, so remove it from
4889 // the almost full set.
4890 self.streams.remove_almost_full(stream_id);
4891 continue;
4892 }
4893 };
4894
4895 // Autotune the stream window size, but only if this is not a
4896 // retransmission (on a retransmit the stream will be in
4897 // `self.streams.almost_full()` but it's `almost_full()`
4898 // method returns false.
4899 if stream.recv.almost_full() {
4900 stream.recv.autotune_window(now, path.recovery.rtt());
4901 }
4902
4903 let frame = frame::Frame::MaxStreamData {
4904 stream_id,
4905 max: stream.recv.max_data_next(),
4906 };
4907
4908 if push_frame_to_pkt!(b, frames, frame, left) {
4909 let recv_win = stream.recv.window();
4910
4911 stream.recv.update_max_data(now);
4912
4913 self.streams.remove_almost_full(stream_id);
4914
4915 ack_eliciting = true;
4916 in_flight = true;
4917
4918 // Make sure the connection window always has some
4919 // room compared to the stream window.
4920 flow_control.ensure_window_lower_bound(
4921 (recv_win as f64 * CONNECTION_WINDOW_FACTOR) as u64,
4922 );
4923 }
4924 }
4925
4926 // Create MAX_DATA frame as needed.
4927 if flow_control.should_update_max_data()
4928 && flow_control.max_data() < flow_control.max_data_next()
4929 {
4930 // Autotune the connection window size. We only tune the window
4931 // if we are sending an "organic" update, not on retransmits.
4932 flow_control.autotune_window(now, path.recovery.rtt());
4933 self.should_send_max_data = true;
4934 }
4935
4936 if self.should_send_max_data {
4937 let frame = frame::Frame::MaxData {
4938 max: flow_control.max_data_next(),
4939 };
4940
4941 if push_frame_to_pkt!(b, frames, frame, left) {
4942 self.should_send_max_data = false;
4943
4944 // Commits the new max_rx_data limit.
4945 flow_control.update_max_data(now);
4946
4947 ack_eliciting = true;
4948 in_flight = true;
4949 }
4950 }
4951
4952 // Create STOP_SENDING frames as needed.
4953 for (stream_id, error_code) in self
4954 .streams
4955 .stopped()
4956 .map(|(&k, &v)| (k, v))
4957 .collect::<Vec<(u64, u64)>>()
4958 {
4959 let frame = frame::Frame::StopSending {
4960 stream_id,
4961 error_code,
4962 };
4963
4964 if push_frame_to_pkt!(b, frames, frame, left) {
4965 self.streams.remove_stopped(stream_id);
4966
4967 ack_eliciting = true;
4968 in_flight = true;
4969 }
4970 }
4971
4972 // Create RESET_STREAM frames as needed.
4973 for (stream_id, (error_code, final_size)) in self
4974 .streams
4975 .reset()
4976 .map(|(&k, &v)| (k, v))
4977 .collect::<Vec<(u64, (u64, u64))>>()
4978 {
4979 let frame = frame::Frame::ResetStream {
4980 stream_id,
4981 error_code,
4982 final_size,
4983 };
4984
4985 if push_frame_to_pkt!(b, frames, frame, left) {
4986 self.streams.remove_reset(stream_id);
4987
4988 ack_eliciting = true;
4989 in_flight = true;
4990 }
4991 }
4992
4993 // Create STREAM_DATA_BLOCKED frames as needed.
4994 for (stream_id, limit) in self
4995 .streams
4996 .blocked()
4997 .map(|(&k, &v)| (k, v))
4998 .collect::<Vec<(u64, u64)>>()
4999 {
5000 let frame = frame::Frame::StreamDataBlocked { stream_id, limit };
5001
5002 if push_frame_to_pkt!(b, frames, frame, left) {
5003 self.streams.remove_blocked(stream_id);
5004 self.stream_data_blocked_sent_count =
5005 self.stream_data_blocked_sent_count.saturating_add(1);
5006
5007 ack_eliciting = true;
5008 in_flight = true;
5009 }
5010 }
5011
5012 // Create RETIRE_CONNECTION_ID frames as needed.
5013 let retire_dcid_seqs = self.ids.retire_dcid_seqs();
5014
5015 for seq_num in retire_dcid_seqs {
5016 // The sequence number specified in a RETIRE_CONNECTION_ID frame
5017 // MUST NOT refer to the Destination Connection ID field of the
5018 // packet in which the frame is contained.
5019 let dcid_seq = path.active_dcid_seq.ok_or(Error::InvalidState)?;
5020
5021 if seq_num == dcid_seq {
5022 continue;
5023 }
5024
5025 let frame = frame::Frame::RetireConnectionId { seq_num };
5026
5027 if push_frame_to_pkt!(b, frames, frame, left) {
5028 self.ids.mark_retire_dcid_seq(seq_num, false)?;
5029
5030 ack_eliciting = true;
5031 in_flight = true;
5032 } else {
5033 break;
5034 }
5035 }
5036 }
5037
5038 // Create CONNECTION_CLOSE frame. Try to send this only on the active
5039 // path, unless it is the last one available.
5040 if path.active() || n_paths == 1 {
5041 if let Some(conn_err) = self.local_error.as_ref() {
5042 if conn_err.is_app {
5043 // Create ApplicationClose frame.
5044 if pkt_type == Type::Short {
5045 let frame = frame::Frame::ApplicationClose {
5046 error_code: conn_err.error_code,
5047 reason: conn_err.reason.clone(),
5048 };
5049
5050 if push_frame_to_pkt!(b, frames, frame, left) {
5051 let pto = path.recovery.pto();
5052 self.draining_timer = Some(now + (pto * 3));
5053
5054 ack_eliciting = true;
5055 in_flight = true;
5056 }
5057 }
5058 } else {
5059 // Create ConnectionClose frame.
5060 let frame = frame::Frame::ConnectionClose {
5061 error_code: conn_err.error_code,
5062 frame_type: 0,
5063 reason: conn_err.reason.clone(),
5064 };
5065
5066 if push_frame_to_pkt!(b, frames, frame, left) {
5067 let pto = path.recovery.pto();
5068 self.draining_timer = Some(now + (pto * 3));
5069
5070 ack_eliciting = true;
5071 in_flight = true;
5072 }
5073 }
5074 }
5075 }
5076
5077 // Create CRYPTO frame.
5078 let split_first_flight = !self.is_server
5079 && epoch == packet::Epoch::Initial
5080 && self.initial_crypto_split != InitialCryptoSplit::Fill
5081 && !self.initial_crypto_split_sent
5082 && crypto_ctx.crypto_stream.send.off_front() == 0;
5083
5084 if split_first_flight
5085 && crypto_ctx.crypto_stream.is_flushable()
5086 && left > 2 * frame::MAX_CRYPTO_OVERHEAD
5087 && !is_closing
5088 && path.active()
5089 {
5090 let send = &mut crypto_ctx.crypto_stream.send;
5091 let mut hello = vec![0; send.off_back() as usize];
5092 let (len, _) = send.emit(&mut hello)?;
5093 hello.truncate(len);
5094
5095 let chunks = crypto_split::first_packet_chunks(
5096 self.initial_crypto_split,
5097 &hello,
5098 left - 2 * frame::MAX_CRYPTO_OVERHEAD,
5099 );
5100
5101 for gap in crypto_split::unsent(&chunks, hello.len()) {
5102 send.retransmit(gap.start as u64, gap.len());
5103 }
5104
5105 for chunk in chunks {
5106 let offset = chunk.start as u64;
5107 frame::encode_crypto_header(offset, chunk.len() as u64, &mut b)?;
5108 b.put_bytes(&hello[chunk.clone()])?;
5109
5110 let frame = frame::Frame::CryptoHeader {
5111 offset,
5112 length: chunk.len(),
5113 };
5114
5115 if push_frame_to_pkt!(b, frames, frame, left) {
5116 ack_eliciting = true;
5117 in_flight = true;
5118 has_data = true;
5119 }
5120 }
5121
5122 self.initial_crypto_split_sent = true;
5123 } else if crypto_ctx.crypto_stream.is_flushable()
5124 && left > frame::MAX_CRYPTO_OVERHEAD
5125 && !is_closing
5126 && path.active()
5127 {
5128 let crypto_off = crypto_ctx.crypto_stream.send.off_front();
5129
5130 // Encode the frame.
5131 //
5132 // Instead of creating a `frame::Frame` object, encode the frame
5133 // directly into the packet buffer.
5134 //
5135 // First we reserve some space in the output buffer for writing the
5136 // frame header (we assume the length field is always a 2-byte
5137 // varint as we don't know the value yet).
5138 //
5139 // Then we emit the data from the crypto stream's send buffer.
5140 //
5141 // Finally we go back and encode the frame header with the now
5142 // available information.
5143 let hdr_off = b.off();
5144 let hdr_len = 1 + // frame type
5145 octets::varint_len(crypto_off) + // offset
5146 2; // length, always encode as 2-byte varint
5147
5148 if let Some(max_len) = left.checked_sub(hdr_len) {
5149 let (mut crypto_hdr, mut crypto_payload) = b.split_at(hdr_off + hdr_len)?;
5150
5151 // Write stream data into the packet buffer.
5152 let (len, _) = crypto_ctx
5153 .crypto_stream
5154 .send
5155 .emit(&mut crypto_payload.as_mut()[..max_len])?;
5156
5157 // Encode the frame's header.
5158 //
5159 // Due to how `OctetsMut::split_at()` works, `crypto_hdr` starts
5160 // from the initial offset of `b` (rather than the current
5161 // offset), so it needs to be advanced to the
5162 // initial frame offset.
5163 crypto_hdr.skip(hdr_off)?;
5164
5165 frame::encode_crypto_header(crypto_off, len as u64, &mut crypto_hdr)?;
5166
5167 // Advance the packet buffer's offset.
5168 b.skip(hdr_len + len)?;
5169
5170 let frame = frame::Frame::CryptoHeader {
5171 offset: crypto_off,
5172 length: len,
5173 };
5174
5175 if push_frame_to_pkt!(b, frames, frame, left) {
5176 ack_eliciting = true;
5177 in_flight = true;
5178 has_data = true;
5179 }
5180 }
5181 }
5182
5183 // The preference of data-bearing frame to include in a packet
5184 // is managed by `self.emit_dgram`. However, whether any frames
5185 // can be sent depends on the state of their buffers. In the case
5186 // where one type is preferred but its buffer is empty, fall back
5187 // to the other type in order not to waste this function call.
5188 let mut dgram_emitted = false;
5189 let dgrams_to_emit = max_dgram_len.is_some();
5190 let stream_to_emit = self.streams.has_flushable();
5191
5192 let mut do_dgram = self.emit_dgram && dgrams_to_emit;
5193 let do_stream = !self.emit_dgram && stream_to_emit;
5194
5195 if !do_stream && dgrams_to_emit {
5196 do_dgram = true;
5197 }
5198
5199 // Create DATAGRAM frame.
5200 if (pkt_type == Type::Short || pkt_type == Type::ZeroRTT)
5201 && left > frame::MAX_DGRAM_OVERHEAD
5202 && !is_closing
5203 && path.active()
5204 && do_dgram
5205 {
5206 if let Some(max_dgram_payload) = max_dgram_len {
5207 while let Some(len) = self.dgram_send_queue.peek_front_len() {
5208 let hdr_off = b.off();
5209 let hdr_len = 1 + // frame type
5210 2; // length, always encode as 2-byte varint
5211
5212 if (hdr_len + len) <= left {
5213 // Front of the queue fits this packet, send it.
5214 match self.dgram_send_queue.pop() {
5215 Some(data) => {
5216 // Encode the frame.
5217 //
5218 // Instead of creating a `frame::Frame` object,
5219 // encode the frame directly into the packet
5220 // buffer.
5221 //
5222 // First we reserve some space in the output
5223 // buffer for writing the frame header (we
5224 // assume the length field is always a 2-byte
5225 // varint as we don't know the value yet).
5226 //
5227 // Then we emit the data from the DATAGRAM's
5228 // buffer.
5229 //
5230 // Finally we go back and encode the frame
5231 // header with the now available information.
5232 let (mut dgram_hdr, mut dgram_payload) =
5233 b.split_at(hdr_off + hdr_len)?;
5234
5235 dgram_payload.as_mut()[..len].copy_from_slice(data.as_ref());
5236
5237 // Encode the frame's header.
5238 //
5239 // Due to how `OctetsMut::split_at()` works,
5240 // `dgram_hdr` starts from the initial offset
5241 // of `b` (rather than the current offset), so
5242 // it needs to be advanced to the initial frame
5243 // offset.
5244 dgram_hdr.skip(hdr_off)?;
5245
5246 frame::encode_dgram_header(len as u64, &mut dgram_hdr)?;
5247
5248 // Advance the packet buffer's offset.
5249 b.skip(hdr_len + len)?;
5250
5251 let frame = frame::Frame::DatagramHeader { length: len };
5252
5253 if push_frame_to_pkt!(b, frames, frame, left) {
5254 ack_eliciting = true;
5255 in_flight = true;
5256 dgram_emitted = true;
5257 self.dgram_sent_count = self.dgram_sent_count.saturating_add(1);
5258 path.dgram_sent_count = path.dgram_sent_count.saturating_add(1);
5259 }
5260 }
5261
5262 None => continue,
5263 };
5264 } else if len > max_dgram_payload {
5265 // This dgram frame will never fit. Let's purge it.
5266 self.dgram_send_queue.pop();
5267 } else {
5268 break;
5269 }
5270 }
5271 }
5272 }
5273
5274 // Create a single STREAM frame for the first stream that is flushable.
5275 if (pkt_type == Type::Short || pkt_type == Type::ZeroRTT)
5276 && left > frame::MAX_STREAM_OVERHEAD
5277 && !is_closing
5278 && path.active()
5279 && !dgram_emitted
5280 {
5281 while let Some(priority_key) = self.streams.peek_flushable() {
5282 let stream_id = priority_key.id;
5283 let stream = match self.streams.get_mut(stream_id) {
5284 // Avoid sending frames for streams that were already stopped.
5285 //
5286 // This might happen if stream data was buffered but not yet
5287 // flushed on the wire when a STOP_SENDING frame is received.
5288 Some(v) if !v.send.is_stopped() => v,
5289 _ => {
5290 self.streams.remove_flushable(&priority_key);
5291 continue;
5292 }
5293 };
5294
5295 let stream_off = stream.send.off_front();
5296
5297 // Encode the frame.
5298 //
5299 // Instead of creating a `frame::Frame` object, encode the frame
5300 // directly into the packet buffer.
5301 //
5302 // First we reserve some space in the output buffer for writing
5303 // the frame header (we assume the length field is always a
5304 // 2-byte varint as we don't know the value yet).
5305 //
5306 // Then we emit the data from the stream's send buffer.
5307 //
5308 // Finally we go back and encode the frame header with the now
5309 // available information.
5310 let hdr_off = b.off();
5311 let hdr_len = 1 + // frame type
5312 octets::varint_len(stream_id) + // stream_id
5313 octets::varint_len(stream_off) + // offset
5314 2; // length, always encode as 2-byte varint
5315
5316 let max_len = match left.checked_sub(hdr_len) {
5317 Some(v) => v,
5318 None => {
5319 let priority_key = Arc::clone(&stream.priority_key);
5320 self.streams.remove_flushable(&priority_key);
5321
5322 continue;
5323 }
5324 };
5325
5326 let (mut stream_hdr, mut stream_payload) = b.split_at(hdr_off + hdr_len)?;
5327
5328 // Write stream data into the packet buffer.
5329 let (len, fin) = stream.send.emit(&mut stream_payload.as_mut()[..max_len])?;
5330
5331 // Don't emit an empty non-fin STREAM frame when only its
5332 // header fits: it would carry no data but still advance the
5333 // peer's largest received offset.
5334 if len == 0 && !fin {
5335 stream_data_skipped = true;
5336
5337 // Rotate incremental streams so a stream whose header
5338 // doesn't leave room for data doesn't block the others.
5339 if stream.incremental {
5340 let priority_key = Arc::clone(&stream.priority_key);
5341 self.streams.remove_flushable(&priority_key);
5342 self.streams.insert_flushable(&priority_key);
5343 }
5344
5345 break;
5346 }
5347
5348 // Encode the frame's header.
5349 //
5350 // Due to how `OctetsMut::split_at()` works, `stream_hdr` starts
5351 // from the initial offset of `b` (rather than the current
5352 // offset), so it needs to be advanced to the initial frame
5353 // offset.
5354 stream_hdr.skip(hdr_off)?;
5355
5356 frame::encode_stream_header(
5357 stream_id,
5358 stream_off,
5359 len as u64,
5360 fin,
5361 &mut stream_hdr,
5362 )?;
5363
5364 // Advance the packet buffer's offset.
5365 b.skip(hdr_len + len)?;
5366
5367 let frame = frame::Frame::StreamHeader {
5368 stream_id,
5369 offset: stream_off,
5370 length: len,
5371 fin,
5372 };
5373
5374 if push_frame_to_pkt!(b, frames, frame, left) {
5375 ack_eliciting = true;
5376 in_flight = true;
5377 has_data = true;
5378 }
5379
5380 let priority_key = Arc::clone(&stream.priority_key);
5381 // Remove the stream when it is no longer flushable.
5382 if !stream.is_flushable() {
5383 self.streams.remove_flushable(&priority_key);
5384 } else if stream.incremental {
5385 // Shuffle the incremental stream to the back of the
5386 // queue.
5387 self.streams.remove_flushable(&priority_key);
5388 self.streams.insert_flushable(&priority_key);
5389 }
5390
5391 // Update tx_buffered when data is emitted.
5392 self.streams.sub_tx_buffered(len);
5393
5394 #[cfg(feature = "fuzzing")]
5395 // Coalesce STREAM frames when fuzzing.
5396 if left > frame::MAX_STREAM_OVERHEAD {
5397 continue;
5398 }
5399
5400 break;
5401 }
5402 }
5403
5404 // Alternate trying to send DATAGRAMs next time.
5405 self.emit_dgram = !dgram_emitted;
5406
5407 // If no other ack-eliciting frame is sent, include a PING frame
5408 // - if PTO probe needed; OR
5409 // - if we've sent too many non ack-eliciting packets without having
5410 // sent an ACK eliciting one; OR
5411 // - the application requested an ack-eliciting frame be sent.
5412 if (ack_elicit_required || path.needs_ack_eliciting)
5413 && !ack_eliciting
5414 && left >= 1
5415 && !is_closing
5416 {
5417 let frame = frame::Frame::Ping { mtu_probe: None };
5418
5419 if push_frame_to_pkt!(b, frames, frame, left) {
5420 ack_eliciting = true;
5421 in_flight = true;
5422 }
5423 }
5424
5425 if ack_eliciting && !is_pmtud_probe {
5426 path.needs_ack_eliciting = false;
5427 path.recovery.ping_sent(epoch);
5428 }
5429
5430 // Pending stream data means the sender is size-, not app-limited.
5431 if !has_data
5432 && !stream_data_skipped
5433 && !dgram_emitted
5434 && cwnd_available > frame::MAX_STREAM_OVERHEAD
5435 {
5436 path.recovery.on_app_limited();
5437 }
5438
5439 if frames.is_empty() {
5440 // When we reach this point we are not able to write more, so set
5441 // app_limited to false.
5442 path.recovery.update_app_limited(false);
5443 return Err(Error::Done);
5444 }
5445
5446 // When coalescing a 1-RTT packet, we can't add padding in the UDP
5447 // datagram, so use PADDING frames instead.
5448 //
5449 // This is only needed if
5450 // 1) an Initial packet has already been written to the UDP datagram,
5451 // as Initial always requires padding.
5452 //
5453 // 2) this is a probing packet towards an unvalidated peer address.
5454 if (((has_initial || !path.validated()) && pkt_type == Type::Short) || pad_initial)
5455 && left >= 1
5456 {
5457 let frame = frame::Frame::Padding { len: left };
5458
5459 if push_frame_to_pkt!(b, frames, frame, left) {
5460 in_flight = true;
5461 }
5462 }
5463
5464 // Pad payload so that it's always at least 4 bytes.
5465 if b.off() - payload_offset < PAYLOAD_MIN_LEN {
5466 let payload_len = b.off() - payload_offset;
5467
5468 let frame = frame::Frame::Padding {
5469 len: PAYLOAD_MIN_LEN - payload_len,
5470 };
5471
5472 #[allow(unused_assignments)]
5473 if push_frame_to_pkt!(b, frames, frame, left) {
5474 in_flight = true;
5475 }
5476 }
5477
5478 let payload_len = b.off() - payload_offset;
5479
5480 // Fill in payload length.
5481 if pkt_type != Type::Short {
5482 let len = pn_len + payload_len + crypto_overhead;
5483
5484 let (_, mut payload_with_len) = b.split_at(header_offset)?;
5485 payload_with_len.put_varint_with_len(len as u64, PAYLOAD_LENGTH_LEN)?;
5486 }
5487
5488 trace!(
5489 "{} tx pkt {} len={} pn={} {}",
5490 self.trace_id,
5491 hdr_trace.unwrap_or_default(),
5492 payload_len,
5493 pn,
5494 AddrTupleFmt(path.local_addr(), path.peer_addr())
5495 );
5496
5497 #[cfg(feature = "qlog")]
5498 let mut qlog_frames: Vec<qlog::events::quic::QuicFrame> = Vec::with_capacity(frames.len());
5499
5500 for frame in &mut frames {
5501 trace!("{} tx frm {:?}", self.trace_id, frame);
5502
5503 qlog_with_type!(QLOG_PACKET_TX, self.qlog, _q, {
5504 qlog_frames.push(frame.to_qlog());
5505 });
5506 }
5507
5508 qlog_with_type!(QLOG_PACKET_TX, self.qlog, q, {
5509 if let Some(header) = qlog_pkt_hdr {
5510 // Qlog packet raw info described at
5511 // https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-main-schema-00#section-5.1
5512 //
5513 // `length` includes packet headers and trailers (AEAD tag).
5514 let length = payload_len + payload_offset + crypto_overhead;
5515 let qlog_raw_info = RawInfo {
5516 length: Some(length as u64),
5517 payload_length: Some(payload_len as u64),
5518 data: None,
5519 };
5520
5521 let send_at_time = now.duration_since(q.start_time()).as_secs_f64() * 1000.0;
5522
5523 let ev_data = EventData::QuicPacketSent(qlog::events::quic::PacketSent {
5524 header,
5525 frames: Some(qlog_frames),
5526 raw: Some(qlog_raw_info),
5527 send_at_time: Some(send_at_time),
5528 ..Default::default()
5529 });
5530
5531 q.add_event_data_with_instant(ev_data, now).ok();
5532 }
5533 });
5534
5535 let aead = match crypto_ctx.crypto_seal {
5536 Some(ref mut v) => v,
5537 None => return Err(Error::InvalidState),
5538 };
5539
5540 let written =
5541 packet::encrypt_pkt(&mut b, pn, pn_len, payload_len, payload_offset, None, aead)?;
5542
5543 let sent_pkt_has_data = if path.recovery.gcongestion_enabled() {
5544 has_data || dgram_emitted
5545 } else {
5546 has_data
5547 };
5548
5549 let sent_pkt = recovery::Sent {
5550 pkt_num: pn,
5551 frames,
5552 time_sent: now,
5553 time_acked: None,
5554 time_lost: None,
5555 size: if ack_eliciting { written } else { 0 },
5556 ack_eliciting,
5557 in_flight,
5558 delivered: 0,
5559 delivered_time: now,
5560 first_sent_time: now,
5561 is_app_limited: false,
5562 tx_in_flight: 0,
5563 lost: 0,
5564 has_data: sent_pkt_has_data,
5565 is_pmtud_probe,
5566 };
5567
5568 if in_flight && is_app_limited {
5569 path.recovery.delivery_rate_update_app_limited(true);
5570 }
5571
5572 self.next_pkt_num += 1;
5573
5574 let handshake_status = recovery::HandshakeStatus {
5575 has_handshake_keys: self.crypto_ctx[packet::Epoch::Handshake].has_keys(),
5576 peer_verified_address: self.peer_verified_initial_address,
5577 completed: self.handshake_completed,
5578 };
5579
5580 self.on_packet_sent(send_pid, sent_pkt, epoch, handshake_status, now)?;
5581
5582 let path = self.paths.get_mut(send_pid)?;
5583 qlog_with_type!(QLOG_METRICS, self.qlog, q, {
5584 path.recovery.maybe_qlog(q, now);
5585 });
5586
5587 // Record sent packet size if we probe the path.
5588 if let Some(data) = challenge_data {
5589 path.add_challenge_sent(data, written, now);
5590 }
5591
5592 self.sent_count += 1;
5593 self.sent_bytes += written as u64;
5594 path.sent_count += 1;
5595 path.sent_bytes += written as u64;
5596
5597 if self.dgram_send_queue.byte_size() > path.recovery.cwnd_available() {
5598 path.recovery.update_app_limited(false);
5599 }
5600
5601 let had_send_budget = path.max_send_bytes > 0;
5602 path.max_send_bytes = path.max_send_bytes.saturating_sub(written);
5603 if self.is_server
5604 && !path.verified_peer_address
5605 && had_send_budget
5606 && path.max_send_bytes == 0
5607 {
5608 self.amplification_limited_count = self.amplification_limited_count.saturating_add(1);
5609 }
5610
5611 // On the client, drop initial state after sending an Handshake packet.
5612 if !self.is_server && hdr_ty == Type::Handshake {
5613 self.drop_epoch_state(packet::Epoch::Initial, now);
5614 }
5615
5616 // (Re)start the idle timer if we are sending the first ack-eliciting
5617 // packet since last receiving a packet.
5618 if ack_eliciting && !self.ack_eliciting_sent {
5619 if let Some(idle_timeout) = self.idle_timeout() {
5620 self.idle_timer = Some(now + idle_timeout);
5621 }
5622 }
5623
5624 if ack_eliciting {
5625 self.ack_eliciting_sent = true;
5626 }
5627
5628 Ok((pkt_type, written))
5629 }
5630
5631 fn on_packet_sent(
5632 &mut self,
5633 send_pid: usize,
5634 sent_pkt: recovery::Sent,
5635 epoch: packet::Epoch,
5636 handshake_status: recovery::HandshakeStatus,
5637 now: Instant,
5638 ) -> Result<()> {
5639 let path = self.paths.get_mut(send_pid)?;
5640
5641 // The skip counter may use values from an inactive path.
5642 let cwnd = path.recovery.cwnd();
5643 let max_datagram_size = path.recovery.max_datagram_size();
5644 self.pkt_num_spaces[epoch].on_packet_sent(&sent_pkt);
5645 self.pkt_num_manager
5646 .on_packet_sent(cwnd, max_datagram_size, self.handshake_completed);
5647
5648 path.recovery
5649 .on_packet_sent(sent_pkt, epoch, handshake_status, now, &self.trace_id);
5650
5651 Ok(())
5652 }
5653
5654 /// Returns the desired send time for the next packet.
5655 #[inline]
5656 pub fn get_next_release_time(&self) -> Option<ReleaseDecision> {
5657 Some(
5658 self.paths
5659 .get_active()
5660 .ok()?
5661 .recovery
5662 .get_next_release_time(),
5663 )
5664 }
5665
5666 /// Returns whether gcongestion is enabled.
5667 #[inline]
5668 pub fn gcongestion_enabled(&self) -> Option<bool> {
5669 Some(self.paths.get_active().ok()?.recovery.gcongestion_enabled())
5670 }
5671
5672 /// Returns the maximum pacing into the future.
5673 ///
5674 /// Equals 1/8 of the smoothed RTT, but at least 1ms and not greater than
5675 /// 5ms.
5676 pub fn max_release_into_future(&self) -> Duration {
5677 self.paths
5678 .get_active()
5679 .map(|p| p.recovery.rtt().mul_f64(0.125))
5680 .unwrap_or(Duration::from_millis(1))
5681 .max(Duration::from_millis(1))
5682 .min(Duration::from_millis(5))
5683 }
5684
5685 /// Returns whether pacing is enabled.
5686 #[inline]
5687 pub fn pacing_enabled(&self) -> bool {
5688 self.recovery_config.pacing
5689 }
5690
5691 /// Returns the size of the send quantum, in bytes.
5692 ///
5693 /// This represents the maximum size of a packet burst as determined by the
5694 /// congestion control algorithm in use.
5695 ///
5696 /// Applications can, for example, use it in conjunction with segmentation
5697 /// offloading mechanisms as the maximum limit for outgoing aggregates of
5698 /// multiple packets.
5699 #[inline]
5700 pub fn send_quantum(&self) -> usize {
5701 match self.paths.get_active() {
5702 Ok(p) => p.recovery.send_quantum(),
5703 _ => 0,
5704 }
5705 }
5706
5707 /// Returns the size of the send quantum over the given 4-tuple, in bytes.
5708 ///
5709 /// This represents the maximum size of a packet burst as determined by the
5710 /// congestion control algorithm in use.
5711 ///
5712 /// Applications can, for example, use it in conjunction with segmentation
5713 /// offloading mechanisms as the maximum limit for outgoing aggregates of
5714 /// multiple packets.
5715 ///
5716 /// If the (`local_addr`, peer_addr`) 4-tuple relates to a non-existing
5717 /// path, this method returns 0.
5718 pub fn send_quantum_on_path(&self, local_addr: SocketAddr, peer_addr: SocketAddr) -> usize {
5719 self.paths
5720 .path_id_from_addrs(&(local_addr, peer_addr))
5721 .and_then(|pid| self.paths.get(pid).ok())
5722 .map(|path| path.recovery.send_quantum())
5723 .unwrap_or(0)
5724 }
5725
5726 /// Reads contiguous data from a stream into the provided slice.
5727 ///
5728 /// The slice must be sized by the caller and will be populated up to its
5729 /// capacity.
5730 ///
5731 /// On success the amount of bytes read and a flag indicating the fin state
5732 /// is returned as a tuple, or [`Done`] if there is no data to read.
5733 ///
5734 /// Reading data from a stream may trigger queueing of control messages
5735 /// (e.g. MAX_STREAM_DATA). [`send()`] should be called afterwards.
5736 ///
5737 /// [`Done`]: enum.Error.html#variant.Done
5738 /// [`send()`]: struct.Connection.html#method.send
5739 ///
5740 /// ## Examples:
5741 ///
5742 /// ```no_run
5743 /// # let mut buf = [0; 512];
5744 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
5745 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
5746 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
5747 /// # let peer = "127.0.0.1:1234".parse().unwrap();
5748 /// # let local = socket.local_addr().unwrap();
5749 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
5750 /// # let stream_id = 0;
5751 /// while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
5752 /// println!("Got {} bytes on stream {}", read, stream_id);
5753 /// }
5754 /// # Ok::<(), quiche::Error>(())
5755 /// ```
5756 #[inline]
5757 pub fn stream_recv(&mut self, stream_id: u64, out: &mut [u8]) -> Result<(usize, bool)> {
5758 self.stream_recv_buf(stream_id, out)
5759 }
5760
5761 /// Reads contiguous data from a stream into the provided [`bytes::BufMut`].
5762 ///
5763 /// **NOTE**:
5764 /// The BufMut will be populated with all available data up to its capacity.
5765 /// Since some BufMut implementations, e.g., [`Vec<u8>`], dynamically
5766 /// allocate additional memory, the caller may use [`BufMut::limit()`]
5767 /// to limit the maximum amount of data that can be written.
5768 ///
5769 /// On success the amount of bytes read and a flag indicating the fin state
5770 /// is returned as a tuple, or [`Done`] if there is no data to read.
5771 /// [`BufMut::advance_mut()`] will have been called with the same number of
5772 /// total bytes.
5773 ///
5774 /// Reading data from a stream may trigger queueing of control messages
5775 /// (e.g. MAX_STREAM_DATA). [`send()`] should be called afterwards.
5776 ///
5777 /// [`BufMut::limit()`]: bytes::BufMut::limit
5778 /// [`BufMut::advance_mut()`]: bytes::BufMut::advance_mut
5779 /// [`Done`]: enum.Error.html#variant.Done
5780 /// [`send()`]: struct.Connection.html#method.send
5781 ///
5782 /// ## Examples:
5783 ///
5784 /// ```no_run
5785 /// # use bytes::BufMut as _;
5786 /// # let mut buf = Vec::new().limit(1024); // Read at most 1024 bytes
5787 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
5788 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
5789 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
5790 /// # let peer = "127.0.0.1:1234".parse().unwrap();
5791 /// # let local = socket.local_addr().unwrap();
5792 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
5793 /// # let stream_id = 0;
5794 /// # let mut total_read = 0;
5795 /// while let Ok((read, fin)) = conn.stream_recv_buf(stream_id, &mut buf) {
5796 /// println!("Got {} bytes on stream {}", read, stream_id);
5797 /// total_read += read;
5798 /// assert_eq!(buf.get_ref().len(), total_read);
5799 /// }
5800 /// # Ok::<(), quiche::Error>(())
5801 /// ```
5802 pub fn stream_recv_buf<B: bytes::BufMut>(
5803 &mut self,
5804 stream_id: u64,
5805 out: B,
5806 ) -> Result<(usize, bool)> {
5807 self.do_stream_recv(stream_id, RecvAction::Emit { out })
5808 }
5809
5810 /// Discard contiguous data from a stream without copying.
5811 ///
5812 /// On success the amount of bytes discarded and a flag indicating the fin
5813 /// state is returned as a tuple, or [`Done`] if there is no data to
5814 /// discard.
5815 ///
5816 /// Discarding data from a stream may trigger queueing of control messages
5817 /// (e.g. MAX_STREAM_DATA). [`send()`] should be called afterwards.
5818 ///
5819 /// [`Done`]: enum.Error.html#variant.Done
5820 /// [`send()`]: struct.Connection.html#method.send
5821 ///
5822 /// ## Examples:
5823 ///
5824 /// ```no_run
5825 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
5826 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
5827 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
5828 /// # let peer = "127.0.0.1:1234".parse().unwrap();
5829 /// # let local = socket.local_addr().unwrap();
5830 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
5831 /// # let stream_id = 0;
5832 /// while let Ok((read, fin)) = conn.stream_discard(stream_id, 1) {
5833 /// println!("Discarded {} byte(s) on stream {}", read, stream_id);
5834 /// }
5835 /// # Ok::<(), quiche::Error>(())
5836 /// ```
5837 pub fn stream_discard(&mut self, stream_id: u64, len: usize) -> Result<(usize, bool)> {
5838 // `do_stream_recv()` is generic on the kind of `BufMut` in RecvAction.
5839 // Since we are discarding, it doesn't matter, but the compiler still
5840 // wants to know, so we say `&mut [u8]`.
5841 self.do_stream_recv::<&mut [u8]>(stream_id, RecvAction::Discard { len })
5842 }
5843
5844 // Reads or discards contiguous data from a stream.
5845 //
5846 // Passing an `action` of `StreamRecvAction::Emit` results in a read into
5847 // the provided slice. It must be sized by the caller and will be populated
5848 // up to its capacity.
5849 //
5850 // Passing an `action` of `StreamRecvAction::Discard` results in discard up
5851 // to the indicated length.
5852 //
5853 // On success the amount of bytes read or discarded, and a flag indicating
5854 // the fin state, is returned as a tuple, or [`Done`] if there is no data to
5855 // read or discard.
5856 //
5857 // Reading or discarding data from a stream may trigger queueing of control
5858 // messages (e.g. MAX_STREAM_DATA). [`send()`] should be called afterwards.
5859 //
5860 // [`Done`]: enum.Error.html#variant.Done
5861 // [`send()`]: struct.Connection.html#method.send
5862 fn do_stream_recv<B: bytes::BufMut>(
5863 &mut self,
5864 stream_id: u64,
5865 action: RecvAction<B>,
5866 ) -> Result<(usize, bool)> {
5867 // We can't read on our own unidirectional streams.
5868 if !stream::is_bidi(stream_id) && stream::is_local(stream_id, self.is_server) {
5869 return Err(Error::InvalidStreamState(stream_id));
5870 }
5871
5872 let stream = self
5873 .streams
5874 .get_mut(stream_id)
5875 .ok_or(Error::InvalidStreamState(stream_id))?;
5876
5877 if !stream.is_readable() {
5878 return Err(Error::Done);
5879 }
5880
5881 let local = stream.local;
5882 let priority_key = Arc::clone(&stream.priority_key);
5883
5884 #[cfg(feature = "qlog")]
5885 let offset = stream.recv.off_front();
5886
5887 #[cfg(feature = "qlog")]
5888 let to = match action {
5889 RecvAction::Emit { .. } => Some(DataRecipient::Application),
5890
5891 RecvAction::Discard { .. } => Some(DataRecipient::Dropped),
5892 };
5893
5894 let (read, fin) = match stream.recv.emit_or_discard(action) {
5895 Ok(v) => v,
5896
5897 Err(e) => {
5898 // Collect the stream if it is now complete. This can happen if
5899 // we got a `StreamReset` error which will now be propagated to
5900 // the application, so we don't need to keep the stream's state
5901 // anymore.
5902 if stream.is_complete() {
5903 self.streams.collect(stream_id, local);
5904 }
5905
5906 self.streams.remove_readable(&priority_key);
5907 return Err(e);
5908 }
5909 };
5910
5911 self.flow_control.add_consumed(read as u64);
5912
5913 let readable = stream.is_readable();
5914
5915 let complete = stream.is_complete();
5916
5917 if stream.recv.almost_full() {
5918 self.streams.insert_almost_full(stream_id);
5919 }
5920
5921 if !readable {
5922 self.streams.remove_readable(&priority_key);
5923 }
5924
5925 if complete {
5926 self.streams.collect(stream_id, local);
5927 }
5928
5929 qlog_with_type!(QLOG_DATA_MV, self.qlog, q, {
5930 let ev_data = EventData::QuicStreamDataMoved(qlog::events::quic::StreamDataMoved {
5931 stream_id: Some(stream_id),
5932 offset: Some(offset),
5933 raw: Some(RawInfo {
5934 length: Some(read as u64),
5935 ..Default::default()
5936 }),
5937 from: Some(DataRecipient::Transport),
5938 to,
5939 additional_info: fin.then_some(DataMovedAdditionalInfo::FinSet),
5940 });
5941
5942 let now = Instant::now();
5943 q.add_event_data_with_instant(ev_data, now).ok();
5944 });
5945
5946 if priority_key.incremental && readable {
5947 // Shuffle the incremental stream to the back of the queue.
5948 self.streams.remove_readable(&priority_key);
5949 self.streams.insert_readable(&priority_key);
5950 }
5951
5952 Ok((read, fin))
5953 }
5954
5955 /// Writes data to a stream.
5956 ///
5957 /// On success the number of bytes written is returned, or [`Done`] if no
5958 /// data was written (e.g. because the stream has no capacity).
5959 ///
5960 /// Applications can provide a 0-length buffer with the fin flag set to
5961 /// true. This will lead to a 0-length FIN STREAM frame being sent at the
5962 /// latest offset. The `Ok(0)` value is only returned when the application
5963 /// provided a 0-length buffer.
5964 ///
5965 /// In addition, if the peer has signalled that it doesn't want to receive
5966 /// any more data from this stream by sending the `STOP_SENDING` frame, the
5967 /// [`StreamStopped`] error will be returned instead of any data.
5968 ///
5969 /// Note that in order to avoid buffering an infinite amount of data in the
5970 /// stream's send buffer, streams are only allowed to buffer outgoing data
5971 /// up to the amount that the peer allows it to send (that is, up to the
5972 /// stream's outgoing flow control capacity).
5973 ///
5974 /// This means that the number of written bytes returned can be lower than
5975 /// the length of the input buffer when the stream doesn't have enough
5976 /// capacity for the operation to complete. The application should retry the
5977 /// operation once the stream is reported as writable again.
5978 ///
5979 /// Applications should call this method only after the handshake is
5980 /// completed (whenever [`is_established()`] returns `true`) or during
5981 /// early data if enabled (whenever [`is_in_early_data()`] returns `true`).
5982 ///
5983 /// [`Done`]: enum.Error.html#variant.Done
5984 /// [`StreamStopped`]: enum.Error.html#variant.StreamStopped
5985 /// [`is_established()`]: struct.Connection.html#method.is_established
5986 /// [`is_in_early_data()`]: struct.Connection.html#method.is_in_early_data
5987 ///
5988 /// ## Examples:
5989 ///
5990 /// ```no_run
5991 /// # let mut buf = [0; 512];
5992 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
5993 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
5994 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
5995 /// # let peer = "127.0.0.1:1234".parse().unwrap();
5996 /// # let local = "127.0.0.1:4321".parse().unwrap();
5997 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
5998 /// # let stream_id = 0;
5999 /// conn.stream_send(stream_id, b"hello", true)?;
6000 /// # Ok::<(), quiche::Error>(())
6001 /// ```
6002 pub fn stream_send(&mut self, stream_id: u64, buf: &[u8], fin: bool) -> Result<usize> {
6003 self.stream_do_send(
6004 stream_id,
6005 buf,
6006 fin,
6007 |stream: &mut stream::Stream<F>, buf: &[u8], cap: usize, fin: bool| {
6008 stream.send.write(&buf[..cap], fin).map(|v| (v, v))
6009 },
6010 )
6011 }
6012
6013 /// Writes data to a stream with zero copying, instead, it appends the
6014 /// provided buffer directly to the send queue if the capacity allows
6015 /// it.
6016 ///
6017 /// When a partial write happens (including when [`Error::Done`] is
6018 /// returned) the remaining (unwritten) buffer will also be returned.
6019 /// The application should retry the operation once the stream is
6020 /// reported as writable again.
6021 pub fn stream_send_zc(
6022 &mut self,
6023 stream_id: u64,
6024 buf: F::Buf,
6025 fin: bool,
6026 ) -> Result<(usize, Option<F::Buf>)>
6027 where
6028 F::Buf: BufSplit,
6029 {
6030 self.stream_do_send(
6031 stream_id,
6032 buf,
6033 fin,
6034 |stream: &mut stream::Stream<F>, buf: F::Buf, cap: usize, fin: bool| {
6035 let (sent, remaining) = stream.send.append_buf(buf, cap, fin)?;
6036 Ok((sent, (sent, remaining)))
6037 },
6038 )
6039 }
6040
6041 fn stream_do_send<B, R, SND>(
6042 &mut self,
6043 stream_id: u64,
6044 buf: B,
6045 fin: bool,
6046 write_fn: SND,
6047 ) -> Result<R>
6048 where
6049 B: AsRef<[u8]>,
6050 SND: FnOnce(&mut stream::Stream<F>, B, usize, bool) -> Result<(usize, R)>,
6051 {
6052 // We can't write on the peer's unidirectional streams.
6053 if !stream::is_bidi(stream_id) && !stream::is_local(stream_id, self.is_server) {
6054 return Err(Error::InvalidStreamState(stream_id));
6055 }
6056
6057 let len = buf.as_ref().len();
6058
6059 // Mark the connection as blocked if the connection-level flow control
6060 // limit doesn't let us buffer all the data.
6061 //
6062 // Note that this is separate from "send capacity" as that also takes
6063 // congestion control into consideration.
6064 if self.max_tx_data - self.tx_data < len as u64 {
6065 self.blocked_limit = Some(self.max_tx_data);
6066 }
6067
6068 let cap = self.tx_cap;
6069
6070 // Get existing stream or create a new one.
6071 let stream = match self.get_or_create_stream(stream_id, true) {
6072 Ok(v) => v,
6073
6074 Err(Error::StreamLimit) => {
6075 // If the local endpoint has exhausted the peer's stream count
6076 // limit, record the current limit so that a STREAMS_BLOCKED
6077 // frame can be sent.
6078 if self.enable_send_streams_blocked && stream::is_local(stream_id, self.is_server) {
6079 if stream::is_bidi(stream_id) {
6080 let limit = self.streams.peer_max_streams_bidi();
6081 self.streams_blocked_bidi_state.update_at(limit);
6082 } else {
6083 let limit = self.streams.peer_max_streams_uni();
6084 self.streams_blocked_uni_state.update_at(limit);
6085 }
6086 }
6087
6088 return Err(Error::StreamLimit);
6089 }
6090
6091 Err(e) => return Err(e),
6092 };
6093
6094 #[cfg(feature = "qlog")]
6095 let offset = stream.send.off_back();
6096
6097 let was_writable = stream.is_writable();
6098
6099 let was_flushable = stream.is_flushable();
6100
6101 let is_complete = stream.is_complete();
6102 let is_readable = stream.is_readable();
6103
6104 let priority_key = Arc::clone(&stream.priority_key);
6105
6106 // Return early if the stream has been stopped, and collect its state
6107 // if complete.
6108 if let Err(Error::StreamStopped(e)) = stream.send.cap() {
6109 // Only collect the stream if it is complete and not readable.
6110 // If it is readable, it will get collected when stream_recv()
6111 // is used.
6112 //
6113 // The stream can't be writable if it has been stopped.
6114 if is_complete && !is_readable {
6115 let local = stream.local;
6116 self.streams.collect(stream_id, local);
6117 }
6118
6119 return Err(Error::StreamStopped(e));
6120 };
6121
6122 // Truncate the input buffer based on the connection's send capacity if
6123 // necessary.
6124 //
6125 // When the cap is zero, the method returns Ok(0) *only* when the passed
6126 // buffer is empty. We return Error::Done otherwise.
6127 if cap == 0 && len > 0 {
6128 if was_writable {
6129 // When `stream_writable_next()` returns a stream, the writable
6130 // mark is removed, but because the stream is blocked by the
6131 // connection-level send capacity it won't be marked as writable
6132 // again once the capacity increases.
6133 //
6134 // Since the stream is writable already, mark it here instead.
6135 self.streams.insert_writable(&priority_key);
6136 }
6137
6138 return Err(Error::Done);
6139 }
6140
6141 let (cap, fin, blocked_by_cap) = if cap < len {
6142 (cap, false, true)
6143 } else {
6144 (len, fin, false)
6145 };
6146
6147 let (sent, ret) = match write_fn(stream, buf, cap, fin) {
6148 Ok(v) => v,
6149
6150 Err(e) => {
6151 self.streams.remove_writable(&priority_key);
6152 return Err(e);
6153 }
6154 };
6155
6156 let incremental = stream.incremental;
6157 let priority_key = Arc::clone(&stream.priority_key);
6158
6159 let flushable = stream.is_flushable();
6160
6161 let writable = stream.is_writable();
6162
6163 let empty_fin = len == 0 && fin;
6164
6165 if sent < cap {
6166 let max_off = stream.send.max_off();
6167
6168 if stream.send.blocked_at() != Some(max_off) {
6169 stream.send.update_blocked_at(Some(max_off));
6170 self.streams.insert_blocked(stream_id, max_off);
6171 }
6172 } else {
6173 stream.send.update_blocked_at(None);
6174 self.streams.remove_blocked(stream_id);
6175 }
6176
6177 // If the stream is now flushable push it to the flushable queue, but
6178 // only if it wasn't already queued.
6179 //
6180 // Consider the stream flushable also when we are sending a zero-length
6181 // frame that has the fin flag set.
6182 if (flushable || empty_fin) && !was_flushable {
6183 self.streams.insert_flushable(&priority_key);
6184 }
6185
6186 if !writable {
6187 self.streams.remove_writable(&priority_key);
6188 } else if was_writable && blocked_by_cap {
6189 // When `stream_writable_next()` returns a stream, the writable
6190 // mark is removed, but because the stream is blocked by the
6191 // connection-level send capacity it won't be marked as writable
6192 // again once the capacity increases.
6193 //
6194 // Since the stream is writable already, mark it here instead.
6195 self.streams.insert_writable(&priority_key);
6196 }
6197
6198 self.tx_cap -= sent;
6199
6200 self.tx_data += sent as u64;
6201
6202 self.streams.add_tx_buffered(sent);
6203
6204 qlog_with_type!(QLOG_DATA_MV, self.qlog, q, {
6205 let ev_data = EventData::QuicStreamDataMoved(qlog::events::quic::StreamDataMoved {
6206 stream_id: Some(stream_id),
6207 offset: Some(offset),
6208 raw: Some(RawInfo {
6209 length: Some(sent as u64),
6210 ..Default::default()
6211 }),
6212 from: Some(DataRecipient::Application),
6213 to: Some(DataRecipient::Transport),
6214 additional_info: fin.then_some(DataMovedAdditionalInfo::FinSet),
6215 });
6216
6217 let now = Instant::now();
6218 q.add_event_data_with_instant(ev_data, now).ok();
6219 });
6220
6221 if sent == 0 && cap > 0 {
6222 return Err(Error::Done);
6223 }
6224
6225 if incremental && writable {
6226 // Shuffle the incremental stream to the back of the queue.
6227 self.streams.remove_writable(&priority_key);
6228 self.streams.insert_writable(&priority_key);
6229 }
6230
6231 Ok(ret)
6232 }
6233
6234 /// Sets the priority for a stream.
6235 ///
6236 /// A stream's priority determines the order in which stream data is sent
6237 /// on the wire (streams with lower priority are sent first). Streams are
6238 /// created with a default priority of `127`.
6239 ///
6240 /// The target stream is created if it did not exist before calling this
6241 /// method.
6242 pub fn stream_priority(
6243 &mut self,
6244 stream_id: u64,
6245 urgency: u8,
6246 incremental: bool,
6247 ) -> Result<()> {
6248 // Get existing stream or create a new one, but if the stream
6249 // has already been closed and collected, ignore the prioritization.
6250 let stream = match self.get_or_create_stream(stream_id, true) {
6251 Ok(v) => v,
6252
6253 Err(Error::Done) => return Ok(()),
6254
6255 Err(e) => return Err(e),
6256 };
6257
6258 if stream.urgency == urgency && stream.incremental == incremental {
6259 return Ok(());
6260 }
6261
6262 stream.urgency = urgency;
6263 stream.incremental = incremental;
6264
6265 let new_priority_key = Arc::new(StreamPriorityKey {
6266 urgency: stream.urgency,
6267 incremental: stream.incremental,
6268 id: stream_id,
6269 ..Default::default()
6270 });
6271
6272 let old_priority_key =
6273 std::mem::replace(&mut stream.priority_key, new_priority_key.clone());
6274
6275 self.streams
6276 .update_priority(&old_priority_key, &new_priority_key);
6277
6278 Ok(())
6279 }
6280
6281 /// Shuts down reading or writing from/to the specified stream.
6282 ///
6283 /// When the `direction` argument is set to [`Shutdown::Read`], outstanding
6284 /// data in the stream's receive buffer is dropped, and no additional data
6285 /// is added to it. Data received after calling this method is still
6286 /// validated and acked but not stored, and [`stream_recv()`] will not
6287 /// return it to the application. In addition, a `STOP_SENDING` frame will
6288 /// be sent to the peer to signal it to stop sending data.
6289 ///
6290 /// When the `direction` argument is set to [`Shutdown::Write`], outstanding
6291 /// data in the stream's send buffer is dropped, and no additional data is
6292 /// added to it. Data passed to [`stream_send()`] after calling this method
6293 /// will be ignored. In addition, a `RESET_STREAM` frame will be sent to the
6294 /// peer to signal the reset.
6295 ///
6296 /// Locally-initiated unidirectional streams can only be closed in the
6297 /// [`Shutdown::Write`] direction. Remotely-initiated unidirectional streams
6298 /// can only be closed in the [`Shutdown::Read`] direction. Using an
6299 /// incorrect direction will return [`InvalidStreamState`].
6300 ///
6301 /// [`Shutdown::Read`]: enum.Shutdown.html#variant.Read
6302 /// [`Shutdown::Write`]: enum.Shutdown.html#variant.Write
6303 /// [`stream_recv()`]: struct.Connection.html#method.stream_recv
6304 /// [`stream_send()`]: struct.Connection.html#method.stream_send
6305 /// [`InvalidStreamState`]: enum.Error.html#variant.InvalidStreamState
6306 pub fn stream_shutdown(&mut self, stream_id: u64, direction: Shutdown, err: u64) -> Result<()> {
6307 // Don't try to stop a local unidirectional stream.
6308 if direction == Shutdown::Read
6309 && stream::is_local(stream_id, self.is_server)
6310 && !stream::is_bidi(stream_id)
6311 {
6312 return Err(Error::InvalidStreamState(stream_id));
6313 }
6314
6315 // Don't try to reset a remote unidirectional stream.
6316 if direction == Shutdown::Write
6317 && !stream::is_local(stream_id, self.is_server)
6318 && !stream::is_bidi(stream_id)
6319 {
6320 return Err(Error::InvalidStreamState(stream_id));
6321 }
6322
6323 // Get existing stream.
6324 let stream = self.streams.get_mut(stream_id).ok_or(Error::Done)?;
6325
6326 let priority_key = Arc::clone(&stream.priority_key);
6327
6328 match direction {
6329 Shutdown::Read => {
6330 let consumed = stream.recv.shutdown()?;
6331 self.flow_control.add_consumed(consumed);
6332
6333 if !stream.recv.is_fin() {
6334 self.streams.insert_stopped(stream_id, err);
6335 }
6336
6337 // Once shutdown, the stream is guaranteed to be non-readable.
6338 self.streams.remove_readable(&priority_key);
6339
6340 self.stopped_stream_local_count = self.stopped_stream_local_count.saturating_add(1);
6341 }
6342
6343 Shutdown::Write => {
6344 // Save the buffered length before shutdown (shutdown clears the
6345 // buffer).
6346 let buffered_len = stream.send.buffered_bytes() as usize;
6347
6348 let (final_size, unsent) = stream.send.shutdown()?;
6349
6350 // Claw back some flow control allowance from data that was
6351 // buffered but not actually sent before the stream was reset.
6352 self.tx_data = self.tx_data.saturating_sub(unsent);
6353
6354 // Update tx_buffered: subtract only the buffered data, not
6355 // inflight data.
6356 self.streams.sub_tx_buffered(buffered_len);
6357
6358 // Match App-to-Transport moves with Transport-to-Dropped moves.
6359 // A Network transition would distinguish sent bytes from drops
6360 // before transmission.
6361 qlog_with_type!(QLOG_DATA_MV, self.qlog, q, {
6362 let ev_data =
6363 EventData::QuicStreamDataMoved(qlog::events::quic::StreamDataMoved {
6364 stream_id: Some(stream_id),
6365 offset: Some(final_size),
6366 raw: Some(RawInfo {
6367 length: Some(unsent),
6368 ..Default::default()
6369 }),
6370 from: Some(DataRecipient::Transport),
6371 to: Some(DataRecipient::Dropped),
6372 ..Default::default()
6373 });
6374
6375 q.add_event_data_with_instant(ev_data, Instant::now()).ok();
6376 });
6377
6378 // Update send capacity.
6379 self.update_tx_cap();
6380
6381 self.streams.insert_reset(stream_id, err, final_size);
6382
6383 // Once shutdown, the stream is guaranteed to be non-writable.
6384 self.streams.remove_writable(&priority_key);
6385
6386 self.reset_stream_local_count = self.reset_stream_local_count.saturating_add(1);
6387 }
6388 }
6389
6390 Ok(())
6391 }
6392
6393 /// Returns the stream's send capacity in bytes.
6394 ///
6395 /// The returned capacity takes into account the stream's flow control limit
6396 /// as well as connection level flow and congestion control.
6397 ///
6398 /// If the specified stream doesn't exist (including when it has already
6399 /// been completed and closed), the [`InvalidStreamState`] error will be
6400 /// returned.
6401 ///
6402 /// In addition, if the peer has signalled that it doesn't want to receive
6403 /// any more data from this stream by sending the `STOP_SENDING` frame, the
6404 /// [`StreamStopped`] error will be returned.
6405 ///
6406 /// [`InvalidStreamState`]: enum.Error.html#variant.InvalidStreamState
6407 /// [`StreamStopped`]: enum.Error.html#variant.StreamStopped
6408 #[inline]
6409 pub fn stream_capacity(&mut self, stream_id: u64) -> Result<usize> {
6410 if let Some(stream) = self.streams.get(stream_id) {
6411 let stream_cap = match stream.send.cap() {
6412 Ok(v) => v,
6413
6414 Err(Error::StreamStopped(e)) => {
6415 // Only collect the stream if it is complete and not
6416 // readable. If it is readable, it will get collected when
6417 // stream_recv() is used.
6418 if stream.is_complete() && !stream.is_readable() {
6419 let local = stream.local;
6420 self.streams.collect(stream_id, local);
6421 }
6422
6423 return Err(Error::StreamStopped(e));
6424 }
6425
6426 Err(e) => return Err(e),
6427 };
6428
6429 let cap = cmp::min(self.tx_cap, stream_cap);
6430 return Ok(cap);
6431 };
6432
6433 Err(Error::InvalidStreamState(stream_id))
6434 }
6435
6436 /// Returns the next stream that has data to read.
6437 ///
6438 /// Note that once returned by this method, a stream ID will not be returned
6439 /// again until it is "re-armed".
6440 ///
6441 /// The application will need to read all of the pending data on the stream,
6442 /// and new data has to be received before the stream is reported again.
6443 ///
6444 /// This is unlike the [`readable()`] method, that returns the same list of
6445 /// readable streams when called multiple times in succession.
6446 ///
6447 /// [`readable()`]: struct.Connection.html#method.readable
6448 pub fn stream_readable_next(&mut self) -> Option<u64> {
6449 let priority_key = self.streams.readable.front().clone_pointer()?;
6450
6451 self.streams.remove_readable(&priority_key);
6452
6453 Some(priority_key.id)
6454 }
6455
6456 /// Returns true if the stream has data that can be read.
6457 pub fn stream_readable(&self, stream_id: u64) -> bool {
6458 let stream = match self.streams.get(stream_id) {
6459 Some(v) => v,
6460
6461 None => return false,
6462 };
6463
6464 stream.is_readable()
6465 }
6466
6467 /// Returns the number of contiguous bytes buffered for a stream, up to
6468 /// `max_len`.
6469 ///
6470 /// This is the length of the contiguous, in-order data buffered at the
6471 /// stream's current read offset, i.e. the bytes a call to [`stream_recv`]
6472 /// would return right now. Data received out of order that sits behind a
6473 /// gap is not counted, so this never reports bytes that are not yet
6474 /// readable.
6475 ///
6476 /// This is a companion to [`stream_readable`], which only reports *whether*
6477 /// data is available; this reports *how much*. It is intended for sizing a
6478 /// receive buffer. The cost is proportional to the number of contiguous
6479 /// buffered chunks at the front of the stream, up to `max_len`, and no data
6480 /// is copied.
6481 ///
6482 /// Returns 0 if the stream does not exist.
6483 ///
6484 /// [`stream_recv`]: struct.Connection.html#method.stream_recv
6485 /// [`stream_readable`]: struct.Connection.html#method.stream_readable
6486 pub fn stream_readable_len(&self, stream_id: u64, max_len: usize) -> usize {
6487 match self.streams.get(stream_id) {
6488 Some(s) => s.recv.readable_len(max_len),
6489
6490 None => 0,
6491 }
6492 }
6493
6494 /// Returns the next stream that can be written to.
6495 ///
6496 /// Note that once returned by this method, a stream ID will not be returned
6497 /// again until it is "re-armed".
6498 ///
6499 /// This is unlike the [`writable()`] method, that returns the same list of
6500 /// writable streams when called multiple times in succession. It is not
6501 /// advised to use both `stream_writable_next()` and [`writable()`] on the
6502 /// same connection, as it may lead to unexpected results.
6503 ///
6504 /// The [`stream_writable()`] method can also be used to fine-tune when a
6505 /// stream is reported as writable again.
6506 ///
6507 /// [`stream_writable()`]: struct.Connection.html#method.stream_writable
6508 /// [`writable()`]: struct.Connection.html#method.writable
6509 pub fn stream_writable_next(&mut self) -> Option<u64> {
6510 // If there is not enough connection-level send capacity, none of the
6511 // streams are writable.
6512 if self.tx_cap == 0 {
6513 return None;
6514 }
6515
6516 let mut cursor = self.streams.writable.front();
6517
6518 while let Some(priority_key) = cursor.clone_pointer() {
6519 if let Some(stream) = self.streams.get(priority_key.id) {
6520 let cap = match stream.send.cap() {
6521 Ok(v) => v,
6522
6523 // Return the stream to the application immediately if it's
6524 // stopped.
6525 Err(_) => {
6526 return {
6527 self.streams.remove_writable(&priority_key);
6528
6529 Some(priority_key.id)
6530 };
6531 }
6532 };
6533
6534 if cmp::min(self.tx_cap, cap) >= stream.send_lowat {
6535 self.streams.remove_writable(&priority_key);
6536 return Some(priority_key.id);
6537 }
6538 }
6539
6540 cursor.move_next();
6541 }
6542
6543 None
6544 }
6545
6546 /// Returns true if the stream has enough send capacity.
6547 ///
6548 /// When `len` more bytes can be buffered into the given stream's send
6549 /// buffer, `true` will be returned, `false` otherwise.
6550 ///
6551 /// In the latter case, if the additional data can't be buffered due to
6552 /// flow control limits, the peer will also be notified, and a "low send
6553 /// watermark" will be set for the stream, such that it is not going to be
6554 /// reported as writable again by [`stream_writable_next()`] until its send
6555 /// capacity reaches `len`.
6556 ///
6557 /// If the specified stream doesn't exist (including when it has already
6558 /// been completed and closed), the [`InvalidStreamState`] error will be
6559 /// returned.
6560 ///
6561 /// In addition, if the peer has signalled that it doesn't want to receive
6562 /// any more data from this stream by sending the `STOP_SENDING` frame, the
6563 /// [`StreamStopped`] error will be returned.
6564 ///
6565 /// [`stream_writable_next()`]: struct.Connection.html#method.stream_writable_next
6566 /// [`InvalidStreamState`]: enum.Error.html#variant.InvalidStreamState
6567 /// [`StreamStopped`]: enum.Error.html#variant.StreamStopped
6568 #[inline]
6569 pub fn stream_writable(&mut self, stream_id: u64, len: usize) -> Result<bool> {
6570 if self.stream_capacity(stream_id)? >= len {
6571 return Ok(true);
6572 }
6573
6574 let stream = match self.streams.get_mut(stream_id) {
6575 Some(v) => v,
6576
6577 None => return Err(Error::InvalidStreamState(stream_id)),
6578 };
6579
6580 stream.send_lowat = cmp::max(1, len);
6581
6582 let is_writable = stream.is_writable();
6583
6584 let priority_key = Arc::clone(&stream.priority_key);
6585
6586 if self.max_tx_data - self.tx_data < len as u64 {
6587 self.blocked_limit = Some(self.max_tx_data);
6588 }
6589
6590 if stream.send.cap()? < len {
6591 let max_off = stream.send.max_off();
6592 if stream.send.blocked_at() != Some(max_off) {
6593 stream.send.update_blocked_at(Some(max_off));
6594 self.streams.insert_blocked(stream_id, max_off);
6595 }
6596 } else if is_writable {
6597 // When `stream_writable_next()` returns a stream, the writable
6598 // mark is removed, but because the stream is blocked by the
6599 // connection-level send capacity it won't be marked as writable
6600 // again once the capacity increases.
6601 //
6602 // Since the stream is writable already, mark it here instead.
6603 self.streams.insert_writable(&priority_key);
6604 }
6605
6606 Ok(false)
6607 }
6608
6609 /// Returns true if all the data has been read from the specified stream.
6610 ///
6611 /// This instructs the application that all the data received from the
6612 /// peer on the stream has been read, and there won't be anymore in the
6613 /// future.
6614 ///
6615 /// Basically this returns true when the peer either set the `fin` flag
6616 /// for the stream, or sent `RESET_STREAM`.
6617 #[inline]
6618 pub fn stream_finished(&self, stream_id: u64) -> bool {
6619 let stream = match self.streams.get(stream_id) {
6620 Some(v) => v,
6621
6622 None => return true,
6623 };
6624
6625 stream.recv.is_fin()
6626 }
6627
6628 /// Returns true if the specified stream is closed.
6629 ///
6630 /// For bidirectional streams this happens when both the receive and send
6631 /// sides have signaled `fin`. For unidirectional streams only the
6632 /// relevant direction is checked, depending on whether the stream was
6633 /// created locally or not.
6634 ///
6635 /// This also returns true if the stream has already been collected, but
6636 /// returns false if the stream was never opened.
6637 #[inline]
6638 pub fn stream_closed(&self, stream_id: u64) -> bool {
6639 let Some(stream) = self.streams.get(stream_id) else {
6640 return self.streams.is_collected(stream_id);
6641 };
6642
6643 match (stream.bidi, stream.local) {
6644 // For bidirectional streams both directions must have signaled
6645 // FIN.
6646 (true, _) => stream.recv.is_fin() && stream.send.is_fin(),
6647
6648 // For unidirectional streams created locally, only the send side
6649 // is checked.
6650 (false, true) => stream.send.is_fin(),
6651
6652 // For unidirectional streams created by the peer, only the
6653 // receive side is checked.
6654 (false, false) => stream.recv.is_fin(),
6655 }
6656 }
6657
6658 /// Returns the number of bidirectional streams that can be created
6659 /// before the peer's stream count limit is reached.
6660 ///
6661 /// This can be useful to know if it's possible to create a bidirectional
6662 /// stream without trying it first.
6663 #[inline]
6664 pub fn peer_streams_left_bidi(&self) -> u64 {
6665 self.streams.peer_streams_left_bidi()
6666 }
6667
6668 /// Returns the number of unidirectional streams that can be created
6669 /// before the peer's stream count limit is reached.
6670 ///
6671 /// This can be useful to know if it's possible to create a unidirectional
6672 /// stream without trying it first.
6673 #[inline]
6674 pub fn peer_streams_left_uni(&self) -> u64 {
6675 self.streams.peer_streams_left_uni()
6676 }
6677
6678 /// Returns an iterator over streams that have outstanding data to read.
6679 ///
6680 /// Note that the iterator will only include streams that were readable at
6681 /// the time the iterator itself was created (i.e. when `readable()` was
6682 /// called). To account for newly readable streams, the iterator needs to
6683 /// be created again.
6684 ///
6685 /// ## Examples:
6686 ///
6687 /// ```no_run
6688 /// # let mut buf = [0; 512];
6689 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
6690 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
6691 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
6692 /// # let peer = "127.0.0.1:1234".parse().unwrap();
6693 /// # let local = socket.local_addr().unwrap();
6694 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
6695 /// // Iterate over readable streams.
6696 /// for stream_id in conn.readable() {
6697 /// // Stream is readable, read until there's no more data.
6698 /// while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
6699 /// println!("Got {} bytes on stream {}", read, stream_id);
6700 /// }
6701 /// }
6702 /// # Ok::<(), quiche::Error>(())
6703 /// ```
6704 #[inline]
6705 pub fn readable(&self) -> StreamIter {
6706 self.streams.readable()
6707 }
6708
6709 /// Returns an iterator over streams that can be written in priority order.
6710 ///
6711 /// The priority order is based on RFC 9218 scheduling recommendations.
6712 /// Stream priority can be controlled using [`stream_priority()`]. In order
6713 /// to support fairness requirements, each time this method is called,
6714 /// internal state is updated. Therefore the iterator ordering can change
6715 /// between calls, even if no streams were added or removed.
6716 ///
6717 /// A "writable" stream is a stream that has enough flow control capacity to
6718 /// send data to the peer. To avoid buffering an infinite amount of data,
6719 /// streams are only allowed to buffer outgoing data up to the amount that
6720 /// the peer allows to send.
6721 ///
6722 /// Note that the iterator will only include streams that were writable at
6723 /// the time the iterator itself was created (i.e. when `writable()` was
6724 /// called). To account for newly writable streams, the iterator needs to be
6725 /// created again.
6726 ///
6727 /// ## Examples:
6728 ///
6729 /// ```no_run
6730 /// # let mut buf = [0; 512];
6731 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
6732 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
6733 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
6734 /// # let local = socket.local_addr().unwrap();
6735 /// # let peer = "127.0.0.1:1234".parse().unwrap();
6736 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
6737 /// // Iterate over writable streams.
6738 /// for stream_id in conn.writable() {
6739 /// // Stream is writable, write some data.
6740 /// if let Ok(written) = conn.stream_send(stream_id, &buf, false) {
6741 /// println!("Written {} bytes on stream {}", written, stream_id);
6742 /// }
6743 /// }
6744 /// # Ok::<(), quiche::Error>(())
6745 /// ```
6746 /// [`stream_priority()`]: struct.Connection.html#method.stream_priority
6747 #[inline]
6748 pub fn writable(&self) -> StreamIter {
6749 // If there is not enough connection-level send capacity, none of the
6750 // streams are writable, so return an empty iterator.
6751 if self.tx_cap == 0 {
6752 return StreamIter::default();
6753 }
6754
6755 self.streams.writable()
6756 }
6757
6758 /// Returns the maximum possible size of egress UDP payloads.
6759 ///
6760 /// This is the maximum size of UDP payloads that can be sent, and depends
6761 /// on both the configured maximum send payload size of the local endpoint
6762 /// (as configured with [`set_max_send_udp_payload_size()`]), as well as
6763 /// the transport parameter advertised by the remote peer.
6764 ///
6765 /// Note that this value can change during the lifetime of the connection,
6766 /// but should remain stable across consecutive calls to [`send()`].
6767 ///
6768 /// [`set_max_send_udp_payload_size()`]:
6769 /// struct.Config.html#method.set_max_send_udp_payload_size
6770 /// [`send()`]: struct.Connection.html#method.send
6771 pub fn max_send_udp_payload_size(&self) -> usize {
6772 let max_datagram_size = self
6773 .paths
6774 .get_active()
6775 .ok()
6776 .map(|p| p.recovery.max_datagram_size());
6777
6778 if let Some(max_datagram_size) = max_datagram_size {
6779 if self.is_established() {
6780 // Cap the packet size at 16,383 bytes so a two-byte varint can
6781 // always encode it.
6782 return cmp::min(16383, max_datagram_size);
6783 }
6784 }
6785
6786 // Allow for 1200 bytes (minimum QUIC packet size) during the
6787 // handshake.
6788 self.client_initial_datagram_size()
6789 .unwrap_or(MIN_CLIENT_INITIAL_LEN)
6790 }
6791
6792 fn client_initial_datagram_size(&self) -> Option<usize> {
6793 if self.initial_size_fallback {
6794 return None;
6795 }
6796
6797 let size = self.initial_datagram_size?;
6798
6799 match self.paths.get_active() {
6800 Ok(path) if path.peer_addr().is_ipv6() => Some(size.min(MAX_IPV6_INITIAL_LEN)),
6801
6802 _ => Some(size),
6803 }
6804 }
6805
6806 /// Schedule an ack-eliciting packet on the active path.
6807 ///
6808 /// QUIC packets might not contain ack-eliciting frames during normal
6809 /// operating conditions. If the packet would already contain
6810 /// ack-eliciting frames, this method does not change any behavior.
6811 /// However, if the packet would not ordinarily contain ack-eliciting
6812 /// frames, this method ensures that a PING frame sent.
6813 ///
6814 /// Calling this method multiple times before [`send()`] has no effect.
6815 ///
6816 /// [`send()`]: struct.Connection.html#method.send
6817 pub fn send_ack_eliciting(&mut self) -> Result<()> {
6818 if self.is_closed() || self.is_draining() {
6819 return Ok(());
6820 }
6821 self.paths.get_active_mut()?.needs_ack_eliciting = true;
6822 Ok(())
6823 }
6824
6825 /// Schedule an ack-eliciting packet on the specified path.
6826 ///
6827 /// See [`send_ack_eliciting()`] for more detail. [`InvalidState`] is
6828 /// returned if there is no record of the path.
6829 ///
6830 /// [`send_ack_eliciting()`]: struct.Connection.html#method.send_ack_eliciting
6831 /// [`InvalidState`]: enum.Error.html#variant.InvalidState
6832 pub fn send_ack_eliciting_on_path(
6833 &mut self,
6834 local: SocketAddr,
6835 peer: SocketAddr,
6836 ) -> Result<()> {
6837 if self.is_closed() || self.is_draining() {
6838 return Ok(());
6839 }
6840 let path_id = self
6841 .paths
6842 .path_id_from_addrs(&(local, peer))
6843 .ok_or(Error::InvalidState)?;
6844 self.paths.get_mut(path_id)?.needs_ack_eliciting = true;
6845 Ok(())
6846 }
6847
6848 /// Reads the first received DATAGRAM.
6849 ///
6850 /// On success the DATAGRAM's data is returned along with its size.
6851 ///
6852 /// [`Done`] is returned if there is no data to read.
6853 ///
6854 /// [`BufferTooShort`] is returned if the provided buffer is too small for
6855 /// the DATAGRAM.
6856 ///
6857 /// [`Done`]: enum.Error.html#variant.Done
6858 /// [`BufferTooShort`]: enum.Error.html#variant.BufferTooShort
6859 ///
6860 /// ## Examples:
6861 ///
6862 /// ```no_run
6863 /// # let mut buf = [0; 512];
6864 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
6865 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
6866 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
6867 /// # let peer = "127.0.0.1:1234".parse().unwrap();
6868 /// # let local = socket.local_addr().unwrap();
6869 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
6870 /// let mut dgram_buf = [0; 512];
6871 /// while let Ok((len)) = conn.dgram_recv(&mut dgram_buf) {
6872 /// println!("Got {} bytes of DATAGRAM", len);
6873 /// }
6874 /// # Ok::<(), quiche::Error>(())
6875 /// ```
6876 #[inline]
6877 pub fn dgram_recv(&mut self, buf: &mut [u8]) -> Result<usize> {
6878 match self.dgram_recv_queue.pop() {
6879 Some(d) => {
6880 if d.as_ref().len() > buf.len() {
6881 return Err(Error::BufferTooShort);
6882 }
6883 let len = d.as_ref().len();
6884
6885 buf[..len].copy_from_slice(d.as_ref());
6886 Ok(len)
6887 }
6888
6889 None => Err(Error::Done),
6890 }
6891 }
6892
6893 /// Reads the first received DATAGRAM.
6894 ///
6895 /// This is the same as [`dgram_recv()`] but returns the DATAGRAM as an
6896 /// owned buffer instead of copying into the provided buffer.
6897 ///
6898 /// [`dgram_recv()`]: struct.Connection.html#method.dgram_recv
6899 #[inline]
6900 pub fn dgram_recv_buf(&mut self) -> Result<F::DgramBuf> {
6901 self.dgram_recv_queue.pop().ok_or(Error::Done)
6902 }
6903
6904 /// Reads the first received DATAGRAM without removing it from the queue.
6905 ///
6906 /// On success the DATAGRAM's data is returned along with the actual number
6907 /// of bytes peeked. The requested length cannot exceed the DATAGRAM's
6908 /// actual length.
6909 ///
6910 /// [`Done`] is returned if there is no data to read.
6911 ///
6912 /// [`BufferTooShort`] is returned if the provided buffer is smaller the
6913 /// number of bytes to peek.
6914 ///
6915 /// [`Done`]: enum.Error.html#variant.Done
6916 /// [`BufferTooShort`]: enum.Error.html#variant.BufferTooShort
6917 #[inline]
6918 pub fn dgram_recv_peek(&self, buf: &mut [u8], len: usize) -> Result<usize> {
6919 self.dgram_recv_queue.peek_front_bytes(buf, len)
6920 }
6921
6922 /// Returns the length of the first stored DATAGRAM.
6923 #[inline]
6924 pub fn dgram_recv_front_len(&self) -> Option<usize> {
6925 self.dgram_recv_queue.peek_front_len()
6926 }
6927
6928 /// Returns the number of items in the DATAGRAM receive queue.
6929 #[inline]
6930 pub fn dgram_recv_queue_len(&self) -> usize {
6931 self.dgram_recv_queue.len()
6932 }
6933
6934 /// Returns the total size of all items in the DATAGRAM receive queue.
6935 #[inline]
6936 pub fn dgram_recv_queue_byte_size(&self) -> usize {
6937 self.dgram_recv_queue.byte_size()
6938 }
6939
6940 /// Returns the number of items in the DATAGRAM send queue.
6941 #[inline]
6942 pub fn dgram_send_queue_len(&self) -> usize {
6943 self.dgram_send_queue.len()
6944 }
6945
6946 /// Returns the total size of all items in the DATAGRAM send queue.
6947 #[inline]
6948 pub fn dgram_send_queue_byte_size(&self) -> usize {
6949 self.dgram_send_queue.byte_size()
6950 }
6951
6952 /// Returns whether or not the DATAGRAM send queue is full.
6953 #[inline]
6954 pub fn is_dgram_send_queue_full(&self) -> bool {
6955 self.dgram_send_queue.is_full()
6956 }
6957
6958 /// Returns whether or not the DATAGRAM recv queue is full.
6959 #[inline]
6960 pub fn is_dgram_recv_queue_full(&self) -> bool {
6961 self.dgram_recv_queue.is_full()
6962 }
6963
6964 /// Sends data in a DATAGRAM frame.
6965 ///
6966 /// [`Done`] is returned if no data was written.
6967 /// [`InvalidState`] is returned if the peer does not support DATAGRAM.
6968 /// [`BufferTooShort`] is returned if the DATAGRAM frame length is larger
6969 /// than peer's supported DATAGRAM frame length. Use
6970 /// [`dgram_max_writable_len()`] to get the largest supported DATAGRAM
6971 /// frame length.
6972 ///
6973 /// Note that there is no flow control of DATAGRAM frames, so in order to
6974 /// avoid buffering an infinite amount of frames we apply an internal
6975 /// limit.
6976 ///
6977 /// [`Done`]: enum.Error.html#variant.Done
6978 /// [`InvalidState`]: enum.Error.html#variant.InvalidState
6979 /// [`BufferTooShort`]: enum.Error.html#variant.BufferTooShort
6980 /// [`dgram_max_writable_len()`]:
6981 /// struct.Connection.html#method.dgram_max_writable_len
6982 ///
6983 /// ## Examples:
6984 ///
6985 /// ```no_run
6986 /// # let mut buf = [0; 512];
6987 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
6988 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
6989 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
6990 /// # let peer = "127.0.0.1:1234".parse().unwrap();
6991 /// # let local = socket.local_addr().unwrap();
6992 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
6993 /// conn.dgram_send(b"hello")?;
6994 /// # Ok::<(), quiche::Error>(())
6995 /// ```
6996 pub fn dgram_send(&mut self, buf: &[u8]) -> Result<()> {
6997 self.dgram_send_buf(F::dgram_buf_from_slice(buf))
6998 }
6999
7000 /// Sends data in a DATAGRAM frame.
7001 ///
7002 /// This is the same as [`dgram_send()`] but takes an owned buffer
7003 /// instead of a slice and avoids copying.
7004 ///
7005 /// [`dgram_send()`]: struct.Connection.html#method.dgram_send
7006 pub fn dgram_send_buf(&mut self, buf: F::DgramBuf) -> Result<()> {
7007 let max_payload_len = match self.dgram_max_writable_len() {
7008 Some(v) => v,
7009
7010 None => return Err(Error::InvalidState),
7011 };
7012
7013 if buf.as_ref().len() > max_payload_len {
7014 return Err(Error::BufferTooShort);
7015 }
7016
7017 self.dgram_send_queue.push(buf)?;
7018
7019 let active_path = self.paths.get_active_mut()?;
7020
7021 if self.dgram_send_queue.byte_size() > active_path.recovery.cwnd_available() {
7022 active_path.recovery.update_app_limited(false);
7023 }
7024
7025 Ok(())
7026 }
7027
7028 /// Purges queued outgoing DATAGRAMs matching the predicate.
7029 ///
7030 /// In other words, remove all elements `e` such that `f(&e)` returns true.
7031 ///
7032 /// ## Examples:
7033 /// ```no_run
7034 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
7035 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
7036 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
7037 /// # let peer = "127.0.0.1:1234".parse().unwrap();
7038 /// # let local = socket.local_addr().unwrap();
7039 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
7040 /// conn.dgram_send(b"hello")?;
7041 /// conn.dgram_purge_outgoing(&|d: &[u8]| -> bool { d[0] == 0 });
7042 /// # Ok::<(), quiche::Error>(())
7043 /// ```
7044 #[inline]
7045 pub fn dgram_purge_outgoing<FN: Fn(&[u8]) -> bool>(&mut self, f: FN) {
7046 self.dgram_send_queue.purge(f);
7047 }
7048
7049 /// Returns the maximum DATAGRAM payload that can be sent.
7050 ///
7051 /// [`None`] is returned if the peer hasn't advertised a maximum DATAGRAM
7052 /// frame size.
7053 ///
7054 /// ## Examples:
7055 ///
7056 /// ```no_run
7057 /// # let mut buf = [0; 512];
7058 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
7059 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
7060 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
7061 /// # let peer = "127.0.0.1:1234".parse().unwrap();
7062 /// # let local = socket.local_addr().unwrap();
7063 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
7064 /// if let Some(payload_size) = conn.dgram_max_writable_len() {
7065 /// if payload_size > 5 {
7066 /// conn.dgram_send(b"hello")?;
7067 /// }
7068 /// }
7069 /// # Ok::<(), quiche::Error>(())
7070 /// ```
7071 #[inline]
7072 pub fn dgram_max_writable_len(&self) -> Option<usize> {
7073 match self.peer_transport_params.max_datagram_frame_size {
7074 None => None,
7075 Some(peer_frame_len) => {
7076 let dcid = self.destination_id();
7077 // Start from the maximum packet size...
7078 let mut max_len = self.max_send_udp_payload_size();
7079 // ...subtract the Short packet header overhead...
7080 // (1 byte of pkt_len + len of dcid)
7081 max_len = max_len.saturating_sub(1 + dcid.len());
7082 // ...subtract the packet number (max len)...
7083 max_len = max_len.saturating_sub(packet::MAX_PKT_NUM_LEN);
7084 // ...subtract the crypto overhead...
7085 max_len = max_len
7086 .saturating_sub(self.crypto_ctx[packet::Epoch::Application].crypto_overhead()?);
7087 // ...clamp to what peer can support...
7088 max_len = cmp::min(peer_frame_len as usize, max_len);
7089 // ...subtract frame overhead, checked for underflow.
7090 // (1 byte of frame type + len of length )
7091 max_len.checked_sub(1 + frame::MAX_DGRAM_OVERHEAD)
7092 }
7093 }
7094 }
7095
7096 fn dgram_enabled(&self) -> bool {
7097 self.local_transport_params
7098 .max_datagram_frame_size
7099 .is_some()
7100 }
7101
7102 /// Returns when the next timeout event will occur.
7103 ///
7104 /// Once the timeout Instant has been reached, the [`on_timeout()`] method
7105 /// should be called. A timeout of `None` means that the timer should be
7106 /// disarmed.
7107 ///
7108 /// [`on_timeout()`]: struct.Connection.html#method.on_timeout
7109 pub fn timeout_instant(&self) -> Option<Instant> {
7110 if self.is_closed() {
7111 return None;
7112 }
7113
7114 if self.is_draining() {
7115 // Draining timer takes precedence over all other timers. If it is
7116 // set it means the connection is closing so there's no point in
7117 // processing the other timers.
7118 self.draining_timer
7119 } else {
7120 // Use the lowest timer value (i.e. "sooner") among idle and loss
7121 // detection timers. If they are both unset (i.e. `None`) then the
7122 // result is `None`, but if at least one of them is set then a
7123 // `Some(...)` value is returned.
7124 let path_timer = self
7125 .paths
7126 .iter()
7127 .filter_map(|(_, p)| p.recovery.loss_detection_timer())
7128 .min();
7129
7130 let key_update_timer = self.crypto_ctx[packet::Epoch::Application]
7131 .key_update
7132 .as_ref()
7133 .map(|key_update| key_update.timer);
7134
7135 let timers = [self.idle_timer, path_timer, key_update_timer];
7136
7137 timers.iter().filter_map(|&x| x).min()
7138 }
7139 }
7140
7141 /// Returns the amount of time until the next timeout event.
7142 ///
7143 /// Once the given duration has elapsed, the [`on_timeout()`] method should
7144 /// be called. A timeout of `None` means that the timer should be disarmed.
7145 ///
7146 /// [`on_timeout()`]: struct.Connection.html#method.on_timeout
7147 pub fn timeout(&self) -> Option<Duration> {
7148 self.timeout_instant().map(|timeout| {
7149 let now = Instant::now();
7150
7151 if timeout <= now {
7152 Duration::ZERO
7153 } else {
7154 timeout.duration_since(now)
7155 }
7156 })
7157 }
7158
7159 /// Processes a timeout event.
7160 ///
7161 /// If no timeout has occurred it does nothing.
7162 pub fn on_timeout(&mut self) {
7163 let now = Instant::now();
7164
7165 if let Some(draining_timer) = self.draining_timer {
7166 if draining_timer <= now {
7167 trace!("{} draining timeout expired", self.trace_id);
7168
7169 self.mark_closed();
7170 }
7171
7172 // Draining timer takes precedence over all other timers. If it is
7173 // set it means the connection is closing so there's no point in
7174 // processing the other timers.
7175 return;
7176 }
7177
7178 if let Some(timer) = self.idle_timer {
7179 if timer <= now {
7180 trace!("{} idle timeout expired", self.trace_id);
7181
7182 self.mark_closed();
7183 self.timed_out = true;
7184 return;
7185 }
7186 }
7187
7188 if let Some(timer) = self.crypto_ctx[packet::Epoch::Application]
7189 .key_update
7190 .as_ref()
7191 .map(|key_update| key_update.timer)
7192 {
7193 if timer <= now {
7194 // Discard previous key once key update timer expired.
7195 let _ = self.crypto_ctx[packet::Epoch::Application]
7196 .key_update
7197 .take();
7198 }
7199 }
7200
7201 let handshake_status = self.handshake_status();
7202
7203 let initial_unanswered = !self.is_server && self.recv_count == 0;
7204
7205 for (_, p) in self.paths.iter_mut() {
7206 if let Some(timer) = p.recovery.loss_detection_timer() {
7207 if timer <= now {
7208 trace!("{} loss detection timeout expired", self.trace_id);
7209
7210 self.initial_size_fallback |= initial_unanswered;
7211
7212 let OnLossDetectionTimeoutOutcome {
7213 lost_packets,
7214 lost_bytes,
7215 } = p.on_loss_detection_timeout(
7216 handshake_status,
7217 now,
7218 self.is_server,
7219 &self.trace_id,
7220 );
7221
7222 self.lost_count += lost_packets;
7223 self.lost_bytes += lost_bytes as u64;
7224
7225 qlog_with_type!(QLOG_METRICS, self.qlog, q, {
7226 p.recovery.maybe_qlog(q, now);
7227 });
7228 }
7229 }
7230 }
7231
7232 // Notify timeout events to the application.
7233 self.paths.notify_failed_validations();
7234
7235 // If the active path failed, try to find a new candidate.
7236 if self.paths.get_active_path_id().is_err() {
7237 match self.paths.find_candidate_path() {
7238 Some(pid) => {
7239 if self.set_active_path(pid, now).is_err() {
7240 // The connection cannot continue.
7241 self.mark_closed();
7242 }
7243 }
7244
7245 // The connection cannot continue.
7246 None => {
7247 self.mark_closed();
7248 }
7249 }
7250 }
7251 }
7252
7253 /// Requests the stack to perform path validation of the proposed 4-tuple.
7254 ///
7255 /// Probing new paths requires spare Connection IDs at both the host and the
7256 /// peer sides. If it is not the case, it raises an [`OutOfIdentifiers`].
7257 ///
7258 /// The probing of new addresses can only be done by the client. The server
7259 /// can only probe network paths that were previously advertised by
7260 /// [`PathEvent::New`]. If the server tries to probe such an unseen network
7261 /// path, this call raises an [`InvalidState`].
7262 ///
7263 /// The caller might also want to probe an existing path. In such case, it
7264 /// triggers a PATH_CHALLENGE frame, but it does not require spare CIDs.
7265 ///
7266 /// A server always probes a new path it observes. Calling this method is
7267 /// hence not required to validate a new path. However, a server can still
7268 /// request an additional path validation of the proposed 4-tuple.
7269 ///
7270 /// Calling this method several times before calling [`send()`] or
7271 /// [`send_on_path()`] results in a single probe being generated. An
7272 /// application wanting to send multiple in-flight probes must call this
7273 /// method again after having sent packets.
7274 ///
7275 /// Returns the Destination Connection ID sequence number associated to that
7276 /// path.
7277 ///
7278 /// [`PathEvent::New`]: enum.PathEvent.html#variant.New
7279 /// [`OutOfIdentifiers`]: enum.Error.html#OutOfIdentifiers
7280 /// [`InvalidState`]: enum.Error.html#InvalidState
7281 /// [`send()`]: struct.Connection.html#method.send
7282 /// [`send_on_path()`]: struct.Connection.html#method.send_on_path
7283 pub fn probe_path(&mut self, local_addr: SocketAddr, peer_addr: SocketAddr) -> Result<u64> {
7284 // We may want to probe an existing path.
7285 let pid = match self.paths.path_id_from_addrs(&(local_addr, peer_addr)) {
7286 Some(pid) => pid,
7287 None => self.create_path_on_client(local_addr, peer_addr)?,
7288 };
7289
7290 let path = self.paths.get_mut(pid)?;
7291 path.request_validation();
7292
7293 path.active_dcid_seq.ok_or(Error::InvalidState)
7294 }
7295
7296 /// Migrates the connection to a new local address `local_addr`.
7297 ///
7298 /// The behavior is similar to [`migrate()`], with the nuance that the
7299 /// connection only changes the local address, but not the peer one.
7300 ///
7301 /// See [`migrate()`] for the full specification of this method.
7302 ///
7303 /// [`migrate()`]: struct.Connection.html#method.migrate
7304 pub fn migrate_source(&mut self, local_addr: SocketAddr) -> Result<u64> {
7305 let peer_addr = self.paths.get_active()?.peer_addr();
7306 self.migrate(local_addr, peer_addr)
7307 }
7308
7309 /// Migrates the connection over the given network path between `local_addr`
7310 /// and `peer_addr`.
7311 ///
7312 /// Connection migration can only be initiated by the client. Calling this
7313 /// method as a server returns [`InvalidState`].
7314 ///
7315 /// To initiate voluntary migration, there should be enough Connection IDs
7316 /// at both sides. If this requirement is not satisfied, this call returns
7317 /// [`OutOfIdentifiers`].
7318 ///
7319 /// Returns the Destination Connection ID associated to that migrated path.
7320 ///
7321 /// [`OutOfIdentifiers`]: enum.Error.html#OutOfIdentifiers
7322 /// [`InvalidState`]: enum.Error.html#InvalidState
7323 pub fn migrate(&mut self, local_addr: SocketAddr, peer_addr: SocketAddr) -> Result<u64> {
7324 if self.is_server {
7325 return Err(Error::InvalidState);
7326 }
7327
7328 // If the path already exists, mark it as the active one.
7329 let (pid, dcid_seq) =
7330 if let Some(pid) = self.paths.path_id_from_addrs(&(local_addr, peer_addr)) {
7331 let path = self.paths.get_mut(pid)?;
7332
7333 // If it is already active, do nothing.
7334 if path.active() {
7335 return path.active_dcid_seq.ok_or(Error::OutOfIdentifiers);
7336 }
7337
7338 // Ensures that a Source Connection ID has been dedicated to this
7339 // path, or a free one is available. This is only required if the
7340 // host uses non-zero length Source Connection IDs.
7341 if !self.ids.zero_length_scid()
7342 && path.active_scid_seq.is_none()
7343 && self.ids.available_scids() == 0
7344 {
7345 return Err(Error::OutOfIdentifiers);
7346 }
7347
7348 // Ensures that the migrated path has a Destination Connection ID.
7349 let dcid_seq = if let Some(dcid_seq) = path.active_dcid_seq {
7350 dcid_seq
7351 } else {
7352 let dcid_seq = self
7353 .ids
7354 .lowest_available_dcid_seq()
7355 .ok_or(Error::OutOfIdentifiers)?;
7356
7357 self.ids.link_dcid_to_path_id(dcid_seq, pid)?;
7358 path.active_dcid_seq = Some(dcid_seq);
7359
7360 dcid_seq
7361 };
7362
7363 (pid, dcid_seq)
7364 } else {
7365 let pid = self.create_path_on_client(local_addr, peer_addr)?;
7366
7367 let dcid_seq = self
7368 .paths
7369 .get(pid)?
7370 .active_dcid_seq
7371 .ok_or(Error::InvalidState)?;
7372
7373 (pid, dcid_seq)
7374 };
7375
7376 // Change the active path.
7377 self.set_active_path(pid, Instant::now())?;
7378
7379 Ok(dcid_seq)
7380 }
7381
7382 /// Provides additional source Connection IDs that the peer can use to reach
7383 /// this host.
7384 ///
7385 /// This triggers sending NEW_CONNECTION_ID frames if the provided Source
7386 /// Connection ID is not already present. In the case the caller tries to
7387 /// reuse a Connection ID with a different reset token, this raises an
7388 /// `InvalidState`.
7389 ///
7390 /// At any time, the peer cannot have more Destination Connection IDs than
7391 /// the maximum number of active Connection IDs it negotiated. In such case
7392 /// (i.e., when [`scids_left()`] returns 0), if the host agrees to
7393 /// request the removal of previous connection IDs, it sets the
7394 /// `retire_if_needed` parameter. Otherwise, an [`IdLimit`] is returned.
7395 ///
7396 /// Note that setting `retire_if_needed` does not prevent this function from
7397 /// returning an [`IdLimit`] in the case the caller wants to retire still
7398 /// unannounced Connection IDs.
7399 ///
7400 /// The caller is responsible for ensuring that the provided `scid` is not
7401 /// repeated several times over the connection. quiche ensures that as long
7402 /// as the provided Connection ID is still in use (i.e., not retired), it
7403 /// does not assign a different sequence number.
7404 ///
7405 /// Note that if the host uses zero-length Source Connection IDs, it cannot
7406 /// advertise Source Connection IDs and calling this method returns an
7407 /// [`InvalidState`].
7408 ///
7409 /// Returns the sequence number associated to the provided Connection ID.
7410 ///
7411 /// [`scids_left()`]: struct.Connection.html#method.scids_left
7412 /// [`IdLimit`]: enum.Error.html#IdLimit
7413 /// [`InvalidState`]: enum.Error.html#InvalidState
7414 pub fn new_scid(
7415 &mut self,
7416 scid: &ConnectionId,
7417 reset_token: u128,
7418 retire_if_needed: bool,
7419 ) -> Result<u64> {
7420 self.ids.new_scid(
7421 scid.to_vec().into(),
7422 Some(reset_token),
7423 true,
7424 None,
7425 retire_if_needed,
7426 )
7427 }
7428
7429 /// Returns the number of source Connection IDs that are active. This is
7430 /// only meaningful if the host uses non-zero length Source Connection IDs.
7431 pub fn active_scids(&self) -> usize {
7432 self.ids.active_source_cids()
7433 }
7434
7435 /// Returns the number of additional source Connection IDs that can be
7436 /// provided to the peer without exceeding the limit it advertised.
7437 ///
7438 /// The limit is the minimum of the locally configured active connection
7439 /// ID limit and the one sent by the peer.
7440 ///
7441 /// Returns `0` when the peer's limit is already reached or temporarily
7442 /// exceeded (e.g. during a SCID rotation where a retirement is in
7443 /// flight and `active_scids()` transiently exceeds the advertised
7444 /// limit).
7445 ///
7446 /// To obtain the maximum possible value allowed by the peer an application
7447 /// can instead inspect the [`peer_active_conn_id_limit`] value.
7448 ///
7449 /// [`peer_active_conn_id_limit`]: struct.Stats.html#structfield.peer_active_conn_id_limit
7450 #[inline]
7451 pub fn scids_left(&self) -> usize {
7452 let max_active_source_cids = cmp::min(
7453 self.peer_transport_params.active_conn_id_limit,
7454 self.local_transport_params.active_conn_id_limit,
7455 ) as usize;
7456
7457 max_active_source_cids.saturating_sub(self.active_scids())
7458 }
7459
7460 /// Requests the retirement of the destination Connection ID used by the
7461 /// host to reach its peer.
7462 ///
7463 /// This triggers sending RETIRE_CONNECTION_ID frames.
7464 ///
7465 /// If the application tries to retire a non-existing Destination Connection
7466 /// ID sequence number, or if it uses zero-length Destination Connection ID,
7467 /// this method returns an [`InvalidState`].
7468 ///
7469 /// At any time, the host must have at least one Destination ID. If the
7470 /// application tries to retire the last one, or if the caller tries to
7471 /// retire the destination Connection ID used by the current active path
7472 /// while having neither spare Destination Connection IDs nor validated
7473 /// network paths, this method returns an [`OutOfIdentifiers`]. This
7474 /// behavior prevents the caller from stalling the connection due to the
7475 /// lack of validated path to send non-probing packets.
7476 ///
7477 /// [`InvalidState`]: enum.Error.html#InvalidState
7478 /// [`OutOfIdentifiers`]: enum.Error.html#OutOfIdentifiers
7479 pub fn retire_dcid(&mut self, dcid_seq: u64) -> Result<()> {
7480 if self.ids.zero_length_dcid() {
7481 return Err(Error::InvalidState);
7482 }
7483
7484 let active_path_dcid_seq = self
7485 .paths
7486 .get_active()?
7487 .active_dcid_seq
7488 .ok_or(Error::InvalidState)?;
7489
7490 let active_path_id = self.paths.get_active_path_id()?;
7491
7492 if active_path_dcid_seq == dcid_seq
7493 && self.ids.lowest_available_dcid_seq().is_none()
7494 && !self
7495 .paths
7496 .iter()
7497 .any(|(pid, p)| pid != active_path_id && p.usable())
7498 {
7499 return Err(Error::OutOfIdentifiers);
7500 }
7501
7502 if let Some(pid) = self.ids.retire_dcid(dcid_seq)? {
7503 // The retired Destination CID was associated to a given path. Let's
7504 // find an available DCID to associate to that path.
7505 let path = self.paths.get_mut(pid)?;
7506 let dcid_seq = self.ids.lowest_available_dcid_seq();
7507
7508 if let Some(dcid_seq) = dcid_seq {
7509 self.ids.link_dcid_to_path_id(dcid_seq, pid)?;
7510 }
7511
7512 path.active_dcid_seq = dcid_seq;
7513 }
7514
7515 Ok(())
7516 }
7517
7518 /// Processes path-specific events.
7519 ///
7520 /// On success it returns a [`PathEvent`], or `None` when there are no
7521 /// events to report. Please refer to [`PathEvent`] for the exhaustive event
7522 /// list.
7523 ///
7524 /// Note that all events are edge-triggered, meaning that once reported they
7525 /// will not be reported again by calling this method again, until the event
7526 /// is re-armed.
7527 ///
7528 /// [`PathEvent`]: enum.PathEvent.html
7529 pub fn path_event_next(&mut self) -> Option<PathEvent> {
7530 self.paths.pop_event()
7531 }
7532
7533 /// Returns the number of source Connection IDs that are retired.
7534 pub fn retired_scids(&self) -> usize {
7535 self.ids.retired_source_cids()
7536 }
7537
7538 /// Returns a source `ConnectionId` that has been retired.
7539 ///
7540 /// On success it returns a [`ConnectionId`], or `None` when there are no
7541 /// more retired connection IDs.
7542 ///
7543 /// [`ConnectionId`]: struct.ConnectionId.html
7544 pub fn retired_scid_next(&mut self) -> Option<ConnectionId<'static>> {
7545 self.ids.pop_retired_scid()
7546 }
7547
7548 /// Returns the number of spare Destination Connection IDs, i.e.,
7549 /// Destination Connection IDs that are still unused.
7550 ///
7551 /// Note that this function returns 0 if the host uses zero length
7552 /// Destination Connection IDs.
7553 pub fn available_dcids(&self) -> usize {
7554 self.ids.available_dcids()
7555 }
7556
7557 /// Returns an iterator over destination `SockAddr`s whose association
7558 /// with `from` forms a known QUIC path on which packets can be sent to.
7559 ///
7560 /// This function is typically used in combination with [`send_on_path()`].
7561 ///
7562 /// Note that the iterator includes all the possible combination of
7563 /// destination `SockAddr`s, even those whose sending is not required now.
7564 /// In other words, this is another way for the application to recall from
7565 /// past [`PathEvent::New`] events.
7566 ///
7567 /// [`PathEvent::New`]: enum.PathEvent.html#variant.New
7568 /// [`send_on_path()`]: struct.Connection.html#method.send_on_path
7569 ///
7570 /// ## Examples:
7571 ///
7572 /// ```no_run
7573 /// # let mut out = [0; 512];
7574 /// # let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
7575 /// # let mut config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;
7576 /// # let scid = quiche::ConnectionId::from_ref(&[0xba; 16]);
7577 /// # let local = socket.local_addr().unwrap();
7578 /// # let peer = "127.0.0.1:1234".parse().unwrap();
7579 /// # let mut conn = quiche::accept(&scid, None, local, peer, &mut config)?;
7580 /// // Iterate over possible destinations for the given local `SockAddr`.
7581 /// for dest in conn.paths_iter(local) {
7582 /// loop {
7583 /// let (write, send_info) =
7584 /// match conn.send_on_path(&mut out, Some(local), Some(dest)) {
7585 /// Ok(v) => v,
7586 ///
7587 /// Err(quiche::Error::Done) => {
7588 /// // Done writing for this destination.
7589 /// break;
7590 /// },
7591 ///
7592 /// Err(e) => {
7593 /// // An error occurred, handle it.
7594 /// break;
7595 /// },
7596 /// };
7597 ///
7598 /// socket.send_to(&out[..write], &send_info.to).unwrap();
7599 /// }
7600 /// }
7601 /// # Ok::<(), quiche::Error>(())
7602 /// ```
7603 #[inline]
7604 pub fn paths_iter(&self, from: SocketAddr) -> SocketAddrIter {
7605 // Instead of trying to identify whether packets will be sent on the
7606 // given 4-tuple, simply filter paths that cannot be used.
7607 SocketAddrIter {
7608 sockaddrs: self
7609 .paths
7610 .iter()
7611 .filter(|(_, p)| p.active_dcid_seq.is_some())
7612 .filter(|(_, p)| p.usable() || p.probing_required())
7613 .filter(|(_, p)| p.local_addr() == from)
7614 .map(|(_, p)| p.peer_addr())
7615 .collect(),
7616
7617 index: 0,
7618 }
7619 }
7620
7621 /// Closes the connection with the given error and reason.
7622 ///
7623 /// The `app` parameter specifies whether an application close should be
7624 /// sent to the peer. Otherwise a normal connection close is sent.
7625 ///
7626 /// If `app` is true but the connection is not in a state that is safe to
7627 /// send an application error (not established nor in early data), in
7628 /// accordance with [RFC
7629 /// 9000](https://www.rfc-editor.org/rfc/rfc9000.html#section-10.2.3-3), the
7630 /// error code is changed to APPLICATION_ERROR and the reason phrase is
7631 /// cleared.
7632 ///
7633 /// Returns [`Done`] if the connection had already been closed.
7634 ///
7635 /// Note that the connection will not be closed immediately. An application
7636 /// should continue calling the [`recv()`], [`send()`], [`timeout()`] and
7637 /// [`on_timeout()`] methods as normal, until the [`is_closed()`] method
7638 /// returns `true`.
7639 ///
7640 /// [`Done`]: enum.Error.html#variant.Done
7641 /// [`recv()`]: struct.Connection.html#method.recv
7642 /// [`send()`]: struct.Connection.html#method.send
7643 /// [`timeout()`]: struct.Connection.html#method.timeout
7644 /// [`on_timeout()`]: struct.Connection.html#method.on_timeout
7645 /// [`is_closed()`]: struct.Connection.html#method.is_closed
7646 pub fn close(&mut self, app: bool, err: u64, reason: &[u8]) -> Result<()> {
7647 if self.is_closed() || self.is_draining() {
7648 return Err(Error::Done);
7649 }
7650
7651 if self.local_error.is_some() {
7652 return Err(Error::Done);
7653 }
7654
7655 let is_safe_to_send_app_data = self.is_established() || self.is_in_early_data();
7656
7657 if app && !is_safe_to_send_app_data {
7658 // Clear error information.
7659 self.local_error = Some(ConnectionError {
7660 is_app: false,
7661 error_code: 0x0c,
7662 reason: vec![],
7663 });
7664 } else {
7665 self.local_error = Some(ConnectionError {
7666 is_app: app,
7667 error_code: err,
7668 reason: reason.to_vec(),
7669 });
7670 }
7671
7672 // Close immediately if no packet was processed successfully.
7673 if self.recv_count == 0 {
7674 self.mark_closed();
7675 }
7676
7677 Ok(())
7678 }
7679
7680 /// Returns a string uniquely representing the connection.
7681 ///
7682 /// This can be used for logging purposes to differentiate between multiple
7683 /// connections.
7684 #[inline]
7685 pub fn trace_id(&self) -> &str {
7686 &self.trace_id
7687 }
7688
7689 /// Returns the negotiated ALPN protocol.
7690 ///
7691 /// If no protocol has been negotiated, the returned value is empty.
7692 #[inline]
7693 pub fn application_proto(&self) -> &[u8] {
7694 self.alpn.as_ref()
7695 }
7696
7697 /// Returns the server name requested by the client.
7698 #[inline]
7699 pub fn server_name(&self) -> Option<&str> {
7700 self.handshake.server_name()
7701 }
7702
7703 /// Returns the peer's leaf certificate (if any) as a DER-encoded buffer.
7704 #[inline]
7705 pub fn peer_cert(&self) -> Option<&[u8]> {
7706 self.handshake.peer_cert()
7707 }
7708
7709 /// Returns the negotiated TLS 1.3 cipher suite as its IANA name, once the
7710 /// handshake has completed. QUIC always negotiates TLS 1.3 (RFC 9001 §4.2),
7711 /// so the result is one of the three TLS 1.3 AEAD suites.
7712 #[inline]
7713 pub fn cipher(&self) -> Option<&'static str> {
7714 use crate::crypto::Algorithm;
7715 Some(match self.handshake.cipher()? {
7716 Algorithm::AES128_GCM => "TLS_AES_128_GCM_SHA256",
7717 Algorithm::AES256_GCM => "TLS_AES_256_GCM_SHA384",
7718 Algorithm::ChaCha20_Poly1305 => "TLS_CHACHA20_POLY1305_SHA256",
7719 })
7720 }
7721
7722 /// Returns the peer's certificate chain (if any) as a vector of DER-encoded
7723 /// buffers.
7724 ///
7725 /// The certificate at index 0 is the peer's leaf certificate, the other
7726 /// certificates (if any) are the chain certificate authorities used to
7727 /// sign the leaf certificate.
7728 #[inline]
7729 pub fn peer_cert_chain(&self) -> Option<Vec<&[u8]>> {
7730 self.handshake.peer_cert_chain()
7731 }
7732
7733 /// Returns the serialized cryptographic session for the connection.
7734 ///
7735 /// This can be used by a client to cache a connection's session, and resume
7736 /// it later using the [`set_session()`] method.
7737 ///
7738 /// [`set_session()`]: struct.Connection.html#method.set_session
7739 #[inline]
7740 pub fn session(&self) -> Option<&[u8]> {
7741 self.session.as_deref()
7742 }
7743
7744 /// Returns the source connection ID.
7745 ///
7746 /// When there are multiple IDs, and if there is an active path, the ID used
7747 /// on that path is returned. Otherwise the oldest ID is returned.
7748 ///
7749 /// Note that the value returned can change throughout the connection's
7750 /// lifetime.
7751 #[inline]
7752 pub fn source_id(&self) -> ConnectionId<'_> {
7753 if let Ok(path) = self.paths.get_active() {
7754 if let Some(active_scid_seq) = path.active_scid_seq {
7755 if let Ok(e) = self.ids.get_scid(active_scid_seq) {
7756 return ConnectionId::from_ref(e.cid.as_ref());
7757 }
7758 }
7759 }
7760
7761 let e = self.ids.oldest_scid();
7762 ConnectionId::from_ref(e.cid.as_ref())
7763 }
7764
7765 /// Returns all active source connection IDs.
7766 ///
7767 /// An iterator is returned for all active IDs (i.e. ones that have not
7768 /// been explicitly retired yet).
7769 #[inline]
7770 pub fn source_ids(&self) -> impl Iterator<Item = &ConnectionId<'_>> {
7771 self.ids.scids_iter()
7772 }
7773
7774 /// Returns the destination connection ID.
7775 ///
7776 /// Note that the value returned can change throughout the connection's
7777 /// lifetime.
7778 #[inline]
7779 pub fn destination_id(&self) -> ConnectionId<'_> {
7780 if let Ok(path) = self.paths.get_active() {
7781 if let Some(active_dcid_seq) = path.active_dcid_seq {
7782 if let Ok(e) = self.ids.get_dcid(active_dcid_seq) {
7783 return ConnectionId::from_ref(e.cid.as_ref());
7784 }
7785 }
7786 }
7787
7788 let e = self.ids.oldest_dcid();
7789 ConnectionId::from_ref(e.cid.as_ref())
7790 }
7791
7792 /// Returns the PMTU for the active path if it exists.
7793 ///
7794 /// This requires no additonal packets to be sent but simply checks if PMTUD
7795 /// has completed and has found a valid PMTU.
7796 #[inline]
7797 pub fn pmtu(&self) -> Option<usize> {
7798 if let Ok(path) = self.paths.get_active() {
7799 path.pmtud.as_ref().and_then(|pmtud| pmtud.get_pmtu())
7800 } else {
7801 None
7802 }
7803 }
7804
7805 /// Revalidates the PMTU for the active path by sending a new probe packet
7806 /// of PMTU size. If the probe is dropped PMTUD will restart and find a new
7807 /// valid PMTU.
7808 ///
7809 /// If revalidation invalidates a previously discovered larger size, a
7810 /// [`PathEvent::PmtuUpdated`] event is queued with QUIC's minimum packet
7811 /// size. Further events report larger sizes as probes validate them.
7812 #[inline]
7813 pub fn revalidate_pmtu(&mut self) {
7814 let Ok(active_path) = self.paths.get_active_mut() else {
7815 return;
7816 };
7817
7818 let local = active_path.local_addr();
7819 let peer = active_path.peer_addr();
7820 let Some(pmtud) = active_path.pmtud.as_mut() else {
7821 return;
7822 };
7823
7824 let old_pmtu = pmtud.get_current_mtu();
7825 pmtud.revalidate_pmtu();
7826
7827 let Some(event) = path::pmtu_event(local, peer, old_pmtu, pmtud.get_current_mtu()) else {
7828 return;
7829 };
7830
7831 self.paths.notify_event(event);
7832 }
7833
7834 /// Returns true if the connection handshake is complete.
7835 #[inline]
7836 pub fn is_established(&self) -> bool {
7837 self.handshake_completed
7838 }
7839
7840 /// Returns true if the connection is resumed.
7841 #[inline]
7842 pub fn is_resumed(&self) -> bool {
7843 self.handshake.is_resumed()
7844 }
7845
7846 /// Returns true if the connection has a pending handshake that has
7847 /// progressed enough to send or receive early data.
7848 #[inline]
7849 pub fn is_in_early_data(&self) -> bool {
7850 self.handshake.is_in_early_data()
7851 }
7852
7853 /// Returns the early data reason for the connection.
7854 ///
7855 /// This status can be useful for logging and debugging. See [BoringSSL]
7856 /// documentation for a definition of the reasons.
7857 ///
7858 /// [BoringSSL]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#ssl_early_data_reason_t
7859 #[inline]
7860 pub fn early_data_reason(&self) -> u32 {
7861 self.handshake.early_data_reason()
7862 }
7863
7864 /// Returns whether there is stream or DATAGRAM data available to read.
7865 #[inline]
7866 pub fn is_readable(&self) -> bool {
7867 self.streams.has_readable() || self.dgram_recv_front_len().is_some()
7868 }
7869
7870 /// Returns whether the network path with local address `from` and remote
7871 /// address `peer` has been validated.
7872 ///
7873 /// If the 4-tuple does not exist over the connection, returns an
7874 /// [`InvalidState`].
7875 ///
7876 /// [`InvalidState`]: enum.Error.html#variant.InvalidState
7877 pub fn is_path_validated(&self, from: SocketAddr, to: SocketAddr) -> Result<bool> {
7878 let pid = self
7879 .paths
7880 .path_id_from_addrs(&(from, to))
7881 .ok_or(Error::InvalidState)?;
7882
7883 Ok(self.paths.get(pid)?.validated())
7884 }
7885
7886 /// Returns true if the connection is draining.
7887 ///
7888 /// If this returns `true`, the connection object cannot yet be dropped, but
7889 /// no new application data can be sent or received. An application should
7890 /// continue calling the [`recv()`], [`timeout()`], and [`on_timeout()`]
7891 /// methods as normal, until the [`is_closed()`] method returns `true`.
7892 ///
7893 /// In contrast, once `is_draining()` returns `true`, calling [`send()`]
7894 /// is not required because no new outgoing packets will be generated.
7895 ///
7896 /// [`recv()`]: struct.Connection.html#method.recv
7897 /// [`send()`]: struct.Connection.html#method.send
7898 /// [`timeout()`]: struct.Connection.html#method.timeout
7899 /// [`on_timeout()`]: struct.Connection.html#method.on_timeout
7900 /// [`is_closed()`]: struct.Connection.html#method.is_closed
7901 #[inline]
7902 pub fn is_draining(&self) -> bool {
7903 self.draining_timer.is_some()
7904 }
7905
7906 /// Returns true if the connection is closed.
7907 ///
7908 /// If this returns true, the connection object can be dropped.
7909 #[inline]
7910 pub fn is_closed(&self) -> bool {
7911 self.closed
7912 }
7913
7914 /// Returns true if the connection was closed due to the idle timeout.
7915 #[inline]
7916 pub fn is_timed_out(&self) -> bool {
7917 self.timed_out
7918 }
7919
7920 /// Returns the error received from the peer, if any.
7921 ///
7922 /// Note that a `Some` return value does not necessarily imply
7923 /// [`is_closed()`] or any other connection state.
7924 ///
7925 /// [`is_closed()`]: struct.Connection.html#method.is_closed
7926 #[inline]
7927 pub fn peer_error(&self) -> Option<&ConnectionError> {
7928 self.peer_error.as_ref()
7929 }
7930
7931 /// Returns the error [`close()`] was called with, or internally
7932 /// created quiche errors, if any.
7933 ///
7934 /// Note that a `Some` return value does not necessarily imply
7935 /// [`is_closed()`] or any other connection state.
7936 /// `Some` also does not guarantee that the error has been sent to
7937 /// or received by the peer.
7938 ///
7939 /// [`close()`]: struct.Connection.html#method.close
7940 /// [`is_closed()`]: struct.Connection.html#method.is_closed
7941 #[inline]
7942 pub fn local_error(&self) -> Option<&ConnectionError> {
7943 self.local_error.as_ref()
7944 }
7945
7946 /// Collects and returns statistics about the connection.
7947 #[inline]
7948 pub fn stats(&self) -> Stats {
7949 Stats {
7950 recv: self.recv_count,
7951 sent: self.sent_count,
7952 lost: self.lost_count,
7953 spurious_lost: self.spurious_lost_count,
7954 retrans: self.retrans_count,
7955 sent_bytes: self.sent_bytes,
7956 recv_bytes: self.recv_bytes,
7957 acked_bytes: self.acked_bytes,
7958 lost_bytes: self.lost_bytes,
7959 stream_retrans_bytes: self.stream_retrans_bytes,
7960 dgram_recv: self.dgram_recv_count,
7961 dgram_sent: self.dgram_sent_count,
7962 paths_count: self.paths.len(),
7963 reset_stream_count_local: self.reset_stream_local_count,
7964 stopped_stream_count_local: self.stopped_stream_local_count,
7965 reset_stream_count_remote: self.reset_stream_remote_count,
7966 stopped_stream_count_remote: self.stopped_stream_remote_count,
7967 data_blocked_sent_count: self.data_blocked_sent_count,
7968 stream_data_blocked_sent_count: self.stream_data_blocked_sent_count,
7969 data_blocked_recv_count: self.data_blocked_recv_count,
7970 stream_data_blocked_recv_count: self.stream_data_blocked_recv_count,
7971 streams_blocked_bidi_recv_count: self.streams_blocked_bidi_recv_count,
7972 streams_blocked_uni_recv_count: self.streams_blocked_uni_recv_count,
7973 path_challenge_rx_count: self.path_challenge_rx_count,
7974 amplification_limited_count: self.amplification_limited_count,
7975 bytes_in_flight_duration: self.bytes_in_flight_duration(),
7976 tx_buffered_state: if self.streams.tx_buffered_is_consistent() {
7977 TxBufferTrackingState::Ok
7978 } else {
7979 TxBufferTrackingState::Inconsistent
7980 },
7981 }
7982 }
7983
7984 /// Returns the sum of the durations when each path in the
7985 /// connection was actively sending bytes or waiting for acks.
7986 /// Note that this could result in a duration that is longer than
7987 /// the actual connection duration in cases where multiple paths
7988 /// are active for extended periods of time. In practice only 1
7989 /// path is typically active at a time.
7990 /// TODO revisit computation if in the future multiple paths are
7991 /// often active at the same time.
7992 fn bytes_in_flight_duration(&self) -> Duration {
7993 self.paths.iter().fold(Duration::ZERO, |acc, (_, path)| {
7994 acc + path.bytes_in_flight_duration()
7995 })
7996 }
7997
7998 /// Returns reference to peer's transport parameters. Returns `None` if we
7999 /// have not yet processed the peer's transport parameters.
8000 pub fn peer_transport_params(&self) -> Option<&TransportParams> {
8001 if !self.parsed_peer_transport_params {
8002 return None;
8003 }
8004
8005 Some(&self.peer_transport_params)
8006 }
8007
8008 /// Collects and returns statistics about each known path for the
8009 /// connection.
8010 pub fn path_stats(&self) -> impl Iterator<Item = PathStats> + '_ {
8011 self.paths.iter().map(|(_, p)| p.stats())
8012 }
8013
8014 /// Returns whether or not this is a server-side connection.
8015 pub fn is_server(&self) -> bool {
8016 self.is_server
8017 }
8018
8019 #[cfg(feature = "boringssl-bssl-crate")]
8020 pub fn ssl_mut(&mut self) -> &mut leyline_bssl::ssl::SslRef {
8021 self.handshake.ssl_mut()
8022 }
8023
8024 fn encode_transport_params(&mut self) -> Result<()> {
8025 let version = self.version;
8026
8027 let plan = self.transport_params_plan.as_ref().map(|plan| {
8028 plan.iter()
8029 .map(|entry| match entry {
8030 TransportParamEntry::Raw(0x0011, value) if value.len() >= 4 => {
8031 let mut value = value.clone();
8032 value[..4].copy_from_slice(&version.to_be_bytes());
8033 TransportParamEntry::Raw(0x0011, value)
8034 }
8035
8036 other => other.clone(),
8037 })
8038 .collect::<Vec<_>>()
8039 });
8040
8041 self.handshake.set_quic_transport_params(
8042 &self.local_transport_params,
8043 self.is_server,
8044 plan.as_deref(),
8045 )
8046 }
8047
8048 fn check_version_information(&self, info: Option<&[u32]>) -> Result<()> {
8049 let Some((&chosen, available)) = info.and_then(|info| info.split_first()) else {
8050 if self.did_compatible_version_negotiation
8051 || (self.did_version_negotiation && !self.compatible_versions.is_empty())
8052 {
8053 return Err(Error::VersionNegotiation);
8054 }
8055
8056 return Ok(());
8057 };
8058
8059 if chosen != self.version {
8060 return Err(Error::VersionNegotiation);
8061 }
8062
8063 if self.did_version_negotiation {
8064 let preferred = self
8065 .compatible_versions
8066 .iter()
8067 .take_while(|&&v| v != self.version);
8068
8069 for v in preferred {
8070 if available.contains(v) {
8071 return Err(Error::VersionNegotiation);
8072 }
8073 }
8074 }
8075
8076 Ok(())
8077 }
8078
8079 fn parse_peer_transport_params(&mut self, peer_params: TransportParams) -> Result<()> {
8080 // Validate initial_source_connection_id.
8081 match &peer_params.initial_source_connection_id {
8082 Some(v) if v != &self.destination_id() => return Err(Error::InvalidTransportParam),
8083
8084 Some(_) => (),
8085
8086 // initial_source_connection_id must be sent by
8087 // both endpoints.
8088 None => return Err(Error::InvalidTransportParam),
8089 }
8090
8091 // Validate original_destination_connection_id.
8092 if let Some(odcid) = &self.odcid {
8093 match &peer_params.original_destination_connection_id {
8094 Some(v) if v != odcid => return Err(Error::InvalidTransportParam),
8095
8096 Some(_) => (),
8097
8098 // original_destination_connection_id must be
8099 // sent by the server.
8100 None if !self.is_server => return Err(Error::InvalidTransportParam),
8101
8102 None => (),
8103 }
8104 }
8105
8106 // Validate retry_source_connection_id.
8107 if let Some(rscid) = &self.rscid {
8108 match &peer_params.retry_source_connection_id {
8109 Some(v) if v != rscid => return Err(Error::InvalidTransportParam),
8110
8111 Some(_) => (),
8112
8113 // retry_source_connection_id must be sent by
8114 // the server.
8115 None => return Err(Error::InvalidTransportParam),
8116 }
8117 }
8118
8119 if !self.is_server {
8120 self.check_version_information(peer_params.version_information.as_deref())?;
8121 }
8122
8123 self.process_peer_transport_params(peer_params)?;
8124
8125 self.parsed_peer_transport_params = true;
8126
8127 Ok(())
8128 }
8129
8130 fn process_peer_transport_params(&mut self, peer_params: TransportParams) -> Result<()> {
8131 self.max_tx_data = peer_params.initial_max_data;
8132
8133 // Update send capacity.
8134 self.update_tx_cap();
8135
8136 self.streams
8137 .update_peer_max_streams_bidi(peer_params.initial_max_streams_bidi);
8138 self.streams
8139 .update_peer_max_streams_uni(peer_params.initial_max_streams_uni);
8140
8141 let max_ack_delay = Duration::from_millis(peer_params.max_ack_delay);
8142
8143 self.recovery_config.max_ack_delay = max_ack_delay;
8144
8145 let active_path = self.paths.get_active_mut()?;
8146
8147 active_path.recovery.update_max_ack_delay(max_ack_delay);
8148
8149 if active_path
8150 .pmtud
8151 .as_ref()
8152 .map(|pmtud| pmtud.should_probe())
8153 .unwrap_or(false)
8154 {
8155 active_path.recovery.pmtud_update_max_datagram_size(
8156 active_path
8157 .pmtud
8158 .as_mut()
8159 .expect("PMTUD existence verified above")
8160 .get_probe_size()
8161 .min(peer_params.max_udp_payload_size as usize),
8162 );
8163 } else {
8164 active_path
8165 .recovery
8166 .update_max_datagram_size(peer_params.max_udp_payload_size as usize);
8167 }
8168
8169 // Record the max_active_conn_id parameter advertised by the peer.
8170 self.ids
8171 .set_source_conn_id_limit(peer_params.active_conn_id_limit);
8172
8173 self.peer_transport_params = peer_params;
8174
8175 Ok(())
8176 }
8177
8178 /// Continues the handshake.
8179 ///
8180 /// If the connection is already established, it does nothing.
8181 fn do_handshake(&mut self, now: Instant) -> Result<()> {
8182 let mut ex_data = tls::ExData {
8183 application_protos: &self.application_protos,
8184
8185 crypto_ctx: &mut self.crypto_ctx,
8186
8187 session: &mut self.session,
8188
8189 local_error: &mut self.local_error,
8190
8191 keylog: self.keylog.as_mut(),
8192
8193 trace_id: &self.trace_id,
8194
8195 local_transport_params: self.local_transport_params.clone(),
8196
8197 recovery_config: self.recovery_config,
8198
8199 tx_cap_factor: self.tx_cap_factor,
8200
8201 pmtud: None,
8202
8203 is_server: self.is_server,
8204
8205 version: self.version,
8206 };
8207
8208 if self.handshake_completed {
8209 return self.handshake.process_post_handshake(&mut ex_data);
8210 }
8211
8212 let handshake_needs_retry = match self.handshake.do_handshake(&mut ex_data) {
8213 Ok(_) => false,
8214 Err(Error::Done) => true,
8215 Err(e) => return Err(e),
8216 };
8217
8218 // BoringSSL reports success when entering early data before the
8219 // handshake completes. Apply callback configuration after either
8220 // non-fatal outcome so it is not lost on that path.
8221 if self
8222 .paths
8223 .get_active()
8224 .map(|p| p.can_reinit_recovery())
8225 .unwrap_or(false)
8226 {
8227 if ex_data.recovery_config != self.recovery_config {
8228 if let Ok(path) = self.paths.get_active_mut() {
8229 self.recovery_config = ex_data.recovery_config;
8230 path.reinit_recovery(&self.recovery_config);
8231 }
8232 }
8233
8234 if ex_data.tx_cap_factor != self.tx_cap_factor {
8235 self.tx_cap_factor = ex_data.tx_cap_factor;
8236 }
8237
8238 if let Some((discover, max_probes)) = ex_data.pmtud {
8239 self.paths.set_discover_pmtu_on_existing_paths(
8240 discover,
8241 self.recovery_config.max_send_udp_payload_size,
8242 max_probes,
8243 );
8244 }
8245
8246 if ex_data.local_transport_params != self.local_transport_params {
8247 self.streams
8248 .set_max_streams_bidi(ex_data.local_transport_params.initial_max_streams_bidi);
8249
8250 self.local_transport_params = ex_data.local_transport_params;
8251 }
8252 }
8253
8254 if handshake_needs_retry {
8255 // Try to parse transport parameters as soon as the first flight of
8256 // handshake data is processed.
8257 //
8258 // This is potentially dangerous as the handshake hasn't been
8259 // completed yet, though it's required to be able to send data in
8260 // 0.5 RTT.
8261 let raw_params = self.handshake.quic_transport_params();
8262
8263 if !self.parsed_peer_transport_params && !raw_params.is_empty() {
8264 let peer_params = TransportParams::decode(
8265 raw_params,
8266 self.is_server,
8267 self.peer_transport_params_track_unknown,
8268 )?;
8269
8270 self.parse_peer_transport_params(peer_params)?;
8271 }
8272
8273 return Ok(());
8274 }
8275
8276 self.handshake_completed = self.handshake.is_completed();
8277
8278 self.alpn = self.handshake.alpn_protocol().to_vec();
8279
8280 let raw_params = self.handshake.quic_transport_params();
8281
8282 if !self.parsed_peer_transport_params && !raw_params.is_empty() {
8283 let peer_params = TransportParams::decode(
8284 raw_params,
8285 self.is_server,
8286 self.peer_transport_params_track_unknown,
8287 )?;
8288
8289 self.parse_peer_transport_params(peer_params)?;
8290 }
8291
8292 if self.handshake_completed {
8293 // The handshake is considered confirmed at the server when the
8294 // handshake completes, at which point we can also drop the
8295 // handshake epoch.
8296 if self.is_server {
8297 self.handshake_confirmed = true;
8298
8299 self.drop_epoch_state(packet::Epoch::Handshake, now);
8300 }
8301
8302 // Once the handshake is completed there's no point in processing
8303 // 0-RTT packets anymore, so clear the buffer now.
8304 self.undecryptable_pkts.clear();
8305
8306 trace!(
8307 "{} connection established: proto={:?} cipher={:?} curve={:?} sigalg={:?} resumed={} {:?}",
8308 self.trace_id,
8309 std::str::from_utf8(self.application_proto()),
8310 self.handshake.cipher(),
8311 self.handshake.curve(),
8312 self.handshake.sigalg(),
8313 self.handshake.is_resumed(),
8314 self.peer_transport_params
8315 );
8316 }
8317
8318 Ok(())
8319 }
8320
8321 /// Selects the packet type for the next outgoing packet.
8322 fn write_pkt_type(&self, send_pid: usize) -> Result<Type> {
8323 // On error send packet in the latest epoch available, but only send
8324 // 1-RTT ones when the handshake is completed.
8325 if self
8326 .local_error
8327 .as_ref()
8328 .is_some_and(|conn_err| !conn_err.is_app)
8329 {
8330 let epoch = match self.handshake.write_level() {
8331 crypto::Level::Initial => packet::Epoch::Initial,
8332 crypto::Level::ZeroRTT => unreachable!(),
8333 crypto::Level::Handshake => packet::Epoch::Handshake,
8334 crypto::Level::OneRTT => packet::Epoch::Application,
8335 };
8336
8337 if !self.handshake_confirmed {
8338 match epoch {
8339 // Downgrade the epoch to Handshake as the handshake is not
8340 // completed yet.
8341 packet::Epoch::Application => return Ok(Type::Handshake),
8342
8343 // Downgrade the epoch to Initial as the remote peer might
8344 // not be able to decrypt handshake packets yet.
8345 packet::Epoch::Handshake
8346 if self.crypto_ctx[packet::Epoch::Initial].has_keys() =>
8347 {
8348 return Ok(Type::Initial);
8349 }
8350
8351 _ => (),
8352 };
8353 }
8354
8355 return Ok(Type::from_epoch(epoch));
8356 }
8357
8358 for &epoch in packet::Epoch::epochs(packet::Epoch::Initial..=packet::Epoch::Application) {
8359 let crypto_ctx = &self.crypto_ctx[epoch];
8360 let pkt_space = &self.pkt_num_spaces[epoch];
8361
8362 // Only send packets in a space when we have the send keys for it.
8363 if crypto_ctx.crypto_seal.is_none() {
8364 continue;
8365 }
8366
8367 // We are ready to send data for this packet number space.
8368 if crypto_ctx.data_available() || pkt_space.ready() {
8369 return Ok(Type::from_epoch(epoch));
8370 }
8371
8372 // There are lost frames in this packet number space.
8373 for (_, p) in self.paths.iter() {
8374 if p.recovery.has_lost_frames(epoch) {
8375 return Ok(Type::from_epoch(epoch));
8376 }
8377
8378 // We need to send PTO probe packets.
8379 if p.recovery.loss_probes(epoch) > 0 {
8380 return Ok(Type::from_epoch(epoch));
8381 }
8382 }
8383 }
8384
8385 // If there are flushable, almost full or blocked streams, use the
8386 // Application epoch.
8387 let send_path = self.paths.get(send_pid)?;
8388 if (self.is_established() || self.is_in_early_data())
8389 && (self.should_send_handshake_done()
8390 || self.flow_control.should_update_max_data()
8391 || self.should_send_max_data
8392 || self.blocked_limit.is_some()
8393 || self
8394 .streams_blocked_bidi_state
8395 .has_pending_stream_blocked_frame()
8396 || self
8397 .streams_blocked_uni_state
8398 .has_pending_stream_blocked_frame()
8399 || self.dgram_send_queue.has_pending()
8400 || self
8401 .local_error
8402 .as_ref()
8403 .is_some_and(|conn_err| conn_err.is_app)
8404 || self.should_send_max_streams_bidi
8405 || self.streams.should_update_max_streams_bidi()
8406 || self.should_send_max_streams_uni
8407 || self.streams.should_update_max_streams_uni()
8408 || self.streams.has_flushable()
8409 || self.streams.has_almost_full()
8410 || self.streams.has_blocked()
8411 || self.streams.has_reset()
8412 || self.streams.has_stopped()
8413 || self.ids.has_new_scids()
8414 || self.ids.has_retire_dcids()
8415 || send_path
8416 .pmtud
8417 .as_ref()
8418 .is_some_and(|pmtud| pmtud.should_probe())
8419 || send_path.needs_ack_eliciting
8420 || send_path.probing_required())
8421 {
8422 // Only clients can send 0-RTT packets.
8423 if !self.is_server && self.is_in_early_data() {
8424 return Ok(Type::ZeroRTT);
8425 }
8426
8427 return Ok(Type::Short);
8428 }
8429
8430 Err(Error::Done)
8431 }
8432
8433 /// Returns the mutable stream with the given ID if it exists, or creates
8434 /// a new one otherwise.
8435 fn get_or_create_stream(&mut self, id: u64, local: bool) -> Result<&mut stream::Stream<F>> {
8436 self.streams.get_or_create(
8437 id,
8438 &self.local_transport_params,
8439 &self.peer_transport_params,
8440 local,
8441 self.is_server,
8442 )
8443 }
8444
8445 /// Processes an incoming frame.
8446 fn process_frame(
8447 &mut self,
8448 frame: frame::Frame,
8449 hdr: &Header,
8450 recv_path_id: usize,
8451 epoch: packet::Epoch,
8452 now: Instant,
8453 ) -> Result<()> {
8454 trace!("{} rx frm {:?}", self.trace_id, frame);
8455
8456 match frame {
8457 frame::Frame::Padding { .. } => (),
8458
8459 frame::Frame::Ping { .. } => (),
8460
8461 frame::Frame::ACK {
8462 ranges, ack_delay, ..
8463 } => {
8464 let ack_delay = ack_delay
8465 .checked_mul(2_u64.pow(self.peer_transport_params.ack_delay_exponent as u32))
8466 .ok_or(Error::InvalidFrame)?;
8467
8468 if epoch == packet::Epoch::Handshake
8469 || (epoch == packet::Epoch::Application && self.is_established())
8470 {
8471 self.peer_verified_initial_address = true;
8472 }
8473
8474 let handshake_status = self.handshake_status();
8475
8476 let is_app_limited = self.delivery_rate_check_if_app_limited();
8477
8478 let largest_acked = ranges
8479 .last()
8480 .expect("ACK frames should always have at least one ack range");
8481
8482 for (_, p) in self.paths.iter_mut() {
8483 if self.pkt_num_spaces[epoch]
8484 .largest_tx_pkt_num
8485 .is_some_and(|largest_sent| largest_sent < largest_acked)
8486 {
8487 // https://www.rfc-editor.org/rfc/rfc9000#section-13.1
8488 // An endpoint SHOULD treat receipt of an acknowledgment
8489 // for a packet it did not send as
8490 // a connection error of type PROTOCOL_VIOLATION
8491 return Err(Error::InvalidAckRange);
8492 }
8493
8494 if is_app_limited {
8495 p.recovery.delivery_rate_update_app_limited(true);
8496 }
8497
8498 let OnAckReceivedOutcome {
8499 lost_packets,
8500 lost_bytes,
8501 acked_bytes,
8502 spurious_losses,
8503 } = p.recovery.on_ack_received(
8504 &ranges,
8505 ack_delay,
8506 epoch,
8507 handshake_status,
8508 now,
8509 self.pkt_num_manager.skip_pn(),
8510 &self.trace_id,
8511 )?;
8512
8513 let skip_pn = self.pkt_num_manager.skip_pn();
8514 let largest_acked = p.recovery.get_largest_acked_on_epoch(epoch);
8515
8516 // A higher ACK validates `skip_pn`.
8517 if let Some((largest_acked, skip_pn)) = largest_acked.zip(skip_pn) {
8518 if largest_acked > skip_pn {
8519 self.pkt_num_manager.set_skip_pn(None);
8520 }
8521 }
8522
8523 self.lost_count += lost_packets;
8524 self.lost_bytes += lost_bytes as u64;
8525 self.acked_bytes += acked_bytes as u64;
8526 self.spurious_lost_count += spurious_losses;
8527 }
8528 }
8529
8530 frame::Frame::ResetStream {
8531 stream_id,
8532 error_code,
8533 final_size,
8534 } => {
8535 // Peer can't send on our unidirectional streams.
8536 if !stream::is_bidi(stream_id) && stream::is_local(stream_id, self.is_server) {
8537 return Err(Error::InvalidStreamState(stream_id));
8538 }
8539
8540 let max_rx_data_left = self.max_rx_data() - self.rx_data;
8541
8542 // Get existing stream or create a new one, but if the stream
8543 // has already been closed and collected, ignore the frame.
8544 //
8545 // This can happen if e.g. an ACK frame is lost, and the peer
8546 // retransmits another frame before it realizes that the stream
8547 // is gone.
8548 //
8549 // Note that it makes it impossible to check if the frame is
8550 // illegal, since we have no state, but since we ignore the
8551 // frame, it should be fine.
8552 let stream = match self.get_or_create_stream(stream_id, false) {
8553 Ok(v) => v,
8554
8555 Err(Error::Done) => return Ok(()),
8556
8557 Err(e) => return Err(e),
8558 };
8559
8560 let was_readable = stream.is_readable();
8561 let priority_key = Arc::clone(&stream.priority_key);
8562
8563 let stream::RecvBufResetReturn {
8564 max_data_delta,
8565 consumed_flowcontrol,
8566 } = stream.recv.reset(error_code, final_size)?;
8567
8568 if max_data_delta > max_rx_data_left {
8569 return Err(Error::FlowControl);
8570 }
8571
8572 if !was_readable && stream.is_readable() {
8573 self.streams.insert_readable(&priority_key);
8574 }
8575
8576 self.rx_data += max_data_delta;
8577 // We dropped the receive buffer, return connection level
8578 // flow-control
8579 self.flow_control.add_consumed(consumed_flowcontrol);
8580
8581 self.reset_stream_remote_count = self.reset_stream_remote_count.saturating_add(1);
8582 }
8583
8584 frame::Frame::StopSending {
8585 stream_id,
8586 error_code,
8587 } => {
8588 // STOP_SENDING on a receive-only stream is a fatal error.
8589 if !stream::is_local(stream_id, self.is_server) && !stream::is_bidi(stream_id) {
8590 return Err(Error::InvalidStreamState(stream_id));
8591 }
8592
8593 // Get existing stream or create a new one, but if the stream
8594 // has already been closed and collected, ignore the frame.
8595 //
8596 // This can happen if e.g. an ACK frame is lost, and the peer
8597 // retransmits another frame before it realizes that the stream
8598 // is gone.
8599 //
8600 // Note that it makes it impossible to check if the frame is
8601 // illegal, since we have no state, but since we ignore the
8602 // frame, it should be fine.
8603 let stream = match self.get_or_create_stream(stream_id, false) {
8604 Ok(v) => v,
8605
8606 Err(Error::Done) => return Ok(()),
8607
8608 Err(e) => return Err(e),
8609 };
8610
8611 let was_writable = stream.is_writable();
8612
8613 let priority_key = Arc::clone(&stream.priority_key);
8614
8615 // Save the buffered length before stopping (stop clears the
8616 // buffer).
8617 let buffered_len = stream.send.buffered_bytes() as usize;
8618
8619 // Try stopping the stream.
8620 if let Ok((final_size, unsent)) = stream.send.stop(error_code) {
8621 // Claw back some flow control allowance from data that was
8622 // buffered but not actually sent before the stream was
8623 // reset.
8624 //
8625 // Note that `tx_cap` will be updated later on, so no need
8626 // to touch it here.
8627 self.tx_data = self.tx_data.saturating_sub(unsent);
8628
8629 // Update tx_buffered: subtract only the buffered data, not
8630 // inflight data.
8631 self.streams.sub_tx_buffered(buffered_len);
8632
8633 // Match moves from App to Transport with moves from
8634 // Transport to Dropped.
8635 // A Network transition would distinguish sent bytes from
8636 // drops before transmission.
8637 qlog_with_type!(QLOG_DATA_MV, self.qlog, q, {
8638 let ev_data =
8639 EventData::QuicStreamDataMoved(qlog::events::quic::StreamDataMoved {
8640 stream_id: Some(stream_id),
8641 offset: Some(final_size),
8642 raw: Some(RawInfo {
8643 length: Some(unsent),
8644 ..Default::default()
8645 }),
8646 from: Some(DataRecipient::Transport),
8647 to: Some(DataRecipient::Dropped),
8648 ..Default::default()
8649 });
8650
8651 q.add_event_data_with_instant(ev_data, now).ok();
8652 });
8653
8654 self.streams.insert_reset(stream_id, error_code, final_size);
8655
8656 if !was_writable {
8657 self.streams.insert_writable(&priority_key);
8658 }
8659
8660 self.stopped_stream_remote_count =
8661 self.stopped_stream_remote_count.saturating_add(1);
8662 self.reset_stream_local_count = self.reset_stream_local_count.saturating_add(1);
8663 }
8664 }
8665
8666 frame::Frame::Crypto { data } => {
8667 if data.max_off() >= MAX_CRYPTO_STREAM_OFFSET {
8668 return Err(Error::CryptoBufferExceeded);
8669 }
8670
8671 // Push the data to the stream so it can be re-ordered.
8672 self.crypto_ctx[epoch].crypto_stream.recv.write(data)?;
8673
8674 // Feed crypto data to the TLS state, if there's data
8675 // available at the expected offset.
8676 let mut crypto_buf = [0; 512];
8677
8678 let level = crypto::Level::from_epoch(epoch);
8679
8680 let stream = &mut self.crypto_ctx[epoch].crypto_stream;
8681
8682 while let Ok((read, _)) = stream.recv.emit(&mut crypto_buf) {
8683 let recv_buf = &crypto_buf[..read];
8684 self.handshake.provide_data(level, recv_buf)?;
8685 }
8686
8687 self.do_handshake(now)?;
8688 }
8689
8690 frame::Frame::CryptoHeader { .. } => unreachable!(),
8691
8692 // TODO: implement stateless retry
8693 frame::Frame::NewToken { .. } => {
8694 if self.is_server {
8695 return Err(Error::InvalidPacket);
8696 }
8697 }
8698
8699 frame::Frame::Stream { stream_id, data } => {
8700 // Peer can't send on our unidirectional streams.
8701 if !stream::is_bidi(stream_id) && stream::is_local(stream_id, self.is_server) {
8702 return Err(Error::InvalidStreamState(stream_id));
8703 }
8704
8705 let max_rx_data_left = self.max_rx_data() - self.rx_data;
8706
8707 // Get existing stream or create a new one, but if the stream
8708 // has already been closed and collected, ignore the frame.
8709 //
8710 // This can happen if e.g. an ACK frame is lost, and the peer
8711 // retransmits another frame before it realizes that the stream
8712 // is gone.
8713 //
8714 // Note that it makes it impossible to check if the frame is
8715 // illegal, since we have no state, but since we ignore the
8716 // frame, it should be fine.
8717 let stream = match self.get_or_create_stream(stream_id, false) {
8718 Ok(v) => v,
8719
8720 Err(Error::Done) => return Ok(()),
8721
8722 Err(e) => return Err(e),
8723 };
8724
8725 // Check for the connection-level flow control limit.
8726 let max_off_delta = data.max_off().saturating_sub(stream.recv.max_off());
8727
8728 if max_off_delta > max_rx_data_left {
8729 return Err(Error::FlowControl);
8730 }
8731
8732 let was_readable = stream.is_readable();
8733 let priority_key = Arc::clone(&stream.priority_key);
8734
8735 let was_draining = stream.recv.is_draining();
8736
8737 stream.recv.write(data)?;
8738
8739 if !was_readable && stream.is_readable() {
8740 self.streams.insert_readable(&priority_key);
8741 }
8742
8743 self.rx_data += max_off_delta;
8744
8745 if was_draining {
8746 // When a stream is in draining state it will not queue
8747 // incoming data for the application to read, so consider
8748 // the received data as consumed, which might trigger a flow
8749 // control update.
8750 self.flow_control.add_consumed(max_off_delta);
8751 }
8752 }
8753
8754 frame::Frame::StreamHeader { .. } => unreachable!(),
8755
8756 frame::Frame::MaxData { max } => {
8757 self.max_tx_data = cmp::max(self.max_tx_data, max);
8758 }
8759
8760 frame::Frame::MaxStreamData { stream_id, max } => {
8761 // Peer can't receive on its own unidirectional streams.
8762 if !stream::is_bidi(stream_id) && !stream::is_local(stream_id, self.is_server) {
8763 return Err(Error::InvalidStreamState(stream_id));
8764 }
8765
8766 // Get existing stream or create a new one, but if the stream
8767 // has already been closed and collected, ignore the frame.
8768 //
8769 // This can happen if e.g. an ACK frame is lost, and the peer
8770 // retransmits another frame before it realizes that the stream
8771 // is gone.
8772 //
8773 // Note that it makes it impossible to check if the frame is
8774 // illegal, since we have no state, but since we ignore the
8775 // frame, it should be fine.
8776 let stream = match self.get_or_create_stream(stream_id, false) {
8777 Ok(v) => v,
8778
8779 Err(Error::Done) => return Ok(()),
8780
8781 Err(e) => return Err(e),
8782 };
8783
8784 let was_flushable = stream.is_flushable();
8785
8786 stream.send.update_max_data(max);
8787
8788 let writable = stream.is_writable();
8789
8790 let priority_key = Arc::clone(&stream.priority_key);
8791
8792 // If the stream became flushable, add it to the queue unless it
8793 // is already present.
8794 if stream.is_flushable() && !was_flushable {
8795 let priority_key = Arc::clone(&stream.priority_key);
8796 self.streams.insert_flushable(&priority_key);
8797 }
8798
8799 if writable {
8800 self.streams.insert_writable(&priority_key);
8801 }
8802 }
8803
8804 frame::Frame::MaxStreamsBidi { max } => {
8805 if max > MAX_STREAM_ID {
8806 return Err(Error::InvalidFrame);
8807 }
8808
8809 self.streams.update_peer_max_streams_bidi(max);
8810 }
8811
8812 frame::Frame::MaxStreamsUni { max } => {
8813 if max > MAX_STREAM_ID {
8814 return Err(Error::InvalidFrame);
8815 }
8816
8817 self.streams.update_peer_max_streams_uni(max);
8818 }
8819
8820 frame::Frame::DataBlocked { .. } => {
8821 self.data_blocked_recv_count = self.data_blocked_recv_count.saturating_add(1);
8822 }
8823
8824 frame::Frame::StreamDataBlocked { .. } => {
8825 self.stream_data_blocked_recv_count =
8826 self.stream_data_blocked_recv_count.saturating_add(1);
8827 }
8828
8829 frame::Frame::StreamsBlockedBidi { limit } => {
8830 if limit > MAX_STREAM_ID {
8831 return Err(Error::InvalidFrame);
8832 }
8833
8834 self.streams_blocked_bidi_recv_count =
8835 self.streams_blocked_bidi_recv_count.saturating_add(1);
8836 }
8837
8838 frame::Frame::StreamsBlockedUni { limit } => {
8839 if limit > MAX_STREAM_ID {
8840 return Err(Error::InvalidFrame);
8841 }
8842
8843 self.streams_blocked_uni_recv_count =
8844 self.streams_blocked_uni_recv_count.saturating_add(1);
8845 }
8846
8847 frame::Frame::NewConnectionId {
8848 seq_num,
8849 retire_prior_to,
8850 conn_id,
8851 reset_token,
8852 } => {
8853 if self.ids.zero_length_dcid() {
8854 return Err(Error::InvalidState);
8855 }
8856
8857 let mut retired_path_ids = SmallVec::new();
8858
8859 // Retire pending path IDs before propagating the error code to
8860 // make sure retired connection IDs are not in use anymore.
8861 let new_dcid_res = self.ids.new_dcid(
8862 conn_id.into(),
8863 seq_num,
8864 u128::from_be_bytes(reset_token),
8865 retire_prior_to,
8866 &mut retired_path_ids,
8867 );
8868
8869 for (dcid_seq, pid) in retired_path_ids {
8870 let path = self.paths.get_mut(pid)?;
8871
8872 // Maybe the path already switched to another DCID.
8873 if path.active_dcid_seq != Some(dcid_seq) {
8874 continue;
8875 }
8876
8877 if let Some(new_dcid_seq) = self.ids.lowest_available_dcid_seq() {
8878 path.active_dcid_seq = Some(new_dcid_seq);
8879
8880 self.ids.link_dcid_to_path_id(new_dcid_seq, pid)?;
8881
8882 trace!(
8883 "{} path ID {} changed DCID: old seq num {} new seq num {}",
8884 self.trace_id, pid, dcid_seq, new_dcid_seq,
8885 );
8886 } else {
8887 // We cannot use this path anymore for now.
8888 path.active_dcid_seq = None;
8889
8890 trace!(
8891 "{} path ID {} cannot be used; DCID seq num {} has been retired",
8892 self.trace_id, pid, dcid_seq,
8893 );
8894 }
8895 }
8896
8897 // Propagate error (if any) now...
8898 new_dcid_res?;
8899 }
8900
8901 frame::Frame::RetireConnectionId { seq_num } => {
8902 if self.ids.zero_length_scid() {
8903 return Err(Error::InvalidState);
8904 }
8905
8906 if let Some(pid) = self.ids.retire_scid(seq_num, &hdr.dcid)? {
8907 let path = self.paths.get_mut(pid)?;
8908
8909 // Maybe we already linked a new SCID to that path.
8910 if path.active_scid_seq == Some(seq_num) {
8911 // XXX: We do not remove unused paths now, we instead
8912 // wait until we need to maintain more paths than the
8913 // host is willing to.
8914 path.active_scid_seq = None;
8915 }
8916 }
8917 }
8918
8919 frame::Frame::PathChallenge { data } => {
8920 self.path_challenge_rx_count += 1;
8921
8922 self.paths
8923 .get_mut(recv_path_id)?
8924 .on_challenge_received(data);
8925 }
8926
8927 frame::Frame::PathResponse { data } => {
8928 self.paths.on_response_received(data)?;
8929 }
8930
8931 frame::Frame::ConnectionClose {
8932 error_code, reason, ..
8933 } => {
8934 self.peer_error = Some(ConnectionError {
8935 is_app: false,
8936 error_code,
8937 reason,
8938 });
8939
8940 let path = self.paths.get_active()?;
8941 self.draining_timer = Some(now + (path.recovery.pto() * 3));
8942 }
8943
8944 frame::Frame::ApplicationClose { error_code, reason } => {
8945 self.peer_error = Some(ConnectionError {
8946 is_app: true,
8947 error_code,
8948 reason,
8949 });
8950
8951 let path = self.paths.get_active()?;
8952 self.draining_timer = Some(now + (path.recovery.pto() * 3));
8953 }
8954
8955 frame::Frame::HandshakeDone => {
8956 if self.is_server {
8957 return Err(Error::InvalidPacket);
8958 }
8959
8960 self.peer_verified_initial_address = true;
8961
8962 self.handshake_confirmed = true;
8963
8964 // Once the handshake is confirmed, we can drop Handshake keys.
8965 self.drop_epoch_state(packet::Epoch::Handshake, now);
8966 }
8967
8968 frame::Frame::Datagram { data } => {
8969 // Close the connection if DATAGRAMs are not enabled.
8970 // quiche always advertises support for 64K sized DATAGRAM
8971 // frames, as recommended by the standard, so we don't need a
8972 // size check.
8973 if !self.dgram_enabled() {
8974 return Err(Error::InvalidState);
8975 }
8976
8977 // If recv queue is full, discard oldest
8978 if self.dgram_recv_queue.is_full() {
8979 self.dgram_recv_queue.pop();
8980 }
8981
8982 self.dgram_recv_queue.push(data.into())?;
8983
8984 self.dgram_recv_count = self.dgram_recv_count.saturating_add(1);
8985
8986 let path = self.paths.get_mut(recv_path_id)?;
8987 path.dgram_recv_count = path.dgram_recv_count.saturating_add(1);
8988 }
8989
8990 frame::Frame::DatagramHeader { .. } => unreachable!(),
8991 }
8992
8993 Ok(())
8994 }
8995
8996 /// Drops the keys and recovery state for the given epoch.
8997 fn drop_epoch_state(&mut self, epoch: packet::Epoch, now: Instant) {
8998 let crypto_ctx = &mut self.crypto_ctx[epoch];
8999 if crypto_ctx.crypto_open.is_none() {
9000 return;
9001 }
9002 crypto_ctx.clear();
9003 self.pkt_num_spaces[epoch].clear();
9004
9005 let handshake_status = self.handshake_status();
9006 for (_, p) in self.paths.iter_mut() {
9007 p.recovery
9008 .on_pkt_num_space_discarded(epoch, handshake_status, now);
9009 }
9010
9011 trace!("{} dropped epoch {} state", self.trace_id, epoch);
9012 }
9013
9014 /// Returns the connection level flow control limit.
9015 fn max_rx_data(&self) -> u64 {
9016 self.flow_control.max_data()
9017 }
9018
9019 /// Returns true if the HANDSHAKE_DONE frame needs to be sent.
9020 fn should_send_handshake_done(&self) -> bool {
9021 self.is_established() && !self.handshake_done_sent && self.is_server
9022 }
9023
9024 /// Returns the idle timeout value.
9025 ///
9026 /// `None` is returned if both end-points disabled the idle timeout.
9027 fn idle_timeout(&self) -> Option<Duration> {
9028 // If the transport parameter is set to 0, then the respective endpoint
9029 // decided to disable the idle timeout. If both are disabled we should
9030 // not set any timeout.
9031 if self.local_transport_params.max_idle_timeout == 0
9032 && self.peer_transport_params.max_idle_timeout == 0
9033 {
9034 return None;
9035 }
9036
9037 // If the local endpoint or the peer disabled the idle timeout, use the
9038 // other peer's value, otherwise use the minimum of the two values.
9039 let idle_timeout = if self.local_transport_params.max_idle_timeout == 0 {
9040 self.peer_transport_params.max_idle_timeout
9041 } else if self.peer_transport_params.max_idle_timeout == 0 {
9042 self.local_transport_params.max_idle_timeout
9043 } else {
9044 cmp::min(
9045 self.local_transport_params.max_idle_timeout,
9046 self.peer_transport_params.max_idle_timeout,
9047 )
9048 };
9049
9050 let path_pto = match self.paths.get_active() {
9051 Ok(p) => p.recovery.pto(),
9052 Err(_) => Duration::ZERO,
9053 };
9054
9055 let idle_timeout = Duration::from_millis(idle_timeout);
9056 let idle_timeout = cmp::max(idle_timeout, 3 * path_pto);
9057
9058 Some(idle_timeout)
9059 }
9060
9061 /// Returns the connection's handshake status for use in loss recovery.
9062 fn handshake_status(&self) -> recovery::HandshakeStatus {
9063 recovery::HandshakeStatus {
9064 has_handshake_keys: self.crypto_ctx[packet::Epoch::Handshake].has_keys(),
9065
9066 peer_verified_address: self.peer_verified_initial_address,
9067
9068 completed: self.is_established(),
9069 }
9070 }
9071
9072 /// Updates send capacity.
9073 fn update_tx_cap(&mut self) {
9074 let cwin_available = match self.paths.get_active() {
9075 Ok(p) => p.recovery.cwnd_available() as u64,
9076 Err(_) => 0,
9077 };
9078
9079 let cap = cmp::min(cwin_available, self.max_tx_data - self.tx_data) as usize;
9080 self.tx_cap = (cap as f64 * self.tx_cap_factor).ceil() as usize;
9081 }
9082
9083 fn delivery_rate_check_if_app_limited(&self) -> bool {
9084 // Enter the app-limited phase of delivery rate when these conditions
9085 // are met:
9086 //
9087 // - The remaining capacity exceeds the available bytes in CWND (there
9088 // is more room to send).
9089 // - New data since the last `send()` is smaller than available bytes in
9090 // CWND (we queued less than what we can send).
9091 // - CWND has room for more data.
9092 //
9093 // In application-limited phases the transmission rate is limited by the
9094 // application rather than the congestion control algorithm.
9095 //
9096 // This mirrors `CheckIfApplicationLimited()` from the delivery-rate
9097 // draft but affects only delivery-rate calculation, not
9098 // `recovery.app_limited`.
9099 let cwin_available = self
9100 .paths
9101 .iter()
9102 .filter(|&(_, p)| p.active())
9103 .map(|(_, p)| p.recovery.cwnd_available())
9104 .sum();
9105
9106 ((self.streams.tx_buffered() + self.dgram_send_queue_byte_size()) < cwin_available)
9107 && (self.tx_data.saturating_sub(self.last_tx_data)) < cwin_available as u64
9108 && cwin_available > 0
9109 }
9110
9111 fn set_initial_dcid(
9112 &mut self,
9113 cid: ConnectionId<'static>,
9114 reset_token: Option<u128>,
9115 path_id: usize,
9116 ) -> Result<()> {
9117 self.ids.set_initial_dcid(cid, reset_token, Some(path_id));
9118 self.paths.get_mut(path_id)?.active_dcid_seq = Some(0);
9119
9120 Ok(())
9121 }
9122
9123 /// Selects the path that the incoming packet belongs to, or creates a new
9124 /// one if no existing path matches.
9125 fn get_or_create_recv_path_id(
9126 &mut self,
9127 recv_pid: Option<usize>,
9128 dcid: &ConnectionId,
9129 buf_len: usize,
9130 info: &RecvInfo,
9131 ) -> Result<usize> {
9132 let ids = &mut self.ids;
9133
9134 let (in_scid_seq, mut in_scid_pid) = ids.find_scid_seq(dcid).ok_or(Error::InvalidState)?;
9135
9136 if let Some(recv_pid) = recv_pid {
9137 // If the path observes a change of SCID used, note it.
9138 let recv_path = self.paths.get_mut(recv_pid)?;
9139
9140 let cid_entry = recv_path.active_scid_seq.and_then(|v| ids.get_scid(v).ok());
9141
9142 if cid_entry.map(|e| &e.cid) != Some(dcid) {
9143 let incoming_cid_entry = ids.get_scid(in_scid_seq)?;
9144
9145 let prev_recv_pid = incoming_cid_entry.path_id.unwrap_or(recv_pid);
9146
9147 if prev_recv_pid != recv_pid {
9148 trace!(
9149 "{} peer reused CID {:?} from path {} on path {}",
9150 self.trace_id, dcid, prev_recv_pid, recv_pid
9151 );
9152
9153 // TODO: reset congestion control.
9154 }
9155
9156 trace!(
9157 "{} path ID {} now see SCID with seq num {}",
9158 self.trace_id, recv_pid, in_scid_seq
9159 );
9160
9161 recv_path.active_scid_seq = Some(in_scid_seq);
9162 ids.link_scid_to_path_id(in_scid_seq, recv_pid)?;
9163 }
9164
9165 return Ok(recv_pid);
9166 }
9167
9168 // This is a new 4-tuple. See if the CID has not been assigned on
9169 // another path.
9170
9171 // Ignore this step if are using zero-length SCID.
9172 if ids.zero_length_scid() {
9173 in_scid_pid = None;
9174 }
9175
9176 // Capture old path info before insert_path() so we can emit the
9177 // ReusedSourceConnectionId event after successful insertion. This
9178 // ensures the event count is bounded by path Slab capacity.
9179 let reused_cid_info = match in_scid_pid {
9180 Some(pid) => {
9181 let old_path = self.paths.get(pid)?;
9182 Some((pid, old_path.local_addr(), old_path.peer_addr()))
9183 }
9184
9185 None => None,
9186 };
9187
9188 // This is a new path using an unassigned CID; create it!
9189 let mut path = path::Path::new(
9190 info.to,
9191 info.from,
9192 &self.recovery_config,
9193 self.path_challenge_recv_max_queue_len,
9194 false,
9195 None,
9196 );
9197
9198 path.max_send_bytes = buf_len * self.max_amplification_factor;
9199 path.active_scid_seq = Some(in_scid_seq);
9200
9201 // Automatically probes the new path.
9202 path.request_validation();
9203
9204 let pid = self.paths.insert_path(path, self.is_server)?;
9205
9206 // Notify the application of CID reuse only after the path was
9207 // successfully admitted. This bounds event queue growth by path Slab
9208 // capacity, preventing an attacker from growing the queue unboundedly
9209 // by rotating source ports.
9210 match reused_cid_info {
9211 Some((old_pid, old_local_addr, old_peer_addr)) => {
9212 trace!(
9213 "{} reused CID seq {} of ({},{}) (path {}) on ({},{})",
9214 self.trace_id,
9215 in_scid_seq,
9216 old_local_addr,
9217 old_peer_addr,
9218 old_pid,
9219 info.to,
9220 info.from
9221 );
9222
9223 self.paths.notify_event(PathEvent::ReusedSourceConnectionId(
9224 in_scid_seq,
9225 (old_local_addr, old_peer_addr),
9226 (info.to, info.from),
9227 ));
9228 }
9229
9230 None => {
9231 ids.link_scid_to_path_id(in_scid_seq, pid)?;
9232 }
9233 }
9234
9235 Ok(pid)
9236 }
9237
9238 /// Selects the path on which the next packet must be sent.
9239 fn get_send_path_id(&self, from: Option<SocketAddr>, to: Option<SocketAddr>) -> Result<usize> {
9240 // A probing packet must be sent, but only if the connection is fully
9241 // established.
9242 if self.is_established() {
9243 let mut probing = self
9244 .paths
9245 .iter()
9246 .filter(|(_, p)| from.is_none() || Some(p.local_addr()) == from)
9247 .filter(|(_, p)| to.is_none() || Some(p.peer_addr()) == to)
9248 .filter(|(_, p)| p.active_dcid_seq.is_some())
9249 .filter(|(_, p)| p.probing_required())
9250 .map(|(pid, _)| pid);
9251
9252 if let Some(pid) = probing.next() {
9253 return Ok(pid);
9254 }
9255 }
9256
9257 if let Some((pid, p)) = self.paths.get_active_with_pid() {
9258 if from.is_some() && Some(p.local_addr()) != from {
9259 return Err(Error::Done);
9260 }
9261
9262 if to.is_some() && Some(p.peer_addr()) != to {
9263 return Err(Error::Done);
9264 }
9265
9266 return Ok(pid);
9267 };
9268
9269 Err(Error::InvalidState)
9270 }
9271
9272 /// Sets the path with identifier 'path_id' to be active.
9273 fn set_active_path(&mut self, path_id: usize, now: Instant) -> Result<()> {
9274 if let Ok(old_active_path) = self.paths.get_active_mut() {
9275 for &e in packet::Epoch::epochs(packet::Epoch::Initial..=packet::Epoch::Application) {
9276 let (lost_packets, lost_bytes) =
9277 old_active_path
9278 .recovery
9279 .on_path_change(e, now, &self.trace_id);
9280
9281 self.lost_count += lost_packets;
9282 self.lost_bytes += lost_bytes as u64;
9283 }
9284 }
9285
9286 self.paths.set_active_path(path_id)
9287 }
9288
9289 /// Handles potential connection migration.
9290 fn on_peer_migrated(
9291 &mut self,
9292 new_pid: usize,
9293 disable_dcid_reuse: bool,
9294 now: Instant,
9295 ) -> Result<()> {
9296 let active_path_id = self.paths.get_active_path_id()?;
9297
9298 if active_path_id == new_pid {
9299 return Ok(());
9300 }
9301
9302 self.set_active_path(new_pid, now)?;
9303
9304 let no_spare_dcid = self.paths.get_mut(new_pid)?.active_dcid_seq.is_none();
9305
9306 if no_spare_dcid && !disable_dcid_reuse {
9307 self.paths.get_mut(new_pid)?.active_dcid_seq =
9308 self.paths.get_mut(active_path_id)?.active_dcid_seq;
9309 }
9310
9311 Ok(())
9312 }
9313
9314 /// Creates a new client-side path.
9315 fn create_path_on_client(
9316 &mut self,
9317 local_addr: SocketAddr,
9318 peer_addr: SocketAddr,
9319 ) -> Result<usize> {
9320 if self.is_server {
9321 return Err(Error::InvalidState);
9322 }
9323
9324 // If we use zero-length SCID and go over our local active CID limit,
9325 // the `insert_path()` call will raise an error.
9326 if !self.ids.zero_length_scid() && self.ids.available_scids() == 0 {
9327 return Err(Error::OutOfIdentifiers);
9328 }
9329
9330 // Do we have a spare DCID? If we are using zero-length DCID, just use
9331 // the default having sequence 0 (note that if we exceed our local CID
9332 // limit, the `insert_path()` call will raise an error.
9333 let dcid_seq = if self.ids.zero_length_dcid() {
9334 0
9335 } else {
9336 self.ids
9337 .lowest_available_dcid_seq()
9338 .ok_or(Error::OutOfIdentifiers)?
9339 };
9340
9341 let mut path = path::Path::new(
9342 local_addr,
9343 peer_addr,
9344 &self.recovery_config,
9345 self.path_challenge_recv_max_queue_len,
9346 false,
9347 None,
9348 );
9349 path.active_dcid_seq = Some(dcid_seq);
9350
9351 let pid = self
9352 .paths
9353 .insert_path(path, false)
9354 .map_err(|_| Error::OutOfIdentifiers)?;
9355 self.ids.link_dcid_to_path_id(dcid_seq, pid)?;
9356
9357 Ok(pid)
9358 }
9359
9360 // Marks the connection as closed and does any related tidyup.
9361 fn mark_closed(&mut self) {
9362 #[cfg(feature = "qlog")]
9363 {
9364 let cc = match (
9365 self.is_established(),
9366 self.timed_out,
9367 &self.peer_error,
9368 &self.local_error,
9369 ) {
9370 (false, _, _, _) => qlog::events::quic::ConnectionClosed {
9371 initiator: Some(TransportInitiator::Local),
9372 connection_error: None,
9373 application_error: None,
9374 error_code: None,
9375 internal_code: None,
9376 reason: Some("Failed to establish connection".to_string()),
9377 trigger: Some(qlog::events::quic::ConnectionClosedTrigger::HandshakeTimeout),
9378 },
9379
9380 (true, true, _, _) => qlog::events::quic::ConnectionClosed {
9381 initiator: Some(TransportInitiator::Local),
9382 connection_error: None,
9383 application_error: None,
9384 error_code: None,
9385 internal_code: None,
9386 reason: Some("Idle timeout".to_string()),
9387 trigger: Some(qlog::events::quic::ConnectionClosedTrigger::IdleTimeout),
9388 },
9389
9390 (true, false, Some(peer_error), None) => {
9391 let (connection_code, application_error, trigger) = if peer_error.is_app {
9392 (None, Some(qlog::events::ApplicationError::Unknown), None)
9393 } else {
9394 let trigger = if peer_error.error_code == WireErrorCode::NoError as u64 {
9395 Some(qlog::events::quic::ConnectionClosedTrigger::Clean)
9396 } else {
9397 Some(qlog::events::quic::ConnectionClosedTrigger::Error)
9398 };
9399
9400 (
9401 Some(qlog::events::ConnectionClosedEventError::TransportError(
9402 qlog::events::quic::TransportError::Unknown,
9403 )),
9404 None,
9405 trigger,
9406 )
9407 };
9408
9409 // TODO: select more appopriate connection_code and application_error than unknown.
9410 qlog::events::quic::ConnectionClosed {
9411 initiator: Some(TransportInitiator::Remote),
9412 connection_error: connection_code,
9413 application_error,
9414 error_code: Some(peer_error.error_code),
9415 internal_code: None,
9416 reason: Some(String::from_utf8_lossy(&peer_error.reason).to_string()),
9417 trigger,
9418 }
9419 }
9420
9421 (true, false, None, Some(local_error)) => {
9422 let (connection_code, application_error, trigger) = if local_error.is_app {
9423 (None, Some(qlog::events::ApplicationError::Unknown), None)
9424 } else {
9425 let trigger = if local_error.error_code == WireErrorCode::NoError as u64 {
9426 Some(qlog::events::quic::ConnectionClosedTrigger::Clean)
9427 } else {
9428 Some(qlog::events::quic::ConnectionClosedTrigger::Error)
9429 };
9430
9431 (
9432 Some(qlog::events::ConnectionClosedEventError::TransportError(
9433 qlog::events::quic::TransportError::Unknown,
9434 )),
9435 None,
9436 trigger,
9437 )
9438 };
9439
9440 // TODO: select more appopriate connection_code and application_error than unknown.
9441 qlog::events::quic::ConnectionClosed {
9442 initiator: Some(TransportInitiator::Local),
9443 connection_error: connection_code,
9444 application_error,
9445 error_code: Some(local_error.error_code),
9446 internal_code: None,
9447 reason: Some(String::from_utf8_lossy(&local_error.reason).to_string()),
9448 trigger,
9449 }
9450 }
9451
9452 _ => qlog::events::quic::ConnectionClosed {
9453 initiator: None,
9454 connection_error: None,
9455 application_error: None,
9456 error_code: None,
9457 internal_code: None,
9458 reason: None,
9459 trigger: None,
9460 },
9461 };
9462
9463 qlog_with_type!(QLOG_CONNECTION_CLOSED, self.qlog, q, {
9464 let ev_data = EventData::QuicConnectionClosed(cc);
9465
9466 q.add_event_data_now(ev_data).ok();
9467 });
9468 self.qlog.streamer = None;
9469 }
9470 self.closed = true;
9471 }
9472}
9473
9474#[cfg(feature = "boringssl-bssl-crate")]
9475impl<F: BufFactory> AsMut<leyline_bssl::ssl::SslRef> for Connection<F> {
9476 fn as_mut(&mut self) -> &mut leyline_bssl::ssl::SslRef {
9477 self.handshake.ssl_mut()
9478 }
9479}
9480
9481/// Maps an `Error` to `Error::Done`, or itself.
9482///
9483/// When a received packet that hasn't yet been authenticated triggers a failure
9484/// it should, in most cases, be ignored, instead of raising a connection error,
9485/// to avoid potential man-in-the-middle and man-on-the-side attacks.
9486///
9487/// However, if no other packet was previously received, the connection should
9488/// indeed be closed as the received packet might just be network background
9489/// noise, and it shouldn't keep resources occupied indefinitely.
9490///
9491/// This function maps an error to `Error::Done` to ignore a packet failure
9492/// without aborting the connection, except when no other packet was previously
9493/// received, in which case the error itself is returned, but only on the
9494/// server-side as the client will already have armed the idle timer.
9495///
9496/// This must only be used for errors preceding packet authentication. Failures
9497/// happening after a packet has been authenticated should still cause the
9498/// connection to be aborted.
9499fn drop_pkt_on_err(e: Error, recv_count: usize, is_server: bool, trace_id: &str) -> Error {
9500 // On the server, if no other packet has been successfully processed, abort
9501 // the connection to avoid keeping the connection open when only junk is
9502 // received.
9503 if is_server && recv_count == 0 {
9504 return e;
9505 }
9506
9507 trace!("{trace_id} dropped invalid packet");
9508
9509 // Ignore other invalid packets that haven't been authenticated to prevent
9510 // man-in-the-middle and man-on-the-side attacks.
9511 Error::Done
9512}
9513
9514struct AddrTupleFmt(SocketAddr, SocketAddr);
9515
9516impl std::fmt::Display for AddrTupleFmt {
9517 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
9518 let AddrTupleFmt(src, dst) = &self;
9519
9520 if src.ip().is_unspecified() || dst.ip().is_unspecified() {
9521 return Ok(());
9522 }
9523
9524 f.write_fmt(format_args!("src:{src} dst:{dst}"))
9525 }
9526}
9527
9528/// Statistics about the connection.
9529///
9530/// A connection's statistics can be collected using the [`stats()`] method.
9531///
9532/// [`stats()`]: struct.Connection.html#method.stats
9533#[derive(Clone, Default)]
9534#[non_exhaustive]
9535pub struct Stats {
9536 /// The number of QUIC packets received.
9537 pub recv: usize,
9538
9539 /// The number of QUIC packets sent.
9540 pub sent: usize,
9541
9542 /// The number of QUIC packets that were lost.
9543 pub lost: usize,
9544
9545 /// The number of QUIC packets that were marked as lost but later acked.
9546 pub spurious_lost: usize,
9547
9548 /// The number of sent QUIC packets with retransmitted data.
9549 pub retrans: usize,
9550
9551 /// The number of sent bytes.
9552 pub sent_bytes: u64,
9553
9554 /// The number of received bytes.
9555 pub recv_bytes: u64,
9556
9557 /// The number of bytes sent acked.
9558 pub acked_bytes: u64,
9559
9560 /// The number of bytes sent lost.
9561 pub lost_bytes: u64,
9562
9563 /// The number of stream bytes retransmitted.
9564 pub stream_retrans_bytes: u64,
9565
9566 /// The number of DATAGRAM frames received.
9567 pub dgram_recv: usize,
9568
9569 /// The number of DATAGRAM frames sent.
9570 pub dgram_sent: usize,
9571
9572 /// The number of known paths for the connection.
9573 pub paths_count: usize,
9574
9575 /// The number of streams reset by local.
9576 pub reset_stream_count_local: u64,
9577
9578 /// The number of streams stopped by local.
9579 pub stopped_stream_count_local: u64,
9580
9581 /// The number of streams reset by remote.
9582 pub reset_stream_count_remote: u64,
9583
9584 /// The number of streams stopped by remote.
9585 pub stopped_stream_count_remote: u64,
9586
9587 /// The number of DATA_BLOCKED frames sent due to hitting the connection
9588 /// flow control limit.
9589 pub data_blocked_sent_count: u64,
9590
9591 /// The number of STREAM_DATA_BLOCKED frames sent due to a stream hitting
9592 /// the stream flow control limit.
9593 pub stream_data_blocked_sent_count: u64,
9594
9595 /// The number of DATA_BLOCKED frames received from the remote.
9596 pub data_blocked_recv_count: u64,
9597
9598 /// The number of STREAM_DATA_BLOCKED frames received from the remote.
9599 pub stream_data_blocked_recv_count: u64,
9600
9601 /// The number of STREAMS_BLOCKED frames for bidirectional streams received
9602 /// from the remote, indicating the peer is blocked on opening new
9603 /// bidirectional streams.
9604 pub streams_blocked_bidi_recv_count: u64,
9605
9606 /// The number of STREAMS_BLOCKED frames for unidirectional streams received
9607 /// from the remote, indicating the peer is blocked on opening new
9608 /// unidirectional streams.
9609 pub streams_blocked_uni_recv_count: u64,
9610
9611 /// The total number of PATH_CHALLENGE frames that were received.
9612 pub path_challenge_rx_count: u64,
9613
9614 /// The number of times send() was blocked because the anti-amplification
9615 /// budget (bytes received × max_amplification_factor) was exhausted.
9616 pub amplification_limited_count: u64,
9617
9618 /// Total duration during which this side of the connection was
9619 /// actively sending bytes or waiting for those bytes to be acked.
9620 pub bytes_in_flight_duration: Duration,
9621
9622 /// Health state of the connection's tx_buffered.
9623 ///
9624 /// Indicates whether the streams.tx_buffered value is consistent with
9625 /// the actual sum of bytes buffered across all stream send buffers.
9626 /// Returns `Ok` if consistent, `Inconsistent` if there's a mismatch.
9627 pub tx_buffered_state: TxBufferTrackingState,
9628}
9629
9630impl std::fmt::Debug for Stats {
9631 #[inline]
9632 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
9633 write!(
9634 f,
9635 "recv={} sent={} lost={} retrans={}",
9636 self.recv, self.sent, self.lost, self.retrans,
9637 )?;
9638
9639 write!(
9640 f,
9641 " sent_bytes={} recv_bytes={} lost_bytes={}",
9642 self.sent_bytes, self.recv_bytes, self.lost_bytes,
9643 )?;
9644
9645 Ok(())
9646 }
9647}
9648
9649#[doc(hidden)]
9650#[cfg(any(test, feature = "internal"))]
9651pub mod test_utils;
9652
9653#[cfg(test)]
9654mod tests;
9655
9656pub use crate::packet::ConnectionId;
9657pub use crate::packet::Header;
9658pub use crate::packet::Type;
9659
9660pub use crate::path::PathEvent;
9661pub use crate::path::PathStats;
9662pub use crate::path::SocketAddrIter;
9663
9664pub use crate::recovery::BbrBwLoReductionStrategy;
9665pub use crate::recovery::BbrParams;
9666#[cfg(feature = "internal")]
9667pub use crate::recovery::BbrRttJumpDetector;
9668pub use crate::recovery::CongestionControlAlgorithm;
9669pub use crate::recovery::StartupExit;
9670pub use crate::recovery::StartupExitReason;
9671
9672pub use crate::stream::StreamIter;
9673
9674pub use crate::transport_params::MAX_ACK_DELAY_EXPONENT;
9675pub use crate::transport_params::TransportParamEntry;
9676pub use crate::transport_params::TransportParams;
9677pub use crate::transport_params::UnknownTransportParameter;
9678pub use crate::transport_params::UnknownTransportParameterIterator;
9679pub use crate::transport_params::UnknownTransportParameters;
9680
9681pub use crate::buffers::BufFactory;
9682pub use crate::buffers::BufSplit;
9683
9684pub use crate::crypto_split::InitialCryptoSplit;
9685pub use crate::error::ConnectionError;
9686pub use crate::error::Error;
9687pub use crate::error::Result;
9688pub use crate::error::WireErrorCode;
9689
9690mod buffers;
9691mod cid;
9692mod crypto;
9693mod crypto_split;
9694mod dgram;
9695mod error;
9696#[cfg(feature = "ffi")]
9697mod ffi;
9698mod flowcontrol;
9699mod frame;
9700pub mod h3;
9701mod minmax;
9702mod packet;
9703mod path;
9704mod pmtud;
9705mod rand;
9706mod range_buf;
9707mod ranges;
9708mod recovery;
9709mod stream;
9710mod tls;
9711mod transport_params;