`flare.quic.varint`

Variable-length integer codec for QUIC (RFC 9000 §16).

QUIC encodes integers in a self-describing format where the two most-significant bits of the first byte select the encoding length:

2 MSB	Length	Usable bits	Range
0b00	1	6	0 .. 63
0b01	2	14	0 .. 16,383
0b10	4	30	0 .. 1,073,741,823
0b11	8	62	0 .. 4,611,686,018,427,387,903

All multi-byte forms are big-endian. The two-bit length tag lives in the highest two bits of the first byte; the remaining bits of that byte are part of the value.

This module is intentionally sans-I/O: every function takes either a buffer slice or a value and returns the other, with no socket state. The codec is the load-bearing primitive for every other QUIC frame: STREAM frame offsets, packet numbers, frame types, ACK ranges -- everything is varint-encoded.

References:

RFC 9000 §16 "Variable-Length Integer Encoding".
aioquic buffer.pull_uint_var / buffer.push_uint_var (the Python reference implementation we cross-validate against).

Structs

`Varint`

struct Varint

A decoded QUIC varint together with the number of wire bytes that produced it.

value is the integer payload; consumed is the number of bytes the encoded form occupied (1, 2, 4, or 8). Callers use consumed to advance their cursor over the input buffer.

Implements Copyable, Movable

Fields: value: UInt64; consumed: Int

Functions

`varint_encoded_length`

def varint_encoded_length(value: UInt64) -> Int

Return the wire length (1, 2, 4, or 8 bytes) required to encode value.

Raises Error if value exceeds :data:VARINT_MAX.

`encode_varint`

def encode_varint(value: UInt64) -> List[UInt8]

Encode value into a fresh byte buffer.

The encoding picks the shortest length that fits per RFC 9000 §16. Raises Error for values above :data:VARINT_MAX. The "shortest form" rule is enforced on the encoder side; the decoder accepts any valid encoding (a producer may legitimately pad to a longer form for byte-alignment reasons -- aioquic does this for packet-number space).

`encode_varint_into`

def encode_varint_into(value: UInt64, mut out: List[UInt8])

Append the encoding of value to out; see :func:encode_varint.

`decode_varint`

def decode_varint(buf: Span[UInt8]) -> Varint

Decode the varint at the start of buf.

Returns a :class:Varint carrying the decoded value plus the number of bytes consumed. Raises Error if buf is too short to contain a complete encoding (truncated input is the most common varint-level failure mode).

Aliases

comptime VARINT_MAX = Int(4611686018427387903)

Largest representable varint value (2 ** 62 - 1 per RFC 9000 §16). Values above this cannot be encoded and must be rejected at the codec boundary.