Project: Pipy (Orchestration & Management / Service Proxy)
File: quic-ackm.md

QUIC ACK Manager ================ The QUIC ACK manager is responsible for, on the TX side: Handling received ACK frames Generating notifications that a packet we sent was delivered successfully Generating notifications that a packet we sent was lost Generating requests for probe transmission Providing information on the largest unacked packet number so that packet numbers in packet headers can be encoded and decoded correctly On the RX side, it is responsible for: Generating ACK frames for later transmission in response to packets we received Providing information on whether a given RX packet number is potentially duplicate and should not be processed In order to allow it to perform these tasks, the ACK manager must: be notified of all transmitted packets be notified of all received datagrams be notified of all received packets be notified of all received ACK frames be notified when a packet number space is discarded be notified when its loss detection deadline arrives The ACK manager consumes: an arbitrary function which returns the current time; a RTT statistics tracker; a congestion controller. The ACK manager provides the following outputs: It indicates the current deadline by which the loss detection event should be invoked. It indicates when probes should be generated. It indicates what ACK frames should be generated. It indicates the current deadline by which new ACK frames will be generated, if any. It indicates the largest unacknowledged packet number for a given packet number space. It calls a callback for each transmitted packet it is notified of, specifying whether the packet was successfully acknowledged by the peer, lost or discarded. It may communicate with a congestion controller, causing the congestion controller to update its state. It may communicate with a RTT statistics tracker, causing it to update its state. In this document, the caller refers to the system which makes use of the ACK manager. Utility Definitions There are three QUIC packet number spaces: Initial, Handshake and Application Data. ```c / QUIC packet number spaces. / ``` Packet numbers are 62-bit values represented herein by `QUIC_PN`. `QUICPNINFINITE` evaluates to an invalid QUIC packet number value. ```c / QUIC packet number representation. / typedef uint64t QUICPN; ``` Instantiation The QUIC ACK manager is instantiated as follows: ```c typedef struct osslackmst OSSL_ACKM; OSSLACKM *osslackmnew(OSSLTIME (now)(void arg), void *now_arg, QUIC_STATM *statm, OSSLCCMETHOD *cc_method, OSSLCCDATA *cc_data); void osslackmfree(OSSL_ACKM *ackm); ``` The function pointer `now` is invoked by the ACK manager to obtain the current time. `now_arg` is passed as the argument. The congestion controller method and instance passed are used by the ACK manager instance. `statm` points to a . Events The ACK manager state is evolved in response to events provided to the ACK manager by the caller. This must be called when a packet is transmitted. It does not provide the payload of the packet, but provides metadata about the packet which is relevant to the loss detection and acknowledgement process. The caller is responsible for the allocation of the structure and the structure must remain allocated until one of the callbacks is called or the ACK manager is freed. It is expected this structure will usually be freed (or returned to a pool) in the implementation of either callback passed by the caller. Only exactly one of the callbacks in the structure will be called over the lifetime of a `OSSLACKMTX_PKT`, and only once. Returns 1 on success. ```c typedef struct osslackmtxpktst { / The packet number of the transmitted

/ QUICPN pktnum; / The number of bytes in the packet which was sent. / sizet numbytes; / The time at which the packet was sent. / OSSL_TIME time; /* If the packet being described by this structure contains an ACK frame, this must be set to the largest PN ACK'd by that frame. * Otherwise, it should be set to QUICPNINVALID. * This is necessary to bound the number of PNs we have to keep track of on the RX side (RFC 9000 s. 13.2.4). It allows older PN tracking information on the RX side to be discarded. */ QUICPN largestacked; /* One of the QUIC_PN_SPACE_ values. This qualifies the pkt_num field into a packet number space. */ unsigned int pkt_space :2; / 1 if the packet is in flight. / unsigned int is_inflight :1; / 1 if the packet has one or more ACK-eliciting frames. / unsigned int isackeliciting :1; / 1 if the packet is a PTO probe. / unsigned int isptoprobe :1; / 1 if the packet is an MTU probe. / unsigned int ismtuprobe :1; / Callback called if frames in this packet are lost. arg is cb_arg. / void (on_lost)(void arg); / Callback called if frames in this packet are acked. arg is cb_arg. / void (on_acked)(void arg); /* Callback called if frames in this packet are neither acked nor lost. arg is cb_arg. */ void (on_discarded)(void arg); void *cb_arg; / (Internal use fields are appended here and must be zero-initialized.) / } OSSLACKMTX_PKT; int osslackmontxpacket(OSSLACKM *ackm, const OSSLACKMTXPKT *pkt); ``` This must be called whenever a datagram is received. A datagram may contain multiple packets, and this function should be called before the calls to `osslackmonrxpacket`. The primary use of this function is to inform the ACK manager of new credit to the anti-amplification budget. Packet and ACK-frame related logic are handled separately in the subsequent calls to `osslackmonrxpacket` and `osslackmonrxack_frame`, respectively. Returns 1 on success. ```c int osslackmonrxdatagram(OSSLACKM *ackm, sizet num_bytes); ``` This must be called whenever a packet is received. It should be called after `osslackmonrxdatagram` was called for the datagram containing the packet. Returns 1 on success. ```c typedef struct osslackmrxpktst { / The packet number of the received packet. / QUICPN pktnum; / The time at which the packet was received. / OSSL_TIME time; /* One of the QUIC_PN_SPACE_ values. This qualifies the pkt_num field into a packet number space. */ unsigned int pkt_space :2; / 1 if the packet has one or more ACK-eliciting frames. / unsigned int isackeliciting :1; /* One of the OSSL_ACKM_ECN_ values. This is the ECN labelling applied to the received packet. If unknown, use OSSLACKMECN_NONE. */ unsigned int ecn :2; } OSSLACKMRX_PKT; int osslackmonrxpacket(OSSLACKM *ackm, const OSSLACKMRXPKT *pkt); ``` This must be called whenever an ACK frame is received. It should be called after any call to `osslackmonrxpacket`. The ranges of packet numbers being acknowledged are passed as an argument. `pktspace` is one of the `QUICPNSPACE*` values, specifying the packet number space of the containing packet. `rx_time` is the time the frame was received. This function causes `on_acked` callbacks to be invoked on applicable packets. Returns 1 on success. ```c typedef struct osslackmackrangest { /* Represents an inclusive range of packet numbers [start, end]. start must be <= end. */ QUIC_PN start, end; } OSSLACKMACK_RANGE; typedef struct osslackmack { /* A sequence of packet number ranges [[start,

* The ranges must be sorted in descending order, for example: [ 95, 100] [ 90, 92] etc. * As such, ack_ranges[0].end is always the highest packet number being acknowledged and ackranges[numack_ranges-1].start is always the lowest packet number being acknowledged. * numackranges must be greater than zero, as an ACK frame must acknowledge at least one packet number. */ const OSSLACKMACKRANGE *ackranges; sizet numack_ranges; OSSLTIME delaytime; uint64_t ect0, ect1, ecnce; / 1 if the ect0, ect1 and ecnce fields are valid / char ecn_present; } OSSLACKMACK; int osslackmonrxackframe(OSSLACKM ackm, const OSSL_ACKM_ACK ack, int pktspace, OSSLTIME rx_time); ``` This must be called whenever a packet number space is discarded. ACK-tracking information for the number space is thrown away. Any previously provided `OSSLACKMTXPKT` structures have their `ondiscarded` callback invoked, providing an opportunity for them to be freed. Returns 1 on success. ```c int osslackmonpktspacediscarded(OSSLACKM *ackm, int pkt_space); ``` This should be called by the caller when the QUIC handshake is confirmed. The Probe Timeout (PTO) algorithm behaves differently depending on whether the QUIC handshake is confirmed yet. Returns 1 on success. ```c int osslackmonhandshakeconfirmed(OSSL_ACKM *ackm); ``` This must be called whenever the loss detection deadline expires. ```c int osslackmontimeout(OSSLACKM *ackm); ``` Queries These functions allow information about the status of the ACK manager to be obtained. This returns a deadline after which `osslackmon_timeout` should be called. If it is `OSSLTIMEINFINITY`, no timeout is currently active. The value returned by this function may change after any call to any of the event functions above is made. ```c OSSLTIME osslackmgetlossdetectiondeadline(OSSL_ACKM *ackm); ``` This returns a pointer to a `OSSLACKMACK` structure representing the information which should be packed into an ACK frame and transmitted. This generates an ACK frame regardless of whether the ACK manager thinks one should currently be sent. To determine if the ACK manager thinks an ACK frame should be sent, use `osslackmisackdesired`, discussed below. If no new ACK frame is currently needed, returns NULL. After calling this function, calling the function immediately again will return NULL. The structure pointed to by the returned pointer, and the referenced ACK range structures, are guaranteed to remain valid until the next call to any `OSSL_ACKM` function. After such a call is made, all fields become undefined. This function is used to provide ACK frames for acknowledging packets which have been received and notified to the ACK manager via `osslackmonrxpacket`. Calling this function clears the flag returned by `osslackmisackdesired` and the deadline returned by `osslackmgetackdeadline`. ```c const OSSLACKMACK ossl_ackm_get_ack_frame(OSSL_ACKM ackm, int pkt_space); ``` This returns 1 if the ACK manager thinks an ACK frame ought to be generated and sent at this time. `osslackmgetackframe` will always provide an ACK frame whether or not this returns 1, so it is suggested that you call this function first to determine whether you need to generate an ACK frame. The return value of this function can change based on calls to `osslackmonrxpacket` and based on the passage of time (see `osslackmgetackdeadline`). ```c int osslackmisackdesired(OSSLACKM *ackm, int pktspace); ``` The ACK manager may defer generation of ACK frames to optimize performance. For example, after a packet requiring acknowledgement is received, it may decide to wait until a few more packets are received before generating an ACK frame, so that a single ACK frame can acknowledge all of them. However, if further packets do not arrive, an ACK frame must be generated anyway within a certain amount of

