@blockcast/fec-worker 0.1.0 → 0.3.0

package/src/fec-worker-types.test.ts

@@ -1,400 +0,0 @@
-import { describe, it, expect } from "vitest";
-import type {
-	FecWorkerCommand,
-	FecWorkerEvent,
-	FecTrackConfig,
-	FecBlockSnapshot,
-	FecTrackStats,
-	FrameMeta,
-} from "./fec-worker-types.js";
-
-// Helper: compile-time type assertion — if this file compiles, types are correct
-function assertType<T>(_value: T): void {
-	/* compile-time only */
-}
-
-describe("FecWorkerCommand", () => {
-	it("configure includes wasmModule and optional altaPublicKey (AUTH-03)", () => {
-		const cmd: FecWorkerCommand = {
-			type: "configure",
-			config: {
-				codec: "avc1.64001f",
-				trackName: "video",
-				trackType: "video",
-				algorithm: "raptor",
-				k: 32,
-				repairCount: 8,
-				symbolSize: 1320,
-				interleaveDepth: 4,
-				interleaveMs: 133,
-				deliveryWindowMs: 1000,
-				fecMode: "subframe",
-				altaEnabled: false,
-				relayBlockSigEnabled: false,
-			},
-			wasmModule: {} as WebAssembly.Module,
-			altaPublicKey: new ArrayBuffer(32),
-		};
-		expect(cmd.type).toBe("configure");
-		assertType<WebAssembly.Module>(cmd.wasmModule);
-	});
-
-	it("feedSource carries ssId, data ArrayBuffer, ts (matches WASM add_source signature)", () => {
-		const cmd: FecWorkerCommand = {
-			type: "feedSource",
-			ssId: 0,
-			data: new ArrayBuffer(1320),
-			ts: 1000,
-		};
-		expect(cmd.type).toBe("feedSource");
-		assertType<ArrayBuffer>(cmd.data);
-		assertType<number>(cmd.ssId);
-	});
-
-	it("feedRepair carries ssStart, ssbLength, rsId, data, ts (matches WASM add_repair)", () => {
-		const cmd: FecWorkerCommand = {
-			type: "feedRepair",
-			ssStart: 0,
-			ssbLength: 4,
-			rsId: 0,
-			data: new ArrayBuffer(1320),
-			ts: 1000,
-		};
-		expect(cmd.type).toBe("feedRepair");
-		assertType<ArrayBuffer>(cmd.data);
-		assertType<number>(cmd.ssStart);
-		assertType<number>(cmd.ssbLength);
-		assertType<number>(cmd.rsId);
-	});
-
-	it("relayBlockSig carries sbn, sig, hash as ArrayBuffers", () => {
-		const cmd: FecWorkerCommand = {
-			type: "relayBlockSig",
-			sbn: 5,
-			sig: new ArrayBuffer(64),
-			hash: new ArrayBuffer(32),
-		};
-		expect(cmd.type).toBe("relayBlockSig");
-		assertType<ArrayBuffer>(cmd.sig);
-		assertType<ArrayBuffer>(cmd.hash);
-	});
-
-	it("cleanup carries every coalesced SBN", () => {
-		const cmd: FecWorkerCommand = {
-			type: "cleanup",
-			sbns: [10, 11],
-		};
-		expect(cmd.type).toBe("cleanup");
-		expect(cmd.sbns).toEqual([10, 11]);
-	});
-
-	it("dispose has no additional fields", () => {
-		const cmd: FecWorkerCommand = { type: "dispose" };
-		expect(cmd.type).toBe("dispose");
-	});
-
-	it("discriminates all 6 command types", () => {
-		const types = [
-			"configure",
-			"feedSource",
-			"feedRepair",
-			"relayBlockSig",
-			"cleanup",
-			"dispose",
-		] as const;
-		// Verify each type string is assignable to FecWorkerCommand['type']
-		for (const t of types) {
-			assertType<FecWorkerCommand["type"]>(t);
-		}
-		expect(types).toHaveLength(6);
-	});
-});
-
-describe("FecWorkerEvent", () => {
-	it("frame event carries data ArrayBuffer and FrameMeta", () => {
-		const evt: FecWorkerEvent = {
-			type: "frame",
-			data: new ArrayBuffer(1320),
-			meta: { altaVerified: null, recovered: false, sbn: 0 },
-		};
-		expect(evt.type).toBe("frame");
-	});
-
-	it("snapshot event carries FecTrackStats", () => {
-		const config: FecTrackConfig = {
-			codec: "avc1.64001f",
-			trackName: "video",
-			trackType: "video",
-			algorithm: "raptor",
-			k: 32,
-			repairCount: 8,
-			symbolSize: 1320,
-			interleaveDepth: 4,
-			interleaveMs: 133,
-			deliveryWindowMs: 1000,
-			fecMode: "subframe",
-			altaEnabled: false,
-			relayBlockSigEnabled: false,
-		};
-		const evt: FecWorkerEvent = {
-			type: "snapshot",
-			stats: {
-				config,
-				sourceSymbols: 0,
-				repairSymbols: 0,
-				blocksComplete: 0,
-				blocksRecovered: 0,
-				blocksFailed: 0,
-				greenFillFrames: 0,
-				recoveryRate: 0,
-				altaVerified: 0,
-				altaFailed: 0,
-				relayBlocksVerified: 0,
-				relayBlocksFailed: 0,
-				liveSbn: 0,
-				blocks: [],
-				interleaveWindowBlocks: 0,
-				avgRecoveryMs: 0,
-				maxRecoveryMs: 0,
-			},
-		};
-		expect(evt.type).toBe("snapshot");
-	});
-
-	it("blockUpdate event carries FecBlockSnapshot", () => {
-		const evt: FecWorkerEvent = {
-			type: "blockUpdate",
-			block: {
-				sbn: 0,
-				state: "collecting",
-				sourceReceived: 5,
-				repairReceived: 0,
-				k: 32,
-				repairCount: 8,
-				firstSymbolTs: 1000,
-				lastSymbolTs: 1100,
-				deadlineTs: 2000,
-				altaVerified: 5,
-				relayBlockSigValid: null,
-			},
-		};
-		expect(evt.type).toBe("blockUpdate");
-	});
-
-	it("greenFill event carries sbn and data", () => {
-		const evt: FecWorkerEvent = {
-			type: "greenFill",
-			sbn: 3,
-			data: new ArrayBuffer(0),
-		};
-		expect(evt.type).toBe("greenFill");
-	});
-
-	it("cleanupComplete event carries every acknowledged SBN", () => {
-		const evt: FecWorkerEvent = {
-			type: "cleanupComplete",
-			sbns: [3, 4],
-		};
-		expect(evt.type).toBe("cleanupComplete");
-		expect(evt.sbns).toEqual([3, 4]);
-	});
-
-	it("error event carries message string", () => {
-		const evt: FecWorkerEvent = {
-			type: "error",
-			code: "command-failed",
-			message: "WASM init failed",
-		};
-		expect(evt.type).toBe("error");
-		expect(evt.message).toBe("WASM init failed");
-		expect(evt.code).toBe("command-failed");
-	});
-
-	it("discriminates all 6 event types", () => {
-		const types = [
-			"frame",
-			"snapshot",
-			"blockUpdate",
-			"greenFill",
-			"cleanupComplete",
-			"error",
-		] as const;
-		for (const t of types) {
-			assertType<FecWorkerEvent["type"]>(t);
-		}
-		expect(types).toHaveLength(6);
-	});
-});
-
-describe("FecTrackConfig", () => {
-	it("contains altaEnabled boolean (AUTH-01)", () => {
-		const config: FecTrackConfig = {
-			codec: "mp4a.40.2",
-			trackName: "audio",
-			trackType: "audio",
-			sampleRate: 48000,
-			algorithm: "raptor",
-			k: 16,
-			repairCount: 4,
-			symbolSize: 512,
-			interleaveDepth: 2,
-			interleaveMs: 42,
-			deliveryWindowMs: 500,
-			fecMode: "object",
-			altaEnabled: true,
-			relayBlockSigEnabled: false,
-		};
-		assertType<boolean>(config.altaEnabled);
-		expect(config.altaEnabled).toBe(true);
-	});
-
-	it("contains relayBlockSigEnabled boolean (AUTH-01)", () => {
-		const config: FecTrackConfig = {
-			codec: "avc1.64001f",
-			trackName: "video",
-			trackType: "video",
-			resolution: { w: 1280, h: 720 },
-			framerate: 30,
-			algorithm: "raptor",
-			k: 32,
-			repairCount: 8,
-			symbolSize: 1320,
-			interleaveDepth: 4,
-			interleaveMs: 133,
-			deliveryWindowMs: 1000,
-			fecMode: "subframe",
-			altaEnabled: false,
-			relayBlockSigEnabled: true,
-		};
-		assertType<boolean>(config.relayBlockSigEnabled);
-		expect(config.relayBlockSigEnabled).toBe(true);
-	});
-});
-
-describe("FecBlockSnapshot", () => {
-	it("contains altaVerified number (AUTH-02)", () => {
-		const block: FecBlockSnapshot = {
-			sbn: 0,
-			state: "complete",
-			sourceReceived: 32,
-			repairReceived: 0,
-			k: 32,
-			repairCount: 8,
-			firstSymbolTs: 100,
-			lastSymbolTs: 200,
-			completedTs: 250,
-			deadlineTs: 500,
-			altaVerified: 30,
-			relayBlockSigValid: true,
-		};
-		assertType<number>(block.altaVerified);
-		expect(block.altaVerified).toBe(30);
-	});
-
-	it("relayBlockSigValid can be boolean or null (AUTH-02)", () => {
-		const pending: FecBlockSnapshot = {
-			sbn: 1,
-			state: "collecting",
-			sourceReceived: 10,
-			repairReceived: 2,
-			k: 32,
-			repairCount: 8,
-			firstSymbolTs: 300,
-			lastSymbolTs: 400,
-			deadlineTs: 700,
-			altaVerified: 8,
-			relayBlockSigValid: null,
-		};
-		assertType<boolean | null>(pending.relayBlockSigValid);
-		expect(pending.relayBlockSigValid).toBeNull();
-	});
-});
-
-describe("FecTrackStats", () => {
-	it("contains all required aggregate fields", () => {
-		const config: FecTrackConfig = {
-			codec: "avc1.64001f",
-			trackName: "video",
-			trackType: "video",
-			algorithm: "raptor",
-			k: 32,
-			repairCount: 8,
-			symbolSize: 1320,
-			interleaveDepth: 4,
-			interleaveMs: 133,
-			deliveryWindowMs: 1000,
-			fecMode: "subframe",
-			altaEnabled: false,
-			relayBlockSigEnabled: false,
-		};
-		const stats: FecTrackStats = {
-			config,
-			sourceSymbols: 1240,
-			repairSymbols: 312,
-			blocksComplete: 380,
-			blocksRecovered: 18,
-			blocksFailed: 2,
-			greenFillFrames: 2,
-			recoveryRate: 90,
-			altaVerified: 12400,
-			altaFailed: 3,
-			relayBlocksVerified: 380,
-			relayBlocksFailed: 0,
-			liveSbn: 400,
-			blocks: [],
-			interleaveWindowBlocks: 4,
-			avgRecoveryMs: 42,
-			maxRecoveryMs: 180,
-		};
-		assertType<FecTrackConfig>(stats.config);
-		assertType<number>(stats.sourceSymbols);
-		assertType<number>(stats.repairSymbols);
-		assertType<number>(stats.blocksComplete);
-		assertType<number>(stats.blocksRecovered);
-		assertType<number>(stats.blocksFailed);
-		assertType<number>(stats.greenFillFrames);
-		assertType<number>(stats.recoveryRate);
-		assertType<number>(stats.altaVerified);
-		assertType<number>(stats.altaFailed);
-		assertType<number>(stats.liveSbn);
-		assertType<FecBlockSnapshot[]>(stats.blocks);
-		assertType<number>(stats.interleaveWindowBlocks);
-		assertType<number>(stats.avgRecoveryMs);
-		assertType<number>(stats.maxRecoveryMs);
-		expect(stats.recoveryRate).toBe(90);
-	});
-});
-
-describe("FrameMeta", () => {
-	it("altaVerified is boolean | null (AUTH-04)", () => {
-		const metaWithAlta: FrameMeta = {
-			altaVerified: true,
-			recovered: false,
-			sbn: 5,
-		};
-		assertType<boolean | null>(metaWithAlta.altaVerified);
-		expect(metaWithAlta.altaVerified).toBe(true);
-
-		const metaWithoutAlta: FrameMeta = {
-			altaVerified: null,
-			recovered: true,
-			sbn: 5,
-		};
-		expect(metaWithoutAlta.altaVerified).toBeNull();
-	});
-
-	it("contains recovered boolean plus block and symbol coordinates", () => {
-		const meta: FrameMeta = {
-			altaVerified: null,
-			recovered: true,
-			sbn: 42,
-			esi: 3,
-		};
-		assertType<boolean>(meta.recovered);
-		assertType<number>(meta.sbn);
-		assertType<number | undefined>(meta.esi);
-		expect(meta.recovered).toBe(true);
-		expect(meta.sbn).toBe(42);
-		expect(meta.esi).toBe(3);
-	});
-});

