@blockcast/fec-worker 0.1.0

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

@@ -0,0 +1,530 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type {
+	FecWorkerCommand,
+	FecWorkerEvent,
+	FecTrackConfig,
+	FecTrackStats,
+	FecBlockSnapshot,
+	FrameMeta,
+} from "./fec-worker-types.js";
+import { FecWorkerClient } from "./fec-worker-client.js";
+
+// --- Mock Worker ---
+
+class MockWorker {
+	onmessage: ((e: MessageEvent) => void) | null = null;
+	onerror: ((e: ErrorEvent) => void) | null = null;
+	onmessageerror: ((e: MessageEvent) => void) | null = null;
+	posted: Array<{ data: unknown; transfer: Transferable[] }> = [];
+	terminated = false;
+
+	postMessage(data: unknown, transfer?: Transferable[]): void {
+		this.posted.push({ data, transfer: transfer ?? [] });
+	}
+
+	terminate(): void {
+		this.terminated = true;
+	}
+
+	// Test helper: simulate Worker sending event back
+	simulateMessage(event: FecWorkerEvent): void {
+		this.onmessage?.({ data: event } as MessageEvent);
+	}
+
+	simulateError(message: string): void {
+		this.onerror?.({ message } as ErrorEvent);
+	}
+
+	simulateDetailedError(event: Partial<ErrorEvent>): void {
+		this.onerror?.(event as ErrorEvent);
+	}
+
+	simulateMessageError(data?: unknown): void {
+		this.onmessageerror?.({ data } as MessageEvent);
+	}
+}
+
+function makeConfig(overrides?: Partial<FecTrackConfig>): FecTrackConfig {
+	return {
+		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,
+		...overrides,
+	};
+}
+
+describe("FecWorkerClient", () => {
+	let mockWorker: MockWorker;
+	let client: FecWorkerClient;
+
+	beforeEach(() => {
+		mockWorker = new MockWorker();
+		client = new FecWorkerClient(mockWorker as unknown as Worker);
+	});
+
+	it("constructor accepts a Worker instance", () => {
+		expect(mockWorker.onmessage).toBeTypeOf("function");
+	});
+
+	describe("configure", () => {
+		it("posts configure command with wasmModule in message body (NOT transfer list — Module is structured-cloneable)", () => {
+			const config = makeConfig();
+			const wasmModule = {} as WebAssembly.Module;
+			client.configure(config, wasmModule);
+
+			expect(mockWorker.posted).toHaveLength(1);
+			const msg = mockWorker.posted[0];
+			const cmd = msg.data as Extract<FecWorkerCommand, { type: "configure" }>;
+			expect(cmd.type).toBe("configure");
+			expect(cmd.config).toBe(config);
+			expect(cmd.wasmModule).toBe(wasmModule);
+			// WebAssembly.Module is structured-cloneable, NOT transferable
+			expect(msg.transfer).not.toContain(wasmModule);
+		});
+
+		it("includes altaPublicKey in transferList but NOT altaWasmModule (AUTH-03, Plan 08-03)", () => {
+			const config = makeConfig({ altaEnabled: true });
+			const wasmModule = {} as WebAssembly.Module;
+			const altaKey = new ArrayBuffer(32);
+			const altaWasmModule = {} as WebAssembly.Module;
+			client.configure(config, wasmModule, altaKey, altaWasmModule);
+
+			const msg = mockWorker.posted[0];
+			const cmd = msg.data as Extract<FecWorkerCommand, { type: "configure" }>;
+			expect(cmd.altaPublicKey).toBe(altaKey);
+			expect(cmd.altaWasmModule).toBe(altaWasmModule);
+			// ArrayBuffer (altaPublicKey) is transferable
+			expect(msg.transfer).toContain(altaKey);
+			// WebAssembly.Module is structured-cloneable — must NOT be in transfer list
+			expect(msg.transfer).not.toContain(wasmModule);
+			expect(msg.transfer).not.toContain(altaWasmModule);
+		});
+
+		it("throws if disposed", () => {
+			client.dispose();
+			expect(() => client.configure(makeConfig(), {} as WebAssembly.Module)).toThrow(
+				"disposed",
+			);
+		});
+	});
+
+	describe("feedSource", () => {
+		it("posts feedSource carrying the flat SS_ID (matches WASM add_source signature)", () => {
+			const data = new ArrayBuffer(1320);
+			// SS_ID = SBN * K + ESI  (e.g. K=4, SBN=5, ESI=3 → ss_id = 23)
+			client.feedSource(23, data, 1000);
+
+			expect(mockWorker.posted).toHaveLength(1);
+			const msg = mockWorker.posted[0];
+			const cmd = msg.data as Extract<FecWorkerCommand, { type: "feedSource" }>;
+			expect(cmd.type).toBe("feedSource");
+			expect(cmd.ssId).toBe(23);
+			expect(cmd.data).toBe(data);
+			expect(cmd.ts).toBe(1000);
+			expect(msg.transfer).toContain(data);
+		});
+
+		it("does not serialize caller-supplied transport provenance", () => {
+			const data = new ArrayBuffer(1320);
+			(client.feedSource as unknown as (...args: unknown[]) => void)(
+				23,
+				data,
+				1000,
+				undefined,
+				"multicast",
+			);
+
+			expect(mockWorker.posted[0]?.data).not.toHaveProperty("source");
+		});
+
+		it("silently returns if disposed", () => {
+			client.dispose();
+			client.feedSource(0, new ArrayBuffer(0), 0);
+			// Only the dispose command should be posted, not feedSource
+			const feedCmds = mockWorker.posted.filter(
+				(p) => (p.data as FecWorkerCommand).type === "feedSource",
+			);
+			expect(feedCmds).toHaveLength(0);
+		});
+	});
+
+	describe("feedRepair", () => {
+		it("posts feedRepair carrying SS_Start/SSB_length/RS_ID (matches WASM add_repair)", () => {
+			const data = new ArrayBuffer(1320);
+			// SS_Start=20 (SBN=5, K=4), SSB_length=4 (K), RS_ID=2 (2nd repair symbol)
+			client.feedRepair(20, 4, 2, data, 1000);
+
+			expect(mockWorker.posted).toHaveLength(1);
+			const msg = mockWorker.posted[0];
+			const cmd = msg.data as Extract<FecWorkerCommand, { type: "feedRepair" }>;
+			expect(cmd.type).toBe("feedRepair");
+			expect(cmd.ssStart).toBe(20);
+			expect(cmd.ssbLength).toBe(4);
+			expect(cmd.rsId).toBe(2);
+			expect(cmd.data).toBe(data);
+			expect(cmd.ts).toBe(1000);
+			expect(msg.transfer).toContain(data);
+		});
+
+		it("does not serialize caller-supplied transport provenance", () => {
+			const data = new ArrayBuffer(1320);
+			(client.feedRepair as unknown as (...args: unknown[]) => void)(
+				20,
+				4,
+				2,
+				data,
+				1000,
+				"moq",
+			);
+
+			expect(mockWorker.posted[0]?.data).not.toHaveProperty("source");
+		});
+	});
+
+	describe("relayBlockSig", () => {
+		it("posts relayBlockSig with sig and hash in transferList", () => {
+			const sig = new ArrayBuffer(64);
+			const hash = new ArrayBuffer(32);
+			client.relayBlockSig(10, sig, hash);
+
+			expect(mockWorker.posted).toHaveLength(1);
+			const msg = mockWorker.posted[0];
+			const cmd = msg.data as Extract<FecWorkerCommand, { type: "relayBlockSig" }>;
+			expect(cmd.type).toBe("relayBlockSig");
+			expect(cmd.sbn).toBe(10);
+			expect(msg.transfer).toContain(sig);
+			expect(msg.transfer).toContain(hash);
+		});
+	});
+
+	describe("cleanup", () => {
+		it("posts cleanup command with the timed-out SBN", () => {
+			client.cleanup(15);
+
+			expect(mockWorker.posted).toHaveLength(1);
+			const cmd = mockWorker.posted[0].data as Extract<
+				FecWorkerCommand,
+				{ type: "cleanup" }
+			>;
+			expect(cmd.type).toBe("cleanup");
+			expect(cmd.sbns).toEqual([15]);
+		});
+
+		it("rejects an invalid SBN without blocking the next valid cleanup", () => {
+			expect(() => client.cleanup(0x1_0000_0000)).toThrow(
+				"[FecWorkerClient] cleanup: SBN must be a uint32",
+			);
+			expect(mockWorker.posted).toHaveLength(0);
+
+			client.cleanup(15);
+
+			expect(mockWorker.posted).toHaveLength(1);
+			expect(mockWorker.posted[0]?.data).toEqual({
+				type: "cleanup",
+				sbns: [15],
+			});
+		});
+
+		it("coalesces cleanup while preserving per-SBN fill and acknowledgement ownership", () => {
+			const cb = vi.fn();
+			const fills = vi.fn();
+			client.onCleanupComplete(cb);
+			client.onGreenFill(fills);
+
+			client.cleanup(15);
+			client.cleanup(16);
+			client.cleanup(18);
+
+			let cleanupMessages = mockWorker.posted.filter(
+				(p) => (p.data as FecWorkerCommand).type === "cleanup",
+			);
+			expect(cleanupMessages).toHaveLength(1);
+
+			mockWorker.simulateMessage({ type: "cleanupComplete", sbns: [15] });
+			expect(cb.mock.calls.map(([sbn]) => sbn)).toEqual([15]);
+
+			cleanupMessages = mockWorker.posted.filter(
+				(p) => (p.data as FecWorkerCommand).type === "cleanup",
+			);
+			expect(cleanupMessages).toHaveLength(2);
+			expect(
+				(cleanupMessages[1]?.data as Extract<FecWorkerCommand, { type: "cleanup" }>).sbns,
+			).toEqual([16, 18]);
+
+			const fill16 = new ArrayBuffer(5);
+			const fill18 = new ArrayBuffer(5);
+			mockWorker.simulateMessage({ type: "greenFill", sbn: 16, data: fill16 });
+			mockWorker.simulateMessage({ type: "greenFill", sbn: 18, data: fill18 });
+			mockWorker.simulateMessage({ type: "cleanupComplete", sbns: [16, 18] });
+			expect(fills.mock.calls).toEqual([
+				[16, fill16],
+				[18, fill18],
+			]);
+			expect(cb.mock.calls.map(([sbn]) => sbn)).toEqual([15, 16, 18]);
+		});
+	});
+
+	describe("event dispatch", () => {
+		it("dispatches frame events to onFrame callback with ArrayBuffer data (FEC-03)", () => {
+			const cb = vi.fn();
+			client.onFrame(cb);
+
+			const frameData = new ArrayBuffer(1320);
+			const meta: FrameMeta = { altaVerified: null, recovered: false, sbn: 5 };
+			mockWorker.simulateMessage({ type: "frame", data: frameData, meta });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb).toHaveBeenCalledWith(frameData, meta);
+			// Verify data is ArrayBuffer (not Uint8Array) for zero-copy
+			expect(cb.mock.calls[0][0]).toBeInstanceOf(ArrayBuffer);
+		});
+
+		it("dispatches frame events with altaVerified metadata (AUTH-04)", () => {
+			const cb = vi.fn();
+			client.onFrame(cb);
+
+			const meta: FrameMeta = { altaVerified: true, recovered: true, sbn: 3 };
+			mockWorker.simulateMessage({
+				type: "frame",
+				data: new ArrayBuffer(100),
+				meta,
+			});
+
+			expect(cb.mock.calls[0][1].altaVerified).toBe(true);
+			expect(cb.mock.calls[0][1].recovered).toBe(true);
+		});
+
+		it("dispatches snapshot events to onSnapshot callback (FEC-04)", () => {
+			const cb = vi.fn();
+			client.onSnapshot(cb);
+
+			const stats: FecTrackStats = {
+				config: makeConfig(),
+				sourceSymbols: 100,
+				repairSymbols: 25,
+				blocksComplete: 3,
+				blocksRecovered: 1,
+				blocksFailed: 0,
+				greenFillFrames: 0,
+				recoveryRate: 100,
+				altaVerified: 0,
+				altaFailed: 0,
+				relayBlocksVerified: 0,
+				relayBlocksFailed: 0,
+				liveSbn: 4,
+				blocks: [],
+				interleaveWindowBlocks: 4,
+				avgRecoveryMs: 30,
+				maxRecoveryMs: 60,
+			};
+			mockWorker.simulateMessage({ type: "snapshot", stats });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb).toHaveBeenCalledWith(stats);
+		});
+
+		it("dispatches blockUpdate events to onBlockUpdate callback", () => {
+			const cb = vi.fn();
+			client.onBlockUpdate(cb);
+
+			const block: FecBlockSnapshot = {
+				sbn: 7,
+				state: "recovered",
+				sourceReceived: 28,
+				repairReceived: 6,
+				k: 32,
+				repairCount: 8,
+				firstSymbolTs: 100,
+				lastSymbolTs: 200,
+				completedTs: 210,
+				deadlineTs: 500,
+				altaVerified: 28,
+				relayBlockSigValid: true,
+			};
+			mockWorker.simulateMessage({ type: "blockUpdate", block });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb).toHaveBeenCalledWith(block);
+		});
+
+		it("dispatches greenFill events to onGreenFill callback", () => {
+			const cb = vi.fn();
+			client.onGreenFill(cb);
+
+			const data = new ArrayBuffer(0);
+			mockWorker.simulateMessage({ type: "greenFill", sbn: 3, data });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb).toHaveBeenCalledWith(3, data);
+		});
+
+		it("dispatches cleanupComplete events after queued cleanup work", () => {
+			const cb = vi.fn();
+			client.onCleanupComplete(cb);
+
+			mockWorker.simulateMessage({ type: "cleanupComplete", sbns: [3] });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb).toHaveBeenCalledWith(3);
+		});
+
+		it("dispatches error events to onError callback", () => {
+			const cb = vi.fn();
+			client.onError(cb);
+
+			mockWorker.simulateMessage({ type: "error", message: "WASM decode failed" });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb).toHaveBeenCalledWith("WASM decode failed");
+		});
+
+		it("preserves stable error codes for messages with volatile details", () => {
+			const cb = vi.fn();
+			client.onError(cb);
+
+			mockWorker.simulateMessage({
+				type: "error",
+				code: "repair-symbol-size-mismatch",
+				message: "invalid repair size (ssStart=320)",
+			});
+
+			expect(cb).toHaveBeenCalledWith(
+				"invalid repair size (ssStart=320)",
+				"repair-symbol-size-mismatch",
+			);
+		});
+
+		it("dispatches Worker-level errors to onError callback", () => {
+			const cb = vi.fn();
+			client.onError(cb);
+
+			mockWorker.simulateError("Script error");
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb.mock.calls[0][0]).toContain("Script error");
+		});
+
+		it("includes Worker script location and stack for load/runtime failures", () => {
+			const cb = vi.fn();
+			client.onError(cb);
+			const error = new Error("import failed");
+			error.stack = "Error: import failed\n    at /vendor/fec-worker.js:7:3";
+
+			mockWorker.simulateDetailedError({
+				message: "Failed to fetch dynamically imported module",
+				filename: "/vendor/node_modules/@blockcast/fec-worker/fec-worker.js",
+				lineno: 7,
+				colno: 3,
+				error,
+			});
+
+			expect(cb).toHaveBeenCalledOnce();
+			const message = cb.mock.calls[0][0];
+			expect(message).toContain("Failed to fetch dynamically imported module");
+			expect(message).toContain("/vendor/node_modules/@blockcast/fec-worker/fec-worker.js:7:3");
+			expect(message).toContain("import failed");
+		});
+
+		it("dispatches Worker messageerror to onError callback", () => {
+			const cb = vi.fn();
+			client.onError(cb);
+
+			mockWorker.simulateMessageError({ type: "frame" });
+
+			expect(cb).toHaveBeenCalledOnce();
+			expect(cb.mock.calls[0][0]).toContain("Worker messageerror");
+		});
+	});
+
+	describe("dispose", () => {
+		it("posts dispose command and terminates Worker", () => {
+			client.dispose();
+
+			const disposeCmds = mockWorker.posted.filter(
+				(p) => (p.data as FecWorkerCommand).type === "dispose",
+			);
+			expect(disposeCmds).toHaveLength(1);
+			expect(mockWorker.terminated).toBe(true);
+		});
+
+		it("is idempotent", () => {
+			client.dispose();
+			client.dispose();
+
+			const disposeCmds = mockWorker.posted.filter(
+				(p) => (p.data as FecWorkerCommand).type === "dispose",
+			);
+			expect(disposeCmds).toHaveLength(1);
+		});
+	});
+
+		describe("reset", () => {
+			it("suppresses stale events until the Worker acknowledges the new epoch", () => {
+				const onFrame = vi.fn();
+				client.onFrame(onFrame);
+
+			client.reset();
+			expect(mockWorker.posted.at(-1)?.data).toEqual({ type: "reset" });
+			mockWorker.simulateMessage({
+				type: "frame",
+				data: new ArrayBuffer(1),
+				meta: { recovered: true, sbn: 1, esi: 0 },
+			});
+			expect(onFrame).not.toHaveBeenCalled();
+
+				mockWorker.simulateMessage({ type: "resetComplete" });
+				mockWorker.simulateMessage({
+					type: "frame",
+					data: new ArrayBuffer(1),
+					meta: { recovered: true, sbn: 2, esi: 0 },
+				});
+				expect(onFrame).toHaveBeenCalledOnce();
+			});
+
+			it("quarantines a failed reset until a later reset succeeds", () => {
+				const onError = vi.fn();
+				const onFrame = vi.fn();
+				client.onError(onError);
+				client.onFrame(onFrame);
+
+				client.reset();
+				mockWorker.simulateMessage({
+					type: "error",
+					code: "reset-failed",
+					message: "[FecWorker] reset failed: flush failed",
+				});
+				mockWorker.simulateMessage({
+					type: "frame",
+					data: new ArrayBuffer(1),
+					meta: { recovered: true, sbn: 1, esi: 0 },
+				});
+
+				expect(onError).toHaveBeenCalledWith(
+					"[FecWorker] reset failed: flush failed",
+					"reset-failed",
+				);
+				expect(onFrame).not.toHaveBeenCalled();
+
+				client.reset();
+				mockWorker.simulateMessage({ type: "resetComplete" });
+				mockWorker.simulateMessage({
+					type: "frame",
+					data: new ArrayBuffer(1),
+					meta: { recovered: true, sbn: 2, esi: 0 },
+				});
+
+				expect(onFrame).toHaveBeenCalledOnce();
+			});
+		});
+
+	});