@blockcast/mmt-transport 0.2.0

package/src/amt-gateway.ts

@@ -0,0 +1,511 @@
+/**
+ * @blockcast/transport - AMT Gateway
+ *
+ * Consolidated AMT (Automatic Multicast Tunneling) implementation
+ * supporting both Service Worker and Direct Sockets approaches.
+ *
+ * RFC 7450: Automatic Multicast Tunneling
+ */
+
+import type { GroupKey, PacketMetadata, AmtRelayInfo } from "./types.js";
+import { DRIADDiscovery } from "./driad-discovery.js";
+
+/** Default AMT port (RFC 7450) */
+const DEFAULT_AMT_PORT = 2268;
+
+/** AMT message types */
+const AMT_MESSAGE_TYPES = {
+	RELAY_DISCOVERY: 1,
+	RELAY_ADVERTISEMENT: 2,
+	REQUEST: 3,
+	MEMBERSHIP_QUERY: 4,
+	MEMBERSHIP_UPDATE: 5,
+	MULTICAST_DATA: 6,
+	TEARDOWN: 7,
+} as const;
+
+/** AMT gateway states */
+const GATEWAY_STATES = {
+	IDLE: "idle",
+	DISCOVERING: "discovering",
+	REQUESTING: "requesting",
+	QUERYING: "querying",
+	ACTIVE: "active",
+	LEAVING: "leaving",
+	CLOSED: "closed",
+} as const;
+
+type GatewayState = (typeof GATEWAY_STATES)[keyof typeof GATEWAY_STATES];
+
+/** AMT subscription configuration */
+export interface AMTSubscriptionConfig {
+	key: GroupKey;
+	relayAddress?: string;
+	relayPort?: number;
+	onPacket: (data: ArrayBuffer, metadata: PacketMetadata) => void;
+	onError: (error: Error) => void;
+}
+
+/** AMT packet info */
+export interface AMTPacketInfo {
+	data: Uint8Array;
+	srcAddress: string;
+	dstAddress: string;
+	srcPort: number;
+	dstPort: number;
+	groupKey: string;
+	timestamp: number;
+}
+
+/** AMT Gateway options */
+export interface AMTGatewayOptions {
+	relayAddress: string;
+	relayPort?: number;
+	onPacket?: (packet: AMTPacketInfo) => void;
+	onStateChange?: (newState: GatewayState, oldState: GatewayState) => void;
+	onError?: (error: Error) => void;
+	onLog?: (message: string) => void;
+}
+
+/** Active AMT subscription */
+interface AMTSubscription {
+	key: GroupKey;
+	subscriptionId: string;
+	config: AMTSubscriptionConfig;
+	relay?: AmtRelayInfo;
+	handshakeComplete: boolean;
+	keepAliveTimer?: ReturnType<typeof setInterval>;
+	lastKeepAlive?: number;
+}
+
+/** Check if address is IPv4 */
+function isIPv4(address: string): boolean {
+	return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(address);
+}
+
+/**
+ * AMT Gateway Manager (Service Worker based)
+ *
+ * Manages AMT tunnel subscriptions using Service Worker for UDP communication.
+ * Handles DRIAD discovery, AMT handshake, and packet decapsulation.
+ */
+export class AMTGatewayManager {
+	private subscriptions = new Map<string, AMTSubscription>();
+	private messageHandler?: (event: MessageEvent) => void;
+	private pendingPackets = new Map<string, Array<{ data: ArrayBuffer; remoteAddress: string; remotePort: number }>>();
+	private driad = new DRIADDiscovery();
+
+	constructor() {
+		// Set up message handler for packets from service worker
+		this.messageHandler = (event: MessageEvent) => {
+			const data = event.data as { type: string; subscriptionId?: string; data?: unknown; error?: string; message?: string };
+			console.log(`[AMT] SW message received:`, data.type);
+			if (data.type === "UDP_PACKET") {
+				this.handlePacket(data);
+			} else if (data.type === "SOCKET_ERROR") {
+				this.handleSocketError(data);
+			} else if (data.type === "DEBUG_LOG") {
+				console.log(`[AMT SW Debug] ${data.message}`);
+			}
+		};
+
+		// Register message handler
+		if (typeof navigator !== "undefined" && navigator.serviceWorker) {
+			navigator.serviceWorker.addEventListener("message", this.messageHandler);
+			console.log("[AMT] Registered service worker message handler");
+		} else {
+			console.warn("[AMT] Service worker not available");
+		}
+	}
+
+	/**
+	 * Subscribe via AMT tunnel
+	 */
+	async subscribe(config: AMTSubscriptionConfig): Promise<string> {
+		const { key } = config;
+		const keyStr = this.getKeyString(key);
+
+		if (this.subscriptions.has(keyStr)) {
+			throw new Error(`Already subscribed to ${keyStr}`);
+		}
+
+		try {
+			let relayAddress: string;
+			let discoveryMethod: "driad" | "manual";
+			const relayPort = config.relayPort || DEFAULT_AMT_PORT;
+
+			if (config.relayAddress) {
+				relayAddress = config.relayAddress;
+				discoveryMethod = "manual";
+				console.log(`[AMT] Using configured relay ${relayAddress}:${relayPort}`);
+			} else if (key.source) {
+				// DRIAD (RFC 8777) discovers relays based on SOURCE address, not group
+				console.log(`[AMT] No relay configured, discovering via DRIAD for source ${key.source}...`);
+				const relays = await this.driad.discoverRelays(key.source);
+				const bestRelay = await this.driad.selectBestRelay(relays);
+
+				if (!bestRelay) {
+					throw new Error(
+						`AMT relay discovery failed for source ${key.source}. ` +
+							`Please specify a relay address in the subscription configuration.`,
+					);
+				}
+
+				relayAddress = bestRelay.host;
+				discoveryMethod = "driad";
+				console.log(`[AMT] Discovered relay via DRIAD: ${relayAddress}:${relayPort}`);
+			} else {
+				throw new Error(
+					`AMT relay discovery requires a source address for SSM (RFC 8777). ` +
+						`Please specify either a relay address or source address.`,
+				);
+			}
+
+			const subscriptionId = keyStr;
+
+			// Initialize packet queue for handshake
+			this.pendingPackets.set(subscriptionId, []);
+
+			// Create subscription
+			const subscription: AMTSubscription = {
+				key,
+				subscriptionId,
+				config,
+				handshakeComplete: false,
+				relay: {
+					address: relayAddress,
+					port: relayPort,
+					discoveryMethod,
+					discoveredAt: Date.now(),
+				},
+			};
+
+			this.subscriptions.set(keyStr, subscription);
+
+			// Note: Actual UDP socket creation and handshake would require
+			// Service Worker communication - this is a simplified version
+			console.log(`[AMT] Subscription created for ${keyStr} via ${relayAddress}:${relayPort}`);
+
+			return keyStr;
+		} catch (error) {
+			const subscription = this.subscriptions.get(keyStr);
+			if (subscription) {
+				this.subscriptions.delete(keyStr);
+				this.pendingPackets.delete(subscription.subscriptionId);
+			}
+
+			throw new Error(`Failed to subscribe via AMT: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	/**
+	 * Unsubscribe from AMT tunnel
+	 */
+	async unsubscribe(handle: string): Promise<void> {
+		const subscription = this.subscriptions.get(handle);
+		if (!subscription) {
+			throw new Error(`Subscription ${handle} not found`);
+		}
+
+		try {
+			// Stop keep-alive timer
+			if (subscription.keepAliveTimer) {
+				clearInterval(subscription.keepAliveTimer);
+			}
+
+			console.log(`[AMT] Unsubscribed from ${handle}`);
+		} catch (error) {
+			console.error("[AMT] Error during unsubscribe:", error);
+		} finally {
+			this.subscriptions.delete(handle);
+			this.pendingPackets.delete(subscription.subscriptionId);
+		}
+	}
+
+	/**
+	 * Get list of active subscriptions
+	 */
+	getSubscriptions(): string[] {
+		return Array.from(this.subscriptions.keys());
+	}
+
+	/**
+	 * Handle packet from service worker
+	 */
+	private handlePacket(message: { subscriptionId?: string; data?: unknown }): void {
+		const { subscriptionId, data } = message;
+		if (!subscriptionId) return;
+
+		const subscription = this.subscriptions.get(subscriptionId);
+		if (!subscription) {
+			console.warn(`[AMT] Received packet for unknown subscription: ${subscriptionId}`);
+			return;
+		}
+
+		// During handshake, queue packets
+		if (!subscription.handshakeComplete) {
+			const queue = this.pendingPackets.get(subscriptionId);
+			const packetData = data as { data: ArrayBuffer; remoteAddress: string; remotePort: number };
+			if (queue) {
+				queue.push({
+					data: packetData.data,
+					remoteAddress: packetData.remoteAddress,
+					remotePort: packetData.remotePort,
+				});
+			}
+			return;
+		}
+
+		// After handshake, forward to callback
+		const packetData = data as { data: ArrayBuffer };
+		const metadata: PacketMetadata = {
+			sourceAddress: subscription.relay?.address || "unknown",
+			sourcePort: subscription.relay?.port || 0,
+			transport: "tunnel",
+			timestamp: performance.now(),
+		};
+
+		subscription.config.onPacket(packetData.data, metadata);
+	}
+
+	/**
+	 * Handle socket error from service worker
+	 */
+	private handleSocketError(message: { subscriptionId?: string; error?: string }): void {
+		const { subscriptionId, error } = message;
+		if (!subscriptionId) return;
+
+		const subscription = this.subscriptions.get(subscriptionId);
+		if (!subscription) {
+			console.warn(`[AMT] Received error for unknown subscription: ${subscriptionId}`);
+			return;
+		}
+
+		subscription.config.onError(new Error(error || "Unknown error"));
+	}
+
+	/**
+	 * Cleanup on destroy
+	 */
+	destroy(): void {
+		if (this.messageHandler && typeof navigator !== "undefined" && navigator.serviceWorker) {
+			navigator.serviceWorker.removeEventListener("message", this.messageHandler);
+		}
+
+		const handles = Array.from(this.subscriptions.keys());
+		for (const handle of handles) {
+			this.unsubscribe(handle).catch((err) => {
+				console.error(`[AMT] Error unsubscribing ${handle}:`, err);
+			});
+		}
+	}
+
+	/**
+	 * Get key string for HashMap
+	 */
+	private getKeyString(key: GroupKey): string {
+		const source = key.source ? `@${key.source}` : "";
+		return `${key.group}:${key.port}${source}`;
+	}
+}
+
+/**
+ * AMT Gateway Client (Direct Sockets based)
+ *
+ * Connects to an AMT relay to receive multicast data via unicast tunnel.
+ * Implements the gateway side of RFC 7450.
+ * Supports multiple (S,G) groups over a single AMT tunnel.
+ */
+export class AMTGateway {
+	private relayAddress: string;
+	private relayPort: number;
+	private groups = new Map<
+		string,
+		{
+			groupPort: number;
+			onPacket: ((packet: AMTPacketInfo) => void) | null;
+			joinedAt: number;
+		}
+	>();
+
+	// Callbacks
+	private onPacket: (packet: AMTPacketInfo) => void;
+	private onStateChange: (newState: GatewayState, oldState: GatewayState) => void;
+	private onError: (error: Error) => void;
+	private onLog: (message: string) => void;
+
+	// State
+	private state: GatewayState = GATEWAY_STATES.IDLE;
+	private nonce: Uint8Array | null = null;
+	private responseMAC: Uint8Array | null = null;
+	private relayConfirmedAddress: string | null = null;
+	private lastDataTime = 0;
+
+	// Stats
+	private stats = {
+		packetsReceived: 0,
+		bytesReceived: 0,
+		queriesReceived: 0,
+		updatesSet: 0,
+	};
+
+	constructor(options: AMTGatewayOptions) {
+		this.relayAddress = options.relayAddress;
+		this.relayPort = options.relayPort || DEFAULT_AMT_PORT;
+
+		this.onPacket = options.onPacket || (() => {});
+		this.onStateChange = options.onStateChange || (() => {});
+		this.onError = options.onError || ((err) => console.error("AMT Error:", err));
+		this.onLog = options.onLog || ((msg) => console.log("AMT:", msg));
+	}
+
+	/**
+	 * Generate random nonce
+	 */
+	private generateNonce(): Uint8Array {
+		const nonce = new Uint8Array(4);
+		crypto.getRandomValues(nonce);
+		return nonce;
+	}
+
+	/**
+	 * Set gateway state
+	 */
+	private setState(newState: GatewayState): void {
+		const oldState = this.state;
+		this.state = newState;
+		this.onLog(`State: ${oldState} -> ${newState}`);
+		this.onStateChange(newState, oldState);
+	}
+
+	/**
+	 * Join a multicast group
+	 */
+	async joinGroup(
+		groupAddress: string,
+		groupPort: number,
+		sourceAddress: string | null = null,
+		onPacket: ((packet: AMTPacketInfo) => void) | null = null,
+	): Promise<string> {
+		const groupKey = `${sourceAddress || "*"},${groupAddress}`;
+
+		if (this.groups.has(groupKey)) {
+			this.onLog(`Group already joined: ${groupKey}`);
+			return groupKey;
+		}
+
+		this.groups.set(groupKey, {
+			groupPort,
+			onPacket,
+			joinedAt: Date.now(),
+		});
+
+		this.onLog(`Joined group: ${groupKey} (port ${groupPort})`);
+		return groupKey;
+	}
+
+	/**
+	 * Leave a multicast group
+	 */
+	async leaveGroup(groupAddress: string, sourceAddress: string | null = null): Promise<boolean> {
+		const groupKey = `${sourceAddress || "*"},${groupAddress}`;
+
+		if (!this.groups.has(groupKey)) {
+			this.onLog(`Group not found: ${groupKey}`);
+			return false;
+		}
+
+		this.groups.delete(groupKey);
+		this.onLog(`Left group: ${groupKey} (${this.groups.size} remaining)`);
+
+		if (this.groups.size === 0) {
+			this.onLog("No groups remaining - closing AMT tunnel");
+			await this.close();
+		}
+
+		return true;
+	}
+
+	/**
+	 * Get list of active groups
+	 */
+	getGroups(): Array<{
+		groupKey: string;
+		groupAddress: string;
+		sourceAddress: string | null;
+		groupPort: number;
+		joinedAt: number;
+	}> {
+		return Array.from(this.groups.entries()).map(([key, info]) => {
+			const [source, group] = key.split(",");
+			return {
+				groupKey: key,
+				groupAddress: group,
+				sourceAddress: source !== "*" ? source : null,
+				groupPort: info.groupPort,
+				joinedAt: info.joinedAt,
+			};
+		});
+	}
+
+	/**
+	 * Open connection to AMT relay
+	 */
+	async open(): Promise<void> {
+		if (this.state !== GATEWAY_STATES.IDLE) {
+			throw new Error(`Cannot open in state: ${this.state}`);
+		}
+
+		this.setState(GATEWAY_STATES.DISCOVERING);
+		this.onLog(`Connecting to AMT relay ${this.relayAddress}:${this.relayPort}`);
+		this.onLog(`Active groups: ${this.groups.size}`);
+
+		// Generate session nonce
+		this.nonce = this.generateNonce();
+		this.onLog(`Generated nonce: ${Array.from(this.nonce).map((b) => b.toString(16).padStart(2, "0")).join("")}`);
+
+		// Note: Actual UDPSocket connection would go here
+		// This is a simplified version showing the state machine
+	}
+
+	/**
+	 * Close connection
+	 */
+	async close(): Promise<void> {
+		if (this.state === GATEWAY_STATES.CLOSED) {
+			return;
+		}
+
+		this.setState(GATEWAY_STATES.LEAVING);
+
+		// Clear all groups
+		this.groups.clear();
+
+		this.setState(GATEWAY_STATES.CLOSED);
+		this.onLog("AMT Gateway closed");
+	}
+
+	/**
+	 * Get current statistics
+	 */
+	getStats(): typeof this.stats {
+		return { ...this.stats };
+	}
+
+	/**
+	 * Get current state
+	 */
+	getState(): GatewayState {
+		return this.state;
+	}
+
+	/**
+	 * Check if gateway is active and receiving data
+	 */
+	isActive(): boolean {
+		return this.state === GATEWAY_STATES.ACTIVE;
+	}
+}
+
+// Export singleton manager instance
+export const amtGatewayManager = new AMTGatewayManager();

package/src/clock.ts

@@ -0,0 +1,212 @@
+/**
+ * @blockcast/transport - SharedClock
+ *
+ * A/V Synchronization via First Sample Anchor
+ *
+ * Based on ExoPlayer MMT Plugin implementation:
+ * - MMTExtractor.java:46-47 (SystemClockAnchor, MfuClockAnchor)
+ * - MMTExtractor.java:625-631 (anchor setting)
+ * - SystemClockSynchronizedSimpleDecoderAudioRenderer.java:576 (getPositionUs)
+ *
+ * This class provides a shared clock anchor across video and audio tracks
+ * to ensure A/V synchronization. The anchor is set on the first sample
+ * received from ANY track, establishing a common reference point.
+ */
+
+import type { Micro, SyncDecision } from "./types.js";
+
+/** Sync tolerance window in microseconds (66ms = ~2 video frames at 30fps) */
+export const SYNC_TOLERANCE_US = 66000 as Micro;
+
+/** Default buffer delay in milliseconds.
+ * For live streaming without B-frames, use lower value (100ms).
+ * ExoPlayer uses 750ms for broadcast with B-frames, but that's too high for live.
+ */
+const DEFAULT_BUFFER_DELAY_MS = 100;
+
+/** PTS offset for decoder timing (from ExoPlayer MMTExtractor.java:37) */
+export const PTS_OFFSET_US = 266000 as Micro;
+
+/**
+ * Shared clock for A/V synchronization.
+ *
+ * Usage:
+ * ```typescript
+ * const clock = new SharedClock();
+ *
+ * // In video/audio source, on first decoded frame:
+ * clock.setAnchor(frame.timestamp);
+ *
+ * // Before rendering each frame:
+ * const decision = clock.shouldRender(frame.timestamp);
+ * if (decision === "render") { ... }
+ * else if (decision === "hold") { await sleep(10); retry(); }
+ * else { frame.close(); } // discard
+ * ```
+ */
+export class SharedClock {
+	/** Wall clock time when anchor was set (performance.now()) */
+	#anchorWallTime: DOMHighResTimeStamp | undefined;
+
+	/** Media timestamp when anchor was set (in microseconds) */
+	#anchorMediaTime: Micro | undefined;
+
+	/** Buffer delay in milliseconds to account for decode latency */
+	#bufferDelayMs: number;
+
+	/** Track minimum MFU timestamp across all tracks for shared reference */
+	#mfuClockAnchor: Micro = 0 as Micro;
+
+	constructor(bufferDelayMs: number = DEFAULT_BUFFER_DELAY_MS) {
+		this.#bufferDelayMs = bufferDelayMs;
+	}
+
+	/**
+	 * Set the anchor on first sample received from ANY track.
+	 * This should be called once per session, typically on the first keyframe.
+	 *
+	 * @param mediaTimestamp - The presentation timestamp of the first sample (microseconds)
+	 */
+	setAnchor(mediaTimestamp: Micro): void {
+		if (this.#anchorWallTime === undefined) {
+			this.#anchorWallTime = performance.now();
+			this.#anchorMediaTime = mediaTimestamp;
+			console.log(`[SharedClock] Anchor set: wall=${this.#anchorWallTime.toFixed(2)}ms, media=${mediaTimestamp}us`);
+		}
+
+		// Track minimum MFU timestamp for shared reference
+		if (this.#mfuClockAnchor === 0 || mediaTimestamp < this.#mfuClockAnchor) {
+			this.#mfuClockAnchor = mediaTimestamp;
+		}
+	}
+
+	/**
+	 * Get the current playback position in microseconds.
+	 *
+	 * @returns Current position in microseconds, or 0 if anchor not set
+	 */
+	getPositionUs(): Micro {
+		if (this.#anchorWallTime === undefined || this.#anchorMediaTime === undefined) {
+			return 0 as Micro;
+		}
+
+		const elapsedMs = performance.now() - this.#anchorWallTime;
+		const elapsedUs = elapsedMs * 1000;
+
+		// Subtract buffer delay and add anchor media time
+		return (elapsedUs - this.#bufferDelayMs * 1000 + this.#anchorMediaTime) as Micro;
+	}
+
+	/**
+	 * Determine whether a frame should be rendered, held, or discarded.
+	 *
+	 * - HOLD: Frame is ahead of clock by more than 66ms (wait for clock)
+	 * - DISCARD: Frame is behind clock by more than 66ms (too late)
+	 * - RENDER: Within +/-66ms tolerance window
+	 *
+	 * @param frameTimestamp - The presentation timestamp of the frame (microseconds)
+	 * @returns "render", "hold", or "discard"
+	 */
+	shouldRender(frameTimestamp: Micro): SyncDecision {
+		const positionUs = this.getPositionUs();
+		const deltaUs = (frameTimestamp - positionUs) as Micro;
+
+		if (deltaUs > SYNC_TOLERANCE_US) {
+			// Frame is ahead - hold it, wait for clock to catch up
+			return "hold";
+		} else if (deltaUs < -SYNC_TOLERANCE_US) {
+			// Frame is late - discard it
+			return "discard";
+		} else {
+			// Within tolerance - render
+			return "render";
+		}
+	}
+
+	/**
+	 * Get how long to wait before a held frame can be rendered.
+	 *
+	 * @param frameTimestamp - The presentation timestamp of the frame (microseconds)
+	 * @returns Wait time in milliseconds, or 0 if frame should be rendered now
+	 */
+	getWaitTimeMs(frameTimestamp: Micro): number {
+		const positionUs = this.getPositionUs();
+		const deltaUs = frameTimestamp - positionUs;
+
+		if (deltaUs > 0) {
+			return deltaUs / 1000; // Convert us to ms
+		}
+		return 0;
+	}
+
+	/**
+	 * Get the delta between a frame timestamp and current position.
+	 * Positive = frame is ahead, negative = frame is behind.
+	 *
+	 * @param frameTimestamp - The presentation timestamp of the frame (microseconds)
+	 * @returns Delta in microseconds
+	 */
+	getDeltaUs(frameTimestamp: Micro): number {
+		return frameTimestamp - this.getPositionUs();
+	}
+
+	/**
+	 * Check if the anchor has been set.
+	 */
+	hasAnchor(): boolean {
+		return this.#anchorWallTime !== undefined;
+	}
+
+	/**
+	 * Get the MFU clock anchor (minimum PTS across all tracks).
+	 * Used for A/V sync reference point.
+	 */
+	getMfuClockAnchor(): Micro {
+		return this.#mfuClockAnchor;
+	}
+
+	/**
+	 * Reset the clock anchor (e.g., on seek or error recovery).
+	 */
+	reset(): void {
+		this.#anchorWallTime = undefined;
+		this.#anchorMediaTime = undefined;
+		this.#mfuClockAnchor = 0 as Micro;
+		console.log("[SharedClock] Anchor reset");
+	}
+
+	/**
+	 * Get debug info about the current clock state.
+	 */
+	getDebugInfo(): {
+		hasAnchor: boolean;
+		positionUs: Micro;
+		mfuClockAnchor: Micro;
+		bufferDelayMs: number;
+	} {
+		return {
+			hasAnchor: this.hasAnchor(),
+			positionUs: this.getPositionUs(),
+			mfuClockAnchor: this.#mfuClockAnchor,
+			bufferDelayMs: this.#bufferDelayMs,
+		};
+	}
+}
+
+/**
+ * Factory function to create a shared clock instance.
+ * Use this to ensure a single clock is shared across video and audio sources.
+ */
+let globalClock: SharedClock | undefined;
+
+export function getSharedClock(bufferDelayMs?: number): SharedClock {
+	if (!globalClock) {
+		globalClock = new SharedClock(bufferDelayMs);
+	}
+	return globalClock;
+}
+
+export function resetSharedClock(): void {
+	globalClock?.reset();
+	globalClock = undefined;
+}