@blockcast/mmt-transport 0.2.0 → 0.2.2

package/src/multicast-tier.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { MulticastOrchestrator } from "./multicast-orchestrator.js";
+import { endpointKey, selectMulticastTier, type MulticastTierEndpoint } from "./multicast-tier.js";
+
+const low: MulticastTierEndpoint = {
+	groupAddress: "232.1.1.1", port: 5000, tracks: [{ name: "video/720p" }], bandwidth: 2_000_000,
+};
+const high: MulticastTierEndpoint = {
+	groupAddress: "232.1.1.2", port: 5000, tracks: [{ name: "video/4k" }], bandwidth: 15_000_000,
+};
+
+describe("multicast tier selection", () => {
+	it("starts conservatively and applies headroom", () => {
+		expect(selectMulticastTier([high, low], undefined)).toBe(low);
+		expect(selectMulticastTier([low, high], 16_000_000)).toBe(low);
+		expect(selectMulticastTier([low, high], 20_000_000)).toBe(high);
+	});
+
+	it("switches make-before-break only on a valid target RAP", () => {
+		let now = 0;
+		const orchestrator = new MulticastOrchestrator({
+			endpoints: [low, high], now: () => now, dwellMs: 1000, joinDeadlineMs: 5000,
+		});
+		expect(orchestrator.start()).toBe(low);
+		expect(orchestrator.onGoodput({ bitrate: 20_000_000 })).toBeUndefined();
+		now = 1000;
+		expect(orchestrator.onGoodput({ bitrate: 20_000_000 })?.kind).toBe("join-target");
+		expect(orchestrator.onTierPacket({
+			endpointKey: endpointKey(high), keyframe: false, timestamp: 10, hasValidCodecConfig: true,
+		})).toBeUndefined();
+		expect(orchestrator.onTierPacket({
+			endpointKey: endpointKey(high), keyframe: true, timestamp: 11, hasValidCodecConfig: true,
+		})?.kind).toBe("commit-swap");
+	});
+
+	it("preserves a pinned initial tier", () => {
+		let now = 0;
+		const orchestrator = new MulticastOrchestrator({
+			endpoints: [low, high], initialEndpoint: high, adaptive: false,
+			now: () => now, dwellMs: 1000, joinDeadlineMs: 5000,
+		});
+		expect(orchestrator.start()).toBe(high);
+		expect(orchestrator.onGoodput({ bitrate: 1_000_000 })).toBeUndefined();
+		now = 10_000;
+		expect(orchestrator.onGoodput({ bitrate: 1_000_000 })).toBeUndefined();
+		expect(orchestrator.current).toBe(high);
+	});
+
+	it("abandons a silent target when polled after the join deadline", () => {
+		let now = 0;
+		const orchestrator = new MulticastOrchestrator({
+			endpoints: [low, high], now: () => now, dwellMs: 1000, joinDeadlineMs: 5000,
+		});
+		orchestrator.start();
+		orchestrator.onGoodput({ bitrate: 20_000_000 });
+		now = 1000;
+		orchestrator.onGoodput({ bitrate: 20_000_000 });
+		now = 6000;
+		expect(orchestrator.poll()?.kind).toBe("abandon-join");
+		expect(orchestrator.state).toBe("stable");
+	});
+
+	it("rejects a target RAP older than the active tier high-water mark", () => {
+		let now = 0;
+		const orchestrator = new MulticastOrchestrator({
+			endpoints: [low, high], now: () => now, dwellMs: 1000, joinDeadlineMs: 5000,
+		});
+		orchestrator.start();
+		orchestrator.onTierPacket({
+			endpointKey: endpointKey(low), keyframe: false, timestamp: 10_000, hasValidCodecConfig: true,
+		});
+		orchestrator.onGoodput({ bitrate: 20_000_000 });
+		now = 1000;
+		orchestrator.onGoodput({ bitrate: 20_000_000 });
+		expect(orchestrator.onTierPacket({
+			endpointKey: endpointKey(high), keyframe: true, timestamp: 9_000, hasValidCodecConfig: true,
+		})).toBeUndefined();
+		expect(orchestrator.state).toBe("joining");
+	});
+});

package/src/multicast-tier.ts

