Module control_frame 

The control plane as a QUIC-style frame container.

A single CONTROL datagram carries a sequence of type-tagged, length-prefixed frames. Both endpoints emit CONTROL datagrams holding whatever frames they have to report, so the channel is symmetric: an ACK from the receiver and a TIMING beat from the sender are the same packet shape, just different frames.

The point of the framing is extensibility without a version bump. A new between-endpoint signal - a hop-count delta, an ECN-CE marking, a peer’s link class - becomes a new FrameType, not a new fixed layout. Frames a peer does not recognize are length-skipped, so old and new builds interoperate by ignoring each other’s unknown frames rather than mis-parsing the rest of the packet.

Wire shape:

[PKT_CONTROL] ( [frame_type:u8] [length:varint] [payload: length bytes] )*

Integers wider than a byte use the QUIC variable-length encoding (RFC 9000 section 16): the top two bits of the first byte select a 1/2/4/8-byte form, so a small value costs one byte. Byte-sized fields are written raw. The codec is pure and does no I/O, so it is exhaustively testable against synthetic frame sequences.

Modules

link_class

Link-class enum carried in LinkFrame::class.

Structs

AckFrame

Cumulative ack frontier: the next block the receiver still needs.

AvailBwFrame

The receiver’s WBest available-bandwidth estimate, reverse-reported so the sender can cross-check its passive BtlBw. Carried in kbit/s so a multi-Gbit estimate fits a varint without floating point on the wire.

BwProbeFrame

One member of a bandwidth-probe train. The receiver measures inter-arrival dilation across a train sharing probe_id to estimate available bandwidth.

ControlPacket

A decoded control packet: every frame is optional, so a packet carries exactly the signals its sender had to report. Probe and trace frames may repeat (a train), so they are collected.

ForecastFrame

The receiver’s Sprout-style forecast (item 16): the 5th-percentile deliverable rate it predicts for the next tick, so the sender pre-sizes its window ahead of a dip instead of reacting after the loss the dip causes.

LinkFrame

The peer’s link class and a normalized 0..=255 quality (RSSI / RSRP / link-rate). A class change (wifi -> cellular) is a handoff announcement.

LossAcctFrame

Bidirectional control-plane loss accounting. seq is the count of control packets this endpoint has SENT; last_recv_seq is the count it has RECEIVED from the peer. Pairing the two separates forward-path loss (the peer did not get your packets: your seq minus the peer’s reported last_recv_seq) from reverse-path loss (you did not get the peer’s: the peer’s seq minus your last_recv_seq).

LossFrame

Fused channel readings the receiver reports to the sender’s controller.

NakFrame

Selective NAK: which shards of which block are still missing.

PathFrame

The peer’s view of THIS endpoint’s packets: the TTL it saw, the ECN bits, and the hop count it derived from the TTL. A change in hop_count is a router-level path shift, often visible before throughput moves.

PeriodicityFrame

The receiver’s LEO handover-cadence detection (item 17): the detected period and the time to the next predicted delay spike, both in deciseconds (0.1 s), plus a confidence, so the sender pre-arms one cycle ahead. period_ds == 0 means no cadence detected.

PmtuFrame

The peer’s observed path MTU. A drop (1500 -> ~1280) flags a lower-MTU link engaging, e.g. a cellular handoff; the frame size should track it.

RingFrame

Source-ring shape telemetry: the legacy heartbeat payload, now a frame.

TimingFrame

Sender clock beat. echo_ts reflects the peer’s last send_ts back, so either end can compute RTT; send_ts alone drives the OWD-trend slope.

TraceFrame

A mini-traceroute marker: a control packet emitted at a reduced IP TTL so an intermediate router replies with ICMP TimeExceeded, exposing per-hop RTT without a separate probe flow.

Enums

FrameType

Frame type tags. Stable on the wire; append new variants, never renumber.

Constants

PKT_CONTROL

Packet-type tag for a control datagram (vs PKT_DATA). Distinct from the retired fixed PKT_FEEDBACK / PKT_HEARTBEAT tags, which this container subsumes.

Functions

decode_control

Decode a control datagram. Unknown frame types are length-skipped; a frame whose declared length runs past the buffer aborts the parse and returns whatever was decoded up to that point. Returns None only if the packet is not a control datagram.

encode_control

Encode a control packet into a fresh datagram buffer.

is_control

true if buf is a control datagram.

pad_control_to

Pad an encoded control datagram up to target_len bytes by appending one unknown-type frame (which the decoder length-skips). An active bandwidth probe rides a known, large datagram so its inter-arrival dispersion is a capacity measurement at that packet size; this is how it reaches that size without inventing a payload the peer must understand. No-op when the gap is too small to hold the padding frame’s 3-byte header plus a 64-byte body (the threshold that keeps the length varint exactly two bytes, so the final datagram is exactly target_len).