@unboundcx/video-sdk-client 2.0.0 → 2.0.1

package/managers/ConnectionHealthMonitor.js

@@ -0,0 +1,278 @@
+import { Logger } from '../utils/Logger.js';
+
+// ConnectionHealthMonitor — unifies three signals into a single user-facing
+// connection state so the host UI doesn't have to stitch them together:
+//
+//   1) Transport events  (event-driven)  — fast path for clean failures
+//        mediasoup transport connectionstatechange → failed/disconnected
+//   2) Socket disconnect (event-driven)  — Socket.IO has died
+//   3) Liveness heartbeat (poll-driven)  — catches degraded networks where
+//        the OS/socket layer hasn't admitted the problem yet. If we haven't
+//        heard *anything* from the server in N seconds while we still think
+//        we're connected, we are not actually connected.
+//
+// This is critical for genuinely bad networks: ICE can sit in `disconnected`
+// for 30+ seconds before flipping to `failed`, and Socket.IO heartbeats are
+// slow (default ~25s). The user is suffering long before any event arrives.
+// The heartbeat ensures we surface an `unstable` state in ~5s of silence.
+//
+// Emits a single 'connection' event with shape:
+//   { state, prevState, reason, durationMs, at }
+// where state ∈ { connected, unstable, reconnecting, failed }
+//
+//   connected     — happy path
+//   unstable      — silence detected by heartbeat, OR transport disconnected
+//                   transiently; expect auto-recovery
+//   reconnecting  — socket gone OR transport failed; SDK is actively trying
+//   failed        — give-up threshold exceeded (still trying, but tell the
+//                   user it's not transient)
+//
+// The monitor never closes anything itself. It only observes and reports.
+
+const DEFAULTS = {
+  heartbeatIntervalMs: 2000,
+  // If we've heard nothing in this long while nominally connected, flip
+  // to 'unstable'. Set above Socket.IO's default engine ping interval
+  // (~25s) so quiet rooms don't get false unstable flips — solo /
+  // muted-but-fine sessions only see traffic every 10–25s, and
+  // anything shorter than that produces a yellow banner that
+  // flashes on/off as packets dribble in.
+  silenceUnstableMs: 30000,
+  // Pure silence alone never drives us past 'unstable' — escalation to
+  // 'reconnecting' requires corroborating evidence (socket dead or
+  // transport failed) unless silence exceeds this hard cap, which is
+  // well past Socket.IO's own ping timeout (~25s) plus a safety
+  // margin, and so means the engine itself has truly gone quiet.
+  silenceReconnectingMs: 60000,
+  // Time in reconnecting before we declare failed (still trying — UI
+  // should escalate copy from "Reconnecting…" to "Connection lost").
+  failedAfterMs: 15000,
+  // After we re-enter connected, wait this long before emitting the
+  // recovery event. Prevents flapping spam.
+  recoveryHoldMs: 1500,
+};
+
+export class ConnectionHealthMonitor {
+  constructor({
+    connectionManager,
+    mediasoupManager,
+    statsCollector,
+    onConnectionEvent,
+    options = {},
+    debug = false,
+  } = {}) {
+    this.logger = new Logger('SDK:ConnectionHealthMonitor', debug);
+    this.connection = connectionManager;
+    this.mediasoup = mediasoupManager || null;
+    this.statsCollector = statsCollector || null;
+    this.onEvent = typeof onConnectionEvent === 'function' ? onConnectionEvent : () => {};
+    this.opts = { ...DEFAULTS, ...options };
+
+    this._state = 'connected';
+    this._stateSince = Date.now();
+    this._lastActivityAt = Date.now();
+    this._timer = null;
+    this._started = false;
+    this._unsubs = [];
+
+    // Track transport-level state independently of socket-level state so
+    // we can report the right reason in the event payload.
+    this._transportState = { send: 'new', recv: 'new' };
+    this._socketAlive = true;
+  }
+
+  start() {
+    if (this._started) return;
+    this._started = true;
+    this._lastActivityAt = Date.now();
+    this._wireConnection();
+    this._wireStats();
+    this._wireMediasoup();
+    this._timer = setInterval(() => this._tick(), this.opts.heartbeatIntervalMs);
+    this.logger.info('start');
+  }
+
+  stop() {
+    if (!this._started) return;
+    this._started = false;
+    if (this._timer) clearInterval(this._timer);
+    this._timer = null;
+    for (const off of this._unsubs) {
+      try { off(); } catch {}
+    }
+    this._unsubs = [];
+  }
+
+  // Public: call this whenever we know we just heard from the server
+  // (any socket message, any stats sample). The wiring below already
+  // does this for the common cases — exposed for hosts that want to
+  // mark explicit liveness pings.
+  markActivity() {
+    this._lastActivityAt = Date.now();
+    // Hearing from the server is sufficient evidence the connection is
+    // alive. If we'd flipped to unstable purely on silence, recover.
+    if (this._state === 'unstable' && this._socketAlive && !this._transportFailed()) {
+      this._transition('connected', 'activity-resumed');
+    }
+  }
+
+  getSnapshot() {
+    return {
+      state: this._state,
+      stateSince: this._stateSince,
+      durationMs: Date.now() - this._stateSince,
+      lastActivityAt: this._lastActivityAt,
+      silenceMs: Date.now() - this._lastActivityAt,
+      socketAlive: this._socketAlive,
+      transportState: { ...this._transportState },
+      thresholds: { ...this.opts },
+    };
+  }
+
+  // ---- wiring -----------------------------------------------------------
+
+  _wireConnection() {
+    if (!this.connection || typeof this.connection.on !== 'function') return;
+
+    const onConnected = () => {
+      this._socketAlive = true;
+      this._lastActivityAt = Date.now();
+      // Don't immediately flip to connected — let recoveryHold gate it
+      // so we don't spam connect→reconnect→connect during a flap.
+      if (this._state !== 'connected') {
+        this._transition('connected', 'socket-reconnected');
+      }
+    };
+    const onDisconnected = (data) => {
+      this._socketAlive = false;
+      this._transition('reconnecting', `socket-disconnected:${data?.reason || 'unknown'}`);
+    };
+    // Treat any socket message as proof of life. ConnectionManager re-emits
+    // 'message' for arbitrary payloads; if not present, the heartbeat alone
+    // still catches silence.
+    const onMessage = () => this.markActivity();
+
+    this.connection.on('connected', onConnected);
+    this.connection.on('disconnected', onDisconnected);
+    if (typeof this.connection.on === 'function') {
+      this.connection.on('message', onMessage);
+    }
+
+    this._unsubs.push(() => {
+      try { this.connection.off?.('connected', onConnected); } catch {}
+      try { this.connection.off?.('disconnected', onDisconnected); } catch {}
+      try { this.connection.off?.('message', onMessage); } catch {}
+    });
+  }
+
+  _wireStats() {
+    if (!this.statsCollector) return;
+    // Every stats sample = proof of life from the WebRTC side.
+    const cb = () => this.markActivity();
+    if (typeof this.statsCollector.addInternalCallback === 'function') {
+      const off = this.statsCollector.addInternalCallback(cb);
+      this._unsubs.push(off);
+    }
+  }
+
+  _wireMediasoup() {
+    if (!this.mediasoup || typeof this.mediasoup.on !== 'function') return;
+    const onTransportState = ({ direction, state }) => {
+      if (direction === 'send' || direction === 'recv') {
+        this._transportState[direction] = state;
+      }
+      if (state === 'failed') {
+        this._transition('reconnecting', `transport-${direction}-failed`);
+      } else if (state === 'disconnected') {
+        // Transient — escalate to unstable, let heartbeat decide if it
+        // becomes reconnecting.
+        if (this._state === 'connected') {
+          this._transition('unstable', `transport-${direction}-disconnected`);
+        }
+      } else if (state === 'connected' || state === 'completed') {
+        if (this._state === 'unstable' && !this._transportFailed() && this._socketAlive) {
+          this._transition('connected', `transport-${direction}-recovered`);
+        }
+      }
+    };
+    this.mediasoup.on('transport:state', onTransportState);
+    // MediasoupManager also emits transport:closed for the failed case
+    // — surface that too.
+    const onTransportClosed = ({ direction, state }) => {
+      if (direction === 'send' || direction === 'recv') {
+        this._transportState[direction] = state || 'closed';
+      }
+      if (state === 'failed') {
+        this._transition('reconnecting', `transport-${direction}-closed`);
+      }
+    };
+    this.mediasoup.on('transport:closed', onTransportClosed);
+    this._unsubs.push(() => {
+      try { this.mediasoup.off?.('transport:state', onTransportState); } catch {}
+      try { this.mediasoup.off?.('transport:closed', onTransportClosed); } catch {}
+    });
+  }
+
+  // ---- heartbeat --------------------------------------------------------
+
+  _tick() {
+    const now = Date.now();
+    const silence = now - this._lastActivityAt;
+    const inState = now - this._stateSince;
+
+    // Silence-based escalation. 'unstable' is a soft hint we'll fire on
+    // pure silence, but escalation past that requires corroboration:
+    // either the socket actually dropped, a transport failed, or silence
+    // has run long past Socket.IO's own ping timeout (the engine itself
+    // is quiet, which is real evidence). This prevents an idle-but-fine
+    // session (e.g. host alone in the room) from cascading to "failed".
+    const hasCorroboration =
+      !this._socketAlive ||
+      this._transportFailed() ||
+      silence >= this.opts.silenceReconnectingMs;
+
+    if (this._state === 'connected' && silence >= this.opts.silenceUnstableMs) {
+      this._transition('unstable', `silence:${silence}ms`);
+    } else if (this._state === 'unstable' && hasCorroboration) {
+      this._transition(
+        'reconnecting',
+        !this._socketAlive
+          ? 'socket-dead'
+          : this._transportFailed()
+            ? 'transport-failed'
+            : `silence:${silence}ms`,
+      );
+    } else if (
+      this._state === 'reconnecting' &&
+      inState >= this.opts.failedAfterMs
+    ) {
+      this._transition('failed', `still-down-after:${inState}ms`);
+    }
+  }
+
+  _transportFailed() {
+    return (
+      this._transportState.send === 'failed' ||
+      this._transportState.recv === 'failed' ||
+      this._transportState.send === 'closed' ||
+      this._transportState.recv === 'closed'
+    );
+  }
+
+  _transition(next, reason) {
+    if (next === this._state) return;
+    // Don't downgrade from failed straight back to connected without going
+    // through reconnecting → connected; emit recovery explicitly.
+    const prev = this._state;
+    const at = Date.now();
+    const durationMs = at - this._stateSince;
+    this._state = next;
+    this._stateSince = at;
+    this.logger.info(`state ${prev} → ${next} (${reason}, ${durationMs}ms in ${prev})`);
+    try {
+      this.onEvent({ state: next, prevState: prev, reason, durationMs, at });
+    } catch (err) {
+      this.logger.error('onEvent threw', err);
+    }
+  }
+}

