@blockcast/fec-worker 0.1.0

package/dist/shred-worker-client.js

@@ -0,0 +1,181 @@
+/**
+ * @blockcast/fec-worker — Shred Worker Main-Thread Client
+ *
+ * Thin wrapper over the shred (Reed-Solomon) worker, mirroring
+ * {@link FecWorkerClient}'s shape. Spawns one Worker, speaks the
+ * {@link ShredWorkerCommand}/{@link ShredWorkerEvent} protocol, and keeps the
+ * datagram read loop + wire parse + WASM FEC off the main thread.
+ *
+ * Typical wiring for a WebTransport datagram source (fully off-thread):
+ *
+ *   const client = new ShredWorkerClient(new URL("./shred-fec-worker.js", import.meta.url));
+ *   client.onRecovered((data, meta) => renderRecoveredSet(data, meta));
+ *   client.configure({ maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" });
+ *   client.attachStream(wt.datagrams.readable); // transferred; main does no read() per packet
+ *
+ * For sources that demux on the main thread (moqtail OBJECT_DATAGRAM callback,
+ * IWA multicast bridge), push each raw frame with {@link feedShred} instead.
+ *
+ * {@link feedShred} is a fire-and-forget `postMessage` with no native
+ * backpressure, so a consumer that decodes slower than the ingest rate (a
+ * backgrounded/throttled tab, WASM RS falling behind a ~4k shred/s feed) would
+ * grow the worker's inbound message queue without limit — the queue lives in the
+ * renderer process and has been observed to reach multiple GB, GC-thrashing the
+ * page into a wedge. The client bounds it with an in-flight window keyed off the
+ * worker's own periodic stats heartbeat (no per-frame ack round-trip); see
+ * {@link ShredWorkerClientOptions.maxInflight}.
+ */
+/** Default {@link ShredWorkerClientOptions.maxInflight} (~10 MB of queued frames). */
+export const DEFAULT_MAX_INFLIGHT = 8192;
+export class ShredWorkerClient {
+    #worker;
+    #onRecovered = null;
+    #onStats = null;
+    #onError = null;
+    #disposed = false;
+    /** feedShred in-flight backpressure accounting (see ShredWorkerClientOptions.maxInflight). */
+    #maxInflight;
+    #sent = 0; // frames posted via feedShred (monotonic)
+    #processed = 0; // worker-consumed total from the last stats heartbeat (monotonic)
+    #droppedBackpressure = 0; // frames dropped by the in-flight guard (monotonic)
+    /**
+     * @param workerOrUrl - A URL (a Worker is created internally, `type: module`)
+     *   or a pre-created Worker (for testing via constructor injection).
+     * @param opts - Optional {@link ShredWorkerClientOptions}.
+     */
+    constructor(workerOrUrl, opts = {}) {
+        this.#maxInflight = opts.maxInflight ?? DEFAULT_MAX_INFLIGHT;
+        this.#worker =
+            workerOrUrl instanceof URL
+                ? new Worker(workerOrUrl, { type: "module" })
+                : workerOrUrl;
+        this.#worker.onmessage = (e) => this.#handleEvent(e.data);
+        this.#worker.onerror = (e) => this.#onError?.(formatWorkerError(e), "worker-runtime");
+        this.#worker.onmessageerror = () => this.#onError?.("failed to deserialize worker message", "worker-message");
+    }
+    /** Configure the decoder (WASM load + ShredFecBuffer construction happen in the worker). */
+    configure(config) {
+        if (this.#disposed)
+            throw new Error("[ShredWorkerClient] disposed");
+        this.#post({ type: "configure", config });
+    }
+    /**
+     * Hand the worker a stream of raw shred frames to batch-drain. The stream is
+     * transferred — the caller must not use it afterward. One active stream at a
+     * time; attaching a new one cancels the previous.
+     */
+    attachStream(readable) {
+        if (this.#disposed)
+            return;
+        this.#post({ type: "attachStream", readable }, [readable]);
+    }
+    /**
+     * Feed one already-demuxed raw shred frame. `frame` is transferred zero-copy;
+     * the caller must not access it afterward.
+     *
+     * Dropped (frame NOT transferred, so the caller's buffer stays intact) when the
+     * in-flight window is full — i.e. the worker is more than `maxInflight` frames
+     * behind. This is the memory bound: a slow/wedged consumer costs bounded
+     * skip-to-live drops (see {@link droppedBackpressure}), never an unbounded
+     * renderer-heap blow-up.
+     */
+    feedShred(frame) {
+        if (this.#disposed)
+            return;
+        if (this.#maxInflight > 0 && this.#sent - this.#processed >= this.#maxInflight) {
+            this.#droppedBackpressure++;
+            return;
+        }
+        this.#sent++;
+        this.#post({ type: "feedShred", frame }, [frame]);
+    }
+    /** Explicitly drive loss recovery (in addition to the worker's internal timer). */
+    recoverAll(nowMs = Date.now()) {
+        if (this.#disposed)
+            return;
+        this.#post({ type: "recoverAll", nowMs });
+    }
+    /** Register callback for recovered/completed FEC sets. `data` is a transferred buffer. */
+    onRecovered(cb) {
+        this.#onRecovered = cb;
+    }
+    /** Register callback for the coalesced stats heartbeat. */
+    onStats(cb) {
+        this.#onStats = cb;
+    }
+    /** Register callback for worker errors. */
+    onError(cb) {
+        this.#onError = cb;
+    }
+    /**
+     * Frames dropped by the in-flight backpressure guard since construction
+     * (monotonic). Surface this in the UI so sustained loss is visible rather than
+     * silent — a rising counter means the consumer can't keep pace with ingest.
+     */
+    get droppedBackpressure() {
+        return this.#droppedBackpressure;
+    }
+    /**
+     * Frames posted via {@link feedShred} but not yet reported drained by the
+     * worker's last stats heartbeat (best-effort, heartbeat-granular; never < 0).
+     */
+    get inflight() {
+        return Math.max(0, this.#sent - this.#processed);
+    }
+    /** Dispose the worker. Idempotent. */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        try {
+            this.#worker.postMessage({ type: "dispose" });
+        }
+        catch {
+            /* worker may already be gone */
+        }
+        this.#worker.terminate();
+    }
+    #post(cmd, transfer = []) {
+        this.#worker.postMessage(cmd, transfer);
+    }
+    #handleEvent(event) {
+        switch (event.type) {
+            case "recovered":
+                this.#onRecovered?.(event.data, event.meta);
+                break;
+            case "stats":
+                // The worker's monotonic consumed-frame total is the drain signal for
+                // the feedShred in-flight guard. shredsRx counts only valid frames;
+                // malformed + versionMismatch are consumed off the queue too, so the
+                // sum is the true "frames taken off the queue" and keeps the window
+                // from inflating (and false-dropping) on a malformed/skewed source.
+                this.#processed =
+                    event.stats.shredsRx + event.stats.malformed + event.stats.versionMismatch;
+                this.#onStats?.(event.stats);
+                break;
+            case "error":
+                if (event.code)
+                    this.#onError?.(event.message, event.code);
+                else
+                    this.#onError?.(event.message);
+                break;
+        }
+    }
+}
+function formatWorkerError(event) {
+    const parts = ["Worker error"];
+    if (event.message)
+        parts.push(event.message);
+    if (event.filename) {
+        const loc = [event.filename];
+        if (event.lineno)
+            loc.push(String(event.lineno));
+        if (event.colno)
+            loc.push(String(event.colno));
+        parts.push(`at ${loc.join(":")}`);
+    }
+    if (event.error instanceof Error && event.error.stack)
+        parts.push(event.error.stack);
+    return parts.join(": ");
+}
+//# sourceMappingURL=shred-worker-client.js.map

package/dist/shred-worker-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shred-worker-client.js","sourceRoot":"","sources":["../src/shred-worker-client.ts"],"names":[],"mappings":"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"}

package/dist/shred-worker-types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @blockcast/fec-worker — Shred (Reed-Solomon) Worker Protocol
+ *
+ * A sibling codec to the RaptorQ/MMTP worker (`fec-worker.ts`). Solana-style
+ * shred streams carry a different FEC payload identity than MMTP source/repair
+ * symbols — a shred is `(slot, fecSetIndex, localIndex, numData, numCoding,
+ * isCoding, lastInSet)`, not a flat `ssId` — so they need their own command
+ * shape. The transport harness (Worker spawn, onmessage plumbing, zero-copy
+ * `toOwnedArrayBuffer` transfers) is shared; the decoder WASM is not.
+ *
+ * The worker owns the batch-drain: the consumer transfers a WebTransport
+ * `datagrams.readable` (or any `ReadableStream<Uint8Array>` of raw shred
+ * frames) into the Worker via {@link ShredWorkerCommand} `attachStream`, and
+ * the read loop + wire parse + `ShredFecBuffer.add_shred` all run off the main
+ * thread. Only recovered FEC sets (and coalesced stats) cross back. A
+ * `feedShred` command covers sources that have already demuxed the shred bytes
+ * on the main thread (e.g. a moqtail OBJECT_DATAGRAM callback, or the IWA
+ * multicast bridge).
+ *
+ * Types here are importable from both main thread and Worker contexts.
+ */
+/**
+ * Wire header layout the worker parses. Mirrors the deployed shred player's
+ * `onShredBytes` exactly (libmmt shred-forwarder `emit_frame`) so the off-thread
+ * path is bit-identical to the proven on-thread path.
+ *
+ * v3 (28-byte header):
+ *   [0]      version       u8   (== 3; non-3 frames are dropped, not misframed)
+ *   [1-8]    slot          u64 LE
+ *   [9-12]   fecSetIndex   u32 LE
+ *   [13-16]  localIndex    u32 LE   (data: 0..numData; coding: numData+position)
+ *   [17]     flags         u8       (bit0 = DATA_COMPLETE, bit1 = IS_CODING_SHRED)
+ *   [18]     numData       u8       (coding shreds only; 0 on data — WASM infers)
+ *   [19]     numCoding     u8       (coding shreds only; 0 on data)
+ *   [20-27]  sendTsUs      u64 LE   (µs since epoch, 0 when unstamped)
+ *   [28+]    erasureShard           (equal length across the FEC set)
+ *
+ * DATA_COMPLETE (last data shred in the set) is passed to `add_shred` as its
+ * `lastInSet` argument — the WASM uses it to infer numData for a set that
+ * received only data shreds (no coding).
+ */
+export declare const SHRED_WIRE_VERSION = 3;
+export declare const SHRED_HEADER_LEN = 28;
+export declare const SHRED_FLAG_DATA_COMPLETE = 1;
+export declare const SHRED_FLAG_IS_CODING = 2;
+/** Per-decoder configuration for the shred FEC worker. */
+export interface ShredWorkerConfig {
+    /** Ring capacity in slots (matches `new ShredFecBuffer(maxSlots, symbolSize)`). */
+    maxSlots: number;
+    /** Symbol size in bytes (Solana shred payloads are fixed-size within a set). */
+    symbolSize: number;
+    /**
+     * Module URL for the shred WASM (wasm-bindgen ESM exporting `default` init +
+     * `ShredFecBuffer`). The worker `import()`s it and calls `await default()`.
+     * Ignored when `self.__SHRED_WASM_BINDINGS__` is pre-injected (tests / custom
+     * loaders), mirroring the RaptorQ worker's `__MMT_WASM_BINDINGS__` contract.
+     */
+    wasmUrl?: string;
+    /**
+     * How often (ms) the worker coalesces and posts a `stats` event. The read
+     * loop never posts per-shred; only recovered frames and this heartbeat cross
+     * the boundary. Default 250ms.
+     */
+    statsIntervalMs?: number;
+    /**
+     * How often (ms) the worker runs `try_recover_all(now)` to drain timed-out
+     * FEC sets that `add_shred` didn't complete (loss scenarios). Default 50ms,
+     * matching the player's on-thread recovery timer. Set to 0 to disable (the
+     * consumer may instead drive it explicitly with `recoverAll`).
+     */
+    recoverIntervalMs?: number;
+}
+/**
+ * First-shred-per-slot sample, collected by the worker and drained into each
+ * coalesced `stats` heartbeat. Lets the main thread run app-specific,
+ * slot-derived stats (e.g. the turbine-leg latency estimator, per-slot latency
+ * percentiles) WITHOUT re-parsing the wire header — the worker stays the single
+ * source of truth for parsing, and these cross the boundary aggregated (a
+ * handful per heartbeat), never per-packet.
+ */
+export interface SlotSample {
+    /** Slot number (first shred of this slot the worker saw). */
+    slot: bigint;
+    /** Publisher send timestamp (µs since epoch) of that first shred, 0 when unstamped. */
+    sendTsUs: bigint;
+    /** Frame byte length of that first shred. */
+    bytes: number;
+}
+/** Aggregate shred-decode counters, emitted on the coalesced `stats` heartbeat. */
+export interface ShredWorkerStats {
+    /** Total shred frames parsed (data + coding). */
+    shredsRx: number;
+    /** Data (source) shreds observed. */
+    sourceShreds: number;
+    /** Coding (repair) shreds observed. */
+    repairShreds: number;
+    /** FEC sets completed (direct completion + FEC recovery). */
+    fecSetsCompleted: number;
+    /** Bytes handed back as recovered/completed sets. */
+    bytesReassembled: number;
+    /** Sets recovered specifically via `try_recover_all` (loss recovery). */
+    fecSetsRecovered: number;
+    /** Current `ShredFecBuffer.pending_fec_sets()`, or -1 when unavailable. */
+    pendingFecSets: number;
+    /** Frames dropped for being shorter than the v3 header. */
+    malformed: number;
+    /** Frames dropped for carrying a non-v3 version byte (forwarder/worker skew). */
+    versionMismatch: number;
+    /** Highest slot number observed (as a string — bigint isn't JSON-safe for UI). */
+    currentSlot: string;
+    /** First-shred-per-slot samples parsed since the previous heartbeat (drained each emit). */
+    slotSamples: SlotSample[];
+}
+/** Stable identities for worker failures whose message text carries live values. */
+export type ShredWorkerErrorCode = "wasm-load-failed" | "wasm-bindings-missing" | "not-configured" | "stream-read-failed" | "unknown-command" | "worker-runtime" | "worker-message";
+/** Metadata attached to each recovered set the worker emits. */
+export interface RecoveredMeta {
+    /**
+     * Slot the recovered set belongs to. Attributed on both the direct-completion
+     * path and the identity-carrying recovery drain
+     * (`try_recover_all_with_identity`); only 0n on the legacy `ShredReassembler`
+     * fallback, which has no identity variant. Do NOT branch on `slot === 0n` as
+     * "unattributed" — that would drop the majority of recovered sets.
+     */
+    slot: bigint;
+    /** FEC set index within the slot (0 only on the legacy identity-less fallback). */
+    fecSetIndex: number;
+    /**
+     * Publisher send timestamp (µs since epoch), 0 when unstamped/unknown. On
+     * direct completion this is the completing shred's stamp; on the recovery
+     * drain it is the set's first-seen shred stamp (shreds of a set are sent µs
+     * apart, so the two are equivalent latency baselines).
+     */
+    sendTsUs: bigint;
+    /** True when produced by loss recovery (`try_recover_all`) rather than direct completion. */
+    recovered: boolean;
+}
+/** Discriminated union of all commands sent from the main thread to the shred worker. */
+export type ShredWorkerCommand = {
+    type: "configure";
+    config: ShredWorkerConfig;
+} | {
+    /**
+     * Hand the worker a stream of raw shred frames to batch-drain. Each
+     * chunk is one wire frame (one WebTransport datagram). The stream is
+     * transferred (add to the postMessage transfer list) — the main thread
+     * must not touch it afterward.
+     */
+    type: "attachStream";
+    readable: ReadableStream<Uint8Array>;
+} | {
+    /**
+     * Feed one already-demuxed raw shred frame. `frame` is transferred
+     * zero-copy — the caller must not access it after posting. Use this for
+     * sources whose demux stays on the main thread (moqtail OBJECT_DATAGRAM
+     * callback, IWA multicast bridge).
+     */
+    type: "feedShred";
+    frame: ArrayBuffer;
+} | {
+    type: "recoverAll";
+    nowMs: number;
+} | {
+    type: "dispose";
+};
+/** Discriminated union of all events emitted from the shred worker to the main thread. */
+export type ShredWorkerEvent = {
+    type: "recovered";
+    data: ArrayBuffer;
+    meta: RecoveredMeta;
+} | {
+    type: "stats";
+    stats: ShredWorkerStats;
+} | {
+    type: "error";
+    message: string;
+    code?: ShredWorkerErrorCode;
+};
+//# sourceMappingURL=shred-worker-types.d.ts.map

package/dist/shred-worker-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shred-worker-types.d.ts","sourceRoot":"","sources":["../src/shred-worker-types.ts"],"names":[],"mappings":"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"}

package/dist/shred-worker-types.js

@@ -0,0 +1,47 @@
+/**
+ * @blockcast/fec-worker — Shred (Reed-Solomon) Worker Protocol
+ *
+ * A sibling codec to the RaptorQ/MMTP worker (`fec-worker.ts`). Solana-style
+ * shred streams carry a different FEC payload identity than MMTP source/repair
+ * symbols — a shred is `(slot, fecSetIndex, localIndex, numData, numCoding,
+ * isCoding, lastInSet)`, not a flat `ssId` — so they need their own command
+ * shape. The transport harness (Worker spawn, onmessage plumbing, zero-copy
+ * `toOwnedArrayBuffer` transfers) is shared; the decoder WASM is not.
+ *
+ * The worker owns the batch-drain: the consumer transfers a WebTransport
+ * `datagrams.readable` (or any `ReadableStream<Uint8Array>` of raw shred
+ * frames) into the Worker via {@link ShredWorkerCommand} `attachStream`, and
+ * the read loop + wire parse + `ShredFecBuffer.add_shred` all run off the main
+ * thread. Only recovered FEC sets (and coalesced stats) cross back. A
+ * `feedShred` command covers sources that have already demuxed the shred bytes
+ * on the main thread (e.g. a moqtail OBJECT_DATAGRAM callback, or the IWA
+ * multicast bridge).
+ *
+ * Types here are importable from both main thread and Worker contexts.
+ */
+// --- Wire format ------------------------------------------------------------
+/**
+ * Wire header layout the worker parses. Mirrors the deployed shred player's
+ * `onShredBytes` exactly (libmmt shred-forwarder `emit_frame`) so the off-thread
+ * path is bit-identical to the proven on-thread path.
+ *
+ * v3 (28-byte header):
+ *   [0]      version       u8   (== 3; non-3 frames are dropped, not misframed)
+ *   [1-8]    slot          u64 LE
+ *   [9-12]   fecSetIndex   u32 LE
+ *   [13-16]  localIndex    u32 LE   (data: 0..numData; coding: numData+position)
+ *   [17]     flags         u8       (bit0 = DATA_COMPLETE, bit1 = IS_CODING_SHRED)
+ *   [18]     numData       u8       (coding shreds only; 0 on data — WASM infers)
+ *   [19]     numCoding     u8       (coding shreds only; 0 on data)
+ *   [20-27]  sendTsUs      u64 LE   (µs since epoch, 0 when unstamped)
+ *   [28+]    erasureShard           (equal length across the FEC set)
+ *
+ * DATA_COMPLETE (last data shred in the set) is passed to `add_shred` as its
+ * `lastInSet` argument — the WASM uses it to infer numData for a set that
+ * received only data shreds (no coding).
+ */
+export const SHRED_WIRE_VERSION = 3;
+export const SHRED_HEADER_LEN = 28;
+export const SHRED_FLAG_DATA_COMPLETE = 0x01;
+export const SHRED_FLAG_IS_CODING = 0x02;
+//# sourceMappingURL=shred-worker-types.js.map

package/dist/shred-worker-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shred-worker-types.js","sourceRoot":"","sources":["../src/shred-worker-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAC7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC"}

package/dist/transfer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Return a fresh ArrayBuffer containing exactly the bytes in `view`.
+ *
+ * Worker outputs must not transfer buffers that might be owned by a WASM
+ * binding or by a larger shared packet. A fresh JS-owned buffer gives
+ * postMessage() exclusive ownership without detaching unrelated memory.
+ */
+export declare function toOwnedArrayBuffer(view: Uint8Array): ArrayBuffer;
+//# sourceMappingURL=transfer.d.ts.map

package/dist/transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAIhE"}

package/dist/transfer.js

@@ -0,0 +1,13 @@
+/**
+ * Return a fresh ArrayBuffer containing exactly the bytes in `view`.
+ *
+ * Worker outputs must not transfer buffers that might be owned by a WASM
+ * binding or by a larger shared packet. A fresh JS-owned buffer gives
+ * postMessage() exclusive ownership without detaching unrelated memory.
+ */
+export function toOwnedArrayBuffer(view) {
+    const copy = new Uint8Array(view.byteLength);
+    copy.set(view);
+    return copy.buffer;
+}
+//# sourceMappingURL=transfer.js.map

package/dist/transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.js","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IAClD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACf,OAAO,IAAI,CAAC,MAAM,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@blockcast/fec-worker",
+  "version": "0.1.0",
+  "description": "Worker-per-track FEC decode with zero-copy ArrayBuffer transfer and ALTA auth plumbing",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./worker": {
+      "import": "./dist/fec-worker.js"
+    },
+    "./shred-worker": {
+      "import": "./dist/shred-fec-worker.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc && node build.mjs",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@blockcast/mmt-alta-parse": "^0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "fec",
+    "worker",
+    "raptorq",
+    "zero-copy",
+    "transferable",
+    "alta"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/fec-worker"
+  }
+}