@blockcast/mmt-container 0.1.0 → 0.3.0

package/src/multicast-unwrap.ts

@@ -0,0 +1,132 @@
+/**
+ * @mmt/container - Container-aware multicast MMTP unwrapper
+ *
+ * Dispatches raw multicast MMTP packets into typed media or Annex C repair
+ * frames. Handles FEC source payload ID extraction and repair packet parsing.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type MMTPHeader,
+  type MFUExtraction,
+  parseMMTPHeader,
+  parseMoqRepairFrame,
+  extractMFUPayload,
+  hasSourceFecPayloadId,
+  MMTP_HEADER_SIZE,
+  PACKET_TYPE_REPAIR,
+} from '@blockcast/mmt-base'
+
+/** The immutable reader contract selected by a multicast consumer. */
+export interface MulticastContainerContract {
+  version: 1
+  kind: 'mmtp'
+}
+
+export type MulticastContainerErrorCode =
+  | 'unsupported_version'
+  | 'unsupported_kind'
+  | 'ambiguous_kind'
+  | 'malformed_selector'
+
+/** Versioned, fail-closed contract selection error. */
+export class MulticastContainerContractError extends TypeError {
+  readonly version = 1
+  readonly code: MulticastContainerErrorCode
+
+  constructor(code: MulticastContainerErrorCode, detail: string) {
+    super(`multicast-container/v1/${code}: ${detail}`)
+    this.name = 'MulticastContainerContractError'
+    this.code = code
+  }
+}
+
+/** Validate the only reader currently frozen by the container contract. */
+export function validateMulticastContainerContract(
+  contract: unknown,
+): MulticastContainerContract {
+  if (contract === null || typeof contract !== 'object') {
+    throw new MulticastContainerContractError('malformed_selector', 'selector is required')
+  }
+
+  const value = contract as Record<string, unknown>
+  if (value['version'] !== 1) {
+    throw new MulticastContainerContractError('unsupported_version', 'only version 1 is supported')
+  }
+  if (value['kind'] === undefined || value['kind'] === null || value['kind'] === '') {
+    throw new MulticastContainerContractError('ambiguous_kind', 'container kind is required')
+  }
+  if (value['kind'] !== 'mmtp') {
+    throw new MulticastContainerContractError('unsupported_kind', `reader is not implemented for ${String(value['kind'])}`)
+  }
+  return { version: 1, kind: 'mmtp' }
+}
+
+/** Source FEC Payload ID — flat 32-bit SS_ID per ISO 23008-1 §C.5.2 */
+export interface FecPayloadId {
+  ssId: number
+}
+
+/** Discriminated union of unwrapped multicast frames */
+export type MulticastFrame =
+  | { kind: 'mmtp'; header: MMTPHeader; mfu: MFUExtraction; fecId: FecPayloadId | null }
+  | {
+      kind: 'repair'
+      header: MMTPHeader
+      ssStart: number
+      rsbLength: number
+      rsId: number
+      ssbLength: number
+      data: Uint8Array
+    }
+
+/**
+ * Unwrap a raw MMTP multicast packet into a typed MulticastFrame.
+ *
+ * This function handles MMTP-framed multicast only (container 0x01). The
+ * versioned contract is validated before any packet bytes are parsed, so an
+ * unsupported version or container kind fails closed rather than being
+ * reinterpreted under a reader that does not match the wire format.
+ *
+ * @param packet - Raw MMTP packet bytes from multicast UDP
+ * @param contract - Required `multicast-container/v1` selector
+ * @throws {MulticastContainerContractError} if the selector is absent or unsupported
+ * @returns Parsed frame, or null if the packet is too small / malformed
+ */
+export function unwrapMulticastPacket(
+  packet: Uint8Array,
+  contract: unknown,
+): MulticastFrame | null {
+  validateMulticastContainerContract(contract)
+  if (packet.length < MMTP_HEADER_SIZE) return null
+
+  let header: MMTPHeader
+  try {
+    header = parseMMTPHeader(packet)
+  } catch {
+    return null
+  }
+
+  if (header.packetType === PACKET_TYPE_REPAIR || header.fecType >= 2) {
+    const repair = parseMoqRepairFrame(packet)
+    if (!repair) return null
+    return {
+      kind: 'repair',
+      header,
+      ssStart: repair.ssStart,
+      rsbLength: repair.rsbLength,
+      rsId: repair.rsId,
+      ssbLength: repair.ssbLength,
+      data: repair.symbolData,
+    }
+  }
+
+  const hasFec = hasSourceFecPayloadId(packet)
+
+  // MMTP source packet — extract MFU payload
+  const mfu = extractMFUPayload(packet)
+  if (!mfu) return null
+  const fecId = hasFec ? mfu.fecPayloadId : null
+  return { kind: 'mmtp', header, mfu, fecId }
+}