This function returns the deadline at which the return value of `osslackmisackdesired` will change to 1, or `OSSLTIMEINFINITY`, which means that no deadline is currently applicable. If the deadline has already passed, it may either return that deadline or `OSSLTIMEZERO`. ```c OSSLTIME osslackmgetackdeadline(OSSLACKM *ackm, int pkt_space); ``` Returns 1 if the given RX packet number is processable. A processable PN is one that is not either duplicate, meaning that we have already been passed such a PN in a call to `osslackmonrxpacket`; or written off, meaning that the PN is so old that we have stopped tracking state for it (meaning we cannot tell whether it is a duplicate and cannot process it safely). This should be called for a packet before attempting to process its contents. Failure to do so may may result in processing a duplicated packet in violation of the RFC. The returrn value of this function transitions from 1 to 0 for a given PN once that PN is passed to osslackmonrxpacket, thus this function must be used before calling `osslackmonrxpacket`. ```c int osslackmisrxpnprocessable(OSSLACKM *ackm, QUICPN pn, int pktspace); ``` This determines if the ACK manager is requesting any probe packets to be transmitted. The user calls `osslackmgetproberequest`. The structure pointed to by `info` is filled and the function returns 1 on success. The fields of `OSSLACKMPROBE_INFO` record the number of probe requests of each type which are outstanding. In short: `handshake` designates the number of ACK-eliciting Handshake packets being requested. This is equivalent to `SendOneAckElicitingHandshakePacket()` in RFC 9002. `padded_initial` designates the number of ACK-eliciting padded Initial packets being requested. This is equivalent to `SendOneAckElicitingPaddedInitialPacket()` in RFC 9002. `pto` designates the number of ACK-eliciting outstanding probe events corresponding to each packet number space. This is equivalent to `SendOneOrTwoAckElicitingPackets(pn_space)` in RFC 9002. Once the caller has processed these requests, the caller must clear these outstanding requests by calling `osslackmgetproberequest` with `clear` set to 1. If `clear` is non-zero, the current values are returned and then zeroed, so that the next call to `osslackmgetproberequest` (if made immediately) will return zero values for all fields. ```c typedef struct osslackmprobeinfost { uint32_t handshake; uint32t paddedinitial; uint32t pto[QUICPNSPACENUM]; } OSSLACKMPROBE_INFO; int osslackmgetproberequest(OSSL_ACKM *ackm, int clear, OSSLACKMPROBE_INFO *info); ``` This gets the largest unacknowledged packet number in the given packet number space. The packet number is written to `*pn`. Returns 1 on success. This is needed so that packet encoders can determine with what length to encode the abridged packet number in the packet header. ```c int osslackmgetlargestunacked(OSSLACKM *ackm, int pktspace, QUIC_PN *pn); ``` Callback Functionality The ACK manager supports optional callback functionality when its deadlines are updated. By default, the callback functionality is not enabled. To use the callback functionality, call either or both of the following functions with a non-NULL function pointer: ```c void osslackmsetlossdetectiondeadlinecallback(OSSL_ACKM *ackm, void (*fn)(OSSL_TIME deadline, void *arg), void *arg); void osslackmsetackdeadlinecallback(OSSLACKM *ackm, void (*fn)(OSSL_TIME deadline, int pkt_space, void *arg), void *arg); ``` Callbacks can be subsequently disabled by calling these functions with a NULL function pointer. The callbacks are not called at the time that they are set, therefore it is recommended to call them immediately after the call to `osslackmnew`. The loss detection deadline callback is called whenever the value returned by `osslackmgetlossdetection_deadline` changes. The ACK deadline callback is called whenever the value returned by `osslackmgetackdeadline` changes for a given packet space. The `deadline` argument reflects the value which will be newly returned by the corresponding function. If the configured callback calls either of these functions, the returned value will reflect the new deadline.