binary-protocol / encoder

(no submodules)

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

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

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

Usage: Advanced

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.

2.2 KiB Raw Blame History