@blockcast/mmt-fec 0.1.0-main.0399efef1f07

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@blockcast/mmt-fec",
+  "version": "0.1.0-main.0399efef1f07",
+  "description": "Container-agnostic FEC client for RaptorQ (RFC 6330) decoding via WASM",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./block-manager": {
+      "import": "./dist/block-manager.js",
+      "types": "./dist/block-manager.d.ts"
+    },
+    "./block-processor": {
+      "import": "./dist/block-processor.js",
+      "types": "./dist/block-processor.d.ts"
+    },
+    "./reorder-buffer": {
+      "import": "./dist/reorder-buffer.js",
+      "types": "./dist/reorder-buffer.d.ts"
+    },
+    "./cmaf": {
+      "import": "./dist/cmaf-symbols.js",
+      "types": "./dist/cmaf-symbols.d.ts"
+    },
+    "./cmaf-recovery": {
+      "import": "./dist/cmaf-recovery.js",
+      "types": "./dist/cmaf-recovery.d.ts"
+    },
+    "./loc": {
+      "import": "./dist/loc-symbols.js",
+      "types": "./dist/loc-symbols.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/__tests__",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@blockcast/mmt-base": "0.1.0-main.0399efef1f07"
+  },
+  "bundledDependencies": [
+    "@blockcast/mmt-base"
+  ],
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "fec",
+    "raptorq",
+    "rfc6330",
+    "wasm",
+    "forward-error-correction",
+    "streaming"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/fec"
+  }
+}

package/src/block-manager.ts

