ci: create .duvet/config.toml

Author: camshaft

.duvet/.gitignore

@@ -0,0 +1 @@
+reports/

.duvet/config.toml

@@ -0,0 +1,27 @@
+'$schema' = "https://awslabs.github.io/duvet/config/v0.4.0.json"
+
+[[source]]
+pattern = "quic/**/*.rs"
+
+[report.html]
+enabled = true
+issue-link = "https://github.com/aws/s2n-quic/issues"
+blob-link = "https://github.com/aws/s2n-quic/blob/${{ GITHUB_SHA || 'main' }}"
+
+[report.json]
+enabled = true
+
+[[specification]]
+source = "https://www.rfc-editor.org/rfc/rfc8312"
+
+[[specification]]
+source = "https://www.rfc-editor.org/rfc/rfc8899"
+
+[[specification]]
+source = "https://www.rfc-editor.org/rfc/rfc9000"
+
+[[specification]]
+source = "https://www.rfc-editor.org/rfc/rfc9001"
+
+[[specification]]
+source = "https://www.rfc-editor.org/rfc/rfc9002"

specs/exceptions/recovery/6.2.2.toml renamed to .duvet/exceptions/recovery/6.2.2.toml

@@ -0,0 +1,43 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-4.2"
+
+# TCP-Friendly Region
+#
+#    Standard TCP performs well in certain types of networks, for example,
+#    under short RTT and small bandwidth (or small BDP) networks.  In
+#    these networks, we use the TCP-friendly region to ensure that CUBIC
+#    achieves at least the same throughput as Standard TCP.
+# 
+#    The TCP-friendly region is designed according to the analysis
+#    described in [FHP00].  The analysis studies the performance of an
+#    Additive Increase and Multiplicative Decrease (AIMD) algorithm with
+#    an additive factor of alpha_aimd (segments per RTT) and a
+#    multiplicative factor of beta_aimd, denoted by AIMD(alpha_aimd,
+#    beta_aimd).  Specifically, the average congestion window size of
+#    AIMD(alpha_aimd, beta_aimd) can be calculated using Eq. 3.  The
+#    analysis shows that AIMD(alpha_aimd, beta_aimd) with
+#    alpha_aimd=3*(1-beta_aimd)/(1+beta_aimd) achieves the same average
+#    window size as Standard TCP that uses AIMD(1, 0.5).
+# 
+#        AVG_W_aimd = [ alpha_aimd * (1+beta_aimd) /
+#                       (2*(1-beta_aimd)*p) ]^0.5 (Eq. 3)
+# 
+#    Based on the above analysis, CUBIC uses Eq. 4 to estimate the window
+#    size W_est of AIMD(alpha_aimd, beta_aimd) with
+#    alpha_aimd=3*(1-beta_cubic)/(1+beta_cubic) and beta_aimd=beta_cubic,
+#    which achieves the same average window size as Standard TCP.  When
+#    receiving an ACK in congestion avoidance (cwnd could be greater than
+# 
+#    or less than W_max), CUBIC checks whether W_cubic(t) is less than
+#    W_est(t).  If so, CUBIC is in the TCP-friendly region and cwnd SHOULD
+#    be set to W_est(t) at each reception of an ACK.
+# 
+#        W_est(t) = W_max*beta_cubic +
+#                    [3*(1-beta_cubic)/(1+beta_cubic)] * (t/RTT) (Eq. 4)
+
+[[spec]]
+level = "SHOULD"
+quote = '''
+If so, CUBIC is in the TCP-friendly region and cwnd SHOULD
+be set to W_est(t) at each reception of an ACK.
+'''
+

specs/exceptions/recovery/6.2.4.toml renamed to .duvet/exceptions/recovery/6.2.4.toml

@@ -0,0 +1,18 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-4.3"
+
+# Concave Region
+#
+#    When receiving an ACK in congestion avoidance, if CUBIC is not in the
+#    TCP-friendly region and cwnd is less than W_max, then CUBIC is in the
+#    concave region.  In this region, cwnd MUST be incremented by
+#    (W_cubic(t+RTT) - cwnd)/cwnd for each received ACK, where
+#    W_cubic(t+RTT) is calculated using Eq. 1.
+
+[[spec]]
+level = "MUST"
+quote = '''
+In this region, cwnd MUST be incremented by
+(W_cubic(t+RTT) - cwnd)/cwnd for each received ACK, where
+W_cubic(t+RTT) is calculated using Eq.
+'''
+

