feat(s2n-quic-core): BBRv2 recovery and full pipe estimator (#1261)

* Move Fraction to common location and add Bandwidth to RateSample

* Add new_loss_burst to congestion controller trait

* Add BBR congestion control draft RFC

* Add Mul implementation for u32 * Fraction

* Add Debug to Bandwidth

* Add recovery::State

* Add full_pipe::Estimator

* Add BBR skeleton

* Fix compliance

* Fix tests

* Add tests for Fraction

* Add tests for Bandwidth

* Add tests for Recovery

* Add tests for Full Pipe Estimator

* Clippy

* Remove unnecessary pub(crate)s

* Use fully qualified enum

* Use num_rational

* Add typo exception

Author: WesleyRosenblum

.github/config/typos.toml

@@ -9,6 +9,8 @@ check-filename = true
 [default.extend-words]
 # ECN Capable Transport
 ect = "ect"
+# num_rational uses "numer" as short for "numerator"
+numer = "numer"
 
 [files]
 extend-exclude = [

quic/s2n-quic-core/Cargo.toml

@@ -25,6 +25,7 @@ bytes = { version = "1", default-features = false }
 hex-literal = "0.3"
 # used for event snapshot testing - needs an internal API so we require a minimum version
 insta = { version = ">=1.12", optional = true }
+num-rational = { version = "0.4", default-features = false }
 num-traits = { version = "0.2", default-features = false, features = ["libm"] }
 s2n-codec = { version = "=0.1.0", path = "../../common/s2n-codec", default-features = false }
 subtle = { version = "2", default-features = false }

quic/s2n-quic-core/src/recovery/bandwidth/estimator.rs

@@ -3,6 +3,7 @@
 
 use crate::time::Timestamp;
 use core::{cmp::max, time::Duration};
+use num_rational::Ratio;
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 /// Bandwidth-related data tracked for each sent packet
@@ -23,6 +24,37 @@ pub struct PacketInfo {
     pub is_app_limited: bool,
 }
 
+#[derive(Copy, Clone, Debug, Default, PartialOrd, PartialEq)]
+pub struct Bandwidth {
+    bits_per_second: u64,
+}
+
+impl Bandwidth {
+    pub const ZERO: Bandwidth = Bandwidth { bits_per_second: 0 };
+
+    pub fn new(bytes: u64, interval: Duration) -> Self {
+        const MICRO_BITS_PER_BYTE: u64 = 8 * 1000000;
+
+        if interval.is_zero() {
+            Bandwidth::ZERO
+        } else {
+            Self {
+                bits_per_second: (bytes * MICRO_BITS_PER_BYTE / interval.as_micros() as u64),
+            }
+        }
+    }
+}
+
+impl core::ops::Mul<Ratio<u64>> for Bandwidth {
+    type Output = Bandwidth;
+
+    fn mul(self, rhs: Ratio<u64>) -> Self::Output {
+        Bandwidth {
+            bits_per_second: (rhs * self.bits_per_second).to_integer(),
+        }
+    }
+}
+
 #[derive(Clone, Copy, Debug, Default)]
 /// A bandwidth delivery rate estimate with associated metadata
 pub struct RateSample {
@@ -55,6 +87,11 @@ impl RateSample {
         self.prior_lost_bytes = packet_info.lost_bytes;
         self.bytes_in_flight = packet_info.bytes_in_flight;
     }
+
+    /// Gets the delivery rate of this rate sample
+    pub fn delivery_rate(&self) -> Bandwidth {
+        Bandwidth::new(self.delivered_bytes, self.interval)
+    }
 }
 
 /// Bandwidth estimator as defined in [Delivery Rate Estimation](https://datatracker.ietf.org/doc/draft-cheng-iccrg-delivery-rate-estimation/)

quic/s2n-quic-core/src/recovery/bandwidth/estimator/tests.rs

@@ -4,6 +4,29 @@
 use super::*;
 use crate::time::{Clock, NoopClock};
 
+#[test]
+fn bandwidth() {
+    let result = Bandwidth::new(1000, Duration::from_secs(10));
+
+    assert_eq!(100 * 8, result.bits_per_second);
+}
+
+#[test]
+fn bandwidth_zero_interval() {
+    let result = Bandwidth::new(500, Duration::ZERO);
+
+    assert_eq!(Bandwidth::ZERO, result);
+}
+
+#[test]
+fn bandwidth_mul_ratio() {
+    let bandwidth = Bandwidth::new(7000, Duration::from_secs(1));
+
+    let result = bandwidth * Ratio::new(3, 7);
+
+    assert_eq!(result, Bandwidth::new(3000, Duration::from_secs(1)));
+}
+
 // first_sent_time and delivered_time typically hold values from recently acknowledged packets. However,
 // when  no packet has been sent yet, or there are no packets currently in flight, these values are initialized
 // with the time when a packet is sent. This test confirms first_sent_time and delivered_time are

quic/s2n-quic-core/src/recovery/bbr.rs

@@ -0,0 +1,147 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    counter::Counter,
+    recovery::{bandwidth, bandwidth::Bandwidth, CongestionController, RttEstimator},
+    time::Timestamp,
+};
+use num_rational::Ratio;
+
+mod full_pipe;
+mod recovery;
+
+//= https://tools.ietf.org/id/draft-cardwell-iccrg-bbr-congestion-control-02#2.8
+//# The maximum tolerated per-round-trip packet loss rate when probing for bandwidth (the default is 2%).
+const LOSS_THRESH: Ratio<u32> = Ratio::new_raw(1, 50);
+
+/// A congestion controller that implements "Bottleneck Bandwidth and Round-trip propagation time"
+/// version 2 (BBRv2) as specified in <https://datatracker.ietf.org/doc/draft-cardwell-iccrg-bbr-congestion-control/>.
+///
+/// Based in part on the Chromium BBRv2 implementation, see <https://source.chromium.org/chromium/chromium/src/+/main:net/third_party/quiche/src/quic/core/congestion_control/bbr2_sender.cc>
+/// and the Linux Kernel TCP BBRv2 implementation, see <https://github.com/google/bbr/blob/v2alpha/net/ipv4/tcp_bbr2.c>
+#[derive(Debug, Clone)]
+struct BbrCongestionController {
+    bw_estimator: bandwidth::Estimator,
+    //= https://tools.ietf.org/id/draft-cardwell-iccrg-bbr-congestion-control-02#2.9.1
+    //# The windowed maximum recent bandwidth sample - obtained using the BBR delivery rate sampling
+    //# algorithm [draft-cheng-iccrg-delivery-rate-estimation] - measured during the current or
+    //# previous bandwidth probing cycle (or during Startup, if the flow is still in that state).
+    max_bw: Bandwidth,
+    full_pipe_estimator: full_pipe::Estimator,
+    //= https://www.rfc-editor.org/rfc/rfc9002#section-B.2
+    //# The sum of the size in bytes of all sent packets
+    //# that contain at least one ack-eliciting or PADDING frame and have
+    //# not been acknowledged or declared lost.  The size does not include
+    //# IP or UDP overhead, but does include the QUIC header and
+    //# Authenticated Encryption with Associated Data (AEAD) overhead.
+    //# Packets only containing ACK frames do not count toward
+    //# bytes_in_flight to ensure congestion control does not impede
+    //# congestion feedback.
+    bytes_in_flight: BytesInFlight,
+    recovery_state: recovery::State,
+}
+
+type BytesInFlight = Counter<u32>;
+
+impl CongestionController for BbrCongestionController {
+    type PacketInfo = bandwidth::PacketInfo;
+
+    fn congestion_window(&self) -> u32 {
+        todo!()
+    }
+
+    fn bytes_in_flight(&self) -> u32 {
+        *self.bytes_in_flight
+    }
+
+    fn is_congestion_limited(&self) -> bool {
+        todo!()
+    }
+
+    fn requires_fast_retransmission(&self) -> bool {
+        self.recovery_state.requires_fast_retransmission()
+    }
+
+    fn on_packet_sent(
+        &mut self,
+        time_sent: Timestamp,
+        sent_bytes: usize,
+        _rtt_estimator: &RttEstimator,
+    ) -> Self::PacketInfo {
+        let is_app_limited = false; // TODO: determine if app limited
+        let packet_info =
+            self.bw_estimator
+                .on_packet_sent(*self.bytes_in_flight, is_app_limited, time_sent);
+
+        if sent_bytes > 0 {
+            self.recovery_state.on_packet_sent();
+
+            self.bytes_in_flight
+                .try_add(sent_bytes)
+                .expect("sent_bytes should not exceed u32::MAX");
+        }
+
+        packet_info
+    }
+
+    fn on_rtt_update(&mut self, _time_sent: Timestamp, _rtt_estimator: &RttEstimator) {
+        todo!()
+    }
+
+    fn on_ack(
+        &mut self,
+        newest_acked_time_sent: Timestamp,
+        bytes_acknowledged: usize,
+        newest_acked_packet_info: Self::PacketInfo,
+        _rtt_estimator: &RttEstimator,
+        ack_receive_time: Timestamp,
+    ) {
+        self.bw_estimator.on_ack(
+            bytes_acknowledged,
+            newest_acked_time_sent,
+            newest_acked_packet_info,
+            ack_receive_time,
+        );
+        let round_start = false; // TODO: track rounds
+        self.recovery_state
+            .on_ack(round_start, newest_acked_time_sent);
+
+        if round_start {
+            self.full_pipe_estimator.on_round_start(
+                self.bw_estimator.rate_sample(),
+                self.max_bw,
+                self.recovery_state.in_recovery(),
+            )
+        }
+    }
+
+    fn on_packet_lost(
+        &mut self,
+        lost_bytes: u32,
+        _packet_info: Self::PacketInfo,
+        _persistent_congestion: bool,
+        new_loss_burst: bool,
+        timestamp: Timestamp,
+    ) {
+        self.bw_estimator.on_loss(lost_bytes as usize);
+        self.recovery_state.on_congestion_event(timestamp);
+        self.full_pipe_estimator.on_packet_lost(new_loss_burst);
+    }
+
+    fn on_congestion_event(&mut self, event_time: Timestamp) {
+        self.recovery_state.on_congestion_event(event_time);
+    }
+
+    fn on_mtu_update(&mut self, _max_data_size: u16) {
+        todo!()
+    }
+
+    fn on_packet_discarded(&mut self, _bytes_sent: usize) {
+        todo!()
+    }
+
+    fn earliest_departure_time(&self) -> Option<Timestamp> {
+        todo!()
+    }
+}