@@ -0,0 +1,371 @@
+/**
+ * FEC Block State Machine for Multicast
+ *
+ * Manages FEC block collection, timeout-based fallback, and WebTransport
+ * repair integration. Tracks source and repair symbols per block, triggering
+ * decode when complete or requesting repairs when timed out.
+ *
+ * State Machine:
+ *   EMPTY → COLLECTING → COMPLETE → DECODED
+ *                    ↓
+ *              FALLBACK (timeout) → WebTransport repair → DECODED
+ *
+ * Per draft-ramadan-moq-fec-00 Section 4.2:
+ * - k source symbols complete a block (no FEC decode needed)
+ * - After timeout, missing symbols are requested via WebTransport
+ * - With k symbols (source + repair), FEC decode recovers block
+ */
+
+export const FEC_STATE = {
+	EMPTY: 0,
+	COLLECTING: 1,
+	COMPLETE: 2,
+	FALLBACK: 3,
+	DECODED: 4,
+	FAILED: 5,
+} as const;
+
+export type FecState = (typeof FEC_STATE)[keyof typeof FEC_STATE];
+
+export interface FecBlockManagerOptions {
+	/** Block timeout (ms). Derive from catalog: interleaveDepthMs or frameDurationMs * K. Required. */
+	timeoutMs: number;
+	/** K — source symbols per block from catalog fec.sourceSymbols. Required for interleaved mode.
+	 *  For object FEC (§9.1), this is the max K — actual K varies per block via addSourcePacket/addRepairPacket blockK param. */
+	k: number;
+	/** Max concurrent blocks in flight. Resource bound, not timing — default 64. */
+	maxBlocks?: number;
+}
+
+export interface FecBlockStats {
+	sourcePackets: number;
+	repairPackets: number;
+	blocksComplete: number;
+	blocksRecovered: number;
+	blocksFailed: number;
+	fallbackRequests: number;
+	activeBlocks: number;
+	recoveryRate: number;
+}
+
+/**
+ * Individual FEC Block.
+ * Tracks symbols and state for a single source block.
+ */
+class FecBlock {
+	blockId: number;
+	state: FecState = FEC_STATE.EMPTY;
+	sourceSymbols = new Map<number, Uint8Array>();
+	repairSymbols = new Map<number, Uint8Array>();
+	k: number;
+	timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+	createdAt: number;
+	decodedAt: number | undefined;
+
+	constructor(blockId: number, k: number) {
+		this.blockId = blockId;
+		this.k = k;
+		this.createdAt = performance.now();
+	}
+
+	addSourceSymbol(esi: number, data: Uint8Array): boolean {
+		if (this.state >= FEC_STATE.COMPLETE) return false;
+
+		this.sourceSymbols.set(esi, data);
+		this.state = FEC_STATE.COLLECTING;
+
+		if (this.sourceSymbols.size >= this.k) {
+			this.state = FEC_STATE.COMPLETE;
+			return true;
+		}
+		return false;
+	}
+
+	addRepairSymbol(esi: number, data: Uint8Array): boolean {
+		if (this.state >= FEC_STATE.DECODED) return false;
+
+		this.repairSymbols.set(esi, data);
+
+		const totalSymbols = this.sourceSymbols.size + this.repairSymbols.size;
+		if (totalSymbols >= this.k) {
+			return true;
+		}
+		return false;
+	}
+
+	getMissingEsis(): number[] {
+		const missing: number[] = [];
+		for (let esi = 0; esi < this.k; esi++) {
+			if (!this.sourceSymbols.has(esi) && !this.repairSymbols.has(esi)) {
+				missing.push(esi);
+			}
+		}
+		return missing;
+	}
+
+	isDecodable(): boolean {
+		return this.sourceSymbols.size + this.repairSymbols.size >= this.k;
+	}
+
+	clearTimeout(): void {
+		if (this.timeoutHandle !== undefined) {
+			clearTimeout(this.timeoutHandle);
+			this.timeoutHandle = undefined;
+		}
+	}
+}
+
+/**
+ * FEC Block Manager
+ *
+ * Manages multiple FEC blocks, handling:
+ * - Source symbol registration
+ * - Repair symbol registration
+ * - Timeout-based WebTransport fallback
+ * - Block completion and decoding
+ */
+export class FecBlockManager {
+	#blocks = new Map<number, FecBlock>();
+	#timeoutMs: number;
+	#k: number;
+	maxBlocks: number;
+	#repairCallback: ((blockId: number, missingEsis: number[]) => void) | null = null;
+	#decodeCallback: ((blockId: number, data: Uint8Array) => void) | null = null;
+
+	#stats = {
+		sourcePackets: 0,
+		repairPackets: 0,
+		blocksComplete: 0,
+		blocksRecovered: 0,
+		blocksFailed: 0,
+		fallbackRequests: 0,
+	};
+
+	constructor(options: FecBlockManagerOptions) {
+		if (options.timeoutMs <= 0) throw new Error('[FecBlockManager] timeoutMs must be > 0 (derive from catalog FEC config)')
+		if (options.k <= 0) throw new Error('[FecBlockManager] k must be > 0 (from catalog fec.sourceSymbols)')
+		this.#timeoutMs = options.timeoutMs;
+		this.#k = options.k;
+		this.maxBlocks = options.maxBlocks ?? 64;
+	}
+
+	setRepairCallback(callback: (blockId: number, missingEsis: number[]) => void): void {
+		this.#repairCallback = callback;
+	}
+
+	setDecodeCallback(callback: (blockId: number, data: Uint8Array) => void): void {
+		this.#decodeCallback = callback;
+	}
+
+	updateParams(params: { k?: number; timeoutMs?: number }): void {
+		if (params.k !== undefined) this.#k = params.k;
+		if (params.timeoutMs !== undefined) this.#timeoutMs = params.timeoutMs;
+	}
+
+	/**
+	 * Add a source symbol to a block.
+	 * @param blockK — per-block K for object FEC (§9.1). When provided, overrides
+	 *   the global K for this block. For interleaved mode, omit (uses global K).
+	 */
+	addSourcePacket(blockId: number, esi: number, data: Uint8Array, blockK?: number): Uint8Array | null {
+		this.#stats.sourcePackets++;
+
+		let block = this.#blocks.get(blockId);
+		if (!block) {
+			block = this.#createBlock(blockId, blockK);
+		}
+
+		const complete = block.addSourceSymbol(esi, data);
+		if (complete) {
+			return this.#completeBlock(block);
+		}
+
+		return null;
+	}
+
+	/**
+	 * Add a repair symbol to a block.
+	 * @param blockK — per-block K from SSB_length in the Repair FEC Payload ID
+	 *   (ISO 23008-1 C.5.3). RSB_length is a different field: the repair symbol
+	 *   count, which under layered repair is the base-layer total P, not K.
+	 *   Required for object FEC; omit for interleaved mode.
+	 */
+	addRepairPacket(blockId: number, esi: number, data: Uint8Array, blockK?: number): Uint8Array | null {
+		this.#stats.repairPackets++;
+
+		let block = this.#blocks.get(blockId);
+		if (!block) {
+			block = this.#createBlock(blockId, blockK);
+		} else if (blockK && block.k !== blockK) {
+			// Object FEC: repair reveals actual K — update block if first repair arrives
+			// before enough source symbols to infer K.
+			block.k = blockK;
+		}
+
+		const canDecode = block.addRepairSymbol(esi, data);
+		if (canDecode && block.state !== FEC_STATE.DECODED) {
+			return this.#decodeBlock(block);
+		}
+
+		return null;
+	}
+
+	getStats(): FecBlockStats {
+		return {
+			...this.#stats,
+			activeBlocks: this.#blocks.size,
+			recoveryRate:
+				this.#stats.blocksComplete > 0
+					? (this.#stats.blocksRecovered / this.#stats.blocksComplete) * 100
+					: 100,
+		};
+	}
+
+	reset(): void {
+		for (const block of this.#blocks.values()) {
+			block.clearTimeout();
+		}
+		this.#blocks.clear();
+		this.#stats = {
+			sourcePackets: 0,
+			repairPackets: 0,
+			blocksComplete: 0,
+			blocksRecovered: 0,
+			blocksFailed: 0,
+			fallbackRequests: 0,
+		};
+	}
+
+	/**
+	 * @param blockK — per-block K for object FEC (§9.1). Falls back to global #k.
+	 */
+	#createBlock(blockId: number, blockK?: number): FecBlock {
+		if (this.#blocks.size >= this.maxBlocks) {
+			this.#evictOldestBlock();
+		}
+
+		const k = blockK ?? this.#k;
+		if (k <= 0) {
+			throw new Error(`[FecBlockManager] Cannot create block ${blockId}: K=${k}. Derive K from catalog (interleaved) or frame size (object §9.1).`)
+		}
+		const block = new FecBlock(blockId, k);
+		this.#blocks.set(blockId, block);
+
+		block.timeoutHandle = setTimeout(() => {
+			this.#onBlockTimeout(blockId);
+		}, this.#timeoutMs);
+
+		return block;
+	}
+
+	#onBlockTimeout(blockId: number): void {
+		const block = this.#blocks.get(blockId);
+		if (!block || block.state >= FEC_STATE.COMPLETE) {
+			return;
+		}
+
+		block.state = FEC_STATE.FALLBACK;
+		this.#stats.fallbackRequests++;
+
+		const missingEsis = block.getMissingEsis();
+		if (missingEsis.length > 0 && this.#repairCallback) {
+			console.log(
+				`[FecBlockManager] Block ${blockId} timeout, requesting ${missingEsis.length} repair symbols`,
+			);
+			this.#repairCallback(blockId, missingEsis);
+		}
+
+		block.timeoutHandle = setTimeout(() => {
+			if (block.state === FEC_STATE.FALLBACK) {
+				block.state = FEC_STATE.FAILED;
+				this.#stats.blocksFailed++;
+				// Throttle: log only every 50th failure to avoid console flood
+				if (this.#stats.blocksFailed <= 3 || this.#stats.blocksFailed % 50 === 0) {
+					console.warn(
+						`[FecBlockManager] Block ${blockId} failed - insufficient symbols (total: ${this.#stats.blocksFailed})`,
+					);
+				}
+				this.#blocks.delete(blockId);
+			}
+		}, this.#timeoutMs * 2);
+	}
+
+	#completeBlock(block: FecBlock): Uint8Array {
+		block.clearTimeout();
+		block.state = FEC_STATE.DECODED;
+		block.decodedAt = performance.now();
+		this.#stats.blocksComplete++;
+
+		const data = this.#assembleBlock(block);
+
+		if (this.#decodeCallback) {
+			this.#decodeCallback(block.blockId, data);
+		}
+
+		// GC: block reached terminal state — release symbols immediately.
+		// No delay needed: callers already have the assembled data.
+		this.#blocks.delete(block.blockId);
+
+		return data;
+	}
+
+	#decodeBlock(block: FecBlock): Uint8Array {
+		block.clearTimeout();
+		block.state = FEC_STATE.DECODED;
+		block.decodedAt = performance.now();
+		this.#stats.blocksComplete++;
+		this.#stats.blocksRecovered++;
+
+		console.log(
+			`[FecBlockManager] Block ${block.blockId} recovered via FEC ` +
+				`(${block.sourceSymbols.size} source + ${block.repairSymbols.size} repair)`,
+		);
+
+		// TODO: Integrate with RaptorQ WASM decoder for actual FEC recovery
+		const data = this.#assembleBlock(block);
+
+		if (this.#decodeCallback) {
+			this.#decodeCallback(block.blockId, data);
+		}
+
+		// GC: block reached terminal state — release symbols immediately.
+		this.#blocks.delete(block.blockId);
+
+		return data;
+	}
+
+	#assembleBlock(block: FecBlock): Uint8Array {
+		const esis = [...block.sourceSymbols.keys()].sort((a, b) => a - b);
+		const totalSize = esis.reduce((sum, esi) => sum + block.sourceSymbols.get(esi)!.length, 0);
+		const result = new Uint8Array(totalSize);
+
+		let offset = 0;
+		for (const esi of esis) {
+			const symbol = block.sourceSymbols.get(esi)!;
+			result.set(symbol, offset);
+			offset += symbol.length;
+		}
+
+		return result;
+	}
+
+	#evictOldestBlock(): void {
+		let oldest: FecBlock | null = null;
+		let oldestTime = Infinity;
+
+		for (const block of this.#blocks.values()) {
+			if (block.createdAt < oldestTime) {
+				oldestTime = block.createdAt;
+				oldest = block;
+			}
+		}
+
+		if (oldest) {
+			oldest.clearTimeout();
+			if (oldest.state < FEC_STATE.DECODED) {
+				this.#stats.blocksFailed++;
+			}
+			this.#blocks.delete(oldest.blockId);
+		}
+	}
+}