package/src/shred-worker-client.test.ts

@@ -1,182 +0,0 @@
-import { describe, it, expect } from "vitest";
-import type {
-	ShredWorkerCommand,
-	ShredWorkerEvent,
-	ShredWorkerStats,
-} from "./shred-worker-types.js";
-import { ShredWorkerClient } from "./shred-worker-client.js";
-
-class MockWorker {
-	onmessage: ((e: MessageEvent) => void) | null = null;
-	onerror: ((e: ErrorEvent) => void) | null = null;
-	onmessageerror: ((e: MessageEvent) => void) | null = null;
-	posted: Array<{ data: ShredWorkerCommand; transfer: Transferable[] }> = [];
-	terminated = false;
-
-	postMessage(data: ShredWorkerCommand, transfer?: Transferable[]): void {
-		this.posted.push({ data, transfer: transfer ?? [] });
-	}
-	terminate(): void {
-		this.terminated = true;
-	}
-	emit(event: ShredWorkerEvent): void {
-		this.onmessage?.({ data: event } as MessageEvent);
-	}
-}
-
-function makeStats(overrides: Partial<ShredWorkerStats> = {}): ShredWorkerStats {
-	return {
-		shredsRx: 0,
-		sourceShreds: 0,
-		repairShreds: 0,
-		fecSetsCompleted: 0,
-		bytesReassembled: 0,
-		fecSetsRecovered: 0,
-		pendingFecSets: -1,
-		malformed: 0,
-		versionMismatch: 0,
-		currentSlot: "0",
-		slotSamples: [],
-		...overrides,
-	};
-}
-
-describe("ShredWorkerClient", () => {
-	it("posts configure with the config", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		client.configure({ maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" });
-		expect(worker.posted[0].data).toEqual({
-			type: "configure",
-			config: { maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" },
-		});
-	});
-
-	it("transfers the readable stream on attachStream", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		const readable = new ReadableStream<Uint8Array>();
-		client.attachStream(readable);
-		const msg = worker.posted[0];
-		expect(msg.data.type).toBe("attachStream");
-		expect(msg.transfer).toEqual([readable]);
-	});
-
-	it("transfers the frame buffer on feedShred", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		const frame = new Uint8Array([1, 2, 3]).buffer;
-		client.feedShred(frame);
-		const msg = worker.posted[0];
-		expect(msg.data).toEqual({ type: "feedShred", frame });
-		expect(msg.transfer).toEqual([frame]);
-	});
-
-	it("bounds feedShred to maxInflight when the worker never drains", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 4 });
-		for (let i = 0; i < 10; i++) client.feedShred(new Uint8Array([i]).buffer);
-		const fed = worker.posted.filter((p) => p.data.type === "feedShred");
-		expect(fed.length).toBe(4); // only maxInflight frames posted; the rest dropped
-		expect(client.droppedBackpressure).toBe(6);
-		expect(client.inflight).toBe(4);
-	});
-
-	it("does not transfer (detach) a frame dropped by the in-flight guard", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 1 });
-		client.feedShred(new Uint8Array([1]).buffer); // posted (outstanding 0 -> 1)
-		const dropped = new Uint8Array([9, 9, 9]).buffer;
-		client.feedShred(dropped); // dropped (outstanding 1 >= 1)
-		// A dropped frame is never added to a transfer list, so the caller's buffer
-		// is untouched — no attempt to reuse a detached ArrayBuffer.
-		expect(dropped.byteLength).toBe(3);
-		expect(worker.posted.filter((p) => p.transfer.includes(dropped)).length).toBe(0);
-	});
-
-	it("resumes feeding after the worker reports drain progress via stats", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 4 });
-		for (let i = 0; i < 6; i++) client.feedShred(new Uint8Array([i]).buffer);
-		expect(worker.posted.filter((p) => p.data.type === "feedShred").length).toBe(4);
-		expect(client.droppedBackpressure).toBe(2);
-
-		// Worker heartbeat: it consumed all 4 queued frames -> window reopens.
-		worker.emit({ type: "stats", stats: makeStats({ shredsRx: 4 }) });
-		expect(client.inflight).toBe(0);
-
-		for (let i = 0; i < 3; i++) client.feedShred(new Uint8Array([100 + i]).buffer);
-		expect(worker.posted.filter((p) => p.data.type === "feedShred").length).toBe(7);
-		expect(client.droppedBackpressure).toBe(2); // no NEW drops after the window reopened
-	});
-
-	it("counts malformed + versionMismatch as drained so the window can't inflate", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 4 });
-		for (let i = 0; i < 4; i++) client.feedShred(new Uint8Array([i]).buffer);
-		// Worker drained all 4, but only 1 was valid; 2 malformed + 1 version skew.
-		worker.emit({
-			type: "stats",
-			stats: makeStats({ shredsRx: 1, malformed: 2, versionMismatch: 1 }),
-		});
-		expect(client.inflight).toBe(0);
-	});
-
-	it("maxInflight <= 0 disables the bound entirely", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker, { maxInflight: 0 });
-		for (let i = 0; i < 50; i++) client.feedShred(new Uint8Array([i]).buffer);
-		expect(worker.posted.filter((p) => p.data.type === "feedShred").length).toBe(50);
-		expect(client.droppedBackpressure).toBe(0);
-	});
-
-	it("posts recoverAll with the provided time", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		client.recoverAll(9999);
-		expect(worker.posted[0].data).toEqual({ type: "recoverAll", nowMs: 9999 });
-	});
-
-	it("dispatches recovered and stats events to callbacks", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		const recovered: Array<{ len: number; recovered: boolean }> = [];
-		const statsSeen: ShredWorkerStats[] = [];
-		client.onRecovered((data, meta) => recovered.push({ len: data.byteLength, recovered: meta.recovered }));
-		client.onStats((s) => statsSeen.push(s));
-
-		worker.emit({
-			type: "recovered",
-			data: new Uint8Array([1, 2, 3, 4]).buffer,
-			meta: { slot: 5n, fecSetIndex: 1, sendTsUs: 0n, recovered: true },
-		});
-		worker.emit({ type: "stats", stats: makeStats({ shredsRx: 7 }) });
-
-		expect(recovered).toEqual([{ len: 4, recovered: true }]);
-		expect(statsSeen[0].shredsRx).toBe(7);
-	});
-
-	it("routes error events with their code", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		const errs: Array<[string, string | undefined]> = [];
-		client.onError((m, c) => errs.push([m, c]));
-		worker.emit({ type: "error", message: "boom", code: "wasm-load-failed" });
-		expect(errs).toEqual([["boom", "wasm-load-failed"]]);
-	});
-
-	it("dispose posts dispose, terminates, and is idempotent + no-ops afterward", () => {
-		const worker = new MockWorker();
-		const client = new ShredWorkerClient(worker as unknown as Worker);
-		client.dispose();
-		expect(worker.posted[worker.posted.length - 1]?.data).toEqual({ type: "dispose" });
-		expect(worker.terminated).toBe(true);
-		const postedCount = worker.posted.length;
-		// Post-dispose calls are no-ops.
-		client.feedShred(new Uint8Array([1]).buffer);
-		client.attachStream(new ReadableStream<Uint8Array>());
-		client.recoverAll();
-		client.dispose();
-		expect(worker.posted.length).toBe(postedCount);
-	});
-});

package/src/transfer.test.ts

@@ -1,24 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { toOwnedArrayBuffer } from "./transfer.js";
-
-describe("toOwnedArrayBuffer", () => {
-	it("copies exactly the bytes in an offset Uint8Array view", () => {
-		const backing = new Uint8Array([0, 1, 2, 3, 4, 5]);
-		const view = backing.subarray(2, 5);
-
-		const owned = toOwnedArrayBuffer(view);
-
-		expect([...new Uint8Array(owned)]).toEqual([2, 3, 4]);
-		expect(owned.byteLength).toBe(3);
-		expect(owned).not.toBe(backing.buffer);
-	});
-
-	it("does not alias the source buffer after copying", () => {
-		const source = new Uint8Array([9, 8, 7]);
-		const owned = toOwnedArrayBuffer(source);
-
-		source[1] = 1;
-
-		expect([...new Uint8Array(owned)]).toEqual([9, 8, 7]);
-	});
-});