@blockcast/fec-worker 0.1.0

package/src/fec-worker-client.ts

@@ -0,0 +1,309 @@
+/**
+ * @blockcast/fec-worker — Main-Thread Client
+ *
+ * Wraps one Worker per track instance. Provides typed API for the
+ * FecWorkerCommand/FecWorkerEvent protocol with zero-copy ArrayBuffer transfers.
+ *
+ * Constructor accepts either a URL (creates Worker internally) or a pre-created
+ * Worker instance (for testing via constructor injection).
+ */
+
+import type {
+	FecWorkerCommand,
+	FecWorkerEvent,
+	FecTrackConfig,
+	FecTrackStats,
+	FecBlockSnapshot,
+	FrameMeta,
+	FecWorkerErrorCode,
+} from "./fec-worker-types.js";
+
+export class FecWorkerClient {
+	readonly #worker: Worker;
+	#onFrame: ((data: ArrayBuffer, meta: FrameMeta) => void) | null = null;
+	#onSnapshot: ((stats: FecTrackStats) => void) | null = null;
+	#onBlockUpdate: ((block: FecBlockSnapshot) => void) | null = null;
+	#onGreenFill: ((sbn: number, data: ArrayBuffer) => void) | null = null;
+	#onCleanupComplete: ((sbn: number) => void) | null = null;
+	#onError: ((message: string, code?: FecWorkerErrorCode) => void) | null = null;
+	#cleanupInFlight: Set<number> | null = null;
+	#queuedCleanupSbns = new Set<number>();
+	#pendingResets = 0;
+	#resetFailed = false;
+	#disposed = false;
+
+	/**
+	 * Create a FecWorkerClient.
+	 * @param workerOrUrl - Either a Worker instance (for testing) or a URL to create one
+	 */
+	constructor(workerOrUrl: Worker | URL) {
+		if (workerOrUrl instanceof URL) {
+			this.#worker = new Worker(workerOrUrl, { type: "module" });
+		} else {
+			this.#worker = workerOrUrl;
+		}
+		this.#worker.onmessage = (e: MessageEvent<FecWorkerEvent>) =>
+			this.#handleEvent(e.data);
+		this.#worker.onerror = (e) => {
+			this.#onError?.(formatWorkerError(e), "worker-runtime");
+		};
+		this.#worker.onmessageerror = (e) => {
+			this.#onError?.(formatWorkerMessageError(e), "worker-message");
+		};
+	}
+
+	/**
+	 * Configure the Worker with FEC parameters and WASM module.
+	 * wasmModule is transferred (not neutered — WebAssembly.Module is shareable).
+	 * altaPublicKey is PKCS#8 SPKI DER bytes (self-describing — algorithm detected from OID).
+	 *   Transferred (detached from sender).
+	 * altaWasmModule is structured-cloneable (NOT transferable — do not add to transfer list).
+	 */
+	configure(
+		config: FecTrackConfig,
+		wasmModule: WebAssembly.Module,
+		altaPublicKey?: ArrayBuffer,
+		altaWasmModule?: WebAssembly.Module,
+	): void {
+		if (this.#disposed) throw new Error("[FecWorkerClient] disposed");
+		const cmd: FecWorkerCommand = {
+			type: "configure",
+			config,
+			wasmModule,
+			altaPublicKey,
+			altaWasmModule,
+		};
+		// WebAssembly.Module is structured-cloneable, NOT transferable.
+		// Pass it in the message body (Chrome clones it automatically).
+		// Only ArrayBuffers (like altaPublicKey) go in the transfer list.
+		const transferList: Transferable[] = [];
+		if (altaPublicKey) transferList.push(altaPublicKey);
+		// altaWasmModule is structured-cloneable — NOT added to transferList
+		this.#worker.postMessage(cmd, transferList);
+	}
+
+	/**
+	 * Feed a source symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+	 * Caller must not access data after this call — it is detached.
+	 *
+	 * Optional `alta` carries the detached ALTA authenticator bytes and the
+	 * byte offset in `data` where the signed payload ends. The auth buffer is
+	 * transferred zero-copy alongside `data`. Use {@link getMmtpAltaTrailer}
+	 * upstream (mmtp-router) to extract it from the wire packet.
+	 */
+	feedSource(
+		ssId: number,
+		data: ArrayBuffer,
+		ts: number,
+		alta?: { auth: ArrayBuffer; payloadEnd: number },
+	): void {
+		if (this.#disposed) return;
+		const cmd: FecWorkerCommand = alta
+			? {
+					type: "feedSource",
+					ssId,
+					data,
+					ts,
+					altaAuth: alta.auth,
+					altaPayloadEnd: alta.payloadEnd,
+				}
+			: { type: "feedSource", ssId, data, ts };
+		const transfer: Transferable[] = alta ? [data, alta.auth] : [data];
+		this.#worker.postMessage(cmd, transfer);
+	}
+
+	/**
+	 * Feed a repair symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+	 * Caller must not access data after this call — it is detached.
+	 *
+	 * Carries the wire-level Repair FEC Payload ID fields (ISO 23008-1 §C.5.3):
+	 * - ssStart:   SS_ID of first source symbol in the block (= SBN * SSB_length)
+	 * - ssbLength: K for this block
+	 * - rsId:      repair symbol index within the block
+	 */
+	feedRepair(
+		ssStart: number,
+		ssbLength: number,
+		rsId: number,
+		data: ArrayBuffer,
+		ts: number,
+	): void {
+		if (this.#disposed) return;
+		this.#worker.postMessage(
+			{
+				type: "feedRepair",
+				ssStart,
+				ssbLength,
+				rsId,
+				data,
+				ts,
+			} satisfies FecWorkerCommand,
+			[data],
+		);
+	}
+
+	/**
+	 * Submit relay block signature for verification. sig and hash are transferred.
+	 */
+	relayBlockSig(sbn: number, sig: ArrayBuffer, hash: ArrayBuffer): void {
+		if (this.#disposed) return;
+		this.#worker.postMessage(
+			{ type: "relayBlockSig", sbn, sig, hash } satisfies FecWorkerCommand,
+			[sig, hash],
+		);
+	}
+
+	/**
+	 * Trigger cleanup after a block's inactivity deadline.
+	 *
+	 * While one queue-drain barrier is in flight, later SBNs are coalesced into
+	 * the next command without losing their individual acknowledgement identity.
+	 */
+	cleanup(currentSbn: number): void {
+		if (this.#disposed) return;
+		if (
+			!Number.isInteger(currentSbn) ||
+			currentSbn < 0 ||
+			currentSbn > 0xffff_ffff
+		) {
+			throw new Error("[FecWorkerClient] cleanup: SBN must be a uint32");
+		}
+		if (this.#cleanupInFlight) {
+			this.#queuedCleanupSbns.add(currentSbn);
+			return;
+		}
+		this.#postCleanup(new Set([currentSbn]));
+	}
+
+	/** Reset this track's decoder epoch while preserving Worker configuration. */
+	reset(): void {
+		if (this.#disposed) return;
+		this.#pendingResets++;
+		this.#cleanupInFlight = null;
+		this.#queuedCleanupSbns.clear();
+		this.#worker.postMessage({ type: "reset" } satisfies FecWorkerCommand);
+	}
+
+	#postCleanup(sbns: Set<number>): void {
+		this.#cleanupInFlight = sbns;
+		const orderedSbns = [...sbns].sort((a, b) => a - b);
+		this.#worker.postMessage(
+			{ type: "cleanup", sbns: orderedSbns } satisfies FecWorkerCommand,
+		);
+	}
+
+	/** Register callback for decoded/recovered frames (FEC-03). */
+	onFrame(cb: (data: ArrayBuffer, meta: FrameMeta) => void): void {
+		this.#onFrame = cb;
+	}
+
+	/** Register callback for periodic stats snapshots (FEC-04). */
+	onSnapshot(cb: (stats: FecTrackStats) => void): void {
+		this.#onSnapshot = cb;
+	}
+
+	/** Register callback for individual block state changes. */
+	onBlockUpdate(cb: (block: FecBlockSnapshot) => void): void {
+		this.#onBlockUpdate = cb;
+	}
+
+	/** Register callback for green-fill frames. */
+	onGreenFill(cb: (sbn: number, data: ArrayBuffer) => void): void {
+		this.#onGreenFill = cb;
+	}
+
+	/** Register callback fired after the Worker drains all commands queued before cleanup. */
+	onCleanupComplete(cb: (sbn: number) => void): void {
+		this.#onCleanupComplete = cb;
+	}
+
+	/** Register callback for Worker errors. */
+	onError(cb: (message: string, code?: FecWorkerErrorCode) => void): void {
+		this.#onError = cb;
+	}
+
+	/**
+	 * Dispose the Worker. Sends dispose command then terminates.
+	 * Idempotent — safe to call multiple times.
+	 */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#cleanupInFlight = null;
+		this.#queuedCleanupSbns.clear();
+		this.#worker.postMessage({ type: "dispose" } satisfies FecWorkerCommand);
+		this.#worker.terminate();
+	}
+
+	#handleEvent(event: FecWorkerEvent): void {
+		if (event.type === "resetComplete") {
+			this.#pendingResets = Math.max(0, this.#pendingResets - 1);
+			this.#resetFailed = false;
+			return;
+		}
+		if (event.type === "error") {
+			if (event.code === "reset-failed") {
+				this.#pendingResets = Math.max(0, this.#pendingResets - 1);
+				this.#resetFailed = true;
+			}
+			if (event.code) this.#onError?.(event.message, event.code);
+			else this.#onError?.(event.message);
+			return;
+		}
+		if (this.#pendingResets > 0 || this.#resetFailed) return;
+		switch (event.type) {
+			case "frame":
+				this.#onFrame?.(event.data, event.meta);
+				break;
+			case "snapshot":
+				this.#onSnapshot?.(event.stats);
+				break;
+			case "blockUpdate":
+				this.#onBlockUpdate?.(event.block);
+				break;
+			case "greenFill":
+				this.#onGreenFill?.(event.sbn, event.data);
+				break;
+			case "cleanupComplete":
+				for (const sbn of event.sbns) {
+					this.#onCleanupComplete?.(sbn);
+				}
+				this.#cleanupInFlight = null;
+				if (this.#queuedCleanupSbns.size > 0) {
+					const next = this.#queuedCleanupSbns;
+					this.#queuedCleanupSbns = new Set();
+					this.#postCleanup(next);
+				}
+				break;
+		}
+	}
+}
+
+function formatWorkerError(event: ErrorEvent): string {
+	const parts = ["Worker error"];
+	if (event.message) parts.push(event.message);
+	if (event.filename) {
+		const location = [event.filename];
+		if (event.lineno) location.push(String(event.lineno));
+		if (event.colno) location.push(String(event.colno));
+		parts.push(`at ${location.join(":")}`);
+	}
+	if (event.error instanceof Error) {
+		if (event.error.message && event.error.message !== event.message) {
+			parts.push(event.error.message);
+		}
+		if (event.error.stack) parts.push(event.error.stack);
+	} else if (event.error != null) {
+		parts.push(String(event.error));
+	}
+	return parts.join(": ");
+}
+
+function formatWorkerMessageError(event: MessageEvent): string {
+	const data = event.data;
+	const detail =
+		data == null ? "" :
+			data instanceof Error ? `: ${data.message}` :
+				`: ${Object.prototype.toString.call(data)}`;
+	return `Worker messageerror: failed to deserialize worker message${detail}`;
+}

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

@@ -0,0 +1,400 @@
+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);
+	});
+});