@stream-io/video-client 1.54.0 → 1.55.0

package/src/Call.ts

@@ -325,6 +325,7 @@ export class Call {
   private joinResponseTimeout?: number;
   private rpcRequestTimeout?: number;
   private joinCallData?: JoinCallData;
+  private allowOwnTracksLoopback = false;
   private hasJoinedOnce = false;
   private deviceSettingsAppliedOnce = false;
   private credentials?: Credentials;
@@ -740,7 +741,9 @@ export class Call {
 
       const leaveReason = message ?? reason ?? 'user is leaving the call';
       this.tracer.trace('call.leaveReason', leaveReason);
-      this.sfuStatsReporter?.flush();
+      // await the final sample so it's captured from the still-live peer
+      // connections (disposed below); the send itself stays best-effort.
+      await this.sfuStatsReporter?.flush();
       this.sfuStatsReporter?.stop();
       this.sfuStatsReporter = undefined;
       this.lastStatsOptions = undefined;
@@ -787,6 +790,7 @@ export class Call {
       this.leaveCallHooks.forEach((hook) => hook());
       this.initialized = false;
       this.hasJoinedOnce = false;
+      this.allowOwnTracksLoopback = false;
       this.unifiedSessionId = undefined;
       this.ringingSubject.next(false);
       this.cancelAutoDrop();
@@ -830,6 +834,37 @@ export class Call {
     return this.clientStore.connectedUser?.id;
   }
 
+  /**
+   * A flag indicating whether self-subscription is enabled for the call.
+   */
+  get isOwnTracksLoopbackAllowed() {
+    return this.allowOwnTracksLoopback;
+  }
+
+  /**
+   * The largest video publish dimension across the current publish options.
+   *
+   * @internal
+   */
+  getMaxVideoPublishDimension = (): VideoDimension | undefined => {
+    if (!this.currentPublishOptions) return undefined;
+    let maxDimension: VideoDimension | undefined;
+    let maxArea = 0;
+    for (const opt of this.currentPublishOptions) {
+      if (opt.trackType !== TrackType.VIDEO) continue;
+
+      const dim = opt.videoDimension;
+      if (!dim || !dim.width || !dim.height) continue;
+
+      const area = dim.width * dim.height;
+      if (area > maxArea) {
+        maxDimension = dim;
+        maxArea = area;
+      }
+    }
+    return maxDimension;
+  };
+
   /**
    * A flag indicating whether the call was created by the current user.
    */
@@ -1042,11 +1077,13 @@ export class Call {
     maxJoinRetries = 3,
     joinResponseTimeout,
     rpcRequestTimeout,
+    allowOwnTracksLoopback = false,
     ...data
   }: JoinCallData & {
     maxJoinRetries?: number;
     joinResponseTimeout?: number;
     rpcRequestTimeout?: number;
+    allowOwnTracksLoopback?: boolean;
   } = {}): Promise<void> => {
     const callingState = this.state.callingState;
 
@@ -1054,9 +1091,14 @@ export class Call {
       throw new Error(`Illegal State: call.join() shall be called only once`);
     }
 
+    // we need this to be set before the callingx.joinCall() is
+    // called to avoid registering the test call in the CallKit/Telecom
+    this.allowOwnTracksLoopback = allowOwnTracksLoopback;
+
     if (data?.ring) {
       this.ringingSubject.next(true);
     }
+
     const callingX = globalThis.streamRNVideoSDK?.callingX;
     if (callingX) {
       // for Android/iOS, we need to start the call in the callingx library as soon as possible
@@ -1291,23 +1333,9 @@ export class Call {
     // when performing fast reconnect, or when we reuse the same SFU client,
     // (ws remained healthy), we just need to restore the ICE connection
     if (performingFastReconnect) {
-      // The SFU automatically issues an ICE restart on the subscriber,
-      // so we only need to decide about the publisher. If the publisher's
-      // peer connection is still stable (ICE still connected end-to-end),
-      // the signal WebSocket drop was the only problem — the new WS alone
-      // is enough, and restarting ICE would add unnecessary SDP/ICE churn.
-      const publisherIsStable = this.publisher?.isStable() ?? true;
-      const includePublisher =
-        !!this.publisher?.isPublishing() && !publisherIsStable;
-      if (!includePublisher && this.publisher?.isPublishing()) {
-        this.logger.info(
-          '[Reconnect] FAST: skipping publisher ICE restart, publisher PC is stable',
-        );
-      }
-      await this.restoreICE(sfuClient, {
-        includeSubscriber: false,
-        includePublisher,
-      });
+      // the SFU automatically issues an ICE restart on the subscriber
+      // we don't have to do it ourselves
+      await this.restoreICE(sfuClient, { includeSubscriber: false });
     } else {
       const connectionConfig = toRtcConfiguration(this.credentials.ice_servers);
       await this.initPublisherAndSubscriber({
@@ -1506,6 +1534,11 @@ export class Call {
       enable_rtc_stats: enableTracing,
       reporting_interval_ms: reportingIntervalMs,
     } = statsOptions;
+    // Flush the previous reporter's final sample while its peer connections are
+    // still alive, before we dispose them below. Awaits only the sampling step.
+    await this.sfuStatsReporter?.flush();
+    this.sfuStatsReporter?.stop();
+    this.sfuStatsReporter = undefined;
     if (closePreviousInstances && this.subscriber) {
       await this.subscriber.dispose();
     }
@@ -1553,7 +1586,13 @@ export class Call {
       if (closePreviousInstances && this.publisher) {
         await this.publisher.dispose();
       }
-      this.publisher = new Publisher(basePeerConnectionOptions, publishOptions);
+      this.publisher = new Publisher(
+        basePeerConnectionOptions,
+        publishOptions,
+        {
+          selfSubEnabled: this.allowOwnTracksLoopback,
+        },
+      );
     }
 
     this.statsReporter?.stop();
@@ -1568,8 +1607,6 @@ export class Call {
     }
 
     this.tracer.setEnabled(enableTracing);
-    this.sfuStatsReporter?.flush();
-    this.sfuStatsReporter?.stop();
     if (statsOptions?.reporting_interval_ms > 0) {
       this.sfuStatsReporter = new SfuStatsReporter(sfuClient, {
         clientDetails,
@@ -1637,6 +1674,10 @@ export class Call {
     reason: string,
   ) => {
     this.logger.debug('[Reconnect] SFU signal connection closed');
+    // Ignore a close from a superseded client (e.g. an old socket's delayed
+    // `onclose` arriving after a reconnection already swapped in a new client).
+    // Only the currently active client's death may drive a reconnection.
+    if (sfuClient !== this.sfuClient) return;
     const { callingState } = this.state;
     if (
       // SFU WS closed before we finished current join,
@@ -1677,11 +1718,12 @@ export class Call {
     strategy: WebsocketReconnectStrategy,
     reason: ReconnectReason,
   ): Promise<void> => {
+    const { callingState } = this.state;
     if (
-      this.state.callingState === CallingState.JOINING ||
-      this.state.callingState === CallingState.RECONNECTING ||
-      this.state.callingState === CallingState.MIGRATING ||
-      this.state.callingState === CallingState.RECONNECTING_FAILED
+      callingState === CallingState.JOINING ||
+      callingState === CallingState.RECONNECTING ||
+      callingState === CallingState.MIGRATING ||
+      callingState === CallingState.RECONNECTING_FAILED
     )
       return;
 
@@ -2093,10 +2135,17 @@ export class Call {
         } else {
           if (!this.networkAvailableTask) return;
           this.logger.debug('[Reconnect] Going online');
-          this.sfuClient?.close(
-            StreamSfuClient.DISPOSE_OLD_SOCKET,
-            'Closing WS to reconnect after going online',
-          );
+          // Only discard the socket when no reconnect is already in flight. A
+          // running reconnect owns the SFU-client lifecycle (`doJoin` closes
+          // the previous client once the new session is up). Closing here would
+          // tear down the socket it's mid-join on, leaving the in-flight rejoin
+          // to spin on SIGNAL_LOST.
+          if (!hasPending(this.reconnectConcurrencyTag)) {
+            this.sfuClient?.close(
+              StreamSfuClient.DISPOSE_OLD_SOCKET,
+              'Closing WS to reconnect after going online',
+            );
+          }
           // we went online, release the previous waiters and reset the state
           this.networkAvailableTask?.resolve();
           this.networkAvailableTask = undefined;
@@ -2450,9 +2499,8 @@ export class Call {
    */
   muteSelf = (type: TrackMuteType) => {
     const myUserId = this.currentUserId;
-    if (myUserId) {
-      return this.muteUser(myUserId, type);
-    }
+    if (!myUserId) return undefined;
+    return this.muteUser(myUserId, type);
   };
 
   /**
@@ -2470,9 +2518,9 @@ export class Call {
       }
     }
 
-    if (userIdsToMute.length > 0) {
-      return this.muteUser(userIdsToMute, type);
-    }
+    return userIdsToMute.length > 0
+      ? this.muteUser(userIdsToMute, type)
+      : undefined;
   };
 
   /**

package/src/StreamSfuClient.ts

@@ -164,13 +164,24 @@ export class StreamSfuClient {
    */
   isClosingClean = false;
 
+  /**
+   * One-shot latch guarding `onSignalClose`. The signal connection can be
+   * detected as dead by more than one source (the health watchdog and the
+   * WebSocket `close` event, which on a wedged socket can arrive seconds
+   * apart). This ensures revival is triggered at most once per client.
+   */
+  private signalClosed = false;
+
   private readonly rpc: SignalServerClient;
   private keepAliveInterval?: number;
-  private connectionCheckTimeout?: NodeJS.Timeout;
+  private connectionCheckInterval?: number;
   private migrateAwayTimeout?: NodeJS.Timeout;
   private readonly pingIntervalInMs = 5 * 1000;
-  private readonly unhealthyTimeoutInMs = 15 * 1000;
-  private lastMessageTimestamp?: Date;
+  private readonly unhealthyTimeoutInMs = this.pingIntervalInMs * 2 + 2 * 1000;
+  private readonly connectionCheckIntervalInMs = Math.round(
+    this.unhealthyTimeoutInMs / 3,
+  );
+  private lastMessageTimestamp?: number;
   private readonly tracer?: Tracer;
   private readonly unsubscribeIceTrickle: () => void;
   private readonly unsubscribeNetworkChanged: () => void;
@@ -209,7 +220,7 @@ export class StreamSfuClient {
   /**
    * The error code used when the SFU connection is unhealthy.
    * Usually, this means that no message has been received from the SFU for
-   * a certain amount of time (`connectionCheckTimeout`).
+   * a certain amount of time (`unhealthyTimeoutInMs`).
    */
   static ERROR_CONNECTION_UNHEALTHY = 4001;
   /**
@@ -311,7 +322,7 @@ export class StreamSfuClient {
       endpoint: `${this.credentials.server.ws_endpoint}?${new URLSearchParams(params).toString()}`,
       tracer: this.tracer,
       onMessage: (message) => {
-        this.lastMessageTimestamp = new Date();
+        this.lastMessageTimestamp = Date.now();
         this.scheduleConnectionCheck();
         const eventKind = message.eventPayload.oneofKind;
         if (eventsToTrace[eventKind]) {
@@ -336,7 +347,7 @@ export class StreamSfuClient {
           this.signalWs.addEventListener('open', onOpen);
 
           this.signalWs.addEventListener('close', (e) => {
-            this.handleWebSocketClose(e);
+            this.notifySignalClose(`${e.code} ${e.reason ?? ''}`);
             // Normally, this shouldn't have any effect, because WS should never emit 'close'
             // before emitting 'open'. However, stranger things have happened, and we don't
             // want to leave signalReady in a pending state.
@@ -371,11 +382,13 @@ export class StreamSfuClient {
     return this.joinResponseTask.promise;
   }
 
-  private handleWebSocketClose = (e: CloseEvent) => {
-    this.signalWs.removeEventListener('close', this.handleWebSocketClose);
-    getTimers().clearInterval(this.keepAliveInterval);
-    clearTimeout(this.connectionCheckTimeout);
-    this.onSignalClose?.(`${e.code} ${e.reason}`);
+  private notifySignalClose = (reason: string) => {
+    if (this.signalClosed) return;
+    this.signalClosed = true;
+    const timers = getTimers();
+    timers.clearInterval(this.keepAliveInterval);
+    timers.clearInterval(this.connectionCheckInterval);
+    this.onSignalClose?.(reason.trim());
   };
 
   close = (code: number = StreamSfuClient.NORMAL_CLOSURE, reason?: string) => {
@@ -392,7 +405,9 @@ export class StreamSfuClient {
     ) {
       this.logger.debug(`Closing SFU WS connection: ${code} - ${reason}`);
       ws.close(code, `js-client: ${reason}`);
-      ws.removeEventListener('close', this.handleWebSocketClose);
+    }
+    if (!this.isClosingClean) {
+      this.notifySignalClose(`${code} ${reason ?? ''}`);
     }
     this.dispose(reason);
   };
@@ -401,8 +416,9 @@ export class StreamSfuClient {
     this.logger.debug('Disposing SFU client');
     this.unsubscribeIceTrickle();
     this.unsubscribeNetworkChanged();
-    clearInterval(this.keepAliveInterval);
-    clearTimeout(this.connectionCheckTimeout);
+    const timers = getTimers();
+    timers.clearInterval(this.keepAliveInterval);
+    timers.clearInterval(this.connectionCheckInterval);
     clearTimeout(this.migrateAwayTimeout);
     this.abortController.abort();
     this.migrationTask?.resolve();
@@ -697,7 +713,7 @@ export class StreamSfuClient {
       return;
     }
     this.logger.debug(`Sending message to: ${this.edgeName}`, msgJson);
-    this.signalWs.send(SfuRequest.toBinary(message));
+    this.signalWs.send(SfuRequest.toBinary(message) as Uint8Array<ArrayBuffer>);
   };
 
   private keepAlive = () => {
@@ -711,12 +727,11 @@ export class StreamSfuClient {
   };
 
   private scheduleConnectionCheck = () => {
-    clearTimeout(this.connectionCheckTimeout);
-    this.connectionCheckTimeout = setTimeout(() => {
+    const timers = getTimers();
+    timers.clearInterval(this.connectionCheckInterval);
+    this.connectionCheckInterval = timers.setInterval(() => {
       if (this.lastMessageTimestamp) {
-        const timeSinceLastMessage =
-          new Date().getTime() - this.lastMessageTimestamp.getTime();
-
+        const timeSinceLastMessage = Date.now() - this.lastMessageTimestamp;
         if (timeSinceLastMessage > this.unhealthyTimeoutInMs) {
           this.close(
             StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
@@ -724,6 +739,6 @@ export class StreamSfuClient {
           );
         }
       }
-    }, this.unhealthyTimeoutInMs);
+    }, this.connectionCheckIntervalInMs);
   };
 }

package/src/__tests__/StreamSfuClient.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { StreamSfuClient } from '../StreamSfuClient';
 import { Dispatcher } from '../rtc';
 import { StreamClient } from '../coordinator/connection/client';
+import { getTimers } from '../timers';
 
 /**
  * Minimal `WebSocket` stub used to drive `StreamSfuClient.close()` while the
@@ -38,9 +39,13 @@ class CapturingWebSocket {
     this.closeArgs = { code, reason };
     this.readyState = CapturingWebSocket.CLOSED;
   }
+  /** Test helper: synchronously fire a registered event (e.g. `close`). */
+  emit(event: string, payload: unknown) {
+    this.listeners.get(event)?.forEach((listener) => listener(payload));
+  }
 }
 
-const buildSfuClient = () => {
+const buildSfuClient = (onSignalClose?: (reason: string) => void) => {
   const dispatcher = new Dispatcher();
   const streamClient = new StreamClient('test-key');
   return new StreamSfuClient({
@@ -59,9 +64,109 @@ const buildSfuClient = () => {
     },
     tag: 'test',
     enableTracing: false,
+    onSignalClose,
   });
 };
 
+describe('StreamSfuClient unhealthy watchdog timer source', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('arms the unhealthy watchdog on the worker timer, not the main-thread setInterval', () => {
+    const sfuClient = buildSfuClient();
+    const workerSetInterval = vi
+      .spyOn(getTimers(), 'setInterval')
+      .mockReturnValue(1 as unknown as number);
+    const mainSetInterval = vi.spyOn(globalThis, 'setInterval');
+
+    (
+      sfuClient as unknown as { scheduleConnectionCheck: () => void }
+    ).scheduleConnectionCheck();
+
+    expect(workerSetInterval).toHaveBeenCalledTimes(1);
+    expect(mainSetInterval).not.toHaveBeenCalled();
+
+    sfuClient.close(1000, 'test cleanup');
+  });
+});
+
+describe('StreamSfuClient unhealthy watchdog resilience', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('re-arms the unhealthy watchdog after a check passes (not single-shot)', () => {
+    vi.useFakeTimers();
+    const sfuClient = buildSfuClient();
+    const closeSpy = vi.spyOn(sfuClient, 'close').mockImplementation(() => {});
+    const c = sfuClient as unknown as {
+      lastMessageTimestamp?: number;
+      unhealthyTimeoutInMs: number;
+      scheduleConnectionCheck: () => void;
+    };
+    const window = c.unhealthyTimeoutInMs;
+
+    c.lastMessageTimestamp = Date.now();
+    c.scheduleConnectionCheck();
+
+    // At exactly the threshold the connection is still healthy (strict `>`),
+    // so no poll within the first window closes it. A single-shot watchdog
+    // armed for the threshold would now be dead.
+    vi.advanceTimersByTime(window);
+    expect(closeSpy).not.toHaveBeenCalled();
+
+    // No further messages arrive; the self-rescheduling watchdog keeps polling
+    // and detects the connection as unhealthy on a later tick.
+    vi.advanceTimersByTime(window);
+    expect(closeSpy).toHaveBeenCalledWith(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      expect.stringContaining('unhealthy'),
+    );
+  });
+
+  it('detects an unhealthy connection shortly after the threshold, not a full window later', () => {
+    vi.useFakeTimers();
+    const sfuClient = buildSfuClient();
+    const closeSpy = vi.spyOn(sfuClient, 'close').mockImplementation(() => {});
+    const c = sfuClient as unknown as {
+      lastMessageTimestamp?: number;
+      unhealthyTimeoutInMs: number;
+      scheduleConnectionCheck: () => void;
+    };
+    const window = c.unhealthyTimeoutInMs;
+
+    c.lastMessageTimestamp = Date.now();
+    c.scheduleConnectionCheck();
+
+    // healthy up to (and exactly at) the threshold
+    vi.advanceTimersByTime(window);
+    expect(closeSpy).not.toHaveBeenCalled();
+
+    // the watchdog polls finer than the window, so silence is caught well
+    // before a second full window elapses (the old period == window design
+    // could take up to 2x the window to notice).
+    vi.advanceTimersByTime(window / 2);
+    expect(closeSpy).toHaveBeenCalledWith(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      expect.stringContaining('unhealthy'),
+    );
+  });
+});
+
 describe('StreamSfuClient.close()', () => {
   beforeEach(() => {
     CapturingWebSocket.instances = [];
@@ -164,6 +269,59 @@ describe('StreamSfuClient.close()', () => {
   });
 });
 
+describe('StreamSfuClient signal-close revival', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it('drives revival immediately on an unhealthy close, without waiting for the onclose event', () => {
+    const onSignalClose = vi.fn();
+    const sfuClient = buildSfuClient(onSignalClose);
+
+    // A wedged socket may fire `onclose` only after the OS TCP timeout. The
+    // health watchdog closes with ERROR_CONNECTION_UNHEALTHY; revival must
+    // start now, not when (or if) the transport `close` event arrives.
+    sfuClient.close(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      'SFU connection unhealthy',
+    );
+
+    expect(onSignalClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifies revival only once when the late onclose event follows an unhealthy close', () => {
+    const onSignalClose = vi.fn();
+    const sfuClient = buildSfuClient(onSignalClose);
+    const ws = CapturingWebSocket.instances.at(-1)!;
+
+    // watchdog closes the dead socket (revival triggered proactively)...
+    sfuClient.close(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      'SFU connection unhealthy',
+    );
+    // ...then the OS finally surfaces the wedged socket's `close` event.
+    ws.emit('close', { code: 1006, reason: '' });
+
+    expect(onSignalClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifies revival when only the onclose event fires (server-initiated close)', () => {
+    const onSignalClose = vi.fn();
+    buildSfuClient(onSignalClose);
+    const ws = CapturingWebSocket.instances.at(-1)!;
+
+    ws.emit('close', { code: 1006, reason: '' });
+
+    expect(onSignalClose).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('StreamSfuClient.leaveAndClose()', () => {
   beforeEach(() => {
     CapturingWebSocket.instances = [];