specs/exceptions/recovery/6.3.toml renamed to .duvet/exceptions/recovery/6.3.toml

@@ -0,0 +1,28 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-4.4"
+
+# Convex Region
+#
+#    When receiving an ACK in congestion avoidance, if CUBIC is not in the
+#    TCP-friendly region and cwnd is larger than or equal to W_max, then
+#    CUBIC is in the convex region.  The convex region indicates that the
+#    network conditions might have been perturbed since the last
+#    congestion event, possibly implying more available bandwidth after
+#    some flow departures.  Since the Internet is highly asynchronous,
+#    some amount of perturbation is always possible without causing a
+#    major change in available bandwidth.  In this region, CUBIC is being
+#    very careful by very slowly increasing its window size.  The convex
+#    profile ensures that the window increases very slowly at the
+#    beginning and gradually increases its increase rate.  We also call
+#    this region the "maximum probing phase" since CUBIC is searching for
+#    a new W_max.  In this region, cwnd MUST be incremented by
+#    (W_cubic(t+RTT) - cwnd)/cwnd for each received ACK, where
+#    W_cubic(t+RTT) is calculated using Eq. 1.
+
+[[spec]]
+level = "MUST"
+quote = '''
+In this region, cwnd MUST be incremented by
+(W_cubic(t+RTT) - cwnd)/cwnd for each received ACK, where
+W_cubic(t+RTT) is calculated using Eq.
+'''
+

specs/exceptions/recovery/7.3.2.toml renamed to .duvet/exceptions/recovery/7.3.2.toml

@@ -0,0 +1,27 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-4.5"
+
+# Multiplicative Decrease
+#
+#    When a packet loss is detected by duplicate ACKs or a network
+#    congestion is detected by ECN-Echo ACKs, CUBIC updates its W_max,
+#    cwnd, and ssthresh as follows.  Parameter beta_cubic SHOULD be set to
+#    0.7.
+# 
+#       W_max = cwnd;                 // save window size before reduction
+#       ssthresh = cwnd * beta_cubic; // new slow-start threshold
+#       ssthresh = max(ssthresh, 2);  // threshold is at least 2 MSS
+#       cwnd = cwnd * beta_cubic;     // window reduction
+# 
+#    A side effect of setting beta_cubic to a value bigger than 0.5 is
+#    slower convergence.  We believe that while a more adaptive setting of
+#    beta_cubic could result in faster convergence, it will make the
+#    analysis of CUBIC much harder.  This adaptive adjustment of
+#    beta_cubic is an item for the next version of CUBIC.
+
+[[spec]]
+level = "SHOULD"
+quote = '''
+Parameter beta_cubic SHOULD be set to
+0.7.
+'''
+

specs/exceptions/recovery/7.3.3.toml renamed to .duvet/exceptions/recovery/7.3.3.toml

@@ -0,0 +1,54 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-4.6"
+
+# Fast Convergence
+#
+#    To improve the convergence speed of CUBIC, we add a heuristic in
+#    CUBIC.  When a new flow joins the network, existing flows in the
+#    network need to give up some of their bandwidth to allow the new flow
+#    some room for growth if the existing flows have been using all the
+#    bandwidth of the network.  To speed up this bandwidth release by
+#    existing flows, the following mechanism called "fast convergence"
+#    SHOULD be implemented.
+# 
+#    With fast convergence, when a congestion event occurs, before the
+#    window reduction of the congestion window, a flow remembers the last
+#    value of W_max before it updates W_max for the current congestion
+#    event.  Let us call the last value of W_max to be W_last_max.
+# 
+#       if (W_max < W_last_max){ // should we make room for others
+#           W_last_max = W_max;             // remember the last W_max
+#           W_max = W_max*(1.0+beta_cubic)/2.0; // further reduce W_max
+#       } else {
+#           W_last_max = W_max              // remember the last W_max
+#       }
+# 
+#    At a congestion event, if the current value of W_max is less than
+#    W_last_max, this indicates that the saturation point experienced by
+#    this flow is getting reduced because of the change in available
+#    bandwidth.  Then we allow this flow to release more bandwidth by
+#    reducing W_max further.  This action effectively lengthens the time
+#    for this flow to increase its congestion window because the reduced
+#    W_max forces the flow to have the plateau earlier.  This allows more
+#    time for the new flow to catch up to its congestion window size.
+# 
+#    The fast convergence is designed for network environments with
+#    multiple CUBIC flows.  In network environments with only a single
+#    CUBIC flow and without any other traffic, the fast convergence SHOULD
+#    be disabled.
+
+[[spec]]
+level = "SHOULD"
+quote = '''
+To speed up this bandwidth release by
+existing flows, the following mechanism called "fast convergence"
+SHOULD be implemented.
+'''
+
+[[spec]]
+level = "SHOULD"
+quote = '''
+In network environments with only a single
+CUBIC flow and without any other traffic, the fast convergence SHOULD
+be disabled.
+'''
+

