@blockcast/mmt-container 0.1.0-main.149f78a4adae

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;
+}

package/src/repair-fetch.ts

@@ -0,0 +1,217 @@
+/**
+ * D-28 shared repair-fetch shell.
+ *
+ * Player-agnostic orchestration for per-SBN on-demand MoQ FEC repair
+ * backfill. Each player (moqtail client, hang watch, Shaka MSF bridge)
+ * supplies only its protocol verb via {@link RepairFetchTransport}:
+ *
+ *   - moqtail: standalone FETCH (FetchType.Standalone) for group [sbn, sbn+1)
+ *   - moq-lite/hang: Subscribe with startGroup=sbn, endGroup=sbn (the relay
+ *     propagates startGroup upstream to pull the past group from the origin's
+ *     producer cache)
+ *
+ * Everything else — registration, fire-time repair-track resolution, per-fetch
+ * abort/timeout, feeding symbols, and in-flight slot release on failure — is
+ * identical across players and lives here.
+ */
+
+import type { MulticastManager } from './multicast-manager.js'
+
+/** Resolve a packetId to its repair track name at FIRE TIME.
+ *
+ *  Called on every repair request, never cached by the shell: ABR ladder
+ *  rungs can share a packetId (e.g. video/720p and video/360p both p:1), so
+ *  the mapping must reflect the track active when the request fires, not
+ *  when the shell was wired. Return null when the packetId has no
+ *  repair-bearing track — the request is released without a fetch. */
+export type ResolveRepairTarget = (
+  packetId: number,
+  catalogTrackName?: string,
+) => { repairTrack: string } | null
+
+/** Protocol-specific fetch of one FEC block's repair group.
+ *
+ *  Yield each repair object payload (MMTP packet bytes, ISO 23008-1 §C.5.3
+ *  Repair FEC Payload ID framing). Return when the group ends. MUST abort
+ *  promptly when `signal` fires — the shell bounds every fetch by the
+ *  block's remaining repair budget. */
+export type RepairFetchTransport = (
+  repairTrack: string,
+  sbn: number,
+  packetId: number,
+  signal: AbortSignal,
+) => AsyncIterable<Uint8Array>
+
+export interface WireRepairFetchOptions {
+  resolveTarget: ResolveRepairTarget
+  transport: RepairFetchTransport
+  /** Override the per-fetch timeout. Default: the budget between the resolved
+   *  K-symbol source horizon and the block fail bound. */
+  timeoutMsForPacket?: (packetId: number) => number
+  /** Classify a transport error as a transient publisher/relay retention race.
+   *  Matching failures are retried only inside the block's remaining budget. */
+  shouldRetry?: (error: unknown) => boolean
+  /** Delay between classified transient attempts. Default: 10ms. */
+  retryDelayMs?: number
+}
+
+/**
+ * Wire the D-28 repair-fetch shell onto a MulticastManager.
+ *
+ * Call AFTER the manager has a repair-bearing FEC configuration (players gate
+ * this on the first fec-setup that carries a repairTrack) — registration arms
+ * the per-block repair deadlines in the FEC layer.
+ *
+ * Returns a dispose function that aborts outstanding fetches and stops new
+ * ones from being issued.
+ */
+export function wireRepairFetch(mc: MulticastManager, opts: WireRepairFetchOptions): () => void {
+  type InFlightRepair = {
+    controller: AbortController
+    sbn: number
+    packetId: number
+    catalogTrackName?: string
+  }
+  const inFlight = new Map<string, InFlightRepair>()
+  let disposed = false
+  const requestKey = (
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): string => JSON.stringify([packetId, catalogTrackName ?? null, sbn])
+
+  const removeResetObserver = mc.addTrackResetObserver(
+    (packetId, catalogTrackName) => {
+      for (const [key, request] of inFlight) {
+        if (
+          request.packetId === packetId &&
+          request.catalogTrackName === catalogTrackName
+        ) {
+          request.controller.abort()
+          inFlight.delete(key)
+        }
+      }
+    },
+  )
+
+  const timeoutFor = (
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): number =>
+    opts.timeoutMsForPacket?.(packetId) ??
+    mc.fecManager.repairFetchTimeoutMsForBlock(
+      sbn,
+      packetId,
+      catalogTrackName,
+    )
+  const clearRepair = (
+    sbn: number,
+    packetId: number,
+    catalogTrackName?: string,
+  ): void => {
+    if (catalogTrackName === undefined) mc.clearRepairForBlock(sbn, packetId)
+    else mc.clearRepairForBlock(sbn, packetId, catalogTrackName)
+  }
+  const clearRepairIfOwner = (key: string, request: InFlightRepair): void => {
+    if (inFlight.get(key) !== request) return
+    clearRepair(request.sbn, request.packetId, request.catalogTrackName)
+  }
+  const waitForRetry = (signal: AbortSignal): Promise<void> =>
+    new Promise((resolve) => {
+      if (signal.aborted) {
+        resolve()
+        return
+      }
+      let timer: ReturnType<typeof setTimeout>
+      const onAbort = () => {
+        clearTimeout(timer)
+        resolve()
+      }
+      timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort)
+        resolve()
+      }, Math.max(1, opts.retryDelayMs ?? 10))
+      signal.addEventListener('abort', onAbort, { once: true })
+    })
+
+  mc.onRepairSubscribe((sbn, packetId, catalogTrackName) => {
+    if (disposed) {
+      clearRepair(sbn, packetId, catalogTrackName)
+      return
+    }
+
+    // Fire-time resolution — see ResolveRepairTarget.
+    const target = opts.resolveTarget(packetId, catalogTrackName)
+    if (!target) {
+      clearRepair(sbn, packetId, catalogTrackName)
+      return
+    }
+
+    const ctrl = new AbortController()
+    const key = requestKey(sbn, packetId, catalogTrackName)
+    const previous = inFlight.get(key)
+    previous?.controller.abort()
+    const request: InFlightRepair = { controller: ctrl, sbn, packetId, catalogTrackName }
+    inFlight.set(key, request)
+    const timeoutMs = timeoutFor(sbn, packetId, catalogTrackName)
+    const timer = setTimeout(() => ctrl.abort(), Math.max(1, timeoutMs))
+
+    void (async () => {
+      let fed = 0
+      try {
+        while (!ctrl.signal.aborted) {
+          try {
+            for await (const packet of opts.transport(
+              target.repairTrack,
+              sbn,
+              packetId,
+              ctrl.signal,
+            )) {
+              if (ctrl.signal.aborted) break
+              if (inFlight.get(key) !== request) break
+              fed++
+              if (catalogTrackName === undefined) {
+                mc.processRepairFromMoQ(packet, packetId)
+              } else {
+                mc.processRepairFromMoQ(packet, packetId, catalogTrackName)
+              }
+            }
+            break
+          } catch (err) {
+            if (fed > 0 || ctrl.signal.aborted || !opts.shouldRetry?.(err)) throw err
+            await waitForRetry(ctrl.signal)
+          }
+        }
+        // A fetch that ended without feeding anything cannot resolve the
+        // block; release the slot so failure accounting is not wedged. A
+        // fetch that fed symbols leaves resolution to the FEC layer
+        // (onRepairResolved clears the slot on completion OR failure).
+        if (fed === 0) clearRepairIfOwner(key, request)
+      } catch (err) {
+        // Range-not-retained, transport error, or abort: the block can only
+        // resolve via the fail bound now — release the slot immediately.
+        clearRepairIfOwner(key, request)
+        if (!ctrl.signal.aborted) {
+          console.warn(
+            `[RepairFetch] fetch failed pid=${packetId} sbn=${sbn} track=${target.repairTrack}:`,
+            err,
+          )
+        }
+      } finally {
+        clearTimeout(timer)
+        if (inFlight.get(key) === request) inFlight.delete(key)
+      }
+    })()
+  })
+
+  return () => {
+    disposed = true
+    removeResetObserver()
+    for (const request of inFlight.values()) {
+      clearRepair(request.sbn, request.packetId, request.catalogTrackName)
+      request.controller.abort()
+    }
+    inFlight.clear()
+  }
+}