@blockcast/mmt-transport 0.2.0

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @blockcast/transport
+ *
+ * Unified transport manager for MoQ players with WebTransport, multicast, AMT, DRIAD, and FEC support.
+ *
+ * Transport modes:
+ * - Native multicast (ASM/SSM via IGMPv3/MLD + PIM-SSM)
+ * - AMT 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
+ * 4. WebSocket fallback if WebTransport unavailable
+ *
+ * Features:
+ * - Progressive adaptive bitrate based on network conditions
+ * - FEC (Forward Error Correction) for burst loss recovery
+ * - Seamless transport switching with session continuity
+ * - Unified FEC/ABR pipeline across all transport modes
+ * - A/V synchronization via SharedClock
+ */
+
+// Types (new generic names)
+export type {
+	TransportConfig,
+	TransportSubscription,
+	QualityLevel,
+	TransportCapabilities,
+	TransportMode,
+	TransportState,
+	DRIADRelay,
+	AmtRelayInfo,
+	GroupKey,
+	PacketMetadata,
+	MfuFragment,
+	ReassembledMfu,
+	ProcessingStats,
+	MmtFecClientOptions,
+	Micro,
+	SyncDecision,
+	MulticastAPI,
+	MulticastSubscription,
+	// Consolidated from @blockcast/multicast
+	MulticastTransportMode,
+	MulticastConfig,
+	PacketSource,
+	SubscriptionState,
+	SubscriptionStats,
+	MulticastSubscriptionHandle,
+	FecConfig,
+	FecStats,
+	MulticastConfigWithFec,
+	MulticastBridge,
+	// FEC types per draft-ramadan-moq-fec-00
+	MoqFecConfig,
+	RepairObjectHeader,
+	// @deprecated - use TransportConfig and TransportSubscription instead
+	SSMConfig,
+	SSMSubscription,
+} from "./types.js";
+
+// FEC constants and utilities per draft-ramadan-moq-fec-00
+export {
+	FEC_CONFIG_MESSAGE_TYPE,
+	REPAIR_TRACK_SUFFIX,
+	repairTrackPath,
+	isRepairTrack,
+	sourceTrackFromRepair,
+	MoqFecAlgorithm,
+} from "./types.js";
+
+// Transport Manager (renamed from SSMTransportManager)
+export { TransportManager, transportManager } from "./transport-manager.js";
+
+// @deprecated - Use TransportManager and transportManager instead
+export { SSMTransportManager, ssmTransport } from "./transport-manager.js";
+
+// DRIAD Discovery
+export { DRIADDiscovery, driadDiscovery } from "./driad-discovery.js";
+
+// Adaptive Bitrate Controller
+export {
+	AdaptiveBitrateController,
+	QUALITY_LEVELS,
+	type FecStatsForAbr,
+} from "./abr-controller.js";
+
+// AMT Gateway
+export {
+	AMTGatewayManager,
+	AMTGateway,
+	amtGatewayManager,
+	type AMTSubscriptionConfig,
+	type AMTGatewayOptions,
+} from "./amt-gateway.js";
+
+// FEC Client
+export {
+	MmtFecClient,
+	createMulticastFecHandler,
+	setupMmtFec,
+	// MoQ FEC Client (for WebTransport)
+	MoqFecClient,
+	createMoqFecClient,
+	loadMmtWasm,
+	type MoqFecClientConfig,
+	type MoqFecClientStats,
+	// FEC decoder configuration (RFC 6330 OTI parameters)
+	type FecDecoderConfig,
+} from "./fec-client.js";
+
+// A/V Sync Clock
+export {
+	SharedClock,
+	getSharedClock,
+	resetSharedClock,
+	SYNC_TOLERANCE_US,
+	PTS_OFFSET_US,
+} from "./clock.js";

package/src/transport-manager.ts