specs/exceptions/recovery/7.6.2.toml renamed to .duvet/exceptions/recovery/7.6.2.toml

@@ -0,0 +1,34 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-4.8"
+
+# Slow Start
+#
+#    CUBIC MUST employ a slow-start algorithm, when the cwnd is no more
+#    than ssthresh.  Among the slow-start algorithms, CUBIC MAY choose the
+#    standard TCP slow start [RFC5681] in general networks, or the limited
+#    slow start [RFC3742] or hybrid slow start [HR08] for fast and long-
+#    distance networks.
+# 
+#    In the case when CUBIC runs the hybrid slow start [HR08], it may exit
+#    the first slow start without incurring any packet loss and thus W_max
+#    is undefined.  In this special case, CUBIC switches to congestion
+#    avoidance and increases its congestion window size using Eq. 1, where
+#    t is the elapsed time since the beginning of the current congestion
+#    avoidance, K is set to 0, and W_max is set to the congestion window
+#    size at the beginning of the current congestion avoidance.
+
+[[spec]]
+level = "MUST"
+quote = '''
+CUBIC MUST employ a slow-start algorithm, when the cwnd is no more
+than ssthresh.
+'''
+
+[[spec]]
+level = "MAY"
+quote = '''
+Among the slow-start algorithms, CUBIC MAY choose the
+standard TCP slow start [RFC5681] in general networks, or the limited
+slow start [RFC3742] or hybrid slow start [HR08] for fast and long-
+distance networks.
+'''
+

specs/exceptions/recovery/7.toml renamed to .duvet/exceptions/recovery/7.toml

