@blockcast/fec-worker 0.1.0-main.0c300647d0a5

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.ts

@@ -0,0 +1,268 @@
+/**
+ * @blockcast/fec-worker — Shared Type Definitions
+ *
+ * Defines the Worker message protocol (commands/events), FecTrackStats shape
+ * consumed by fec-panel (Phase 5) and CmcdProducer (Phase 6), and auth
+ * interface stubs (ALTA + relay block sig).
+ *
+ * Types here are importable from both main thread and Worker contexts.
+ */
+
+// --- Config ---
+
+/** Per-track FEC configuration. Matches design spec section 3.2 FecTrackConfig. */
+export interface FecTrackConfig {
+	/** Codec string, e.g. 'avc1.64001f', 'mp4a.40.2' */
+	codec: string;
+	/** Track name from catalog */
+	trackName: string;
+	/** Track media type */
+	trackType: "video" | "audio";
+	/** Video resolution (omitted for audio) */
+	resolution?: { w: number; h: number };
+	/** Video framerate (omitted for audio) */
+	framerate?: number;
+	/** Audio sample rate (omitted for video) */
+	sampleRate?: number;
+
+	/** FEC algorithm identifier: 'raptor', 'reed-solomon', 'none' */
+	algorithm: string;
+	/** Source symbols per block (K) */
+	k: number;
+	/** Repair symbols per block (P). NOT symbol size. */
+	repairCount: number;
+	/** Bytes per symbol */
+	symbolSize: number;
+	/** Interleave depth in frames (D) */
+	interleaveDepth: number;
+	/** Interleave depth in milliseconds (D * frameDurationMs) */
+	interleaveMs: number;
+	/** Catalog-derived source+repair delivery window used for decoder cleanup. */
+	deliveryWindowMs: number;
+	/** FEC encoding mode */
+	fecMode: "subframe" | "object";
+	/** MoQ repair track name (optional) */
+	repairTrack?: string;
+
+	/** Whether ALTA publisher auth is enabled (AUTH-01) */
+	altaEnabled: boolean;
+	/** Whether relay block signature verification is enabled (AUTH-01) */
+	relayBlockSigEnabled: boolean;
+}
+
+// --- Block state ---
+
+/** Per-block snapshot for live block visualization and stats. */
+export interface FecBlockSnapshot {
+	/** Source block number */
+	sbn: number;
+	/** Current block state */
+	state: "collecting" | "complete" | "recovered" | "failed" | "green-fill";
+	/** Number of source symbols received */
+	sourceReceived: number;
+	/** Number of repair symbols received */
+	repairReceived: number;
+	/** Expected source symbols (K) */
+	k: number;
+	/** Expected repair symbols (P) */
+	repairCount: number;
+	/** Timestamp of first symbol arrival (ms) */
+	firstSymbolTs: number;
+	/** Timestamp of last symbol arrival (ms) */
+	lastSymbolTs: number;
+	/** Timestamp when block completed (ms), undefined if not yet complete */
+	completedTs?: number;
+	/** Deadline timestamp for block completion (ms) */
+	deadlineTs: number;
+	/** Count of source symbols with valid ALTA signature (AUTH-02) */
+	altaVerified: number;
+	/** Relay block signature validity: true/false after verification, null if not yet verified (AUTH-02) */
+	relayBlockSigValid: boolean | null;
+}
+
+// --- Stats ---
+
+/** Aggregate per-track FEC statistics. Consumed by fec-panel and CmcdProducer. */
+export interface FecTrackStats {
+	/** Track configuration */
+	config: FecTrackConfig;
+
+	/** Total source symbols received */
+	sourceSymbols: number;
+	/** Total repair symbols received */
+	repairSymbols: number;
+	/** Blocks completed without recovery needed */
+	blocksComplete: number;
+	/** Blocks recovered via FEC */
+	blocksRecovered: number;
+	/** Blocks that failed (unrecoverable) */
+	blocksFailed: number;
+	/** Frames replaced with green-fill */
+	greenFillFrames: number;
+	/** Recovery success rate 0-100 */
+	recoveryRate: number;
+
+	/** Packets with valid publisher ALTA signature */
+	altaVerified: number;
+	/** Packets with MAC / signature / hash-chain mismatch (tamper-confirmed) */
+	altaFailed: number;
+	/** Packets that couldn't be verified due to missing trailer / not-ready verifier /
+	 *  late-joiner bootstrap gap. Neither tamper nor error — just unverifiable. */
+	altaPending: number;
+	/** Deferred-queue entries evicted by cap (queue full). Separate counter so
+	 *  cap misconfiguration is distinguishable from natural bootstrap-gap noise. */
+	altaPendingEvictedCap: number;
+	/** Deferred-queue entries evicted by TTL (retry window expired). */
+	altaPendingEvictedTtl: number;
+	/** verifyDetached / parse threw an exception (WASM trap, OOM, unmarshal panic).
+	 *  Not counted as altaFailed because the cause isn't crypto — helps ops
+	 *  distinguish infrastructure flake from tamper. */
+	altaError: number;
+	/** True if ALTA was enabled at configure time but the verifier WASM init
+	 *  failed. Ops alerting should treat this as "ALTA disabled due to error",
+	 *  distinct from "ALTA disabled by config" (altaEnabled flag not present). */
+	altaInitFailed: boolean;
+	/** Diagnostic: last ≤16 altaFailed events with full context (seq, error
+	 *  string from the verifier, auth+payload lengths, and which code path
+	 *  raised the failure). Bounded so it can't blow memory. Intended for
+	 *  investigation — not a stable API; consumers should treat it as
+	 *  opt-in and defensive (may be undefined). */
+	altaFailedDetails?: Array<{
+		seq: number;
+		error: string;
+		authLen: number;
+		payloadLen: number;
+		path: string;
+	}>;
+	/** Blocks with valid relay signature */
+	relayBlocksVerified: number;
+	/** Blocks with invalid relay signature */
+	relayBlocksFailed: number;
+
+	/** Current live source block number */
+	liveSbn: number;
+	/** Active block snapshots */
+	blocks: FecBlockSnapshot[];
+	/** Number of blocks in the interleave window */
+	interleaveWindowBlocks: number;
+
+	/** Average recovery latency (ms) */
+	avgRecoveryMs: number;
+	/** Maximum recovery latency (ms) */
+	maxRecoveryMs: number;
+	/** Repair symbols rejected before WASM because their byte length did not match T. */
+	repairSymbolSizeMismatch?: number;
+	/** Native decoder counters, converted to numbers so browser diagnostics remain JSON-safe. */
+	decoder?: {
+		sourcePackets: number;
+		repairPackets: number;
+		blocksComplete: number;
+		blocksRecovered: number;
+		blocksFailed: number;
+		bytesRecovered: number;
+		pendingBlocks: number;
+	};
+}
+
+/** Stable identities for Worker failures whose message text contains live values. */
+export type FecWorkerErrorCode =
+	| "recovered-symbol-size-unconfigured"
+	| "recovered-block-too-short"
+	| "repair-symbol-size-mismatch"
+	| "reset-failed"
+	| "unknown-command"
+	| "command-failed"
+	| "worker-runtime"
+	| "worker-message";
+
+// --- Frame metadata ---
+
+/** Per-frame metadata emitted with frame events from Worker. */
+export interface FrameMeta {
+	/** ALTA verification result: true/false after check, null when ALTA not configured (AUTH-04) */
+	altaVerified: boolean | null;
+	/** Whether this frame was recovered via FEC (not received directly) */
+	recovered: boolean;
+	/** Source block number this frame belongs to */
+	sbn: number;
+	/** Encoding Symbol ID within the recovered source block (0..K-1). */
+	esi?: number;
+}
+
+// --- Worker commands (main -> worker) ---
+
+/** Discriminated union of all commands sent from main thread to Worker. */
+export type FecWorkerCommand =
+	| {
+			type: "configure";
+			config: FecTrackConfig;
+			wasmModule: WebAssembly.Module;
+			/**
+			 * ALTA public key as PKCS#8 SubjectPublicKeyInfo DER bytes (self-describing).
+			 * Algorithm (Ed25519 or ECDSA P-256) is auto-detected from the SPKI OID.
+			 * Ed25519 SPKI is 44 bytes; P-256 uncompressed is 91 bytes.
+			 */
+			altaPublicKey?: ArrayBuffer;
+			/** Pre-compiled ALTA WASM module. Structured-cloneable (NOT transferable) — do not add to transfer list. */
+			altaWasmModule?: WebAssembly.Module;
+	  }
+	| {
+			type: "feedSource";
+			/** Flat 32-bit Source Symbol ID from the MMTP Source FEC Payload ID
+			 *  (ISO 23008-1 §C.5.2). The WASM decoder derives SBN = floor(ssId/K)
+			 *  and ESI = ssId % K internally — do NOT pre-compute. */
+			ssId: number;
+			data: ArrayBuffer;
+			ts: number;
+			/** Optional ALTA authenticator bytes (detached mode — 08-07 MMTP
+			 *  trailer). Present when the source packet carried a
+			 *  `[0xF0A1][len][auth]` trailer and ALTA is enabled at the worker.
+			 *  When omitted, the worker skips verification and the packet
+			 *  counts as `altaPending`. */
+			altaAuth?: ArrayBuffer;
+			/** Byte offset within `data` where the signed MMTP payload ends
+			 *  (== where the trailer began on the wire). Required when
+			 *  `altaAuth` is present. Worker constructs
+			 *  `payload = new Uint8Array(data, 0, altaPayloadEnd)` for
+			 *  `verifyDetached(altaAuth, payload)`. */
+			altaPayloadEnd?: number;
+	  }
+	| {
+			type: "feedRepair";
+			/** SS_Start: SS_ID of the first source symbol in the block
+			 *  (= SBN * SSB_length), from the MMTP Repair FEC Payload ID
+			 *  (ISO 23008-1 §C.5.3). */
+			ssStart: number;
+			/** SSB_length: K for this block (variable-K allowed per spec). */
+			ssbLength: number;
+			/** RS_ID: repair symbol index within the block; WASM maps to
+			 *  repair ESI = SSB_length + RS_ID. */
+			rsId: number;
+			data: ArrayBuffer;
+			ts: number;
+	  }
+	| {
+			type: "relayBlockSig";
+			sbn: number;
+			sig: ArrayBuffer;
+			hash: ArrayBuffer;
+	  }
+	| {
+			type: "cleanup";
+			/** Every timed-out block covered by this coalesced queue-drain barrier. */
+			sbns: number[];
+	  }
+	| { type: "reset" }
+	| { type: "dispose" };
+
+// --- Worker events (worker -> main) ---
+
+/** Discriminated union of all events emitted from Worker to main thread. */
+export type FecWorkerEvent =
+	| { type: "frame"; data: ArrayBuffer; meta: FrameMeta }
+	| { type: "snapshot"; stats: FecTrackStats }
+	| { type: "blockUpdate"; block: FecBlockSnapshot }
+	| { type: "greenFill"; sbn: number; data: ArrayBuffer }
+	| { type: "cleanupComplete"; sbns: number[] }
+	| { type: "resetComplete" }
+	| { type: "error"; message: string; code?: FecWorkerErrorCode };