1Congestion control API design
2=============================
3
4We use an abstract interface for the QUIC congestion controller to facilitate
5use of pluggable QUIC congestion controllers in the future. The interface is
6based on interfaces suggested by RFC 9002 and MSQUIC's congestion control APIs.
7
8`OSSL_CC_METHOD` provides a vtable of function pointers to congestion controller
9methods. `OSSL_CC_DATA` is an opaque type representing a congestion controller
10instance.
11
12For details on the API, see the comments in `include/internal/quic_cc.h`.
13
14Congestion controllers are not thread safe; the caller is responsible for
15synchronisation.
16
17Congestion controllers may vary their state with respect to time. This is
18facilitated via the `get_wakeup_deadline` method and the `now` argument to the
19`new` method, which provides access to a clock. While no current congestion
20controller makes use of this facility, it can be used by future congestion
21controllers to implement packet pacing.
22
23Congestion controllers may expose arbitrary configuration parameters via the
24`set_input_params` method. Equally, congestion controllers may expose diagnostic
25outputs via the `bind_diagnostics` and `unbind_diagnostics` methods. The
26configuration parameters and diagnostics supported may be specific to the
27congestion controller method, although there are some well known ones intended
28to be common to all congestion controllers.
29
30Currently, the only dependency injected to a congestion controller is access to
31a clock. In the future it is likely that access at least to the statistics
32manager will be provided. Excessive futureproofing of the congestion controller
33interface has been avoided as this is currently an internal API for which no API
34stability guarantees are required; for example, no currently implemented
35congestion control algorithm requires access to the statistics manager, but such
36access can readily be added later as needed.
37
38QUIC congestion control state is per-path, per-connection. Currently we support
39only a single path per connection, so there is one congestion control instance
40per connection. This may change in future.
41
42While the congestion control API is roughly based around the arrangement of
43functions as described by the congestion control pseudocode in RFC 9002, there
44are some deliberate changes in order to obtain cleaner separation between the
45loss detection and congestion control functions. Where a literal option of RFC
469002 pseudocode would require a congestion controller to access the ACK
47manager's internal state directly, the interface between the two has been
48changed to avoid this. This involves some small amounts of functionality which
49RFC 9002 considers part of the congestion controller being part of the ACK
50manager in our implementation. See the comments in `include/internal/quic_cc.h`
51and `ssl/quic/quic_ackm.c` for more information.
52
53The congestion control API may be revised to allow pluggable congestion
54controllers via a provider-based interface in the future.
55