@blockcast/mmt-container 0.1.0 → 0.3.0-main.0bde85f7082f

package/src/catalog-network-source.ts

@@ -0,0 +1,74 @@
+// Catalog → AMT relay discovery (multicast.networkSource).
+//
+// Shared by every player (moq-lib/hang, moqtail, shaka MSF) so networkSource
+// interpretation lives in one place — players keep only wiring, not
+// MMT/catalog semantics.
+//
+// draft-ramadan-moq-multicast §4.1 carries relay discovery as
+// `multicast.networkSource`. Publishers emit the canonical ARRAY form
+// (hang-rs `Option<Vec<NetworkSource>>`; cast's bridge + ladder catalogs), but
+// hang's zod RootSchema also accepts a bare object and older hand-authored
+// catalogs used it — consume both.
+
+import { DEFAULT_AMT_RELAY_PORT } from "@blockcast/mmt-base";
+
+/** One `networkSource[]` entry as published (`{type, discovery?, relay, port?}`). */
+export type CatalogNetworkSource = {
+	type?: string;
+	/** `"manual"` (or absent) names a dialable relay; `"driad"` resolves at runtime. */
+	discovery?: string;
+	relay?: string;
+	port?: number;
+};
+
+/** Resolved AMT relay a player can hand to its multicast join/subscribe. */
+export type AmtNetworkSource = {
+	relay: string;
+	/** Always resolved: `DEFAULT_AMT_RELAY_PORT` when the catalog names none. */
+	port: number;
+};
+
+/**
+ * AMT well-known UDP port (RFC 7450 §4).
+ *
+ * Re-exported so `networkSource` consumers get it from the module that owns
+ * those semantics; the definition lives in `@blockcast/mmt-base` so transport
+ * and container cannot drift.
+ */
+export { DEFAULT_AMT_RELAY_PORT };
+
+function normalizePort(value: unknown): number | undefined {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	return Number.isInteger(n) && n > 0 && n <= 65535 ? n : undefined;
+}
+
+/**
+ * Resolve the AMT relay from a catalog `multicast` block's `networkSource`
+ * (array or bare-object form). Returns the first entry with `type: "amt"`
+ * and a non-blank relay, or `undefined` when the catalog advertises none —
+ * callers fall back to native multicast (or their own explicit relay config).
+ *
+ * A `discovery: "driad"` entry is skipped even when it names a `relay`: that
+ * string is the `_amt._udp` DNS name a runtime RFC 8777 lookup resolves, not
+ * an address to dial, and the emitter derives exactly that shape from
+ * `amtFallback: {discovery: "driad", relayDns}`. Returning it would turn a
+ * catalog that asked for DRIAD into a manual join against an unroutable name.
+ * `findAmtRelay` in `@blockcast/mmt-transport` applies the same rule — the two
+ * readers of one field must agree on which entries are dialable.
+ *
+ * `port` is always resolved: an entry that names none, or names an unusable
+ * one, gets `DEFAULT_AMT_RELAY_PORT`.
+ */
+export function catalogAmtNetworkSource(networkSource: unknown): AmtNetworkSource | undefined {
+	const entries = Array.isArray(networkSource) ? networkSource : networkSource ? [networkSource] : [];
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const ns = raw as CatalogNetworkSource;
+		if (ns.type !== "amt") continue;
+		if (ns.discovery === "driad") continue;
+		const relay = typeof ns.relay === "string" ? ns.relay.trim() : "";
+		if (!relay) continue;
+		return { relay, port: normalizePort(ns.port) ?? DEFAULT_AMT_RELAY_PORT };
+	}
+	return undefined;
+}

package/src/catalog-validator.ts

@@ -0,0 +1,34 @@
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { hasUniqueMulticastAuthTrackBindings } from './multicast-auth-catalog.js'
+
+export interface CatalogSchemaValidationError {
+  instancePath: string
+  schemaPath: string
+  keyword: string
+  params: Record<string, unknown>
+  message?: string
+}
+
+export interface CatalogSchemaValidator {
+  (catalog: unknown): boolean
+  errors: CatalogSchemaValidationError[] | null
+}
+
+/**
+ * Compile the published catalog schema with every package-defined semantic
+ * keyword installed. Consumers must use this entry point instead of compiling
+ * `catalog.schema.json` with a bare JSON Schema validator.
+ */
+export function createCatalogSchemaValidator(schema: object): CatalogSchemaValidator {
+  const ajv = new Ajv2020({ allErrors: true, strict: true })
+  addFormats(ajv)
+  ajv.addKeyword({
+    keyword: 'uniqueMulticastAuthTrackBindings',
+    type: 'array',
+    schemaType: 'boolean',
+    validate: (enabled: boolean, tracks: unknown[]) =>
+      !enabled || hasUniqueMulticastAuthTrackBindings(tracks),
+  })
+  return ajv.compile(schema) as CatalogSchemaValidator
+}