@blockcast/mmt-container 0.3.0 → 0.4.0-main.71d61b2a53f2

package/node_modules/@blockcast/mmt-fec/package.json

@@ -1,79 +0,0 @@
-{
-  "name": "@blockcast/mmt-fec",
-  "version": "0.3.0",
-  "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.3.0"
-  },
-  "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/node_modules/@blockcast/mmt-fec/src/block-manager.ts

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