@blockcast/mmt-transport 0.2.0 → 0.2.2

package/src/transport-manager.ts

@@ -2,15 +2,15 @@
  * @blockcast/transport - Transport Manager
  *
  * Unified transport abstraction for MoQ players supporting:
- * - Native multicast (ASM/SSM via IGMPv3/MLD + PIM-SSM)
- * - AMT tunneling (RFC 7450) with optional DRIAD relay discovery
+ * - window.multicast gateway subscriptions
+ * - AMT proxy tunneling (RFC 7450) with optional DRIAD relay discovery
  * - WebTransport/QUIC (MoQ-lite protocol)
  * - WebSocket fallback
  *
  * Transport promotion hierarchy (WebTransport-first for fast startup):
  * 1. WebTransport - immediate connection for fast channel select
- * 2. Background discovery - check if multicast available
- * 3. Promote to multicast (Native SSM > IGMP > AMT) if available
+ * 2. Background discovery - check if window.multicast is available
+ * 3. Promote to gateway multicast if available
  * 4. WebSocket fallback if WebTransport unavailable
  *
  * Features:
@@ -26,15 +26,27 @@ import type {
 	TransportCapabilities,
 	TransportState,
 	QualityLevel,
+	WindowMulticastCapabilities,
+	WindowMulticastGateway,
+	WindowMulticastSubscriptionState,
 } from "./types.js";
 import { DRIADDiscovery } from "./driad-discovery.js";
 import { AdaptiveBitrateController } from "./abr-controller.js";
