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

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

@@ -0,0 +1,467 @@
+/**
+ * PeerConnectionManager
+ *
+ * Manages RTCPeerConnection lifecycle including:
+ * - Connection creation and teardown
+ * - ICE candidate gathering and exchange
+ * - Connection state monitoring
+ * - Automatic reconnection with exponential backoff
+ */
+
+import { ensureWebRTCGlobals } from './webrtc-globals';
+import {
+  TwinMessagingInterface,
+  PeerConnectionConfig,
+  SignalingMessageType,
+  DEFAULT_WEBRTC_OPTIONS,
+} from './types';
+
+export interface PeerConnectionManagerOptions {
+  connectionTimeout: number;
+  initialRetryDelay: number;
+  maxRetryDelay: number;
+}
+
+export class PeerConnectionManager {
+  private pc: RTCPeerConnection | null = null;
+  private config: PeerConnectionConfig;
+  private twinMessaging: TwinMessagingInterface;
+  private options: PeerConnectionManagerOptions;
+
+  private isShuttingDown = false;
+  private isReconnecting = false;
+  private connectionId = 0;
+  private pendingCandidates: RTCIceCandidateInit[] = [];
+  private connectionTimeout: NodeJS.Timeout | null = null;
+  private messageHandler: ((message: any) => void) | null = null;
+
+  constructor(
+    config: PeerConnectionConfig,
+    twinMessaging: TwinMessagingInterface,
+    options: Partial<PeerConnectionManagerOptions> = {}
+  ) {
+    this.config = config;
+    this.twinMessaging = twinMessaging;
+    this.options = {
+      connectionTimeout: options.connectionTimeout ?? DEFAULT_WEBRTC_OPTIONS.connectionTimeout,
+      initialRetryDelay: options.initialRetryDelay ?? DEFAULT_WEBRTC_OPTIONS.initialRetryDelay,
+      maxRetryDelay: options.maxRetryDelay ?? DEFAULT_WEBRTC_OPTIONS.maxRetryDelay,
+    };
+  }
+
+  /**
+   * Start the WebRTC connection process.
+   * Returns the RTCPeerConnection once connected.
+   */
+  async connect(): Promise<RTCPeerConnection> {
+    await ensureWebRTCGlobals();
+
+    if (this.pc && this.pc.connectionState === 'connected') {
+      return this.pc;
+    }
+
+    return this.attemptConnection(0, this.config.useStun, this.options.initialRetryDelay);
+  }
+
+  /**
+   * Get the current RTCPeerConnection (may be null if not connected)
+   */
+  getPeerConnection(): RTCPeerConnection | null {
+    return this.pc;
+  }
+
+  /**
+   * Check if the connection is currently active
+   */
+  isConnected(): boolean {
+    return this.pc?.connectionState === 'connected';
+  }
+
+  /**
+   * Close the connection and clean up resources
+   */
+  close(): void {
+    this.isShuttingDown = true;
+    this.cleanup();
+  }
+
+  /**
+   * Trigger a manual reconnection
+   */
+  reconnect(): void {
+    if (this.isReconnecting || this.isShuttingDown) {
+      return;
+    }
+    this.triggerReconnect(0);
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  private async attemptConnection(
+    retryCount: number,
+    useStun: boolean,
+    delay: number
+  ): Promise<RTCPeerConnection> {
+    if (this.isShuttingDown) {
+      throw new Error('Connection attempt cancelled - shutting down');
+    }
+
+    return new Promise((resolve, reject) => {
+      const currentConnectionId = ++this.connectionId;
+      let connectionEstablished = false;
+
+      // Create peer connection FIRST, before setting up message handler
+      console.log(`[PeerConnectionManager] Creating peer connection (useStun=${useStun}, isInitiator=${this.config.isInitiator})`);
+      this.pc = this.createPeerConnection(useStun);
+      const pc = this.pc;
+      console.log(`[PeerConnectionManager] Peer connection created: ${pc.connectionState}`);
+
+      // Setup message handler for signaling
+      this.setupMessageHandler(currentConnectionId);
+
+      // Subscribe to the target twin
+      this.twinMessaging.subscribe(this.config.targetTwinId).catch(err => {
+        console.error('[PeerConnectionManager] Failed to subscribe to twin:', err);
+      });
+
+      // Setup ICE handling
+      this.setupIceHandling(pc, currentConnectionId);
+
+      // Setup connection state monitoring
+      pc.onconnectionstatechange = () => {
+        this.config.onSignalingStateChange?.(pc.signalingState);
+
+        if (pc.connectionState === 'connected') {
+          connectionEstablished = true;
+          this.clearConnectionTimeout();
+          this.config.onConnected();
+          resolve(pc);
+        } else if (
+          pc.connectionState === 'failed' ||
+          pc.connectionState === 'disconnected' ||
+          pc.connectionState === 'closed'
+        ) {
+          if (connectionEstablished && !this.isShuttingDown) {
+            this.config.onDisconnected();
+            this.triggerReconnect(0);
+          } else if (!connectionEstablished) {
+            this.handleConnectionFailure(retryCount, useStun, delay, resolve, reject);
+          }
+        }
+      };
+
+      pc.oniceconnectionstatechange = () => {
+        this.config.onIceStateChange?.(pc.iceConnectionState);
+
+        if (pc.iceConnectionState === 'failed' && connectionEstablished) {
+          this.triggerReconnect(0);
+        }
+      };
+
+      // Call the setup callback (for adding data channels/tracks) before creating offer
+      if (this.config.onPeerConnectionCreated) {
+        try {
+          const result = this.config.onPeerConnectionCreated(pc);
+          if (result instanceof Promise) {
+            result.catch(err => console.error('[PeerConnectionManager] Error in onPeerConnectionCreated:', err));
+          }
+        } catch (err) {
+          console.error('[PeerConnectionManager] Error in onPeerConnectionCreated:', err);
+        }
+      }
+
+      // Start the offer/answer exchange if we're the initiator
+      if (this.config.isInitiator) {
+        this.createAndSendOffer(pc).catch(err => {
+          console.error('[PeerConnectionManager] Error creating offer:', err);
+          this.handleConnectionFailure(retryCount, useStun, delay, resolve, reject);
+        });
+      }
+
+      // Set connection timeout
+      this.connectionTimeout = setTimeout(() => {
+        if (!connectionEstablished) {
+          console.log(`[PeerConnectionManager] Connection timeout (${useStun ? 'with' : 'without'} STUN)`);
+          this.handleConnectionFailure(retryCount, useStun, delay, resolve, reject);
+        }
+      }, this.options.connectionTimeout);
+    });
+  }
+
+  private createPeerConnection(useStun: boolean): RTCPeerConnection {
+    const iceServers = useStun
+      ? this.config.stunServers.map(url => ({ urls: url }))
+      : [];
+
+    return new RTCPeerConnection({ iceServers });
+  }
+
+  private setupIceHandling(pc: RTCPeerConnection, connectionId: number): void {
+    pc.onicecandidate = async event => {
+      if (this.connectionId !== connectionId) return;
+
+      console.log('[PeerConnectionManager] ICE candidate:', event.candidate?.candidate || 'gathering complete');
+
+      this.config.onIceCandidate?.(event.candidate);
+
+      if (event.candidate) {
+        try {
+          console.log('[PeerConnectionManager] Sending ICE candidate');
+          await this.sendSignalingMessage('ice', event.candidate);
+        } catch (err) {
+          console.error('[PeerConnectionManager] Error sending ICE candidate:', err);
+        }
+      }
+    };
+
+    pc.onicegatheringstatechange = () => {
+      console.log('[PeerConnectionManager] ICE gathering state:', pc.iceGatheringState);
+    };
+
+    pc.oniceconnectionstatechange = () => {
+      console.log('[PeerConnectionManager] ICE connection state:', pc.iceConnectionState);
+    };
+  }
+
+  private setupMessageHandler(connectionId: number): void {
+    const ownTwinId = this.twinMessaging.getOwnTwinId();
+
+    // Remove old handler if exists
+    if (this.messageHandler) {
+      this.twinMessaging.offMessage(ownTwinId, this.messageHandler);
+    }
+
+    this.messageHandler = async (message: any) => {
+      if (this.isShuttingDown || this.connectionId !== connectionId) return;
+
+      // Filter: only process messages FROM the target peer
+      if (message.sourceTwinId !== this.config.targetTwinId) return;
+
+      try {
+        await this.handleSignalingMessage(message);
+      } catch (err) {
+        console.error('[PeerConnectionManager] Error handling signaling message:', err);
+      }
+    };
+
+    // Register on OWN twinId, filter by sourceTwinId in callback
+    this.twinMessaging.onMessage(ownTwinId, this.messageHandler);
+  }
+
+  private async handleSignalingMessage(message: any): Promise<void> {
+    if (!this.pc) return;
+
+    const messageType = message.data?.type as string;
+    if (!messageType) return;
+
+    // Extract the signal type (offer/answer/ice) from the message type
+    // Message type format: channel-{twinId}:{signalType}
+    // We match on the signal type suffix since the channelId varies by perspective
+    const prefix = `${this.config.channelPrefix}-`;
+    if (!messageType.startsWith(prefix)) return;
+
+    const signalType = messageType.split(':').pop();
+    console.log(`[PeerConnectionManager] Received signaling message: ${signalType}`);
+
+    switch (signalType) {
+      case 'offer':
+        await this.handleOffer(message.data.data);
+        break;
+
+      case 'answer':
+        await this.handleAnswer(message.data.data);
+        break;
+
+      case 'ice':
+        await this.handleIceCandidate(message.data.data);
+        break;
+    }
+  }
+
+  private async handleOffer(offer: RTCSessionDescriptionInit): Promise<void> {
+    if (!this.pc || this.config.isInitiator) {
+      return;
+    }
+
+    const pc = this.pc;
+
+    if (pc.signalingState === 'stable' || pc.signalingState === 'have-remote-offer') {
+      if (pc.signalingState === 'have-remote-offer') {
+        await pc.setLocalDescription({ type: 'rollback' });
+      }
+
+      console.log('[PeerConnectionManager] Setting remote description (offer)');
+      await pc.setRemoteDescription(offer);
+      console.log(`[PeerConnectionManager] Remote description set. signalingState=${pc.signalingState}`);
+      await this.applyPendingCandidates();
+
+      console.log('[PeerConnectionManager] Creating answer...');
+      const answer = await pc.createAnswer();
+      console.log(`[PeerConnectionManager] Answer created. type=${answer.type}`);
+
+      console.log('[PeerConnectionManager] Setting local description (answer)');
+      await pc.setLocalDescription(answer);
+      console.log(`[PeerConnectionManager] Local description set. signalingState=${pc.signalingState}, iceGatheringState=${pc.iceGatheringState}`);
+
+      await this.sendSignalingMessage('answer', answer);
+      console.log('[PeerConnectionManager] Answer sent');
+    }
+  }
+
+  private async handleAnswer(answer: RTCSessionDescriptionInit): Promise<void> {
+    if (!this.pc || !this.config.isInitiator) return;
+
+    const pc = this.pc;
+
+    if (pc.signalingState === 'have-local-offer') {
+      await pc.setRemoteDescription(answer);
+      await this.applyPendingCandidates();
+    }
+  }
+
+  private async handleIceCandidate(candidate: RTCIceCandidateInit): Promise<void> {
+    if (!this.pc) return;
+
+    if (this.pc.remoteDescription) {
+      try {
+        await this.pc.addIceCandidate(candidate);
+      } catch (err) {
+        console.error('[PeerConnectionManager] Error adding ICE candidate:', err);
+      }
+    } else {
+      this.pendingCandidates.push(candidate);
+    }
+  }
+
+  private async applyPendingCandidates(): Promise<void> {
+    if (!this.pc || this.pendingCandidates.length === 0) return;
+
+    for (const candidate of this.pendingCandidates) {
+      try {
+        await this.pc.addIceCandidate(candidate);
+      } catch (err) {
+        console.error('[PeerConnectionManager] Error applying pending ICE candidate:', err);
+      }
+    }
+
+    this.pendingCandidates = [];
+  }
+
+  private async createAndSendOffer(pc: RTCPeerConnection): Promise<void> {
+    console.log('[PeerConnectionManager] Creating offer...');
+    const offer = await pc.createOffer();
+    console.log(`[PeerConnectionManager] Offer created. type=${offer.type}`);
+
+    console.log('[PeerConnectionManager] Setting local description (offer)');
+    await pc.setLocalDescription(offer);
+    console.log(`[PeerConnectionManager] Local description set. signalingState=${pc.signalingState}, iceGatheringState=${pc.iceGatheringState}`);
+
+    await this.sendSignalingMessage('offer', offer);
+    console.log('[PeerConnectionManager] Offer sent');
+  }
+
+  private async sendSignalingMessage(
+    type: SignalingMessageType,
+    data: RTCSessionDescriptionInit | RTCIceCandidateInit | RTCIceCandidate
+  ): Promise<void> {
+    const channelId = `${this.config.channelPrefix}-${this.config.targetTwinId}`;
+
+    await this.twinMessaging.sendMessage(this.config.targetTwinId, {
+      type: `${channelId}:${type}`,
+      data,
+    });
+  }
+
+  private handleConnectionFailure(
+    retryCount: number,
+    currentUseStun: boolean,
+    delay: number,
+    resolve: (pc: RTCPeerConnection) => void,
+    reject: (error: Error) => void
+  ): void {
+    this.cleanup();
+
+    if (this.isShuttingDown) {
+      reject(new Error('Connection cancelled - shutting down'));
+      return;
+    }
+
+    // First retry: toggle STUN setting
+    if (retryCount === 0) {
+      this.attemptConnection(1, !currentUseStun, this.options.initialRetryDelay)
+        .then(resolve)
+        .catch(reject);
+      return;
+    }
+
+    // Subsequent retries: exponential backoff
+    const nextDelay = Math.min(this.options.maxRetryDelay, delay * 2);
+
+    setTimeout(() => {
+      this.attemptConnection(retryCount + 1, currentUseStun, nextDelay)
+        .then(resolve)
+        .catch(reject);
+    }, delay);
+  }
+
+  private triggerReconnect(attempt: number): void {
+    if (this.isReconnecting || this.isShuttingDown) return;
+
+    this.isReconnecting = true;
+    this.config.onReconnecting?.(attempt);
+
+    this.cleanup();
+
+    const reconnectDelay = Math.min(
+      this.options.maxRetryDelay,
+      this.options.initialRetryDelay * Math.pow(2, attempt)
+    );
+
+    setTimeout(() => {
+      this.attemptConnection(0, !this.config.useStun, this.options.initialRetryDelay)
+        .then(() => {
+          this.isReconnecting = false;
+          this.config.onReconnected?.(attempt);
+        })
+        .catch(err => {
+          console.error(`[PeerConnectionManager] Reconnection attempt ${attempt} failed:`, err);
+          this.triggerReconnect(attempt + 1);
+        });
+    }, reconnectDelay);
+  }
+
+  private clearConnectionTimeout(): void {
+    if (this.connectionTimeout) {
+      clearTimeout(this.connectionTimeout);
+      this.connectionTimeout = null;
+    }
+  }
+
+  private cleanup(): void {
+    this.clearConnectionTimeout();
+
+    if (this.messageHandler) {
+      const ownTwinId = this.twinMessaging.getOwnTwinId();
+      this.twinMessaging.offMessage(ownTwinId, this.messageHandler);
+      this.messageHandler = null;
+    }
+
+    if (this.pc) {
+      this.pc.onicecandidate = null;
+      this.pc.onconnectionstatechange = null;
+      this.pc.oniceconnectionstatechange = null;
+
+      try {
+        this.pc.close();
+      } catch (err) {
+        console.error('[PeerConnectionManager] Error closing peer connection:', err);
+      }
+
+      this.pc = null;
+    }
+
+    this.pendingCandidates = [];
+  }
+}