@@ -0,0 +1,90 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-5.1"
+
+# Fairness to Standard TCP
+#
+#    In environments where Standard TCP is able to make reasonable use of
+#    the available bandwidth, CUBIC does not significantly change this
+#    state.
+# 
+#    Standard TCP performs well in the following two types of networks:
+# 
+#    1.  networks with a small bandwidth-delay product (BDP)
+# 
+#    2.  networks with a short RTTs, but not necessarily a small BDP
+# 
+#    CUBIC is designed to behave very similarly to Standard TCP in the
+#    above two types of networks.  The following two tables show the
+#    average window sizes of Standard TCP, HSTCP, and CUBIC.  The average
+#    window sizes of Standard TCP and HSTCP are from [RFC3649].  The
+#    average window size of CUBIC is calculated using Eq. 6 and the CUBIC
+#    TCP-friendly region for three different values of C.
+# 
+#    +--------+----------+-----------+------------+-----------+----------+
+#    |   Loss |  Average |   Average |      CUBIC |     CUBIC |    CUBIC |
+#    | Rate P |    TCP W |   HSTCP W |   (C=0.04) |   (C=0.4) |    (C=4) |
+#    +--------+----------+-----------+------------+-----------+----------+
+#    |  10^-2 |       12 |        12 |         12 |        12 |       12 |
+#    |  10^-3 |       38 |        38 |         38 |        38 |       59 |
+#    |  10^-4 |      120 |       263 |        120 |       187 |      333 |
+#    |  10^-5 |      379 |      1795 |        593 |      1054 |     1874 |
+#    |  10^-6 |     1200 |     12279 |       3332 |      5926 |    10538 |
+#    |  10^-7 |     3795 |     83981 |      18740 |     33325 |    59261 |
+#    |  10^-8 |    12000 |    574356 |     105383 |    187400 |   333250 |
+#    +--------+----------+-----------+------------+-----------+----------+
+# 
+#                                   Table 1
+# 
+#    Table 1 describes the response function of Standard TCP, HSTCP, and
+#    CUBIC in networks with RTT = 0.1 seconds.  The average window size is
+#    in MSS-sized segments.
+# 
+#    +--------+-----------+-----------+------------+-----------+---------+
+#    |   Loss |   Average |   Average |      CUBIC |     CUBIC |   CUBIC |
+#    | Rate P |     TCP W |   HSTCP W |   (C=0.04) |   (C=0.4) |   (C=4) |
+#    +--------+-----------+-----------+------------+-----------+---------+
+#    |  10^-2 |        12 |        12 |         12 |        12 |      12 |
+#    |  10^-3 |        38 |        38 |         38 |        38 |      38 |
+#    |  10^-4 |       120 |       263 |        120 |       120 |     120 |
+#    |  10^-5 |       379 |      1795 |        379 |       379 |     379 |
+#    |  10^-6 |      1200 |     12279 |       1200 |      1200 |    1874 |
+#    |  10^-7 |      3795 |     83981 |       3795 |      5926 |   10538 |
+#    |  10^-8 |     12000 |    574356 |      18740 |     33325 |   59261 |
+#    +--------+-----------+-----------+------------+-----------+---------+
+# 
+#                                   Table 2
+# 
+#    Table 2 describes the response function of Standard TCP, HSTCP, and
+#    CUBIC in networks with RTT = 0.01 seconds.  The average window size
+#    is in MSS-sized segments.
+# 
+#    Both tables show that CUBIC with any of these three C values is more
+#    friendly to TCP than HSTCP, especially in networks with a short RTT
+#    where TCP performs reasonably well.  For example, in a network with
+#    RTT = 0.01 seconds and p=10^-6, TCP has an average window of 1200
+#    packets.  If the packet size is 1500 bytes, then TCP can achieve an
+#    average rate of 1.44 Gbps.  In this case, CUBIC with C=0.04 or C=0.4
+#    achieves exactly the same rate as Standard TCP, whereas HSTCP is
+#    about ten times more aggressive than Standard TCP.
+# 
+#    We can see that C determines the aggressiveness of CUBIC in competing
+#    with other congestion control algorithms for bandwidth.  CUBIC is
+#    more friendly to Standard TCP, if the value of C is lower.  However,
+#    we do not recommend setting C to a very low value like 0.04, since
+#    CUBIC with a low C cannot efficiently use the bandwidth in long RTT
+#    and high-bandwidth networks.  Based on these observations and our
+#    experiments, we find C=0.4 gives a good balance between TCP-
+#    friendliness and aggressiveness of window increase.  Therefore, C
+#    SHOULD be set to 0.4.  With C set to 0.4, Eq. 6 is reduced to:
+# 
+#       AVG_W_cubic = 1.054 * (RTT^0.75) / (p^0.75) (Eq. 7)
+# 
+#    Eq. 7 is then used in the next subsection to show the scalability of
+#    CUBIC.
+
+[[spec]]
+level = "SHOULD"
+quote = '''
+Therefore, C
+SHOULD be set to 0.4.
+'''
+

specs/exceptions/rfc8312/4.6.toml renamed to .duvet/exceptions/rfc8312/4.6.toml

@@ -0,0 +1,19 @@
+target = "https://www.rfc-editor.org/rfc/rfc8312#section-5.8"
+
+# Behavior for Application-Limited Flows
+#
+#    CUBIC does not raise its congestion window size if the flow is
+#    currently limited by the application instead of the congestion
+#    window.  In case of long periods when cwnd has not been updated due
+#    to the application rate limit, such as idle periods, t in Eq. 1 MUST
+#    NOT include these periods; otherwise, W_cubic(t) might be very high
+#    after restarting from these periods.
+
+[[spec]]
+level = "MUST"
+quote = '''
+1 MUST
+NOT include these periods; otherwise, W_cubic(t) might be very high
+after restarting from these periods.
+'''
+