Skip to main content

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(&params, 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;