@@ -0,0 +1,32 @@
+export interface MulticastTierEndpoint {
+	sourceAddress?: string;
+	groupAddress: string;
+	port: number;
+	tracks: { name: string; packetId?: number }[];
+	bandwidth?: number;
+	protocol?: string;
+}
+
+export function endpointKey(endpoint: MulticastTierEndpoint): string {
+	return `${endpoint.sourceAddress ?? ""}|${endpoint.groupAddress}|${endpoint.port}`;
+}
+
+export function selectMulticastTier(
+	endpoints: readonly MulticastTierEndpoint[],
+	estimate: number | undefined,
+): MulticastTierEndpoint | undefined {
+	if (endpoints.length <= 1) return endpoints[0];
+
+	const ranked = endpoints
+		.filter((endpoint) => typeof endpoint.bandwidth === "number" && endpoint.bandwidth > 0)
+		.sort((a, b) => a.bandwidth! - b.bandwidth!);
+	if (ranked.length < 2) return endpoints[0];
+	if (estimate === undefined) return ranked[0];
+
+	const budget = estimate * 0.8;
+	let selected: MulticastTierEndpoint | undefined;
+	for (const endpoint of ranked) {
+		if (endpoint.bandwidth! <= budget) selected = endpoint;
+	}
+	return selected ?? ranked[0];
+}

package/src/no-modules.ts

@@ -0,0 +1,44 @@
+import { AdaptiveBitrateController } from "./abr-controller.js";
+import {
+	isMulticastExplicitlyDisabled,
+	isUsableMulticastEndpoint,
+	isValidMulticastGroupAddress,
+	multicastEndpointKey,
+	normalizeMulticastEndpoint,
+	readUrlMulticastConfig,
+} from "./endpoint-config.js";
+import { MulticastOrchestrator } from "./multicast-orchestrator.js";
+import { MulticastSubscriptionPool } from "./multicast-subscription-pool.js";
+import { endpointKey, selectMulticastTier } from "./multicast-tier.js";
+import { TransportStallDetector } from "./stall-detector.js";
+import { makeSourceSwitchHandler, wireStarvationDetector } from "./takeover.js";
+import { TransportManager } from "./transport-manager.js";
+import { runUnicastFallback } from "./unicast-fallback.js";
+
+const api = {
+	AdaptiveBitrateController,
+	MulticastOrchestrator,
+	MulticastSubscriptionPool,
+	TransportManager,
+	TransportStallDetector,
+	endpointKey,
+	isMulticastExplicitlyDisabled,
+	isUsableMulticastEndpoint,
+	isValidMulticastGroupAddress,
+	makeSourceSwitchHandler,
+	multicastEndpointKey,
+	normalizeMulticastEndpoint,
+	readUrlMulticastConfig,
+	runUnicastFallback,
+	selectMulticastTier,
+	wireStarvationDetector,
+};
+
+Object.defineProperty(globalThis, "__MmtTransport", {
+	configurable: true,
+	enumerable: false,
+	writable: false,
+	value: Object.freeze(api),
+});
+
+export default api;

package/src/stall-detector.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import { TransportStallDetector } from "./stall-detector.js";
+
+describe("TransportStallDetector", () => {
+	it("detects repair-only starvation and recovery", () => {
+		let now = 0;
+		const onStarvation = vi.fn();
+		const onRecovery = vi.fn();
+		const detector = new TransportStallDetector({ windowMs: 1000, now: () => now, onStarvation, onRecovery });
+		detector.update({ sourceSymbols: 0, repairSymbols: 0, blocksComplete: 0, blocksRecovered: 0 });
+		now = 1000;
+		detector.update({ sourceSymbols: 0, repairSymbols: 10, blocksComplete: 0, blocksRecovered: 0 });
+		expect(onStarvation).toHaveBeenCalledOnce();
+		now = 1100;
+		detector.update({ sourceSymbols: 1, repairSymbols: 10, blocksComplete: 1, blocksRecovered: 0 });
+		expect(onRecovery).toHaveBeenCalledOnce();
+	});
+
+	it("detects starvation when all packet counters stop", () => {
+		let now = 0;
+		const onStarvation = vi.fn();
+		const detector = new TransportStallDetector({
+			windowMs: 1000,
+			now: () => now,
+			onStarvation,
+			onRecovery: vi.fn(),
+		});
+		const snapshot = { sourceSymbols: 10, repairSymbols: 2, blocksComplete: 1, blocksRecovered: 0 };
+		detector.update(snapshot);
+		now = 1000;
+		detector.update(snapshot);
+		expect(onStarvation).toHaveBeenCalledOnce();
+	});
+});

