Module sack 

Available on crate feature std only.

Selective-acknowledgement (SACK) range codec.

Purpose

Replaces the legacy 4-byte single-sequence ACK payload inside the ENCRYPTED | ACK crate::transport::PhantomPacket control frame with a compact multi-range encoding that lets the sender retire many segments in a single ACK and detect gaps for fast-retransmit.

This is the AEAD plaintext of that control frame — it is NOT the outer frozen PhantomPacket container. Changing this format does NOT require a WIRE_VERSION or PROTOCOL_VERSION bump and does NOT invalidate core/tests/wire_vectors.

Wire format

All integers are big-endian (network byte order), matching the rest of the Phantom Protocol codec (PacketHeader::to_wire, etc.).

off  0  largest_acked  : u32 be   — the highest sequence number ACKed
off  4  ack_delay_us   : u32 be   — sender-measured ACK delay in µs
off  8  range_count    : u16 be   — number of SACK ranges; ≥ 1, ≤ MAX_SACK_RANGES
off 10  first_len      : u32 be   — length-minus-one of the first (highest) range
off 14  [gap : u32 be, len : u32 be] × (range_count − 1)

Range encoding

Ranges are stored descending (highest first). The first range is:

high = largest_acked
low  = largest_acked − first_len          (inclusive; first_len is length − 1)

Each subsequent (gap, len) pair descends below the previous range’s low:

high_i = low_{i-1} − 1 − gap             (skip `gap` unACKed sequences)
low_i  = high_i − len                    (len is length − 1)

The “length − 1” convention means len == 0 encodes a single-sequence range (one ACKed packet). gap = number of unACKed sequences between a range’s low and the next (lower) range’s high; gap is always ≥ 1 (adjacent ranges are coalesced by the sender and rejected as Malformed on decode).

Minimum wire size

ranges	bytes
1	14
2	22
N	10 + 4 + 8×(N−1)

Decode error conditions

Condition	Error
Buffer shorter than declared	Truncated
range_count > MAX_SACK_RANGES	TooManyRanges
range_count == 0	Malformed
gap == 0 (adjacent ranges)	Malformed
gap/len underflows below 0	Malformed
resulting range overlaps / is adjacent to previous	Malformed

Structs

Sack

A selective acknowledgement over a per-stream u32 sequence space.

Enums

SackError

Errors returned by Sack::from_wire.

Constants

MAX_SACK_RANGES

Maximum number of SACK ranges accepted during decode — anti-DoS bound. A 32-range SACK fits in 262 bytes, well within any AEAD budget.