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

package/src/multicast-input.ts

@@ -0,0 +1,439 @@
+// Module-local ambient: `multicastFromEnv` reads `process.env` when present
+// (Node, FFI host) and falls back to `{}` in browser contexts. The package
+// targets both, so we don't pull in `@types/node` org-wide — declaring the
+// minimal surface we touch keeps the dependency graph tight and the
+// published .d.ts free of node-isms.
+declare const process: { env: Record<string, string | undefined> } | undefined;
+
+/**
+ * Multicast catalog input contract — validator + builder.
+ *
+ * Per draft-ramadan-moq-multicast-00 §3 + §4.1, the publisher (FFmpeg,
+ * cast bridge, GStreamer, OBS-bridge) populates `multicast.endpoints[]`
+ * in the catalog when its output includes a UDP multicast destination.
+ *
+ * This module is the TypeScript-side validator over a versioned input
+ * shape. Sister-language validators (FFmpeg C, cast Rust) target the
+ * same invariants — eventually via a shared JSON Schema + fixtures
+ * (BLO-3341 follow-up); today parity is enforced by code review against
+ * 1:1 ports. Each publisher's integration MUST also assert that the
+ * declared `(sourceAddress, groupAddress, port)` matches what it
+ * actually emits — that's a separate runtime check the helper cannot
+ * perform.
+ *
+ * Validation invariants (per codex review of BLO-3323 v2):
+ *   - protocol === 'ssm' → sourceAddress REQUIRED
+ *   - protocol === 'amt' → relayAddress REQUIRED
+ *   - groupAddress is a valid IPv4 multicast group (224.0.0.0/4)
+ *     or IPv6 multicast group (ff00::/8)
+ *   - SSM groupAddress MUST be in 232.0.0.0/8 (IPv4) or ff3x::/32 (IPv6),
+ *     where the IPv6 form requires P=1 + T=1 (the `3` nibble) AND the
+ *     16-bit reserved-zero second hextet per RFC 3306 §4 / RFC 4607.
+ *   - port in 1..65535
+ *   - tracks non-empty; per-track packetId in 0..65535
+ *   - packetIds unique within an endpoint
+ *   - (sourceAddress, groupAddress, port) tuple unique across endpoints
+ *   - bandwidth (if present) > 0
+ *   - validUntil (if present) is a positive unix-ms timestamp
+ *
+ * @see draft-ramadan-moq-multicast-00 §4.1
+ * @see .planning/drafts/blo-3323-multicast-catalog-source-of-truth.md
+ */
+
+import {
+	type AmtDiscovery,
+	type MulticastCatalogConfig,
+	type MulticastEndpoint,
+	type MulticastProtocol,
+	type MulticastTrackObject,
+} from "./carp-catalog.js";
+
+/**
+ * Strict typed input for one multicast endpoint. The publisher provides
+ * this shape (env vars / CLI / config record), the helper validates and
+ * lifts it into a `MulticastEndpoint` ready to embed in the catalog.
+ */
+export interface MulticastEndpointInput {
+	readonly protocol: MulticastProtocol;
+	readonly sourceAddress?: string;
+	readonly groupAddress: string;
+	readonly port: number;
+	/** New emitters MUST use the object form (name + packetId). */
+	readonly tracks: ReadonlyArray<MulticastTrackObject>;
+	readonly relayAddress?: string;
+	/** Aggregate bandwidth in bits per second. RECOMMENDED per draft §4.1. */
+	readonly bandwidth?: number;
+}
+
+/**
+ * Strict typed input for the catalog-level multicast extension.
+ *
+ * `version` (monotonic) + `validUntil` (unix ms) support the catalog
+ * freshness model: subscribers refetch before expiry, and publishers
+ * MUST republish (with bumped `version`) on any endpoint mutation.
+ */
+export interface MulticastInput {
+	readonly enabled?: boolean;
+	readonly endpoints: ReadonlyArray<MulticastEndpointInput>;
+	readonly amtFallback?: { readonly discovery: AmtDiscovery; readonly relayDns?: string };
+	readonly version?: number;
+	readonly validUntil?: number;
+}
+
+export type MulticastInputErrorKind =
+	| "empty_endpoints"
+	| "ssm_requires_source"
+	| "amt_requires_relay"
+	| "invalid_group_address"
+	| "ssm_group_out_of_range"
+	| "invalid_port"
+	| "empty_tracks"
+	| "invalid_track_name"
+	| "invalid_packet_id"
+	| "duplicate_packet_id"
+	| "duplicate_endpoint_tuple"
+	| "invalid_bandwidth"
+	| "invalid_valid_until"
+	| "invalid_version"
+	| "invalid_env_shape";
+
+export class MulticastInputError extends Error {
+	constructor(
+		public readonly kind: MulticastInputErrorKind,
+		public readonly endpointIndex: number | null,
+		message: string,
+	) {
+		super(message);
+		this.name = "MulticastInputError";
+	}
+}
+
+/**
+ * Validate a typed publisher input and lift it into a
+ * `MulticastCatalogConfig` ready for `catalog.multicast = …`.
+ *
+ * Throws `MulticastInputError` on any invariant violation. Fail-fast
+ * at config-load time, never at runtime — silent fallbacks hide bugs
+ * upstream (per the project's "no anti-patterns" directive).
+ */
+export function multicastFromConfig(input: MulticastInput): MulticastCatalogConfig {
+	if (input.endpoints.length === 0) {
+		throw new MulticastInputError(
+			"empty_endpoints",
+			null,
+			"endpoints[] must be non-empty — a multicast field with zero endpoints declares nothing",
+		);
+	}
+	if (input.version !== undefined && (!Number.isInteger(input.version) || input.version < 0)) {
+		throw new MulticastInputError("invalid_version", null, `version must be a non-negative integer; got ${input.version}`);
+	}
+	if (input.validUntil !== undefined) {
+		if (!Number.isFinite(input.validUntil) || input.validUntil <= 0) {
+			throw new MulticastInputError(
+				"invalid_valid_until",
+				null,
+				`validUntil must be a positive unix-ms timestamp; got ${input.validUntil}`,
+			);
+		}
+	}
+
+	const seenTuples = new Set<string>();
+	const endpoints: MulticastEndpoint[] = input.endpoints.map((ep, idx) => validateEndpoint(ep, idx, seenTuples));
+
+	const out: MulticastCatalogConfig = { endpoints };
+	if (input.enabled !== undefined) out.enabled = input.enabled;
+	if (input.amtFallback !== undefined) out.amtFallback = { ...input.amtFallback };
+	if (input.version !== undefined) out.version = input.version;
+	if (input.validUntil !== undefined) out.validUntil = input.validUntil;
+	return out;
+}
+
+function validateEndpoint(
+	ep: MulticastEndpointInput,
+	idx: number,
+	seenTuples: Set<string>,
+): MulticastEndpoint {
+	if (ep.protocol === "ssm" && (!ep.sourceAddress || ep.sourceAddress.length === 0)) {
+		throw new MulticastInputError(
+			"ssm_requires_source",
+			idx,
+			`endpoint[${idx}] protocol=ssm requires sourceAddress`,
+		);
+	}
+	if (ep.protocol === "amt" && (!ep.relayAddress || ep.relayAddress.length === 0)) {
+		throw new MulticastInputError(
+			"amt_requires_relay",
+			idx,
+			`endpoint[${idx}] protocol=amt requires relayAddress`,
+		);
+	}
+
+	if (!isMulticastGroupAddress(ep.groupAddress)) {
+		throw new MulticastInputError(
+			"invalid_group_address",
+			idx,
+			`endpoint[${idx}] groupAddress "${ep.groupAddress}" is not a valid multicast address`,
+		);
+	}
+	if (ep.protocol === "ssm" && !isSsmGroupAddress(ep.groupAddress)) {
+		throw new MulticastInputError(
+			"ssm_group_out_of_range",
+			idx,
+			`endpoint[${idx}] protocol=ssm requires groupAddress in 232.0.0.0/8 (IPv4) or ff3x::/32 (IPv6); got "${ep.groupAddress}"`,
+		);
+	}
+
+	if (!Number.isInteger(ep.port) || ep.port < 1 || ep.port > 65535) {
+		throw new MulticastInputError("invalid_port", idx, `endpoint[${idx}] port must be 1..65535; got ${ep.port}`);
+	}
+
+	if (ep.tracks.length === 0) {
+		throw new MulticastInputError("empty_tracks", idx, `endpoint[${idx}] tracks must be non-empty`);
+	}
+
+	const seenPids = new Set<number>();
+	for (const t of ep.tracks) {
+		if (typeof t.name !== "string" || t.name.length === 0) {
+			throw new MulticastInputError(
+				"invalid_track_name",
+				idx,
+				`endpoint[${idx}] track name must be a non-empty string`,
+			);
+		}
+		if (!Number.isInteger(t.packetId) || t.packetId < 0 || t.packetId > 65535) {
+			throw new MulticastInputError(
+				"invalid_packet_id",
+				idx,
+				`endpoint[${idx}] track "${t.name}" packetId must be 0..65535; got ${t.packetId}`,
+			);
+		}
+		if (seenPids.has(t.packetId)) {
+			throw new MulticastInputError(
+				"duplicate_packet_id",
+				idx,
+				`endpoint[${idx}] duplicate packetId ${t.packetId}`,
+			);
+		}
+		seenPids.add(t.packetId);
+	}
+
+	if (ep.bandwidth !== undefined && (!Number.isFinite(ep.bandwidth) || ep.bandwidth <= 0)) {
+		throw new MulticastInputError(
+			"invalid_bandwidth",
+			idx,
+			`endpoint[${idx}] bandwidth must be positive; got ${ep.bandwidth}`,
+		);
+	}
+
+	const tupleKey = `${ep.sourceAddress ?? ""}|${ep.groupAddress}|${ep.port}`;
+	if (seenTuples.has(tupleKey)) {
+		throw new MulticastInputError(
+			"duplicate_endpoint_tuple",
+			idx,
+			`endpoint[${idx}] duplicates (sourceAddress, groupAddress, port) tuple "${tupleKey}"`,
+		);
+	}
+	seenTuples.add(tupleKey);
+
+	const out: MulticastEndpoint = {
+		protocol: ep.protocol,
+		groupAddress: ep.groupAddress,
+		port: ep.port,
+		tracks: ep.tracks.map((t) => ({ name: t.name, packetId: t.packetId })),
+	};
+	if (ep.sourceAddress !== undefined) out.sourceAddress = ep.sourceAddress;
+	if (ep.relayAddress !== undefined) out.relayAddress = ep.relayAddress;
+	if (ep.bandwidth !== undefined) out.bandwidth = ep.bandwidth;
+	return out;
+}
+
+function isMulticastGroupAddress(addr: string): boolean {
+	if (addr.includes(":")) {
+		// IPv6: ff00::/8. Prefix-only check; full IPv6 syntax validation
+		// is delegated to the OS bind() call downstream.
+		return /^ff[0-9a-f]{2}:/i.test(addr);
+	}
+	const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(addr);
+	if (!m) return false;
+	for (let i = 1; i <= 4; i++) {
+		const v = Number(m[i]);
+		if (!Number.isInteger(v) || v < 0 || v > 255) return false;
+	}
+	const first = Number(m[1]);
+	return first >= 224 && first <= 239;
+}
+
+function isSsmGroupAddress(addr: string): boolean {
+	if (addr.includes(":")) {
+		// SSM IPv6: ff3x::/32 per RFC 3306 §4. Requires P=1 + T=1 (the `3`
+		// nibble) AND the second 16-bit hextet to be all-zero (RFC 3306's
+		// "prefix length = 0" → next 32 bits are 0). The regex matches
+		// `ff3?:0000:` collapsed forms (`ff3e::`, `ff3e:0::`, `ff3e:0:`,
+		// `ff3e:0000:`) and rejects `ff3e:beef::1` etc.
+		return /^ff3[0-9a-f]:0{0,4}:/i.test(addr);
+	}
+	const m = /^(\d{1,3})\./.exec(addr);
+	return m !== null && Number(m[1]) === 232;
+}
+
+// Env-var helper (BLO-3337): read MOQCAST_MULTICAST_* keys and route
+// through multicastFromConfig so all per-endpoint invariants apply.
+
+/**
+ * Read `MOQCAST_MULTICAST_*` env vars and return a
+ * `MulticastCatalogConfig`. Returns `undefined` when no per-endpoint
+ * key is set.
+ *
+ * Env contract — per-endpoint keys take an optional non-negative index:
+ *
+ *   MOQCAST_MULTICAST[_<idx>]_PROTOCOL=ssm
+ *   MOQCAST_MULTICAST[_<idx>]_GROUP=232.1.1.1
+ *   MOQCAST_MULTICAST[_<idx>]_PORT=5004
+ *   MOQCAST_MULTICAST[_<idx>]_SOURCE=10.0.0.20      (required for ssm)
+ *   MOQCAST_MULTICAST[_<idx>]_RELAY=amt.example.com (required for amt)
+ *   MOQCAST_MULTICAST[_<idx>]_TRACKS=video:1,audio:3
+ *   MOQCAST_MULTICAST[_<idx>]_BANDWIDTH=8000000     (optional, bps)
+ *
+ *   MOQCAST_MULTICAST_AMT_DISCOVERY=driad           (catalog-level)
+ *   MOQCAST_MULTICAST_AMT_RELAY_DNS=relay.example.com (catalog-level)
+ *
+ * The unindexed form (`MOQCAST_MULTICAST_GROUP`) is exactly index 0;
+ * mixing it with explicit `_0_` keys is rejected as ambiguous. Indices
+ * need not be contiguous; observed indices are sorted ascending.
+ */
+export function multicastFromEnv(
+	env: Record<string, string | undefined> = ((globalThis as { process?: { env?: Record<string, string | undefined> } })
+		.process?.env ?? {}) as Record<string, string | undefined>,
+): MulticastCatalogConfig | undefined {
+	const indices = collectMulticastIndices(env);
+	if (indices.length === 0) {
+		// Catalog-level AMT keys without per-endpoint keys is a
+		// misconfiguration, not a no-op: `MOQCAST_MULTICAST_AMT_DISCOVERY`
+		// only makes sense alongside endpoints to fall back FOR. Throw
+		// loudly instead of silently dropping the request — a publisher
+		// that meant to declare AMT fallback shouldn't have its config
+		// disappear without any signal.
+		const strayCatalog = env["MOQCAST_MULTICAST_AMT_DISCOVERY"] !== undefined
+			|| env["MOQCAST_MULTICAST_AMT_RELAY_DNS"] !== undefined;
+		if (strayCatalog) {
+			throw new MulticastInputError(
+				"invalid_env_shape",
+				null,
+				"MOQCAST_MULTICAST_AMT_* env keys are set but no per-endpoint keys " +
+					"(MOQCAST_MULTICAST_GROUP / _PROTOCOL / _PORT / _TRACKS) were found. " +
+					"AMT discovery is a catalog-level fallback for endpoints; declaring it " +
+					"with zero endpoints is a misconfiguration.",
+			);
+		}
+		return undefined;
+	}
+
+	const endpoints: MulticastEndpointInput[] = indices.map((idx) => readEndpointAt(env, idx));
+
+	const input: MulticastInput = {
+		endpoints,
+		...(env["MOQCAST_MULTICAST_AMT_DISCOVERY"]
+			? {
+					amtFallback: {
+						discovery: env["MOQCAST_MULTICAST_AMT_DISCOVERY"] as AmtDiscovery,
+						...(env["MOQCAST_MULTICAST_AMT_RELAY_DNS"]
+							? { relayDns: env["MOQCAST_MULTICAST_AMT_RELAY_DNS"] }
+							: {}),
+					},
+				}
+			: {}),
+	};
+	return multicastFromConfig(input);
+}
+
+const ENV_PER_FIELD = ["PROTOCOL", "GROUP", "PORT", "SOURCE", "RELAY", "TRACKS", "BANDWIDTH"];
+const ENV_CATALOG_LEVEL = new Set(["AMT_DISCOVERY", "AMT_RELAY_DNS"]);
+
+function collectMulticastIndices(env: Record<string, string | undefined>): number[] {
+	const indices = new Set<number>();
+	let hasUnindexed = false;
+	let hasZeroIndexed = false;
+
+	for (const [key, val] of Object.entries(env)) {
+		if (val === undefined) continue;
+		if (!key.startsWith("MOQCAST_MULTICAST_")) continue;
+		const suffix = key.slice("MOQCAST_MULTICAST_".length);
+		if (ENV_CATALOG_LEVEL.has(suffix)) continue;
+
+		const m = /^(\d+)_(.+)$/.exec(suffix);
+		if (m) {
+			const idx = Number(m[1]);
+			const field = m[2];
+			if (!ENV_PER_FIELD.includes(field)) continue;
+			if (idx === 0) hasZeroIndexed = true;
+			indices.add(idx);
+		} else if (ENV_PER_FIELD.includes(suffix)) {
+			hasUnindexed = true;
+			indices.add(0);
+		}
+	}
+
+	if (hasUnindexed && hasZeroIndexed) {
+		throw new MulticastInputError(
+			"invalid_env_shape",
+			null,
+			"MOQCAST_MULTICAST_* env contract: cannot mix unindexed keys (MOQCAST_MULTICAST_GROUP) " +
+				"with explicitly-indexed keys at index 0 (MOQCAST_MULTICAST_0_GROUP) — they refer to " +
+				"the same endpoint. Use one form consistently.",
+		);
+	}
+
+	return [...indices].sort((a, b) => a - b);
+}
+
+function readEndpointAt(env: Record<string, string | undefined>, idx: number): MulticastEndpointInput {
+	const lookup = (field: string): string | undefined => {
+		if (idx === 0) {
+			return env[`MOQCAST_MULTICAST_${field}`] ?? env[`MOQCAST_MULTICAST_0_${field}`];
+		}
+		return env[`MOQCAST_MULTICAST_${idx}_${field}`];
+	};
+
+	const portStr = lookup("PORT");
+	const port = portStr !== undefined ? Number(portStr) : NaN;
+	const tracks = parseTracksEnv(lookup("TRACKS"), idx);
+	const bandwidthStr = lookup("BANDWIDTH");
+	const bandwidth = bandwidthStr !== undefined ? Number(bandwidthStr) : undefined;
+	const source = lookup("SOURCE");
+	const relay = lookup("RELAY");
+
+	return {
+		protocol: lookup("PROTOCOL") as MulticastProtocol,
+		groupAddress: lookup("GROUP") ?? "",
+		port,
+		tracks,
+		...(source ? { sourceAddress: source } : {}),
+		...(relay ? { relayAddress: relay } : {}),
+		...(bandwidth !== undefined ? { bandwidth } : {}),
+	};
+}
+
+function parseTracksEnv(raw: string | undefined, endpointIdx: number): MulticastTrackObject[] {
+	if (!raw || raw.length === 0) return [];
+	return raw.split(",").map((entry, i) => {
+		const colon = entry.lastIndexOf(":");
+		if (colon < 0) {
+			throw new MulticastInputError(
+				"invalid_track_name",
+				endpointIdx,
+				`endpoint[${endpointIdx}] TRACKS[${i}] missing ":" — expected "name:packetId", got ${JSON.stringify(entry)}`,
+			);
+		}
+		const name = entry.slice(0, colon).trim();
+		const idStr = entry.slice(colon + 1).trim();
+		const packetId = Number(idStr);
+		if (!name || idStr.length === 0 || !Number.isFinite(packetId) || !Number.isInteger(packetId)) {
+			throw new MulticastInputError(
+				"invalid_packet_id",
+				endpointIdx,
+				`endpoint[${endpointIdx}] TRACKS[${i}] entry malformed (need "name:integer"): ${JSON.stringify(entry)}`,
+			);
+		}
+		return { name, packetId };
+	});
+}