package/managers/ConnectionManager.js

@@ -95,16 +95,29 @@ export class ConnectionManager extends EventEmitter {
 					this.logger.info('Connected to server');
 					this.isConnected = true;
 					this.reconnectAttempts = 0;
-					this.emit('connected', { socketId: this.socket.id });
+					super.emit('connected', { socketId: this.socket.id });
 					resolve();
 				});
 
 				this.socket.on('disconnect', (reason) => {
 					this.logger.warn('Disconnected from server:', reason);
 					this.isConnected = false;
-					this.emit('disconnected', { reason });
+					super.emit('disconnected', { reason });
 				});
 
+				// Liveness signal for ConnectionHealthMonitor. Re-emit any
+				// inbound socket traffic — including Socket.IO engine pongs
+				// surfaced via the reserved 'pong' event in newer clients —
+				// as a generic 'message' so the monitor can treat it as
+				// proof of life. Without this, an idle room (e.g. host
+				// alone) starves the silence detector and gets flagged as
+				// reconnecting/failed even though the connection is fine.
+				if (typeof this.socket.onAny === 'function') {
+					this.socket.onAny((event) => {
+						super.emit('message', { event });
+					});
+				}
+
 				this.socket.on('connect_error', (error) => {
 					// Socket.IO surfaces server-side middleware rejections as
 					// connect_error with the Error's message set to the code
@@ -118,7 +131,7 @@ export class ConnectionManager extends EventEmitter {
 						// assignment is stale and will reject every time.
 						// VideoMeetingClient handles the re-join flow.
 						this.socket?.disconnect();
-						this.emit('reassignmentRequired', { code: errorCode });
+						super.emit('reassignmentRequired', { code: errorCode });
 						reject(new ConnectionError(`Reassignment required: ${errorCode}`, { code: errorCode }));
 						return;
 					}
@@ -130,7 +143,7 @@ export class ConnectionManager extends EventEmitter {
 						{ error: error.message, attempts: this.reconnectAttempts }
 					);
 
-					this.emit('error', connectionError);
+					super.emit('error', connectionError);
 
 					if (this.reconnectAttempts >= this.maxReconnectAttempts) {
 						reject(connectionError);