package/src/stall-detector.ts

@@ -0,0 +1,63 @@
+export interface FecProgressSnapshot {
+	sourceSymbols: number;
+	repairSymbols: number;
+	blocksComplete: number;
+	blocksRecovered: number;
+	mediaFrames?: number;
+}
+
+export interface StallDetectorConfig {
+	windowMs: number;
+	onStarvation(): void;
+	onRecovery(): void;
+	now?: () => number;
+}
+
+export class TransportStallDetector {
+	#last: FecProgressSnapshot | null = null;
+	#lastSampleAt = 0;
+	#starvedSince: number | null = null;
+	#latched = false;
+	readonly #now: () => number;
+
+	constructor(private readonly config: StallDetectorConfig) {
+		if (config.windowMs <= 0) throw new Error("Stall window must be positive and catalog-derived");
+		this.#now = config.now ?? Date.now;
+	}
+
+	get isStarved(): boolean { return this.#latched; }
+
+	update(snapshot: FecProgressSnapshot): void {
+		const previous = this.#last;
+		const previousAt = this.#lastSampleAt;
+		const now = this.#now();
+		this.#last = { ...snapshot };
+		this.#lastSampleAt = now;
+		if (!previous) return;
+
+		const blockDelta = snapshot.blocksComplete - previous.blocksComplete +
+			snapshot.blocksRecovered - previous.blocksRecovered;
+		const mediaDelta = (snapshot.mediaFrames ?? 0) - (previous.mediaFrames ?? 0);
+
+		if (blockDelta <= 0 && mediaDelta <= 0) {
+			this.#starvedSince ??= previousAt;
+			if (!this.#latched && now - this.#starvedSince >= this.config.windowMs) {
+				this.#latched = true;
+				this.config.onStarvation();
+			}
+			return;
+		}
+
+		this.#starvedSince = null;
+		if (this.#latched) {
+			this.#latched = false;
+			this.config.onRecovery();
+		}
+	}
+
+	reset(): void {
+		this.#last = null;
+		this.#starvedSince = null;
+		this.#latched = false;
+	}
+}

package/src/takeover.ts

@@ -0,0 +1,71 @@
+export interface ActivatableSessions { activateMulticast(): void; }
+
+export function makeSourceSwitchHandler(options: {
+	multicastBridgeAvailable: boolean;
+	sessionsReady: Promise<ActivatableSessions | null>;
+	onMulticastConfirmed?(): void;
+	onAbortTakeover?(): void;
+	log?(message: string): void;
+	warn?(message: string): void;
+}): (source: string) => Promise<void> {
+	const log = options.log ?? console.log;
+	const warn = options.warn ?? console.warn;
+	return async (source) => {
+		if (source !== "multicast") return;
+		if (!options.multicastBridgeAvailable) {
+			warn("[MoqWatch] MediaRouter requested multicast without bridge; keeping MoQ active");
+			return;
+		}
+		const sessions = await options.sessionsReady;
+		if (!sessions) {
+			warn("[MoqWatch] SessionManager unavailable; aborting multicast takeover, staying on MoQ");
+			options.onAbortTakeover?.();
+			return;
+		}
+		log("[MoqWatch] MediaRouter -> multicast; activating via SessionManager");
+		sessions.activateMulticast();
+		options.onMulticastConfirmed?.();
+	};
+}
+
+export interface LossArcSession { lossDetected(): void; lossRecovered(): void; }
+export interface FecStarvationSnapshot {
+	sourceSymbols: number;
+	repairSymbols: number;
+	blocksComplete: number;
+	blocksRecovered: number;
+	mediaFrames?: number;
+}
+export interface StarvationDetectorLike { update(snapshot: FecStarvationSnapshot): void; reset(): void; }
+export type StallDetectorLike = StarvationDetectorLike;
+
+export function wireStallDetector(args: {
+	session: LossArcSession | undefined;
+	windowMs: number;
+	makeDetector(config: { windowMs: number; onStarvation(): void; onRecovery(): void }): StallDetectorLike;
+}): StallDetectorLike | null {
+	if (!args.session || args.windowMs <= 0) return null;
+	return args.makeDetector({
+		windowMs: args.windowMs,
+		onStarvation: () => args.session!.lossDetected(),
+		onRecovery: () => args.session!.lossRecovered(),
+	});
+}
+
+export async function wireStarvationDetector(args: {
+	session: LossArcSession | undefined;
+	trackName: string;
+	fecInterleaveMs: number;
+	fecK: number;
+	makeDetector(config: { windowMs: number; onStarvation(): void; onRecovery(): void }): StarvationDetectorLike;
+	warn?(message: string): void;
+}): Promise<StarvationDetectorLike | null> {
+	if (!args.session || args.fecInterleaveMs <= 0 || args.fecK <= 0) return null;
+	const detector = wireStallDetector({
+		session: args.session,
+		windowMs: Math.ceil(args.fecInterleaveMs * 3),
+		makeDetector: args.makeDetector,
+	});
+	if (!detector) args.warn?.(`Unable to create starvation detector for ${args.trackName}`);
+	return detector;
+}

package/src/transport-manager.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { TransportManager } from "./transport-manager.js";
+import type {
+	TransportConfig,
+	WindowMulticastSubscriptionEventMap,
+} from "./types.js";
+
+const CONFIG: TransportConfig = {
+	group: "232.1.1.50",
+	source: "192.168.1.181",
+	port: 8000,
+	streamType: "video",
+	driadEnabled: false,
+};
+
+describe("TransportManager window.multicast integration", () => {
+	let hadWindow = false;
+	let previousWindow: unknown;
+
+	beforeEach(() => {
+		hadWindow = Object.hasOwn(globalThis, "window");
+		previousWindow = (globalThis as unknown as { window?: unknown })
+			.window;
+		vi.spyOn(console, "log").mockImplementation(() => {});
+		vi.spyOn(console, "warn").mockImplementation(() => {});
+		vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+
+	afterEach(() => {
+		if (hadWindow) {
+			(globalThis as unknown as { window?: unknown }).window =
+				previousWindow;
+		} else {
+			delete (globalThis as unknown as { window?: unknown }).window;
+		}
+		vi.restoreAllMocks();
+	});
+
+	it("does not treat legacy window.Multicast as a usable transport", async () => {
+		const subscribeSSM = vi.fn();
+		(globalThis as unknown as { window?: unknown }).window = {
+			Multicast: { subscribeSSM },
+		};
+
+		const manager = new TransportManager();
+		const connected = await manager.connect(CONFIG);
+
+		expect(connected).toBe(false);
+		expect(subscribeSSM).not.toHaveBeenCalled();
+	});
+
+	it("subscribes through lowercase window.multicast and forwards bytes", async () => {
+		const listeners = new Map<
+			keyof WindowMulticastSubscriptionEventMap,
+			(event: CustomEvent<unknown>) => void
+		>();
+		const subscription = {
+			id: "sub-1",
+			addEventListener: vi.fn((type, listener) => {
+				listeners.set(
+					type as keyof WindowMulticastSubscriptionEventMap,
+					listener as (event: CustomEvent<unknown>) => void,
+				);
+			}),
+			removeEventListener: vi.fn(),
+			unsubscribe: vi.fn().mockResolvedValue(undefined),
+		};
+		const subscribe = vi.fn().mockResolvedValue(subscription);
+		(globalThis as unknown as { window?: unknown }).window = {
+			multicast: {
+				capabilities: { consumeModes: ["bytes"] },
+				subscribe,
+			},
+		};
+
+		const manager = new TransportManager();
+		const onPacket = vi.fn();
+		manager.setPacketCallback(onPacket);
+
+		const connected = await manager.connect(CONFIG);
+		expect(connected).toBe(true);
+		expect(subscribe).toHaveBeenCalledWith({
+			group: CONFIG.group,
+			source: CONFIG.source,
+			port: CONFIG.port,
+			consume: "bytes",
+		});
+
+		const payload = new Uint8Array([1, 2, 3]).buffer;
+		listeners.get("bytes")?.({ detail: payload } as CustomEvent<unknown>);
+
+		expect(onPacket).toHaveBeenCalledWith(payload);
+		expect(manager.getState().packetsReceived).toBe(1);
+		expect(manager.getState().bytesReceived).toBe(3);
+		manager.disconnect();
+	});
+
+	it("releases the previous lease before reconnecting", async () => {
+		const unsubscribe = vi.fn();
+		const subscription = {
+			addEventListener: vi.fn(), removeEventListener: vi.fn(), unsubscribe,
+		};
+		const subscribe = vi.fn().mockResolvedValue(subscription);
+		(globalThis as unknown as { window?: unknown }).window = {
+			multicast: { capabilities: { consumeModes: ["bytes"] }, subscribe },
+		};
+		const manager = new TransportManager();
+		expect(await manager.connect(CONFIG)).toBe(true);
+		expect(await manager.connect(CONFIG)).toBe(true);
+		expect(unsubscribe).toHaveBeenCalledOnce();
+		manager.disconnect();
+		expect(unsubscribe).toHaveBeenCalledTimes(2);
+	});
+
+	it("releases a stale lease when connect calls overlap", async () => {
+		let resolveSubscription!: (subscription: {
+			addEventListener: ReturnType<typeof vi.fn>;
+			removeEventListener: ReturnType<typeof vi.fn>;
+			unsubscribe: ReturnType<typeof vi.fn>;
+		}) => void;
+		const unsubscribe = vi.fn();
+		const subscribe = vi.fn().mockReturnValue(new Promise((resolve) => {
+			resolveSubscription = resolve;
+		}));
+		(globalThis as unknown as { window?: unknown }).window = {
+			multicast: { capabilities: { consumeModes: ["bytes"] }, subscribe },
+		};
+		const manager = new TransportManager();
+		const first = manager.connect(CONFIG);
+		await vi.waitFor(() => expect(subscribe).toHaveBeenCalledOnce());
+		const second = manager.connect(CONFIG);
+		resolveSubscription({ addEventListener: vi.fn(), removeEventListener: vi.fn(), unsubscribe });
+
+		expect(await Promise.all([first, second])).toEqual([false, true]);
+		expect(subscribe).toHaveBeenCalledOnce();
+		manager.disconnect();
+		expect(unsubscribe).toHaveBeenCalledOnce();
+	});
+
+	it("does not publish a connection completed after disconnect", async () => {
+		let resolveSubscription!: (subscription: {
+			addEventListener: ReturnType<typeof vi.fn>;
+			removeEventListener: ReturnType<typeof vi.fn>;
+			unsubscribe: ReturnType<typeof vi.fn>;
+		}) => void;
+		const unsubscribe = vi.fn();
+		const subscribe = vi.fn().mockReturnValue(new Promise((resolve) => {
+			resolveSubscription = resolve;
+		}));
+		(globalThis as unknown as { window?: unknown }).window = {
+			multicast: { capabilities: { consumeModes: ["bytes"] }, subscribe },
+		};
+		const manager = new TransportManager();
+		const connecting = manager.connect(CONFIG);
+		await vi.waitFor(() => expect(subscribe).toHaveBeenCalledOnce());
+		manager.disconnect();
+		resolveSubscription({ addEventListener: vi.fn(), removeEventListener: vi.fn(), unsubscribe });
+
+		expect(await connecting).toBe(false);
+		expect(manager.getState().connected).toBe(false);
+		expect(unsubscribe).toHaveBeenCalledOnce();
+	});
+
+	it("rejects invalid endpoints before AMT fallback", async () => {
+		(globalThis as unknown as { window?: unknown }).window = {};
+		const manager = new TransportManager();
+		const onError = vi.fn();
+		manager.setErrorCallback(onError);
+		expect(await manager.connect({ ...CONFIG, group: "127.0.0.1", amtRelay: "relay.example" })).toBe(false);
+		expect(onError).toHaveBeenCalledOnce();
+	});
+
+	it("reports disconnected after an invalid reconnect", async () => {
+		const unsubscribe = vi.fn();
+		const subscribe = vi.fn().mockResolvedValue({
+			addEventListener: vi.fn(), removeEventListener: vi.fn(), unsubscribe,
+		});
+		(globalThis as unknown as { window?: unknown }).window = {
+			multicast: { capabilities: { consumeModes: ["bytes"] }, subscribe },
+		};
+		const manager = new TransportManager();
+		expect(await manager.connect(CONFIG)).toBe(true);
+
+		expect(await manager.connect({ ...CONFIG, group: "127.0.0.1" })).toBe(false);
+		expect(unsubscribe).toHaveBeenCalledOnce();
+		expect(manager.getState()).toMatchObject({
+			mode: "disconnected",
+			connected: false,
+		});
+	});
+});