package/src/no-modules.ts

@@ -0,0 +1,21 @@
+export { MmtpContainerParser } from './mmtp-container-parser.js'
+export { createWasmMmtpContainerParser } from './wasm-mmtp-container-parser.js'
+export {
+  datagramMfuReassembly,
+  reliableMoqMfuReassembly,
+  mmtpFrameReorderWindowFrames,
+} from './mfu-reassembly-policy.js'
+export {
+  validateCmsfMmtpCatalog,
+  CmsfCatalogValidationError,
+  resolveGroupDurationMs,
+} from './carp-catalog.js'
+export { catalogFecInterleaveMs, computeFecTimeout } from '@blockcast/mmt-fec'
+export { FEC_INACTIVE_REASONS, catalogDeclaresFec, resolveFecState } from './fec-state.js'
+export { MmtpToCmaf } from './mmtp-to-cmaf.js'
+export { createManifestAuthPlan } from './manifest-auth-plan.js'
+export {
+  ManifestVerifier,
+  createWebCryptoEd25519Verifier,
+  manifestBindingId,
+} from '@blockcast/mmt-manifest-verify'

package/src/phase14-catalog-override.ts

@@ -0,0 +1,336 @@
+/**
+ * Phase 14 catalog-override hook (test harness only).
+ *
+ * When `globalThis.__PHASE14_CATALOG_OVERRIDE` is set (injected by the
+ * 7point test via `page.addInitScript` — see
+ * packages/moq-server/tests/7point-validation.test.mjs `applyPhase14CatalogOverride`)
+ * the override's `tracks[]` are merged into whatever catalog the MoQ-delivered
+ * JSON produced:
+ *
+ *   - Dedupe by `track.name`.
+ *   - When both sides carry a track with the same name, the override's
+ *     `fec` config wins — this is how the 7point harness steers multi-track
+ *     tests onto the Phase 14 `video/base` + `video/delta` + `video/repair`
+ *     switching set without asking the publisher to change its catalog.
+ *   - Tracks present only in the override are appended as-is.
+ *   - Tracks present only in the MoQ catalog are preserved unchanged.
+ *
+ * This module is deliberately player-agnostic. It exposes:
+ *
+ *   getPhase14CatalogOverride()        — read + shape-check the global.
+ *   mergeOverrideIntoHangRenditions()  — merge into a `@moq/hang`
+ *                                        Catalog.Root `video.renditions` /
+ *                                        `audio.renditions` dict. Used by
+ *                                        hang-mmt-fec/js/watch/src/broadcast.ts.
+ *   mergeOverrideIntoCmsfTracks()      — merge into moqtail's CMSF-flat
+ *                                        `tracks[]` array. Used by
+ *                                        moqtail-private CMSFCatalog.from().
+ *
+ * Production builds never set the global, so all three helpers are no-ops at
+ * runtime unless the test harness opts in.
+ */
+
+import type { FecAlgorithm, FecCatalogConfig } from "./carp-catalog.js";
+
+// ---------------------------------------------------------------------------
+// Override fixture shape (IETF draft-ietf-moq-catalogformat-01)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single override track entry — mirrors the fixture at
+ * `packages/moq-server/tests/fixtures/multi-track-catalog.json`.
+ *
+ * Kept intentionally permissive: the canonical fixture carries `name`,
+ * `altGroup`, `framerate`, and `fec`, but future 7point scenarios may extend
+ * with additional hints without wanting this module to gate-keep them.
+ */
+export interface Phase14OverrideTrack {
+	name: string;
+	/** CMSF packaging kind. Optional per track — when absent, the merge
+	 *  derives it from the override's top-level `streamingFormat`. */
+	packaging?: "mmtp" | "cmaf" | "loc" | "timeline";
+	/** Required when packaging is `mmtp`; the current publisher emits MFU mode. */
+	mmtpMode?: "mpu" | "mfu";
+	/** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */
+	timescale?: number;
+	/** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */
+	groupDurationMs?: number;
+	/** Codec string. Optional per track — when absent, the merge inherits
+	 *  from the existing video/audio rendition in the MoQ catalog (the
+	 *  publisher's declaration). Throws only when neither the override nor
+	 *  any existing rendition supplies one. */
+	codec?: string;
+	role?: "video" | "audio" | "timeline";
+	altGroup?: number;
+	framerate?: number;
+	fec?: Partial<FecCatalogConfig> & { algorithm: FecAlgorithm };
+}
+
+/**
+ * The shape the 7point harness writes to `globalThis.__PHASE14_CATALOG_OVERRIDE`.
+ * Extra top-level fields (`version`, `streamingFormat`, ...) are ignored —
+ * the merge only consumes `tracks[]`.
+ */
+export interface Phase14CatalogOverride {
+	version?: string;
+	streamingFormat?: string;
+	tracks: Phase14OverrideTrack[];
+}
+
+// ---------------------------------------------------------------------------
+// Global reader
+// ---------------------------------------------------------------------------
+
+/**
+ * Read `globalThis.__PHASE14_CATALOG_OVERRIDE` and return it only when it has
+ * a well-formed `tracks[]` array. Malformed values log + return `null` rather
+ * than throw so a broken fixture never kills the MoQ path for a real stream.
+ */
+export function getPhase14CatalogOverride(): Phase14CatalogOverride | null {
+	// `globalThis` is defined in workers, service workers, and the main window;
+	// it's the portable way to reach the test-injected hook from any context.
+	const g = globalThis as Record<string, unknown>;
+	const raw = g["__PHASE14_CATALOG_OVERRIDE"];
+	if (raw === undefined || raw === null) return null;
+	if (typeof raw !== "object") {
+		console.warn("[phase14-catalog-override] hook is not an object; ignoring");
+		return null;
+	}
+	const obj = raw as Record<string, unknown>;
+	const tracks = obj["tracks"];
+	if (!Array.isArray(tracks)) {
+		console.warn("[phase14-catalog-override] hook.tracks is not an array; ignoring");
+		return null;
+	}
+	// Shallow filter: keep only entries that at least have a string name.
+	// Each consumer (hang or CMSF merge) validates shape further.
+	const filtered: Phase14OverrideTrack[] = [];
+	for (const t of tracks) {
+		if (typeof t === "object" && t !== null) {
+			const entry = t as Record<string, unknown>;
+			if (typeof entry["name"] === "string" && (entry["name"] as string).length > 0) {
+				filtered.push(entry as unknown as Phase14OverrideTrack);
+			}
+		}
+	}
+	if (filtered.length === 0) return null;
+	return {
+		version: typeof obj["version"] === "string" ? (obj["version"] as string) : undefined,
+		streamingFormat:
+			typeof obj["streamingFormat"] === "string" ? (obj["streamingFormat"] as string) : undefined,
+		tracks: filtered,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Hang renditions merge (moq-lib / hang-mmt-fec)
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge override tracks into a `@moq/hang` Catalog.Root-like object. The
+ * caller passes the already-parsed Catalog.Root (mutates in place and also
+ * returns it for convenience). No-op when `override` is null.
+ *
+ * Dedupe rule: override wins for `fec` config and `framerate`. Everything
+ * else (codec, container kind) is preserved from the MoQ-delivered rendition
+ * when it exists, or synthesised from the override when it does not.
+ *
+ * Typed `any` here rather than narrow-matching `Catalog.Root` because the
+ * upstream `@moq/hang` schema is branded (u53) and the container `kind` union
+ * varies by version (`loc` kind appears in hang-mmt-fec's fork). Matching
+ * that surface exactly would over-couple this module to a single upstream
+ * revision; the runtime shape we rely on (`.video.renditions` dict mutation)
+ * is stable.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mergeOverrideIntoHangRenditions<T extends Record<string, any>>(
+	catalog: T,
+	override: Phase14CatalogOverride | null,
+): T {
+	if (!override) return catalog;
+
+	for (const track of override.tracks) {
+		// Default role inference: names without an explicit role field are
+		// treated as video unless the name suffix says audio.
+		const role: "video" | "audio" =
+			track.role === "audio" || track.name.startsWith("audio") ? "audio" : "video";
+
+		const bagKey = role === "audio" ? "audio" : "video";
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const bag: { renditions: Record<string, any>; priority?: number } =
+			catalog[bagKey] ?? { renditions: {}, priority: 1 };
+		const existing = bag.renditions[track.name];
+
+		// Merge: override fills gaps, does NOT overwrite existing fec/framerate.
+		// The publisher's real catalog is ground truth for wire parameters:
+		// if the existing rendition already has a matching fec config, that's
+		// what the publisher's packets actually carry. Overwriting it with a
+		// fixture value (e.g. Phase 14 target K=768 when publisher emits K=4)
+		// causes the FEC manager to wait for symbols that never arrive.
+		// Only when the rendition is brand-new (no existing fec) do we seed
+		// from the fixture.
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const merged: Record<string, any> = {
+			...(existing ?? {}),
+			container: existing?.container ?? { kind: "mmtp-fec" },
+			codec: existing?.codec ?? "",
+		};
+		if (existing?.framerate === undefined && track.framerate !== undefined) {
+			merged["framerate"] = track.framerate;
+		}
+		if (existing?.fec === undefined && track.fec !== undefined) {
+			merged["fec"] = track.fec;
+		}
+
+		bag.renditions[track.name] = merged;
+		// Reassign so a freshly-created bag is actually reachable on the
+		// catalog when the MoQ side was missing video/audio entirely.
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(catalog as any)[bagKey] = bag;
+	}
+	return catalog;
+}
+
+// ---------------------------------------------------------------------------
+// CMSF tracks merge (moqtail-private)
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape-minimal description of a CMSF track input (pre-validation JSON, not
+ * the parsed `CMSFTrack`). Keeps this module free of a hard dependency on
+ * moqtail-ts.
+ */
+type CmsfTrackJson = {
+	name: string;
+	packaging?: string;
+	mmtpMode?: string;
+	timescale?: number;
+	groupDurationMs?: number;
+	role?: string;
+	codec?: string;
+	framerate?: number;
+	fec?: unknown;
+	[k: string]: unknown;
+};
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+/**
+ * Merge override tracks into a raw CMSF `tracks[]` JSON array (as produced
+ * by `JSON.parse(catalog.json)` inside `CMSFCatalog.from`).
+ *
+ * Dedupe by `name`. For name collisions, publisher-emitted `fec` + `framerate`
+ * are preserved (the publisher is ground truth for wire parameters). For new
+ * track names, missing `packaging` is derived from the override's top-level
+ * `streamingFormat`, and missing `codec` is inherited from any existing video
+ * track in the catalog. Throws on bad init when neither source supplies them.
+ */
+export function mergeOverrideIntoCmsfTracks(
+	tracks: CmsfTrackJson[],
+	override: Phase14CatalogOverride | null,
+): CmsfTrackJson[] {
+	if (!override) return tracks;
+
+	const byName = new Map<string, CmsfTrackJson>();
+	for (const t of tracks) {
+		if (typeof t?.name === "string") byName.set(t.name, t);
+	}
+
+	// Catalog-derived fallbacks (NOT magic numbers) — inherited from existing
+	// publisher tracks. Used only when the override track doesn't carry them.
+	const derivedPackaging = override.streamingFormat;
+	const existingVideoTrack = tracks.find(
+		(t) => t.role === "video" && typeof t.codec === "string" && (t.codec as string).length > 0,
+	);
+	const existingAudioTrack = tracks.find(
+		(t) => t.role === "audio" && typeof t.codec === "string" && (t.codec as string).length > 0,
+	);
+
+	for (const ot of override.tracks) {
+		const existing = byName.get(ot.name);
+		if (existing !== undefined) {
+			// Preserve publisher-emitted fec + framerate — those describe what
+			// is actually on the wire. Overwriting with fixture values causes
+			// the player's FEC manager to wait for symbols that never arrive
+			// when the fixture's K/P don't match the publisher's.
+			if (existing.fec === undefined && ot.fec !== undefined) existing.fec = ot.fec;
+			if (existing.framerate === undefined && ot.framerate !== undefined) {
+				existing.framerate = ot.framerate;
+			}
+			if (ot.role !== undefined && existing.role === undefined) existing.role = ot.role;
+			if (existing.packaging === "mmtp") {
+				const mode = existing.mmtpMode ?? ot.mmtpMode;
+				if (mode !== "mpu" && mode !== "mfu") {
+					throw new Error(
+						`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid mmtpMode`,
+					);
+				}
+				existing.mmtpMode = mode;
+				if (existing.timescale === undefined && ot.timescale !== undefined) existing.timescale = ot.timescale;
+				if (existing.groupDurationMs === undefined && ot.groupDurationMs !== undefined) {
+					existing.groupDurationMs = ot.groupDurationMs;
+				}
+				if (!isPositiveInteger(existing.timescale)) {
+					throw new Error(
+						`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid timescale`,
+					);
+				}
+				if (!isPositiveInteger(existing.groupDurationMs)) {
+					throw new Error(
+						`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid groupDurationMs`,
+					);
+				}
+			}
+		} else {
+			const packaging = ot.packaging ?? derivedPackaging;
+			if (typeof packaging !== "string" || packaging.length === 0) {
+				throw new Error(
+					`[phase14-catalog-override] track "${ot.name}" has no packaging — supply per-track or set top-level streamingFormat`,
+				);
+			}
+			// Role inference: repair tracks (ending in /repair) stay role-less
+			// per CMSF convention; others default to video.
+			const role = ot.role ?? (ot.name.endsWith("/repair") ? undefined : "video");
+			const inheritedCodec =
+				role === "audio" ? existingAudioTrack?.codec : existingVideoTrack?.codec;
+			const codec = ot.codec ?? inheritedCodec;
+			if (packaging !== "timeline" && (typeof codec !== "string" || codec.length === 0)) {
+				throw new Error(
+					`[phase14-catalog-override] track "${ot.name}" has no codec (packaging='${packaging}') — supply per-track or ensure the publisher catalog has a ${role ?? "video"} track to inherit from`,
+				);
+			}
+			const mmtpMode = ot.mmtpMode;
+			if (packaging === "mmtp" && mmtpMode !== "mpu" && mmtpMode !== "mfu") {
+				throw new Error(
+					`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid mmtpMode`,
+				);
+			}
+			if (packaging === "mmtp" && !isPositiveInteger(ot.timescale)) {
+				throw new Error(
+					`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid timescale`,
+				);
+			}
+			if (packaging === "mmtp" && !isPositiveInteger(ot.groupDurationMs)) {
+				throw new Error(
+					`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid groupDurationMs`,
+				);
+			}
+			const entry: CmsfTrackJson = {
+				name: ot.name,
+				packaging,
+				codec: codec as string,
+			};
+			if (mmtpMode !== undefined) entry.mmtpMode = mmtpMode;
+			if (ot.timescale !== undefined) entry.timescale = ot.timescale;
+			if (ot.groupDurationMs !== undefined) entry.groupDurationMs = ot.groupDurationMs;
+			if (role !== undefined) entry.role = role;
+			if (ot.framerate !== undefined) entry.framerate = ot.framerate;
+			if (ot.fec !== undefined) entry.fec = ot.fec;
+			tracks.push(entry);
+			byName.set(ot.name, entry);
+		}
+	}
+	return tracks;
+}