+import {
+	MulticastOrchestrator,
+	type MulticastTierPacket,
+	type OrchestratorCommand,
+	type OrchestratorOptions,
+} from "./multicast-orchestrator.js";
+import type { MulticastTierEndpoint } from "./multicast-tier.js";
+import { multicastSubscriptionPool } from "./multicast-subscription-pool.js";
+import { normalizeMulticastEndpoint } from "./endpoint-config.js";
 
 /**
  * Transport Manager
  *
  * Manages transport connections with automatic mode selection:
- * WebTransport -> Native SSM -> IGMP -> AMT -> WebSocket
+ * WebTransport -> window.multicast -> AMT proxy -> WebSocket
  *
  * Renamed from SSMTransportManager - the old name is preserved
  * as a deprecated alias for backwards compatibility.
@@ -52,6 +64,9 @@ export class TransportManager {
 	private subscription: TransportSubscription | null = null;
 	private driad = new DRIADDiscovery();
 	private abr: AdaptiveBitrateController;
+	private multicastOrchestrator: MulticastOrchestrator | null = null;
+	private onOrchestratorCommand?: (command: OrchestratorCommand) => void;
+	private connectionGeneration = 0;
 
 	private onPacket?: (data: ArrayBuffer) => void;
 	private onError?: (error: Error) => void;
@@ -61,22 +76,55 @@ export class TransportManager {
 		this.abr = new AdaptiveBitrateController();
 	}
 
+	private getWindow(): Window | undefined {
+		return typeof window === "undefined" ? undefined : window;
+	}
+
+	private getWindowMulticastGateway(): WindowMulticastGateway | undefined {
+		return this.getWindow()?.multicast;
+	}
+
+	private async getGatewayCapabilities(
+		gateway: WindowMulticastGateway,
+	): Promise<WindowMulticastCapabilities | undefined> {
+		if (!gateway?.capabilities) return undefined;
+		try {
+			return typeof gateway.capabilities === "function" ?
+				await gateway.capabilities() :
+				gateway.capabilities;
+		} catch (error) {
+			console.warn("[Transport] window.multicast capabilities failed:", error);
+			return undefined;
+		}
+	}
+
+	private async gatewaySupportsBytes(gateway: WindowMulticastGateway | undefined): Promise<boolean> {
+		if (typeof gateway?.subscribe !== "function") return false;
+		if (!gateway.capabilities) return true;
+
+		const capabilities = await this.getGatewayCapabilities(gateway);
+		if (!capabilities) return false;
+		const consumeModes = capabilities.consumeModes;
+		return !consumeModes || consumeModes.includes("bytes");
+	}
+
 	/**
 	 * Detect available transport capabilities
 	 */
 	async detectCapabilities(): Promise<TransportCapabilities> {
 		if (this.capabilities) return this.capabilities;
 
-		const hasMulticast = typeof window !== "undefined" && window.Multicast !== undefined;
-		const multicastApi = hasMulticast ? window.Multicast : null;
+		const gateway = this.getWindowMulticastGateway();
+		const hasGatewayBytes = await this.gatewaySupportsBytes(gateway);
+		const win = this.getWindow();
 
 		this.capabilities = {
-			nativeSSM: !!multicastApi?.subscribeSSM,
-			nativeIGMP: !!multicastApi?.subscribe,
-			directSockets: typeof window !== "undefined" && typeof window.UDPSocket !== "undefined",
-			amt: !!multicastApi?.connectAMT,
+			nativeSSM: hasGatewayBytes,
+			nativeIGMP: hasGatewayBytes,
+			directSockets: typeof win?.UDPSocket !== "undefined",
+			amt: false,
 			driad: true, // DRIAD uses HTTP proxy, always available
-			fecDecode: !!multicastApi?.fecDecode,
+			fecDecode: false,
 		};
 
 		console.log("[Transport] Capabilities:", this.capabilities);
@@ -87,13 +135,45 @@ export class TransportManager {
 	 * Connect using best available transport
 	 *
 	 * Promotion hierarchy:
-	 * 1. Native SSM (IWA with Direct Sockets)
-	 * 2. Native IGMP (IWA fallback)
-	 * 3. AMT Gateway (specified or discovered via DRIAD)
-	 * 4. MOQ WebTransport (final fallback)
+	 * 1. window.multicast gateway bytes
+	 * 2. AMT proxy (specified or discovered via DRIAD)
+	 * 3. MOQ WebTransport (final fallback)
 	 */
 	async connect(config: TransportConfig): Promise<boolean> {
+		const generation = ++this.connectionGeneration;
+		this.subscription?.close();
+		this.subscription = null;
+		this.state = {
+			mode: "disconnected",
+			connected: false,
+			packetsReceived: 0,
+			bytesReceived: 0,
+			lastPacketTime: 0,
+		};
+		this.onStateChange?.(this.state);
+		const endpoint = normalizeMulticastEndpoint({
+			groupAddress: config.group,
+			sourceAddress: config.source,
+			port: config.port,
+			mode: config.mode,
+			amtRelay: config.amtRelay,
+			amtRelayPort: config.amtRelayPort,
+		});
+		if (!endpoint) {
+			const error = new Error("Invalid multicast endpoint configuration");
+			this.onError?.(error);
+			return false;
+		}
+		config = {
+			...config,
+			group: endpoint.groupAddress,
+			source: endpoint.sourceAddress ?? "",
+			mode: endpoint.mode,
+			amtRelay: endpoint.amtRelay,
+			amtRelayPort: endpoint.amtRelayPort,
+		};
 		const caps = await this.detectCapabilities();
+		if (generation !== this.connectionGeneration) return false;
 
 		// Initialize ABR with requested quality
 		if (config.initialQuality) {
@@ -109,74 +189,69 @@ export class TransportManager {
 		// Try transport hierarchy
 		let connected = false;
 
-		// 1. Try native SSM (best option)
-		if (caps.nativeSSM && config.source) {
-			console.log("[Transport] Attempting native SSM...");
-			connected = await this.connectNativeSSM(config);
-			if (connected) {
-				this.state.mode = "ssm";
-				return true;
-			}
-		}
-
-		// 2. Try native IGMP (if SSM not available)
-		if (caps.nativeIGMP && !connected) {
-			console.log("[Transport] Attempting native IGMP...");
-			connected = await this.connectNativeIGMP(config);
+		// 1. Try the canonical browser multicast gateway.
+		if (caps.nativeSSM || caps.nativeIGMP) {
+			console.log("[Transport] Attempting window.multicast...");
+			connected = await this.connectWindowMulticast(config, generation);
 			if (connected) {
-				this.state.mode = "igmp";
+				if (generation !== this.connectionGeneration) return false;
+				this.state.mode = "multicast";
 				return true;
 			}
 		}
 
-		// 3. Try AMT (with optional DRIAD discovery)
+		// 2. Try AMT proxy (with optional DRIAD discovery)
 		if (!connected) {
 			console.log("[Transport] Attempting AMT tunnel...");
-			connected = await this.connectAMT(config);
+			connected = await this.connectAmt(config, generation);
 			if (connected) {
-				this.state.mode = config.driadEnabled ? "driad" : "amt";
+				if (generation !== this.connectionGeneration) return false;
+				this.state.mode = "amt";
 				return true;
 			}
 		}
 
-		// 4. Fallback to MOQ
+		// 3. Fallback to MOQ
 		console.log("[Transport] All multicast transports failed, falling back to MOQ");
 		return false;
 	}
 
 	/**
-	 * Connect via native SSM (Source-Specific Multicast)
+	 * Connect via the lowercase window.multicast bytes gateway.
 	 */
-	private async connectNativeSSM(config: TransportConfig): Promise<boolean> {
+	private async connectWindowMulticast(config: TransportConfig, generation: number): Promise<boolean> {
 		try {
-			const multicastApi = window.Multicast;
-			if (!multicastApi?.subscribeSSM) return false;
-
-			const subscription = await multicastApi.subscribeSSM({
-				group: config.group,
-				source: config.source,
-				port: config.port,
-				protocol: "mmtp",
-				fec: true,
+			const gateway = this.getWindowMulticastGateway();
+			if (typeof gateway?.subscribe !== "function") return false;
+
+			const lease = await multicastSubscriptionPool.acquire(gateway, config, {
+				onBytes: (data) => {
+					if (generation === this.connectionGeneration) this.handlePacket(data);
+				},
+				onState: (state: WindowMulticastSubscriptionState) => {
+					if (generation !== this.connectionGeneration) return;
+					this.state.connected = state !== "closed";
+					this.onStateChange?.(this.state);
+				},
+				onError: (error) => {
+					if (generation !== this.connectionGeneration) return;
+					console.error("[Transport] window.multicast error:", error);
+					this.onError?.(error);
+				},
 			});
-
-			subscription.onpacket = (event: { data: ArrayBuffer }) => {
-				this.handlePacket(event.data);
-			};
-
-			subscription.onerror = (error: Error) => {
-				console.error("[Transport] Native SSM error:", error);
-				this.onError?.(error);
-			};
+			if (generation !== this.connectionGeneration) {
+				await lease.release();
+				return false;
+			}
 
 			this.subscription = {
-				id: `ssm-${Date.now()}`,
+				id: lease.key,
 				config,
-				close: () => subscription.unsubscribe(),
+				close: () => { void lease.release(); },
 			};
 
 			this.state = {
-				mode: "ssm",
+				mode: "multicast",
 				connected: true,
 				group: config.group,
 				source: config.source,
@@ -186,63 +261,19 @@ export class TransportManager {
 				lastPacketTime: 0,
 			};
 
-			console.log(`[Transport] Connected via native SSM: (${config.source}, ${config.group})`);
+			console.log(`[Transport] Connected via window.multicast: (${config.source}, ${config.group})`);
 			this.onStateChange?.(this.state);
 			return true;
 		} catch (error) {
-			console.warn("[Transport] Native SSM failed:", error);
+			console.warn("[Transport] window.multicast failed:", error);
 			return false;
 		}
 	}
 
 	/**
-	 * Connect via native IGMP (Any-Source Multicast)
+	 * Connect via AMT proxy (with optional DRIAD discovery)
 	 */
-	private async connectNativeIGMP(config: TransportConfig): Promise<boolean> {
-		try {
-			const multicastApi = window.Multicast;
-			if (!multicastApi?.subscribe) return false;
-
-			const subscription = await multicastApi.subscribe({
-				group: config.group,
-				port: config.port,
-				protocol: "mmtp",
-				fec: true,
-			});
-
-			subscription.onpacket = (event: { data: ArrayBuffer }) => {
-				this.handlePacket(event.data);
-			};
-
-			this.subscription = {
-				id: `igmp-${Date.now()}`,
-				config,
-				close: () => subscription.unsubscribe(),
-			};
-
-			this.state = {
-				mode: "igmp",
-				connected: true,
-				group: config.group,
-				quality: this.abr.getCurrentQuality(),
-				packetsReceived: 0,
-				bytesReceived: 0,
-				lastPacketTime: 0,
-			};
-
-			console.log(`[Transport] Connected via IGMP: ${config.group}`);
-			this.onStateChange?.(this.state);
-			return true;
-		} catch (error) {
-			console.warn("[Transport] Native IGMP failed:", error);
-			return false;
-		}
-	}
-
-	/**
-	 * Connect via AMT Gateway (with optional DRIAD discovery)
-	 */
-	private async connectAMT(config: TransportConfig): Promise<boolean> {
+	private async connectAmt(config: TransportConfig, generation: number): Promise<boolean> {
 		try {
 			let amtRelay = config.amtRelay;
 
@@ -251,11 +282,13 @@ export class TransportManager {
 			if (!amtRelay && config.driadEnabled !== false && config.source) {
 				console.log(`[Transport] Discovering AMT relay via DRIAD for source ${config.source}...`);
 				const relays = await this.driad.discoverRelays(config.source);
+				if (generation !== this.connectionGeneration) return false;
 				const bestRelay = await this.driad.selectBestRelay(relays);
+				if (generation !== this.connectionGeneration) return false;
 
 				if (bestRelay) {
 					amtRelay = bestRelay.host;
-					this.state.driadRelay = amtRelay;
+					this.state.amtRelay = amtRelay;
 				}
 			}
 
@@ -264,46 +297,8 @@ export class TransportManager {
 				return false;
 			}
 
-			// Connect via AMT proxy/gateway
-			const multicastApi = window.Multicast;
-
-			if (multicastApi?.connectAMT) {
-				const gateway = await multicastApi.connectAMT({
-					relay: amtRelay,
-					group: config.group,
-					source: config.source,
-					port: config.port,
-				});
-
-				gateway.onpacket = (event: { data: ArrayBuffer }) => {
-					this.handlePacket(event.data);
-				};
-
-				this.subscription = {
-					id: `amt-${Date.now()}`,
-					config,
-					close: () => gateway.close(),
-				};
-
-				this.state = {
-					mode: config.driadEnabled ? "driad" : "amt",
-					connected: true,
-					group: config.group,
-					source: config.source,
-					amtRelay,
-					quality: this.abr.getCurrentQuality(),
-					packetsReceived: 0,
-					bytesReceived: 0,
-					lastPacketTime: 0,
-				};
-
-				console.log(`[Transport] Connected via AMT: ${amtRelay}`);
-				this.onStateChange?.(this.state);
-				return true;
-			}
-
-			// Fallback: Use WebSocket-based AMT proxy
-			return await this.connectAMTProxy(config, amtRelay);
+			// Use the WebSocket-based AMT proxy when a relay is known.
+			return await this.connectAmtProxy(config, amtRelay, generation);
 		} catch (error) {
 			console.warn("[Transport] AMT connection failed:", error);
 			return false;
@@ -313,16 +308,31 @@ export class TransportManager {
 	/**
 	 * Connect via WebSocket-based AMT proxy (browser fallback)
 	 */
-	private async connectAMTProxy(config: TransportConfig, amtRelay: string): Promise<boolean> {
+	private async connectAmtProxy(config: TransportConfig, amtRelay: string, generation: number): Promise<boolean> {
 		try {
-			const wsUrl = `wss://${amtRelay}/amt-proxy?group=${config.group}&source=${config.source || ""}&port=${config.port}`;
+			const relayHost = amtRelay.includes(":") && !amtRelay.startsWith("[") ? `[${amtRelay}]` : amtRelay;
+			const relayAuthority = config.amtRelayPort ? `${relayHost}:${config.amtRelayPort}` : relayHost;
+			const wsUrl = new URL(`wss://${relayAuthority}/amt-proxy`);
+			wsUrl.searchParams.set("group", config.group);
+			wsUrl.searchParams.set("source", config.source || "");
+			wsUrl.searchParams.set("port", String(config.port));
 
 			const ws = new WebSocket(wsUrl);
 
 			return new Promise((resolve, reject) => {
 				ws.binaryType = "arraybuffer";
+				const timeout = setTimeout(() => {
+					ws.close();
+					reject(new Error("AMT proxy connection timeout"));
+				}, 10000);
 
 				ws.onopen = () => {
+					clearTimeout(timeout);
+					if (generation !== this.connectionGeneration) {
+						ws.close();
+						resolve(false);
+						return;
+					}
 					console.log(`[Transport] Connected to AMT proxy: ${amtRelay}`);
 
 					this.subscription = {
@@ -348,23 +358,31 @@ export class TransportManager {
 				};
 
 				ws.onmessage = (event) => {
-					if (event.data instanceof ArrayBuffer) {
+					if (generation === this.connectionGeneration && event.data instanceof ArrayBuffer) {
 						this.handlePacket(event.data);
 					}
 				};
 
 				ws.onerror = (error) => {
+					clearTimeout(timeout);
+					if (generation !== this.connectionGeneration) {
+						resolve(false);
+						return;
+					}
 					console.error("[Transport] AMT proxy error:", error);
 					reject(error);
 				};
 
 				ws.onclose = () => {
+					clearTimeout(timeout);
+					if (generation !== this.connectionGeneration) {
+						resolve(false);
+						return;
+					}
 					this.state.connected = false;
 					this.onStateChange?.(this.state);
+					resolve(false);
 				};
-
-				// Timeout
-				setTimeout(() => reject(new Error("AMT proxy connection timeout")), 10000);
 			});
 		} catch (error) {
 			console.warn("[Transport] AMT proxy failed:", error);
@@ -408,6 +426,29 @@ export class TransportManager {
 		this.abr.setQuality(name);
 	}
 
+	/** Configures multicast-only ABR while leaving the caller's MoQ ABR untouched. */
+	configureMulticastTiers(
+		options: OrchestratorOptions,
+		onCommand?: (command: OrchestratorCommand) => void,
+	): MulticastTierEndpoint | undefined {
+		this.dispatchOrchestratorCommand(this.multicastOrchestrator?.cancel());
+		this.multicastOrchestrator = new MulticastOrchestrator(options);
+		this.onOrchestratorCommand = onCommand;
+		return this.multicastOrchestrator.start();
+	}
+
+	recordMulticastGoodput(bitrate: number | undefined): OrchestratorCommand | undefined {
+		return this.dispatchOrchestratorCommand(this.multicastOrchestrator?.onGoodput({ bitrate }));
+	}
+
+	recordMulticastTierPacket(packet: MulticastTierPacket): OrchestratorCommand | undefined {
+		return this.dispatchOrchestratorCommand(this.multicastOrchestrator?.onTierPacket(packet));
+	}
+
+	pollMulticastTierSwitch(): OrchestratorCommand | undefined {
+		return this.dispatchOrchestratorCommand(this.multicastOrchestrator?.poll());
+	}
+
 	/**
 	 * Set packet callback
 	 */
@@ -433,8 +474,12 @@ export class TransportManager {
 	 * Disconnect
 	 */
 	disconnect() {
+		this.connectionGeneration++;
 		this.subscription?.close();
 		this.subscription = null;
+		this.dispatchOrchestratorCommand(this.multicastOrchestrator?.cancel());
+		this.multicastOrchestrator = null;
+		this.onOrchestratorCommand = undefined;
 		this.state = {
 			mode: "disconnected",
 			connected: false,
@@ -444,6 +489,11 @@ export class TransportManager {
 		};
 		this.onStateChange?.(this.state);
 	}
+
+	private dispatchOrchestratorCommand(command: OrchestratorCommand | undefined): OrchestratorCommand | undefined {
+		if (command) this.onOrchestratorCommand?.(command);
+		return command;
+	}
 }
 
 // Export singleton instance

package/src/types.ts

@@ -4,39 +4,55 @@
  * Shared interfaces for unified transport (WebTransport, SSM, AMT, DRIAD) and FEC.
  */
 
-/** window.Multicast API type (from IWA/Chrome Direct Sockets) */
-export interface MulticastAPI {
-	subscribeSSM?: (config: {
-		group: string;
-		source: string;
-		port: number;
-		protocol?: string;
-		fec?: boolean;
-	}) => Promise<MulticastSubscription>;
-	subscribe?: (config: {
-		group: string;
-		port: number;
-		protocol?: string;
-		fec?: boolean;
-	}) => Promise<MulticastSubscription>;
-	connectAMT?: (config: {
-		relay: string;
-		group: string;
-		source?: string;
-		port: number;
-	}) => Promise<{ onpacket?: (event: { data: ArrayBuffer }) => void; close: () => void }>;
-	fecDecode?: boolean;
-}
-
-export interface MulticastSubscription {
-	onpacket?: (event: { data: ArrayBuffer }) => void;
-	onerror?: (error: Error) => void;
-	unsubscribe: () => void;
+/** window.multicast gateway config for byte subscriptions. */
+export interface WindowMulticastSubscribeConfig {
+	group: string;
+	port: number;
+	source?: string;
+	consume: "bytes";
+	mode?: "auto" | "native" | "tunnel";
+	amtRelay?: string;
+	amtRelayPort?: number;
+}
+
+export type WindowMulticastSubscriptionState = "connecting" | "connected" | "reconnecting" | "closed";
+
+export interface WindowMulticastSubscriptionEventMap {
+	bytes: CustomEvent<ArrayBuffer>;
+	state: CustomEvent<WindowMulticastSubscriptionState>;
+	error: CustomEvent<unknown>;
+}
+
+/** window.multicast subscription returned by the IWA gateway surface. */
+export interface WindowMulticastSubscription {
+	readonly id?: string;
+	readonly state?: WindowMulticastSubscriptionState;
+	addEventListener<K extends keyof WindowMulticastSubscriptionEventMap>(
+		type: K,
+		listener: (ev: WindowMulticastSubscriptionEventMap[K]) => void,
+		options?: AddEventListenerOptions | boolean,
+	): void;
+	removeEventListener<K extends keyof WindowMulticastSubscriptionEventMap>(
+		type: K,
+		listener: (ev: WindowMulticastSubscriptionEventMap[K]) => void,
+		options?: EventListenerOptions | boolean,
+	): void;
+	unsubscribe: () => Promise<void> | void;
+}
+
+export interface WindowMulticastCapabilities {
+	readonly consumeModes?: ReadonlyArray<"bytes" | string>;
+}
+
+/** Lowercase window.multicast gateway surface. */
+export interface WindowMulticastGateway {
+	subscribe?: (config: WindowMulticastSubscribeConfig) => Promise<WindowMulticastSubscription>;
+	capabilities?: WindowMulticastCapabilities | (() => Promise<WindowMulticastCapabilities>);
 }
 
 declare global {
 	interface Window {
-		Multicast?: MulticastAPI;
+		multicast?: WindowMulticastGateway;
 		UDPSocket?: unknown;
 	}
 }
@@ -53,6 +69,10 @@ export interface TransportConfig {
 	streamType: "video" | "audio";
 	/** Optional AMT relay host for unicast tunneling */
 	amtRelay?: string;
+	/** Optional AMT relay port. */
+	amtRelayPort?: number;
+	/** Browser gateway transport preference. */
+	mode?: "auto" | "native" | "tunnel";
 	/** DRIAD discovery enabled */
 	driadEnabled?: boolean;
 	/** Initial bitrate quality level */
@@ -79,7 +99,7 @@ export interface TransportCapabilities {
 	fecDecode: boolean;
 }
 
-export type TransportMode = "ssm" | "igmp" | "amt" | "driad" | "moq" | "disconnected";
+export type TransportMode = "multicast" | "amt" | "moq" | "disconnected";
 
 export interface TransportState {
 	mode: TransportMode;
@@ -87,7 +107,6 @@ export interface TransportState {
 	group?: string;
 	source?: string;
 	amtRelay?: string;
-	driadRelay?: string;
 	quality?: QualityLevel;
 	packetsReceived: number;
 	bytesReceived: number;