@phystack/hub-client 4.5.19-dev → 4.5.20-dev

package/src/services/webrtc/webrtc-manager.ts

@@ -0,0 +1,490 @@
+/**
+ * WebRTCManager
+ *
+ * Main entry point for WebRTC functionality. Provides:
+ * - Simple API for DataChannel and MediaStream connections
+ * - Event system with opt-in verbose mode
+ * - Connection management and lifecycle handling
+ * - Automatic reconnection (transparent to developers)
+ */
+
+import { DataChannelHandler } from './data-channel-handler';
+import { MediaStreamHandler } from './media-stream-handler';
+import { ensureWebRTCGlobals, isWebRTCAvailable } from './webrtc-globals';
+import {
+  TwinMessagingInterface,
+  WebRTCManagerOptions,
+  WebRTCEvent,
+  WebRTCEventData,
+  WebRTCEventCallback,
+  PhygridDataChannel,
+  PhygridMediaStream,
+  MediaStreamOptions,
+  DEFAULT_WEBRTC_OPTIONS,
+} from './types';
+
+type DataChannelCallback = (channel: PhygridDataChannel, sourceTwinId: string) => void;
+type MediaStreamCallback = (stream: PhygridMediaStream, sourceTwinId: string) => void;
+
+export class WebRTCManager {
+  private twinMessaging: TwinMessagingInterface;
+  private options: Required<WebRTCManagerOptions>;
+
+  // Active connections by "{targetTwinId}:{channelName}"
+  private dataChannelHandlers: Map<string, DataChannelHandler> = new Map();
+  private mediaStreamHandlers: Map<string, MediaStreamHandler> = new Map();
+
+  // Listeners for incoming connections
+  private dataChannelListeners: Set<DataChannelCallback> = new Set();
+  private mediaStreamListeners: Set<MediaStreamCallback> = new Set();
+
+  // Event listeners
+  private eventListeners: Map<WebRTCEvent, Set<WebRTCEventCallback<any>>> = new Map();
+
+  private isInitialized = false;
+  private isClosed = false;
+
+  constructor(twinMessaging: TwinMessagingInterface, options: WebRTCManagerOptions = {}) {
+    this.twinMessaging = twinMessaging;
+    this.options = {
+      verbose: options.verbose ?? DEFAULT_WEBRTC_OPTIONS.verbose,
+      useStun: options.useStun ?? DEFAULT_WEBRTC_OPTIONS.useStun,
+      stunServers: options.stunServers ?? DEFAULT_WEBRTC_OPTIONS.stunServers,
+      connectionTimeout: options.connectionTimeout ?? DEFAULT_WEBRTC_OPTIONS.connectionTimeout,
+      initialRetryDelay: options.initialRetryDelay ?? DEFAULT_WEBRTC_OPTIONS.initialRetryDelay,
+      maxRetryDelay: options.maxRetryDelay ?? DEFAULT_WEBRTC_OPTIONS.maxRetryDelay,
+    };
+  }
+
+  // ===========================================================================
+  // DataChannel API
+  // ===========================================================================
+
+  /**
+   * Create a DataChannel connection to a target twin.
+   * Returns a PhygridDataChannel for sending/receiving messages.
+   * @param targetTwinId - The twin ID to connect to
+   * @param channelName - Optional channel name for multiple channels to same peer (default: 'default')
+   */
+  async createDataChannel(targetTwinId: string, channelName: string = 'default'): Promise<PhygridDataChannel> {
+    await this.ensureInitialized();
+
+    if (this.isClosed) {
+      throw new Error('WebRTCManager has been closed');
+    }
+
+    // Key includes channel name to support multiple channels per peer
+    const handlerKey = `${targetTwinId}:${channelName}`;
+
+    // Check for existing connection
+    const existing = this.dataChannelHandlers.get(handlerKey);
+    if (existing) {
+      // Return a new channel to the same target
+      return existing.connect();
+    }
+
+    const handler = new DataChannelHandler(
+      targetTwinId,
+      true, // isInitiator
+      this.twinMessaging,
+      {
+        useStun: this.options.useStun,
+        stunServers: this.options.stunServers,
+        connectionTimeout: this.options.connectionTimeout,
+        initialRetryDelay: this.options.initialRetryDelay,
+        maxRetryDelay: this.options.maxRetryDelay,
+      },
+      channelName
+    );
+
+    this.setupDataChannelHandlerCallbacks(handler, targetTwinId);
+    this.dataChannelHandlers.set(handlerKey, handler);
+
+    try {
+      return await handler.connect();
+    } catch (error) {
+      this.dataChannelHandlers.delete(handlerKey);
+      throw error;
+    }
+  }
+
+  /**
+   * Listen for incoming DataChannel connections.
+   * The callback is called when a remote peer initiates a connection.
+   */
+  onDataChannel(callback: DataChannelCallback): void {
+    this.dataChannelListeners.add(callback);
+  }
+
+  /**
+   * Stop listening for incoming DataChannel connections.
+   */
+  offDataChannel(callback: DataChannelCallback): void {
+    this.dataChannelListeners.delete(callback);
+  }
+
+  /**
+   * Accept an incoming DataChannel connection from a specific twin.
+   * Call this when you know a twin will initiate a connection.
+   * @param sourceTwinId - The twin ID that will initiate the connection
+   * @param channelName - Optional channel name for multiple channels (default: 'default')
+   */
+  async acceptDataChannel(sourceTwinId: string, channelName: string = 'default'): Promise<PhygridDataChannel> {
+    await this.ensureInitialized();
+
+    if (this.isClosed) {
+      throw new Error('WebRTCManager has been closed');
+    }
+
+    // Key includes channel name to support multiple channels per peer
+    const handlerKey = `${sourceTwinId}:${channelName}`;
+
+    const handler = new DataChannelHandler(
+      sourceTwinId,
+      false, // not initiator (responder)
+      this.twinMessaging,
+      {
+        useStun: this.options.useStun,
+        stunServers: this.options.stunServers,
+        connectionTimeout: this.options.connectionTimeout,
+        initialRetryDelay: this.options.initialRetryDelay,
+        maxRetryDelay: this.options.maxRetryDelay,
+      },
+      channelName
+    );
+
+    this.setupDataChannelHandlerCallbacks(handler, sourceTwinId);
+    this.dataChannelHandlers.set(handlerKey, handler);
+
+    try {
+      const channel = await handler.connect();
+
+      // Notify listeners
+      this.dataChannelListeners.forEach((listener) => {
+        try {
+          listener(channel, sourceTwinId);
+        } catch (err) {
+          console.error('[WebRTCManager] Error in DataChannel listener:', err);
+        }
+      });
+
+      return channel;
+    } catch (error) {
+      this.dataChannelHandlers.delete(handlerKey);
+      throw error;
+    }
+  }
+
+  // ===========================================================================
+  // MediaStream API
+  // ===========================================================================
+
+  /**
+   * Create a MediaStream connection to a target twin.
+   * Returns a PhygridMediaStream for sending/receiving media.
+   * @param targetTwinId - The twin ID to connect to
+   * @param options - Optional MediaStream options
+   * @param channelName - Optional channel name for multiple streams to same peer (default: 'default')
+   */
+  async createMediaStream(
+    targetTwinId: string,
+    options?: MediaStreamOptions,
+    channelName: string = 'default'
+  ): Promise<PhygridMediaStream> {
+    await this.ensureInitialized();
+
+    if (this.isClosed) {
+      throw new Error('WebRTCManager has been closed');
+    }
+
+    // Key includes channel name to support multiple streams per peer
+    const handlerKey = `${targetTwinId}:${channelName}`;
+
+    // Check for existing connection
+    const existing = this.mediaStreamHandlers.get(handlerKey);
+    if (existing) {
+      return existing.connect();
+    }
+
+    const handler = new MediaStreamHandler(
+      targetTwinId,
+      true, // isInitiator
+      this.twinMessaging,
+      {
+        useStun: this.options.useStun,
+        stunServers: this.options.stunServers,
+        connectionTimeout: this.options.connectionTimeout,
+        initialRetryDelay: this.options.initialRetryDelay,
+        maxRetryDelay: this.options.maxRetryDelay,
+        mediaOptions: options,
+      },
+      channelName
+    );
+
+    this.setupMediaStreamHandlerCallbacks(handler, targetTwinId);
+    this.mediaStreamHandlers.set(handlerKey, handler);
+
+    try {
+      return await handler.connect();
+    } catch (error) {
+      this.mediaStreamHandlers.delete(handlerKey);
+      throw error;
+    }
+  }
+
+  /**
+   * Listen for incoming MediaStream connections.
+   * The callback is called when a remote peer initiates a connection.
+   */
+  onMediaStream(callback: MediaStreamCallback): void {
+    this.mediaStreamListeners.add(callback);
+  }
+
+  /**
+   * Stop listening for incoming MediaStream connections.
+   */
+  offMediaStream(callback: MediaStreamCallback): void {
+    this.mediaStreamListeners.delete(callback);
+  }
+
+  /**
+   * Accept an incoming MediaStream connection from a specific twin.
+   * Call this when you know a twin will initiate a connection.
+   * @param sourceTwinId - The twin ID that will initiate the connection
+   * @param options - Optional MediaStream options
+   * @param channelName - Optional channel name for multiple streams (default: 'default')
+   */
+  async acceptMediaStream(
+    sourceTwinId: string,
+    options?: MediaStreamOptions,
+    channelName: string = 'default'
+  ): Promise<PhygridMediaStream> {
+    await this.ensureInitialized();
+
+    if (this.isClosed) {
+      throw new Error('WebRTCManager has been closed');
+    }
+
+    // Key includes channel name to support multiple streams per peer
+    const handlerKey = `${sourceTwinId}:${channelName}`;
+
+    const handler = new MediaStreamHandler(
+      sourceTwinId,
+      false, // not initiator (responder)
+      this.twinMessaging,
+      {
+        useStun: this.options.useStun,
+        stunServers: this.options.stunServers,
+        connectionTimeout: this.options.connectionTimeout,
+        initialRetryDelay: this.options.initialRetryDelay,
+        maxRetryDelay: this.options.maxRetryDelay,
+        mediaOptions: options,
+      },
+      channelName
+    );
+
+    this.setupMediaStreamHandlerCallbacks(handler, sourceTwinId);
+    this.mediaStreamHandlers.set(handlerKey, handler);
+
+    try {
+      const stream = await handler.connect();
+
+      // Notify listeners
+      this.mediaStreamListeners.forEach((listener) => {
+        try {
+          listener(stream, sourceTwinId);
+        } catch (err) {
+          console.error('[WebRTCManager] Error in MediaStream listener:', err);
+        }
+      });
+
+      return stream;
+    } catch (error) {
+      this.mediaStreamHandlers.delete(handlerKey);
+      throw error;
+    }
+  }
+
+  // ===========================================================================
+  // Event API
+  // ===========================================================================
+
+  /**
+   * Subscribe to WebRTC events.
+   *
+   * Standard events (always available):
+   * - 'connected': Connection established
+   * - 'disconnected': Connection lost
+   * - 'error': An error occurred
+   *
+   * Verbose events (when options.verbose is true):
+   * - 'reconnecting': Attempting to reconnect
+   * - 'reconnected': Successfully reconnected
+   * - 'ice-state-change': ICE connection state changed
+   * - 'signaling-state-change': Signaling state changed
+   * - 'ice-candidate': ICE candidate received
+   */
+  on<E extends WebRTCEvent>(event: E, callback: WebRTCEventCallback<E>): void {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    this.eventListeners.get(event)!.add(callback);
+  }
+
+  /**
+   * Unsubscribe from WebRTC events.
+   */
+  off<E extends WebRTCEvent>(event: E, callback: WebRTCEventCallback<E>): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(callback);
+    }
+  }
+
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+
+  /**
+   * Check if WebRTC is available in the current environment.
+   */
+  static isAvailable(): boolean {
+    return isWebRTCAvailable();
+  }
+
+  /**
+   * Get active DataChannel connection count.
+   */
+  getActiveDataChannelCount(): number {
+    return this.dataChannelHandlers.size;
+  }
+
+  /**
+   * Get active MediaStream connection count.
+   */
+  getActiveMediaStreamCount(): number {
+    return this.mediaStreamHandlers.size;
+  }
+
+  /**
+   * Close all connections and clean up resources.
+   */
+  close(): void {
+    if (this.isClosed) return;
+
+    this.isClosed = true;
+
+    // Close all DataChannel handlers
+    this.dataChannelHandlers.forEach((handler) => {
+      try {
+        handler.close();
+      } catch (err) {
+        console.error('[WebRTCManager] Error closing DataChannel handler:', err);
+      }
+    });
+    this.dataChannelHandlers.clear();
+
+    // Close all MediaStream handlers
+    this.mediaStreamHandlers.forEach((handler) => {
+      try {
+        handler.close();
+      } catch (err) {
+        console.error('[WebRTCManager] Error closing MediaStream handler:', err);
+      }
+    });
+    this.mediaStreamHandlers.clear();
+
+    // Clear listeners
+    this.dataChannelListeners.clear();
+    this.mediaStreamListeners.clear();
+    this.eventListeners.clear();
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.isInitialized) return;
+
+    await ensureWebRTCGlobals();
+    this.isInitialized = true;
+  }
+
+  private setupDataChannelHandlerCallbacks(
+    handler: DataChannelHandler,
+    targetTwinId: string
+  ): void {
+    handler.setCallbacks({
+      onConnected: () => {
+        this.emit('connected', { targetTwinId, connectionType: 'datachannel' });
+      },
+      onDisconnected: () => {
+        this.emit('disconnected', { targetTwinId, connectionType: 'datachannel' });
+      },
+      onError: (error) => {
+        this.emit('error', { targetTwinId, error });
+      },
+      onReconnecting: (attempt) => {
+        if (this.options.verbose) {
+          this.emit('reconnecting', { targetTwinId, attempt });
+        }
+      },
+      onReconnected: (attempt) => {
+        if (this.options.verbose) {
+          this.emit('reconnected', { targetTwinId, attempt });
+        }
+      },
+    });
+  }
+
+  private setupMediaStreamHandlerCallbacks(
+    handler: MediaStreamHandler,
+    targetTwinId: string
+  ): void {
+    handler.setCallbacks({
+      onConnected: () => {
+        this.emit('connected', { targetTwinId, connectionType: 'mediastream' });
+      },
+      onDisconnected: () => {
+        this.emit('disconnected', { targetTwinId, connectionType: 'mediastream' });
+      },
+      onError: (error) => {
+        this.emit('error', { targetTwinId, error });
+      },
+      onReconnecting: (attempt) => {
+        if (this.options.verbose) {
+          this.emit('reconnecting', { targetTwinId, attempt });
+        }
+      },
+      onReconnected: (attempt) => {
+        if (this.options.verbose) {
+          this.emit('reconnected', { targetTwinId, attempt });
+        }
+      },
+    });
+  }
+
+  private emit<E extends WebRTCEvent>(event: E, data: WebRTCEventData[E]): void {
+    const listeners = this.eventListeners.get(event);
+    if (!listeners) return;
+
+    listeners.forEach((callback) => {
+      try {
+        callback(data);
+      } catch (err) {
+        console.error(`[WebRTCManager] Error in ${event} event listener:`, err);
+      }
+    });
+  }
+}
+
+// Re-export types for convenience
+export {
+  TwinMessagingInterface,
+  WebRTCManagerOptions,
+  WebRTCEvent,
+  PhygridDataChannel,
+  PhygridMediaStream,
+  MediaStreamOptions,
+} from './types';