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

package/src/repair-layers.ts

@@ -0,0 +1,490 @@
+// Layered and overlay FEC repair contract (draft-ramadan-moq-fec §6.3).
+//
+// One source track may carry several repair tracks. Every base layer is
+// generated from the same source partition (RaptorQ, K, T, interleaveDepthMs,
+// reorderToleranceMs) and differs from its siblings only in its repair symbol
+// count P_i. Layer i owns the Repair Symbol IDs [O_i, O_i + P_i) with
+// O_i = sum(P_j, j < i), and ESI = K + RS_ID, so any subset of layers combines
+// into one decode. A keyframe overlay is a second, independent FEC instance
+// covering only random access point fragments, with its own K and P and its
+// own RS_ID space starting at 0.
+//
+// Repair tracks describe themselves (`depends`, `repairLayer`, `scope`); names
+// carry no meaning. This module holds the one rule set both catalog dialects
+// (MSF `tracks[]` and hang `repair.renditions`) resolve through, so the CMSF
+// validator and the player resolver cannot drift apart.
+//
+// The one dialect difference is where layer 0 lives. In MSF, `fec.repairTrack`
+// must name a `fec-repair` track in `tracks[]`, so a dangling pointer fails
+// closed (`layerZeroMustBeDeclared`). In hang, layer 0 is named only by the
+// rendition's `fec.repairTrack` and needs no `repair.renditions` entry; an
+// entry there is optional and, when present, must agree with the source.
+
+/** Lowest MoQT-scale priority a repair track may declare. */
+export const REPAIR_PRIORITY_MIN = 192;
+/** Highest MoQT-scale priority a repair track may declare. */
+export const REPAIR_PRIORITY_MAX = 255;
+/** Priority of a base layer 0 track that declares none. */
+export const DEFAULT_REPAIR_PRIORITY = 240;
+/** RFC 6330 §4.4.1.2: the largest number of source symbols in one RaptorQ source block. */
+export const MAX_RAPTORQ_SOURCE_SYMBOLS = 56403;
+/** The 24-bit RS_ID field (§7.1) bounds the repair total of one FEC instance. */
+export const MAX_REPAIR_SYMBOLS = 0xffffff;
+/** The 24-bit ESI bounds K + totalP - 1 for one FEC instance. */
+export const MAX_ENCODING_SYMBOL_ID = 0xffffff;
+
+export type RepairContractCode =
+	| "track_fec"
+	| "track_repair_track"
+	| "track_repair_depends"
+	| "track_repair_layer"
+	| "track_repair_priority"
+	| "track_repair_overlay"
+	| "track_repair_geometry"
+	| "track_fec_bounds";
+
+/** Reports one contract violation and never returns. */
+export type RepairContractFail = (code: RepairContractCode, path: string, message: string) => never;
+
+export class RepairContractError extends Error {
+	constructor(
+		public readonly code: RepairContractCode,
+		public readonly path: string,
+		message: string,
+	) {
+		super(`[repair-layers:${code}] ${path}: ${message}`);
+		this.name = "RepairContractError";
+	}
+}
+
+export const throwRepairContractError: RepairContractFail = (code, path, message) => {
+	throw new RepairContractError(code, path, message);
+};
+
+/** The self-describing fields of one repair track entry, in either dialect. */
+export type RepairTrackDescriptor = {
+	/** Track (MSF) or rendition (hang) name. */
+	name: string;
+	/** JSON path of the entry, for error reporting. */
+	path: string;
+	depends?: unknown;
+	repairLayer?: unknown;
+	repairSymbols?: unknown;
+	priority?: unknown;
+	scope?: unknown;
+	sourceSymbols?: unknown;
+};
+
+/** The source track's `fec` object as the layer contract reads it. */
+export type RepairSourceGeometry = {
+	/** Source track or rendition name. */
+	name: string;
+	/** JSON path of the `fec` object, for error reporting. */
+	path: string;
+	algorithm?: unknown;
+	/** K. */
+	sourceSymbols?: unknown;
+	/** P_0. */
+	repairSymbols?: unknown;
+	/** Layer 0 track name. */
+	repairTrack?: unknown;
+};
+
+/** A resolved base repair layer with its derived RS_ID range. */
+export type RepairLayerParams = {
+	/** Layer index; 0 is the track named by the source's `fec.repairTrack`. */
+	layer: number;
+	repairTrackName: string;
+	/** P_i: repair symbols per block carried by this layer. */
+	repairSymbols: number;
+	/** O_i = sum(P_j for j < i): the first RS_ID this layer carries. ESI = K + RS_ID. */
+	rsIdOffset: number;
+	/** MoQT-scale priority (lower first); 240 when layer 0 declares none. */
+	priority: number;
+};
+
+/** A resolved keyframe overlay: a separate FEC instance over RAP fragments only. */
+export type RepairOverlayParams = {
+	repairTrackName: string;
+	scope: "keyframe";
+	/** K_overlay: source symbols of the overlay instance. */
+	sourceSymbols: number;
+	/** P_overlay: repair symbols per overlay block; also the overlay's own RSB_length. */
+	repairSymbols: number;
+	/** MoQT-scale priority, independent of the base layer chain. */
+	priority: number;
+};
+
+export type RepairLayersResolution = {
+	sourceTrackName: string;
+	/** Base layers in layer order, layer 0 first. Never empty. */
+	baseLayers: readonly RepairLayerParams[];
+	/** Keyframe overlay instances, in catalog order. Empty when none is declared. */
+	/** At most one entry: the wire carries one overlay trailer per RAP packet. */
+	overlays: readonly RepairOverlayParams[];
+	/** Sum of P over base layers: the wire RSB_length on every base layer packet. */
+	totalBaseRepairSymbols: number;
+};
+
+const REPAIR_FIELDS = ["depends", "repairLayer", "repairSymbols", "priority", "scope", "sourceSymbols"] as const;
+
+/** Track-level block geometry keys a repair track must not carry (§6.3 rule 8): geometry is the source's. */
+export const REPAIR_TRACK_GEOMETRY_KEYS = [
+	"mmtpMode",
+	"timescale",
+	"groupDurationMs",
+	"groupDurationTicks",
+	"keyframeIntervalMs",
+	"keyframeIntervalTicks",
+	"fec",
+	"symbolSize",
+	"interleaveDepthMs",
+] as const;
+
+/** Self-describing repair fields that only a repair track or repair rendition may carry. */
+export const REPAIR_TRACK_ONLY_KEYS = ["repairLayer", "repairSymbols", "sourceSymbols", "scope"] as const;
+
+/** Rule 8: a repair track (MSF) or repair rendition (hang) carries no block geometry. */
+export function rejectRepairTrackGeometry(path: string, fields: Record<string, unknown>, fail: RepairContractFail): void {
+	for (const key of REPAIR_TRACK_GEOMETRY_KEYS) {
+		if (fields[key] !== undefined) {
+			fail(
+				"track_repair_geometry",
+				`${path}.${key}`,
+				"a repair track carries no block geometry; it is shared with the source track's fec object",
+			);
+		}
+	}
+}
+
+/** Which repair tracks a catalog can reach, for rule 9 (no orphan repair track). */
+export type RepairReachability = {
+	/** True once any track or rendition carries `fec` with an algorithm other than `none`. */
+	declaresFecSource: boolean;
+	/** Every non-empty `fec.repairTrack` a FEC source names: the layer-0 tracks. */
+	layerZeroNames: ReadonlySet<string>;
+};
+
+/**
+ * Derive rule 9's inputs from the raw `fec` objects of every media track (MSF,
+ * packaging other than `fec-repair`) or media rendition (hang) in a catalog.
+ * Callers must not pass repair tracks: rule 8 forbids `fec` on them, and a
+ * repair track that carried one would otherwise name itself as its own
+ * layer 0 and slip past rule 9. One derivation for the validator and both
+ * resolver dialects, so an empty-string pointer or an `algorithm: "none"`
+ * source is read the same way everywhere.
+ */
+export function repairReachability(fecObjects: Iterable<unknown>): RepairReachability {
+	let declaresFecSource = false;
+	const layerZeroNames = new Set<string>();
+	for (const candidate of fecObjects) {
+		if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) continue;
+		const fec = candidate as Record<string, unknown>;
+		if (fec["algorithm"] === "none") continue;
+		declaresFecSource = true;
+		const repairTrack = fec["repairTrack"];
+		if (typeof repairTrack === "string" && repairTrack.length > 0) layerZeroNames.add(repairTrack);
+	}
+	return { declaresFecSource, layerZeroNames };
+}
+
+/**
+ * Rule 9: once a catalog declares a FEC source, a repair track that declares no
+ * `depends` must be some source's layer 0. A catalog with no FEC source may
+ * still carry a naming-era repair track that nothing joins.
+ */
+export function assertRepairTrackReachable(
+	descriptor: RepairTrackDescriptor,
+	reachability: RepairReachability,
+	fail: RepairContractFail,
+): void {
+	if (dependsTarget(descriptor) !== undefined) return;
+	if (reachability.declaresFecSource && !reachability.layerZeroNames.has(descriptor.name)) {
+		fail(
+			"track_repair_depends",
+			`${descriptor.path}.depends`,
+			"no source names this repair track in fec.repairTrack and it declares no depends",
+		);
+	}
+}
+
+/** A media track (MSF) or media rendition (hang) carries no repair-track fields. */
+export function rejectRepairFieldsOnMediaTrack(path: string, fields: Record<string, unknown>, fail: RepairContractFail): void {
+	for (const key of REPAIR_TRACK_ONLY_KEYS) {
+		if (fields[key] !== undefined) {
+			fail("track_repair_layer", `${path}.${key}`, `${key} is a repair track field`);
+		}
+	}
+}
+
+/** Pick the self-describing repair fields out of a raw track or rendition record. */
+export function describeRepairTrack(name: string, path: string, fields: Record<string, unknown>): RepairTrackDescriptor {
+	const descriptor: RepairTrackDescriptor = { name, path };
+	for (const field of REPAIR_FIELDS) {
+		if (field in fields) descriptor[field] = fields[field];
+	}
+	return descriptor;
+}
+
+function isSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value);
+}
+
+function positiveInteger(value: unknown): value is number {
+	return isSafeInteger(value) && value > 0;
+}
+
+/** The single source a repair track names in `depends`, once its shape has been validated. */
+export function dependsTarget(descriptor: RepairTrackDescriptor): string | undefined {
+	const depends = descriptor.depends;
+	return Array.isArray(depends) && depends.length === 1 && typeof depends[0] === "string" && depends[0].length > 0
+		? depends[0]
+		: undefined;
+}
+
+/**
+ * Validate the shape of one repair track's self-describing fields, independent
+ * of any source. Cross-track rules (layer 0 agreement, contiguity, priority
+ * order, bounds) live in `assembleRepairLayers`.
+ */
+export function validateRepairTrackFields(descriptor: RepairTrackDescriptor, fail: RepairContractFail): void {
+	const { path } = descriptor;
+	if (descriptor.depends !== undefined && dependsTarget(descriptor) === undefined) {
+		fail("track_repair_depends", `${path}.depends`, "must name exactly one source track");
+	}
+	if (descriptor.repairLayer !== undefined && (!isSafeInteger(descriptor.repairLayer) || descriptor.repairLayer < 0)) {
+		fail("track_repair_layer", `${path}.repairLayer`, "must be a non-negative integer");
+	}
+	if (
+		descriptor.repairSymbols !== undefined &&
+		(!positiveInteger(descriptor.repairSymbols) || descriptor.repairSymbols > MAX_REPAIR_SYMBOLS)
+	) {
+		fail("track_repair_layer", `${path}.repairSymbols`, `must be a positive integer at most ${MAX_REPAIR_SYMBOLS}`);
+	}
+	if (
+		descriptor.priority !== undefined &&
+		(!isSafeInteger(descriptor.priority) ||
+			descriptor.priority < REPAIR_PRIORITY_MIN ||
+			descriptor.priority > REPAIR_PRIORITY_MAX)
+	) {
+		fail(
+			"track_repair_priority",
+			`${path}.priority`,
+			`must be an integer from ${REPAIR_PRIORITY_MIN} to ${REPAIR_PRIORITY_MAX} (MoQT scale, lower first)`,
+		);
+	}
+	if (descriptor.scope !== undefined) {
+		if (descriptor.scope !== "keyframe") {
+			fail("track_repair_overlay", `${path}.scope`, 'must be "keyframe"');
+		}
+		if (descriptor.repairLayer !== undefined) {
+			fail("track_repair_overlay", `${path}.repairLayer`, "an overlay is a separate FEC instance and carries no repairLayer");
+		}
+		for (const field of ["depends", "sourceSymbols", "repairSymbols", "priority"] as const) {
+			if (descriptor[field] === undefined) {
+				fail("track_repair_overlay", `${path}.${field}`, `an overlay must declare ${field}`);
+			}
+		}
+	}
+	if (descriptor.sourceSymbols !== undefined) {
+		if (descriptor.scope === undefined) {
+			fail("track_repair_overlay", `${path}.sourceSymbols`, "only an overlay (scope: keyframe) declares its own sourceSymbols");
+		}
+		if (!positiveInteger(descriptor.sourceSymbols) || descriptor.sourceSymbols > MAX_RAPTORQ_SOURCE_SYMBOLS) {
+			fail(
+				"track_fec_bounds",
+				`${path}.sourceSymbols`,
+				`must be a positive integer at most ${MAX_RAPTORQ_SOURCE_SYMBOLS} (RFC 6330 source block limit)`,
+			);
+		}
+	}
+	if (isSafeInteger(descriptor.repairLayer) && descriptor.repairLayer >= 1) {
+		for (const field of ["depends", "repairSymbols", "priority"] as const) {
+			if (descriptor[field] === undefined) {
+				fail("track_repair_layer", `${path}.${field}`, `repair layer ${descriptor.repairLayer} must declare ${field}`);
+			}
+		}
+	}
+}
+
+/**
+ * Resolve the base layers and overlays of one source track and derive each
+ * base layer's RS_ID offset. Fails closed on every §6.3 rule violation through
+ * `fail`, which receives the code and the JSON path of the offending field.
+ *
+ * `descriptors` are every repair track (or repair rendition) in the catalog,
+ * already shape-checked by `validateRepairTrackFields`. Returns undefined when
+ * the source names no layer 0 and nothing depends on it.
+ */
+export type AssembleRepairLayersOptions = {
+	/**
+	 * MSF: `fec.repairTrack` must name one of `descriptors` (a `fec-repair`
+	 * track), so a dangling pointer fails closed with `track_repair_track`.
+	 * hang: layer 0 lives outside `repair.renditions`, so leave this unset.
+	 */
+	layerZeroMustBeDeclared?: boolean;
+};
+
+export function assembleRepairLayers(
+	source: RepairSourceGeometry,
+	descriptors: readonly RepairTrackDescriptor[],
+	fail: RepairContractFail = throwRepairContractError,
+	options: AssembleRepairLayersOptions = {},
+): RepairLayersResolution | undefined {
+	const layerZeroName =
+		typeof source.repairTrack === "string" && source.repairTrack.length > 0 ? source.repairTrack : undefined;
+	const layerZero = layerZeroName === undefined ? undefined : descriptors.find((d) => d.name === layerZeroName);
+	if (layerZeroName !== undefined && layerZero === undefined && options.layerZeroMustBeDeclared) {
+		fail("track_repair_track", `${source.path}.repairTrack`, `unknown FEC repair track ${JSON.stringify(layerZeroName)}`);
+	}
+	const dependents = descriptors.filter((d) => d.name !== layerZeroName && dependsTarget(d) === source.name);
+	const k = positiveInteger(source.sourceSymbols) ? source.sourceSymbols : 0;
+	// RFC 6330 bounds every RaptorQ source block, with or without a repair track.
+	if (source.algorithm === "raptorq" && k > MAX_RAPTORQ_SOURCE_SYMBOLS) {
+		fail(
+			"track_fec_bounds",
+			`${source.path}.sourceSymbols`,
+			`must be at most ${MAX_RAPTORQ_SOURCE_SYMBOLS} (RFC 6330 source block limit)`,
+		);
+	}
+	if (layerZeroName === undefined) {
+		if (dependents.length === 0) return undefined;
+		fail(
+			"track_repair_layer",
+			`${dependents[0]!.path}.depends`,
+			`repair layers of ${JSON.stringify(source.name)} require a layer 0 (fec.repairTrack) on the source`,
+		);
+	}
+
+	const layered = dependents.length > 0;
+	let layerZeroSymbols = 0;
+	if (positiveInteger(source.repairSymbols)) {
+		layerZeroSymbols = source.repairSymbols;
+	} else if (layered) {
+		fail("track_fec", `${source.path}.repairSymbols`, "layered or overlay repair needs a positive integer repairSymbols on layer 0");
+	}
+	if (layered && !positiveInteger(source.sourceSymbols)) {
+		fail("track_fec", `${source.path}.sourceSymbols`, "layered or overlay repair needs a positive integer sourceSymbols on the source");
+	}
+	if (layered && source.algorithm !== "raptorq") {
+		fail(
+			"track_fec",
+			`${source.path}.algorithm`,
+			"repair layers and overlays are defined only for raptorq: a block code fixes its codeword length, so symbols of a larger P are not symbols of the code a receiver holding fewer layers decodes",
+		);
+	}
+
+	let layerZeroPriority = DEFAULT_REPAIR_PRIORITY;
+	if (layerZero !== undefined) {
+		if (layerZero.depends !== undefined && dependsTarget(layerZero) !== source.name) {
+			fail(
+				"track_repair_depends",
+				`${layerZero.path}.depends`,
+				`layer 0 of ${JSON.stringify(source.name)} must depend on that source`,
+			);
+		}
+		if (layerZero.repairLayer !== undefined && layerZero.repairLayer !== 0) {
+			fail("track_repair_layer", `${layerZero.path}.repairLayer`, "the track named by fec.repairTrack is layer 0");
+		}
+		if (layerZero.scope !== undefined) {
+			fail("track_repair_overlay", `${layerZero.path}.scope`, "the track named by fec.repairTrack is base layer 0, not an overlay");
+		}
+		if (layerZero.repairSymbols !== undefined && layerZero.repairSymbols !== layerZeroSymbols) {
+			fail(
+				"track_repair_layer",
+				`${layerZero.path}.repairSymbols`,
+				`must agree with the source's fec.repairSymbols (${layerZeroSymbols})`,
+			);
+		}
+		if (typeof layerZero.priority === "number") layerZeroPriority = layerZero.priority;
+	}
+
+	const baseLayers: RepairLayerParams[] = [
+		{ layer: 0, repairTrackName: layerZeroName!, repairSymbols: layerZeroSymbols, rsIdOffset: 0, priority: layerZeroPriority },
+	];
+	// Clarification 7 fixes the wire: a RAP packet carries exactly two Source
+	// FEC Payload IDs, base first and overlay last, and the receiver strips a
+	// fixed trailer length. A second overlay would need a third trailer that
+	// the draft does not define, so one overlay per source is the contract.
+	const overlays: RepairOverlayParams[] = [];
+	for (const d of dependents) {
+		if (d.scope === undefined && d.repairLayer === undefined) {
+			fail(
+				"track_repair_layer",
+				`${d.path}.repairLayer`,
+				`a repair track that depends on ${JSON.stringify(source.name)} must declare repairLayer (1..n) or scope: "keyframe"`,
+			);
+		}
+	}
+	const layerTracks = dependents
+		.filter((d) => d.scope === undefined)
+		.sort((a, b) => (a.repairLayer as number) - (b.repairLayer as number));
+	for (const d of dependents) {
+		if (d.scope !== "keyframe") continue;
+		if (overlays.length === 1) {
+			fail(
+				"track_repair_overlay",
+				`${d.path}.scope`,
+				`${JSON.stringify(source.name)} already has keyframe overlay ${JSON.stringify(overlays[0]!.repairTrackName)}: a RAP packet carries exactly two Source FEC Payload IDs (base, then overlay), so one overlay per source`,
+			);
+		}
+		const sourceSymbols = d.sourceSymbols as number;
+		const repairSymbols = d.repairSymbols as number;
+		if (sourceSymbols + repairSymbols - 1 > MAX_ENCODING_SYMBOL_ID) {
+			fail(
+				"track_fec_bounds",
+				`${d.path}.repairSymbols`,
+				`overlay sourceSymbols + repairSymbols - 1 exceeds the 24-bit ESI space (${MAX_ENCODING_SYMBOL_ID})`,
+			);
+		}
+		overlays.push({ repairTrackName: d.name, scope: "keyframe", sourceSymbols, repairSymbols, priority: d.priority as number });
+	}
+
+	let offset = layerZeroSymbols;
+	let previousPriority = layerZeroPriority;
+	layerTracks.forEach((d, i) => {
+		const expected = i + 1;
+		if (d.repairLayer === 0) {
+			fail("track_repair_layer", `${d.path}.repairLayer`, `layer 0 of ${JSON.stringify(source.name)} is ${JSON.stringify(layerZeroName)}, named by fec.repairTrack`);
+		}
+		if (d.repairLayer !== expected) {
+			fail(
+				"track_repair_layer",
+				`${d.path}.repairLayer`,
+				i > 0 && d.repairLayer === layerTracks[i - 1]!.repairLayer
+					? `repair layer ${d.repairLayer} is declared twice for ${JSON.stringify(source.name)}`
+					: `repair layers must be contiguous from 1: expected ${expected}, found ${d.repairLayer}`,
+			);
+		}
+		const priority = d.priority as number;
+		if (priority < previousPriority) {
+			fail(
+				"track_repair_priority",
+				`${d.path}.priority`,
+				`must be at least ${previousPriority}, the priority of layer ${expected - 1}: priority is monotonic non-decreasing with layer index`,
+			);
+		}
+		previousPriority = priority;
+		const repairSymbols = d.repairSymbols as number;
+		baseLayers.push({ layer: expected, repairTrackName: d.name, repairSymbols, rsIdOffset: offset, priority });
+		offset += repairSymbols;
+	});
+
+	const totalBaseRepairSymbols = offset;
+	if (totalBaseRepairSymbols > MAX_REPAIR_SYMBOLS) {
+		fail(
+			"track_fec_bounds",
+			`${layerTracks.length === 0 ? source.path : layerTracks[layerTracks.length - 1]!.path}.repairSymbols`,
+			`total repair symbols across base layers exceeds the 24-bit RS_ID space (${MAX_REPAIR_SYMBOLS})`,
+		);
+	}
+	if (k + totalBaseRepairSymbols - 1 > MAX_ENCODING_SYMBOL_ID) {
+		fail(
+			"track_fec_bounds",
+			`${source.path}.sourceSymbols`,
+			`sourceSymbols + total base repair symbols - 1 exceeds the 24-bit ESI space (${MAX_ENCODING_SYMBOL_ID})`,
+		);
+	}
+
+	return { sourceTrackName: source.name, baseLayers, overlays, totalBaseRepairSymbols };
+}