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

package/src/services/webrtc/data-channel-handler.ts

@@ -0,0 +1,362 @@
+/**
+ * DataChannelHandler
+ *
+ * Manages RTCDataChannel lifecycle including:
+ * - Channel creation (initiator) or reception (responder)
+ * - Message serialization/deserialization
+ * - Persistent channel abstraction across reconnections
+ * - Message buffering during reconnection
+ */
+
+import { PeerConnectionManager, PeerConnectionManagerOptions } from './peer-connection-manager';
+import {
+  TwinMessagingInterface,
+  PhygridDataChannel,
+  PeerConnectionConfig,
+  DEFAULT_WEBRTC_OPTIONS,
+} from './types';
+
+export interface DataChannelHandlerOptions extends Partial<PeerConnectionManagerOptions> {
+  /** Use STUN servers. Default: true */
+  useStun?: boolean;
+
+  /** STUN server URLs */
+  stunServers?: string[];
+}
+
+export class DataChannelHandler {
+  private targetTwinId: string;
+  private channelName: string;
+  private isInitiator: boolean;
+  private twinMessaging: TwinMessagingInterface;
+  private options: Required<DataChannelHandlerOptions>;
+
+  private pcManager: PeerConnectionManager | null = null;
+  private dataChannel: RTCDataChannel | null = null;
+  private isOpen = false;
+  private isClosed = false;
+
+  // Connection status
+  private isConnecting = false;
+
+  // Event listeners
+  private messageListeners: Set<(data: any) => void> = new Set();
+  private closeListeners: Set<() => void> = new Set();
+
+  // Callbacks for WebRTCManager
+  private onConnectedCallback?: () => void;
+  private onDisconnectedCallback?: () => void;
+  private onErrorCallback?: (error: Error) => void;
+  private onReconnectingCallback?: (attempt: number) => void;
+  private onReconnectedCallback?: (attempt: number) => void;
+
+  constructor(
+    targetTwinId: string,
+    isInitiator: boolean,
+    twinMessaging: TwinMessagingInterface,
+    options: DataChannelHandlerOptions = {},
+    channelName: string = 'default'
+  ) {
+    this.targetTwinId = targetTwinId;
+    this.channelName = channelName;
+    this.isInitiator = isInitiator;
+    this.twinMessaging = twinMessaging;
+    this.options = {
+      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,
+    };
+  }
+
+  /**
+   * Set callbacks for connection events
+   */
+  setCallbacks(callbacks: {
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onError?: (error: Error) => void;
+    onReconnecting?: (attempt: number) => void;
+    onReconnected?: (attempt: number) => void;
+  }): void {
+    this.onConnectedCallback = callbacks.onConnected;
+    this.onDisconnectedCallback = callbacks.onDisconnected;
+    this.onErrorCallback = callbacks.onError;
+    this.onReconnectingCallback = callbacks.onReconnecting;
+    this.onReconnectedCallback = callbacks.onReconnected;
+  }
+
+  /**
+   * Connect and return a PhygridDataChannel
+   */
+  async connect(): Promise<PhygridDataChannel> {
+    if (this.isClosed) {
+      throw new Error('DataChannelHandler has been closed');
+    }
+
+    this.isConnecting = true;
+    // Channel ID includes the name to support multiple channels to same peer
+    const channelId = `dc-${this.channelName}-${this.targetTwinId}`;
+    // Prefix for signaling messages - unique per channel name
+    const channelPrefix = `dc-${this.channelName}`;
+
+    const pcConfig: PeerConnectionConfig = {
+      targetTwinId: this.targetTwinId,
+      isInitiator: this.isInitiator,
+      connectionType: 'datachannel',
+      channelPrefix,
+      useStun: this.options.useStun,
+      stunServers: this.options.stunServers,
+      onConnected: () => this.handlePeerConnected(),
+      onDisconnected: () => this.handlePeerDisconnected(),
+      onError: (err) => this.handleError(err),
+      onReconnecting: (attempt) => {
+        this.isConnecting = true;
+        this.isOpen = false;
+        // Clear old data channel reference - new one will be created/received
+        this.dataChannel = null;
+        this.onReconnectingCallback?.(attempt);
+      },
+      onReconnected: (attempt) => this.handleReconnected(attempt),
+      // Setup data channel/handler before signaling begins
+      onPeerConnectionCreated: (pc) => {
+        if (this.isInitiator) {
+          // Initiator: Create data channel before offer is sent
+          console.log('[DataChannelHandler] Creating data channel before offer');
+          this.dataChannel = pc.createDataChannel(channelId);
+          this.dataChannel.binaryType = 'arraybuffer';
+        } else {
+          // Responder: Set up ondatachannel handler BEFORE receiving offer
+          // This ensures we don't miss the datachannel event
+          console.log('[DataChannelHandler] Setting up ondatachannel handler');
+          pc.ondatachannel = (event) => {
+            console.log('[DataChannelHandler] Received data channel from initiator');
+            this.dataChannel = event.channel;
+            this.dataChannel.binaryType = 'arraybuffer';
+            this.attachDataChannelHandlers(this.dataChannel, () => {
+              // No-op: Channel setup is complete. Handler registration and callbacks
+              // are managed inside attachDataChannelHandlers.
+            });
+          };
+        }
+      },
+    };
+
+    this.pcManager = new PeerConnectionManager(pcConfig, this.twinMessaging, {
+      connectionTimeout: this.options.connectionTimeout,
+      initialRetryDelay: this.options.initialRetryDelay,
+      maxRetryDelay: this.options.maxRetryDelay,
+    });
+
+    const pc = await this.pcManager.connect();
+    await this.setupDataChannel(pc);
+
+    return this.createPhygridDataChannel();
+  }
+
+  /**
+   * Close the data channel and clean up
+   */
+  close(): void {
+    if (this.isClosed) return;
+
+    this.isClosed = true;
+    this.isOpen = false;
+
+    if (this.dataChannel) {
+      try {
+        this.dataChannel.close();
+      } catch (err) {
+        console.error('[DataChannelHandler] Error closing data channel:', err);
+      }
+      this.dataChannel = null;
+    }
+
+    if (this.pcManager) {
+      this.pcManager.close();
+      this.pcManager = null;
+    }
+
+    this.notifyCloseListeners();
+    this.messageListeners.clear();
+    this.closeListeners.clear();
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  private async setupDataChannel(pc: RTCPeerConnection): Promise<void> {
+    return new Promise((resolve) => {
+      // Data channel was already created/received in onPeerConnectionCreated
+      // Just need to attach handlers if not already done
+      if (this.dataChannel) {
+        this.attachDataChannelHandlers(this.dataChannel, resolve);
+      } else if (this.isInitiator) {
+        // Fallback: create data channel now (shouldn't happen normally)
+        const channelId = `channel-${this.targetTwinId}`;
+        this.dataChannel = pc.createDataChannel(channelId);
+        this.dataChannel.binaryType = 'arraybuffer';
+        this.attachDataChannelHandlers(this.dataChannel, resolve);
+      } else {
+        // Responder: ondatachannel handler should already be set,
+        // but it may not have fired yet - we'll resolve when it does
+        const existingHandler = pc.ondatachannel;
+        pc.ondatachannel = (event) => {
+          existingHandler?.call(pc, event);
+          resolve();
+        };
+      }
+    });
+  }
+
+  private attachDataChannelHandlers(dc: RTCDataChannel, onReady: () => void): void {
+    dc.onopen = () => {
+      this.isOpen = true;
+      this.isConnecting = false;
+      this.onConnectedCallback?.();
+      onReady();
+    };
+
+    dc.onmessage = (event) => {
+      this.handleMessage(event.data);
+    };
+
+    dc.onclose = () => {
+      this.isOpen = false;
+      if (!this.isClosed) {
+        this.onDisconnectedCallback?.();
+      }
+    };
+
+    dc.onerror = (event) => {
+      const error = new Error(`DataChannel error: ${(event as any).error?.message || 'Unknown error'}`);
+      this.handleError(error);
+    };
+
+    // If already open (can happen on reconnect), resolve immediately
+    if (dc.readyState === 'open') {
+      this.isOpen = true;
+      this.isConnecting = false;
+      onReady();
+    }
+  }
+
+  private handleMessage(data: string | ArrayBuffer): void {
+    let parsedData = data;
+
+    // Try to parse JSON strings
+    if (typeof data === 'string') {
+      try {
+        parsedData = JSON.parse(data);
+      } catch {
+        // Not JSON, use as-is
+      }
+    }
+
+    this.messageListeners.forEach((listener) => {
+      try {
+        listener(parsedData);
+      } catch (err) {
+        console.error('[DataChannelHandler] Error in message listener:', err);
+      }
+    });
+  }
+
+  private handlePeerConnected(): void {
+    // No-op: Peer connection is established but we don't need to do anything here.
+    // DataChannel setup is handled by onPeerConnectionCreated callback.
+  }
+
+  private handlePeerDisconnected(): void {
+    this.isOpen = false;
+    this.onDisconnectedCallback?.();
+  }
+
+  private handleReconnected(attempt: number): void {
+    // Re-setup data channel after reconnection
+    const pc = this.pcManager?.getPeerConnection();
+    if (pc) {
+      this.setupDataChannel(pc).catch((err) => {
+        console.error('[DataChannelHandler] Error re-setting up data channel:', err);
+      });
+    }
+    this.onReconnectedCallback?.(attempt);
+  }
+
+  private handleError(error: Error): void {
+    console.error('[DataChannelHandler] DataChannel error:', error);
+    this.onErrorCallback?.(error);
+  }
+
+
+  private notifyCloseListeners(): void {
+    this.closeListeners.forEach((listener) => {
+      try {
+        listener();
+      } catch (err) {
+        console.error('[DataChannelHandler] Error in close listener:', err);
+      }
+    });
+  }
+
+  private createPhygridDataChannel(): PhygridDataChannel {
+    return {
+      send: (data: string | ArrayBuffer | object) => {
+        let messageToSend: string | ArrayBuffer;
+
+        if (typeof data === 'object' && !(data instanceof ArrayBuffer)) {
+          messageToSend = JSON.stringify(data);
+        } else {
+          messageToSend = data as string | ArrayBuffer;
+        }
+
+        if (this.dataChannel?.readyState === 'open') {
+          try {
+            this.dataChannel.send(messageToSend as any);
+          } catch (err) {
+            console.error('[DataChannelHandler] Error sending message:', err);
+          }
+        }
+        // If not open, silently drop the message - no buffering
+      },
+
+      onMessage: (callback: (data: any) => void) => {
+        this.messageListeners.add(callback);
+      },
+
+      offMessage: (callback: (data: any) => void) => {
+        this.messageListeners.delete(callback);
+      },
+
+      onClose: (callback: () => void) => {
+        this.closeListeners.add(callback);
+      },
+
+      offClose: (callback: () => void) => {
+        this.closeListeners.delete(callback);
+      },
+
+      close: () => {
+        this.close();
+      },
+
+      isOpen: () => {
+        return this.isOpen && this.dataChannel?.readyState === 'open';
+      },
+
+      isConnecting: () => {
+        return this.isConnecting;
+      },
+
+      getTargetTwinId: () => {
+        return this.targetTwinId;
+      },
+
+      getChannelName: () => {
+        return this.channelName;
+      },
+    };
+  }
+}

package/src/services/webrtc/index.ts

@@ -0,0 +1,36 @@
+/**
+ * WebRTC Module Exports
+ *
+ * This module provides WebRTC functionality for peer-to-peer
+ * DataChannel and MediaStream connections between twins.
+ */
+
+// Main manager class
+export { WebRTCManager } from './webrtc-manager';
+
+// Handler classes (for advanced usage)
+export { DataChannelHandler } from './data-channel-handler';
+export { MediaStreamHandler } from './media-stream-handler';
+export { PeerConnectionManager } from './peer-connection-manager';
+
+// Globals utilities
+export { ensureWebRTCGlobals, isWebRTCAvailable, isWebRTCInitialized } from './webrtc-globals';
+
+// Types
+export type {
+  TwinMessagingInterface,
+  WebRTCManagerOptions,
+  WebRTCEvent,
+  WebRTCStandardEvent,
+  WebRTCVerboseEvent,
+  WebRTCEventData,
+  WebRTCEventCallback,
+  PhygridDataChannel,
+  PhygridMediaStream,
+  MediaStreamOptions,
+  ExtendedMediaStreamTrack,
+  ConnectionType,
+  ConnectionState,
+} from './types';
+
+export { DEFAULT_WEBRTC_OPTIONS } from './types';