# binary-protocol / encoder

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Produces the chunk-request wire frame consumed by `@suaveplan/drive-mesh`,
`drive-transport-https`, and any peer that needs to tell the sender which
chunks of a file it is still missing. The frame is compact (12-byte
header + bitmap) so even a 100k-chunk request stays under 13 kB, and it
is fixed-layout so receivers can validate it without a schema.

## Features

- 8-byte big-endian `fileId` (u64).
- 4-byte big-endian `totalChunks` (u32).
- `⌈totalChunks / 8⌉` byte bitmap where bit `i` of byte `floor(i/8)` is
  set iff chunk `i` is requested.
- Zero-allocation hot path: a single `Uint8Array` of the exact size and
  one DataView for the header.
- Range checks raise `StreamsChunkQueueError` with the matching code
  (`INVALID_CHUNK_ID` for fileId, `INVALID_TOTAL_CHUNKS` for
  totalChunks).
- Chunk ids outside `[0, totalChunks)` are silently dropped — the
  encoder's contract is "request these chunks, capped by the file
  size".

## Usage: Basic

```ts
import { encodeChunkRequest } from "@suaveplan/streams-chunk-queue";

const frame = encodeChunkRequest({
    fileId: 12345n,
    totalChunks: 10n,
    chunkIds: [0n, 2n, 5n],
});
```

## Usage: Advanced

```ts
const missing = queue.getMissingChunkIds();
const frame = encodeChunkRequest({
    fileId: queue.getStatus().fileId,
    totalChunks: queue.getStatus().totalChunks,
    chunkIds: missing,
});
await webrtcDc.send(frame);
```

## API Reference

### `encodeChunkRequest({ fileId, totalChunks, chunkIds })` → `Uint8Array`

Returns the encoded frame. Throws `StreamsChunkQueueError` when
`fileId` is outside the u64 range or `totalChunks` is outside the u32
range.

### `CHUNK_REQUEST_HEADER_SIZE`

Constant `12`. Exposed for callers that decode the frame.

## Implementation Notes

The encoder iterates over `chunkIds` (typically the missing set,
bounded by realistic transfer sizes) instead of `[0, totalChunks)` so
the hot path stays O(|chunkIds|) regardless of file size. The 8-byte
big-endian `fileId` is written as two `setUint32` calls because
`DataView` does not have a `setBigUint64` on every supported runtime
target.