@@ -0,0 +1,460 @@
+/**
+ * @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
+ * - 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
+ * 4. WebSocket fallback if WebTransport unavailable
+ *
+ * Features:
+ * - Progressive adaptive bitrate based on network conditions
+ * - FEC (Forward Error Correction) for burst loss recovery
+ * - Seamless transport switching with session continuity
+ * - Unified FEC/ABR pipeline across all transport modes
+ */
+
+import type {
+	TransportConfig,
+	TransportSubscription,
+	TransportCapabilities,
+	TransportState,
+	QualityLevel,
+} from "./types.js";
+import { DRIADDiscovery } from "./driad-discovery.js";
+import { AdaptiveBitrateController } from "./abr-controller.js";
+
+/**
+ * Transport Manager
+ *
+ * Manages transport connections with automatic mode selection:
+ * WebTransport -> Native SSM -> IGMP -> AMT -> WebSocket
+ *
+ * Renamed from SSMTransportManager - the old name is preserved
+ * as a deprecated alias for backwards compatibility.
+ */
+export class TransportManager {
+	private state: TransportState = {
+		mode: "disconnected",
+		connected: false,
+		packetsReceived: 0,
+		bytesReceived: 0,
+		lastPacketTime: 0,
+	};
+
+	private capabilities: TransportCapabilities | null = null;
+	private subscription: TransportSubscription | null = null;
+	private driad = new DRIADDiscovery();
+	private abr: AdaptiveBitrateController;
+
+	private onPacket?: (data: ArrayBuffer) => void;
+	private onError?: (error: Error) => void;
+	private onStateChange?: (state: TransportState) => void;
+
+	constructor() {
+		this.abr = new AdaptiveBitrateController();
+	}
+
+	/**
+	 * 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;
+
+		this.capabilities = {
+			nativeSSM: !!multicastApi?.subscribeSSM,
+			nativeIGMP: !!multicastApi?.subscribe,
+			directSockets: typeof window !== "undefined" && typeof window.UDPSocket !== "undefined",
+			amt: !!multicastApi?.connectAMT,
+			driad: true, // DRIAD uses HTTP proxy, always available
+			fecDecode: !!multicastApi?.fecDecode,
+		};
+
+		console.log("[Transport] Capabilities:", this.capabilities);
+		return this.capabilities;
+	}
+
+	/**
+	 * 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)
+	 */
+	async connect(config: TransportConfig): Promise<boolean> {
+		const caps = await this.detectCapabilities();
+
+		// Initialize ABR with requested quality
+		if (config.initialQuality) {
+			this.abr = new AdaptiveBitrateController(config.initialQuality);
+		}
+
+		this.abr.setCallback((quality) => {
+			this.state.quality = quality;
+			this.subscription?.onqualitychange?.(quality);
+			this.onStateChange?.(this.state);
+		});
+
+		// 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);
+			if (connected) {
+				this.state.mode = "igmp";
+				return true;
+			}
+		}
+
+		// 3. Try AMT (with optional DRIAD discovery)
+		if (!connected) {
+			console.log("[Transport] Attempting AMT tunnel...");
+			connected = await this.connectAMT(config);
+			if (connected) {
+				this.state.mode = config.driadEnabled ? "driad" : "amt";
+				return true;
+			}
+		}
+
+		// 4. Fallback to MOQ
+		console.log("[Transport] All multicast transports failed, falling back to MOQ");
+		return false;
+	}
+
+	/**
+	 * Connect via native SSM (Source-Specific Multicast)
+	 */
+	private async connectNativeSSM(config: TransportConfig): 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,
+			});
+
+			subscription.onpacket = (event: { data: ArrayBuffer }) => {
+				this.handlePacket(event.data);
+			};
+
+			subscription.onerror = (error: Error) => {
+				console.error("[Transport] Native SSM error:", error);
+				this.onError?.(error);
+			};
+
+			this.subscription = {
+				id: `ssm-${Date.now()}`,
+				config,
+				close: () => subscription.unsubscribe(),
+			};
+
+			this.state = {
+				mode: "ssm",
+				connected: true,
+				group: config.group,
+				source: config.source,
+				quality: this.abr.getCurrentQuality(),
+				packetsReceived: 0,
+				bytesReceived: 0,
+				lastPacketTime: 0,
+			};
+
+			console.log(`[Transport] Connected via native SSM: (${config.source}, ${config.group})`);
+			this.onStateChange?.(this.state);
+			return true;
+		} catch (error) {
+			console.warn("[Transport] Native SSM failed:", error);
+			return false;
+		}
+	}
+
+	/**
+	 * Connect via native IGMP (Any-Source Multicast)
+	 */
+	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> {
+		try {
+			let amtRelay = config.amtRelay;
+
+			// Use DRIAD to discover relay if not specified (RFC 8777)
+			// DRIAD discovers relays based on SOURCE address, not group
+			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);
+				const bestRelay = await this.driad.selectBestRelay(relays);
+
+				if (bestRelay) {
+					amtRelay = bestRelay.host;
+					this.state.driadRelay = amtRelay;
+				}
+			}
+
+			if (!amtRelay) {
+				console.warn("[Transport] No AMT relay available (DRIAD requires source address for SSM)");
+				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);
+		} catch (error) {
+			console.warn("[Transport] AMT connection failed:", error);
+			return false;
+		}
+	}
+
+	/**
+	 * Connect via WebSocket-based AMT proxy (browser fallback)
+	 */
+	private async connectAMTProxy(config: TransportConfig, amtRelay: string): Promise<boolean> {
+		try {
+			const wsUrl = `wss://${amtRelay}/amt-proxy?group=${config.group}&source=${config.source || ""}&port=${config.port}`;
+
+			const ws = new WebSocket(wsUrl);
+
+			return new Promise((resolve, reject) => {
+				ws.binaryType = "arraybuffer";
+
+				ws.onopen = () => {
+					console.log(`[Transport] Connected to AMT proxy: ${amtRelay}`);
+
+					this.subscription = {
+						id: `amt-proxy-${Date.now()}`,
+						config,
+						close: () => ws.close(),
+					};
+
+					this.state = {
+						mode: "amt",
+						connected: true,
+						group: config.group,
+						source: config.source,
+						amtRelay,
+						quality: this.abr.getCurrentQuality(),
+						packetsReceived: 0,
+						bytesReceived: 0,
+						lastPacketTime: 0,
+					};
+
+					this.onStateChange?.(this.state);
+					resolve(true);
+				};
+
+				ws.onmessage = (event) => {
+					if (event.data instanceof ArrayBuffer) {
+						this.handlePacket(event.data);
+					}
+				};
+
+				ws.onerror = (error) => {
+					console.error("[Transport] AMT proxy error:", error);
+					reject(error);
+				};
+
+				ws.onclose = () => {
+					this.state.connected = false;
+					this.onStateChange?.(this.state);
+				};
+
+				// Timeout
+				setTimeout(() => reject(new Error("AMT proxy connection timeout")), 10000);
+			});
+		} catch (error) {
+			console.warn("[Transport] AMT proxy failed:", error);
+			return false;
+		}
+	}
+
+	/**
+	 * Handle received packet
+	 */
+	private handlePacket(data: ArrayBuffer) {
+		this.state.packetsReceived++;
+		this.state.bytesReceived += data.byteLength;
+		this.state.lastPacketTime = Date.now();
+
+		// Update ABR with sample
+		this.abr.recordSample(data.byteLength, 0);
+
+		// Forward to callback
+		this.onPacket?.(data);
+	}
+
+	/**
+	 * Get current transport state
+	 */
+	getState(): TransportState {
+		return { ...this.state };
+	}
+
+	/**
+	 * Get current quality level
+	 */
+	getQuality(): QualityLevel {
+		return this.abr.getCurrentQuality();
+	}
+
+	/**
+	 * Force quality level
+	 */
+	setQuality(name: string) {
+		this.abr.setQuality(name);
+	}
+
+	/**
+	 * Set packet callback
+	 */
+	setPacketCallback(callback: (data: ArrayBuffer) => void) {
+		this.onPacket = callback;
+	}
+
+	/**
+	 * Set error callback
+	 */
+	setErrorCallback(callback: (error: Error) => void) {
+		this.onError = callback;
+	}
+
+	/**
+	 * Set state change callback
+	 */
+	setStateCallback(callback: (state: TransportState) => void) {
+		this.onStateChange = callback;
+	}
+
+	/**
+	 * Disconnect
+	 */
+	disconnect() {
+		this.subscription?.close();
+		this.subscription = null;
+		this.state = {
+			mode: "disconnected",
+			connected: false,
+			packetsReceived: 0,
+			bytesReceived: 0,
+			lastPacketTime: 0,
+		};
+		this.onStateChange?.(this.state);
+	}
+}
+
+// Export singleton instance
+export const transportManager = new TransportManager();
+
+/**
+ * @deprecated Use `TransportManager` instead. This alias is preserved for backwards compatibility.
+ */
+export const SSMTransportManager = TransportManager;
+
+/**
+ * @deprecated Use `transportManager` instead. This alias is preserved for backwards compatibility.
+ */
+export const ssmTransport = transportManager;