# flare.quic.varint

> A module of flare_mlake's API.

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`

```mojo
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`

```mojo
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`

```mojo
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`

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

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

### `decode_varint`

```mojo
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

### `VARINT_MAX`

```mojo
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.