@stream-io/video-client 1.48.0 → 1.49.0

package/src/rtc/__tests__/Publisher.test.ts

@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { anyString } from 'vitest-mock-extended';
 import { NegotiationError } from '../NegotiationError';
 import { Publisher } from '../Publisher';
+import { ReconnectReason } from '../types';
 import { CallState } from '../../store';
 import { StreamSfuClient } from '../../StreamSfuClient';
 import { DispatchableMessage, Dispatcher } from '../Dispatcher';
@@ -87,6 +88,7 @@ describe('Publisher', () => {
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     vi.clearAllMocks();
     vi.resetModules();
     publisher.dispose();
@@ -250,7 +252,14 @@ describe('Publisher', () => {
       expect(publisher['negotiate']).toHaveBeenCalled();
     });
 
+    const simulatePriorIceConnected = () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+    };
+
     it(`should perform ICE restart when connection state changes to 'failed'`, () => {
+      simulatePriorIceConnected();
       vi.spyOn(publisher, 'restartIce').mockResolvedValue();
       // @ts-expect-error private api
       publisher['pc'].iceConnectionState = 'failed';
@@ -259,6 +268,7 @@ describe('Publisher', () => {
     });
 
     it(`should perform rejoin when ICE restart fails after connection state changes to 'failed'`, async () => {
+      simulatePriorIceConnected();
       const { promise: lock, resolve: unlock } = promiseWithResolvers<void>();
       publisher['onReconnectionNeeded'] = vi
         .fn()
@@ -274,6 +284,7 @@ describe('Publisher', () => {
     });
 
     it(`should perform fast reconnect when ICE restart fails with SIGNAL_LOST error`, async () => {
+      simulatePriorIceConnected();
       const { promise: lock, resolve: unlock } = promiseWithResolvers<void>();
       publisher['onReconnectionNeeded'] = vi
         .fn()
@@ -325,6 +336,7 @@ describe('Publisher', () => {
     });
 
     it(`should perform REJOIN reconnect when ICE restart fails with any other error code`, async () => {
+      simulatePriorIceConnected();
       const { promise: lock, resolve: unlock } = promiseWithResolvers<void>();
       publisher['onReconnectionNeeded'] = vi
         .fn()
@@ -365,6 +377,7 @@ describe('Publisher', () => {
     });
 
     it(`should schedule ICE restart when connection state changes to 'disconnected'`, () => {
+      simulatePriorIceConnected();
       vi.spyOn(publisher, 'restartIce').mockResolvedValue();
       vi.useFakeTimers();
       // @ts-expect-error private api
@@ -376,6 +389,7 @@ describe('Publisher', () => {
     });
 
     it(`should perform rejoin when scheduled ICE restart fails`, async () => {
+      simulatePriorIceConnected();
       vi.spyOn(publisher, 'restartIce').mockRejectedValue('ICE restart failed');
       const { promise: lock, resolve } = promiseWithResolvers<void>();
       publisher['onReconnectionNeeded'] = vi
@@ -393,6 +407,202 @@ describe('Publisher', () => {
       expect(publisher['onReconnectionNeeded']).toHaveBeenCalled();
     });
 
+    it(`iceHasEverConnected is false before any connected state is observed`, () => {
+      expect(publisher['iceHasEverConnected']).toBe(false);
+    });
+
+    it(`iceHasEverConnected becomes true after 'connected' ICE state`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher['iceHasEverConnected']).toBe(true);
+    });
+
+    it(`iceHasEverConnected also flips on 'completed' ICE state`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'completed';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher['iceHasEverConnected']).toBe(true);
+    });
+
+    it(`does NOT call restartIce when ICE never connected and state goes to 'failed' — emits REJOIN with 'ice_never_connected'`, () => {
+      vi.spyOn(publisher, 'restartIce').mockResolvedValue();
+      publisher['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'failed';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher.restartIce).not.toHaveBeenCalled();
+      expect(publisher['onReconnectionNeeded']).toHaveBeenCalledWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.ICE_NEVER_CONNECTED,
+        PeerType.PUBLISHER_UNSPECIFIED,
+      );
+    });
+
+    it(`pre-connect 'disconnected' does not restart or escalate immediately`, () => {
+      // ICE has never reached `connected`. A `disconnected` transition at
+      // this point is just the browser's checking phase wobbling; the
+      // browser may yet move back to checking/connected. The SDK should
+      // wait it out — no synchronous restart, no synchronous REJOIN. Only
+      // a terminal `failed` before connect, or the pre-connect watchdog
+      // expiring, should escalate via `ICE_NEVER_CONNECTED`.
+      vi.spyOn(publisher, 'restartIce').mockResolvedValue();
+      publisher['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'disconnected';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher.restartIce).not.toHaveBeenCalled();
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalled();
+    });
+
+    it(`pre-connect 'disconnected' watchdog escalates to REJOIN if state stays stuck`, () => {
+      vi.spyOn(publisher, 'restartIce').mockResolvedValue();
+      publisher['onReconnectionNeeded'] = vi.fn();
+      vi.useFakeTimers();
+      const watchdogMs = publisher['iceRestartDelay'] * 2;
+
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'disconnected';
+      publisher['onIceConnectionStateChange']();
+      // before the watchdog fires, no escalation
+      vi.advanceTimersByTime(watchdogMs - 1);
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalled();
+
+      // watchdog fires; still stuck in disconnected → escalate
+      vi.advanceTimersByTime(2);
+      expect(publisher.restartIce).not.toHaveBeenCalled();
+      expect(publisher['onReconnectionNeeded']).toHaveBeenCalledWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.ICE_NEVER_CONNECTED,
+        PeerType.PUBLISHER_UNSPECIFIED,
+      );
+    });
+
+    it(`pre-connect 'disconnected' watchdog is canceled when ICE recovers to 'connected'`, () => {
+      publisher['onReconnectionNeeded'] = vi.fn();
+      vi.useFakeTimers();
+      const watchdogMs = publisher['iceRestartDelay'] * 2;
+
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'disconnected';
+      publisher['onIceConnectionStateChange']();
+      // recover before the watchdog window expires
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+
+      // advance past the original watchdog window — must NOT fire now
+      vi.advanceTimersByTime(watchdogMs + 100);
+
+      expect(publisher['iceHasEverConnected']).toBe(true);
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalled();
+    });
+
+    it(`pre-connect 'disconnected' that recovers to 'connected' continues normally`, () => {
+      publisher['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'disconnected';
+      publisher['onIceConnectionStateChange']();
+      // browser now reaches connected — the normal connected branch runs
+      // and `iceHasEverConnected` flips to true.
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher['iceHasEverConnected']).toBe(true);
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalled();
+    });
+
+    it(`isStable() returns false when ICE is 'new'`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'new';
+      // default connectionState in mock is 'connected'
+      expect(publisher.isStable()).toBe(false);
+    });
+
+    it(`isStable() returns true when ICE is 'connected' and connectionState is 'connected'`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      // @ts-expect-error private api
+      publisher['pc'].connectionState = 'connected';
+      expect(publisher.isStable()).toBe(true);
+    });
+
+    it(`isStable() returns true when ICE is 'completed' and connectionState is 'connected'`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'completed';
+      // @ts-expect-error private api
+      publisher['pc'].connectionState = 'connected';
+      expect(publisher.isStable()).toBe(true);
+    });
+
+    it(`isStable() returns false when ICE is 'disconnected'`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'disconnected';
+      // @ts-expect-error private api
+      publisher['pc'].connectionState = 'connected';
+      expect(publisher.isStable()).toBe(false);
+    });
+
+    it(`after connected→disconnected→connected cycle, subsequent 'failed' DOES trigger ICE restart (flag stays true)`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'disconnected';
+      publisher['onIceConnectionStateChange']();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+
+      vi.spyOn(publisher, 'restartIce').mockResolvedValue();
+      publisher['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'failed';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher.restartIce).toHaveBeenCalled();
+      // the reason here is the regular restart path, NOT 'ice_never_connected'
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalledWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.ICE_NEVER_CONNECTED,
+        PeerType.PUBLISHER_UNSPECIFIED,
+      );
+    });
+
+    it(`connection-state 'failed' (distinct from ICE state) still fires REJOIN even after ICE was connected`, () => {
+      // mark ICE as connected first
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'connected';
+      publisher['onIceConnectionStateChange']();
+
+      publisher['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error private api
+      publisher['pc'].connectionState = 'failed';
+      publisher['onConnectionStateChange']();
+      expect(publisher['onReconnectionNeeded']).toHaveBeenCalledWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.CONNECTION_FAILED,
+        PeerType.PUBLISHER_UNSPECIFIED,
+      );
+    });
+
+    it(`'completed' state is treated as connectivity — subsequent 'failed' DOES trigger ICE restart`, () => {
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'completed';
+      publisher['onIceConnectionStateChange']();
+
+      vi.spyOn(publisher, 'restartIce').mockResolvedValue();
+      publisher['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error private api
+      publisher['pc'].iceConnectionState = 'failed';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher.restartIce).toHaveBeenCalled();
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalledWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.ICE_NEVER_CONNECTED,
+        PeerType.PUBLISHER_UNSPECIFIED,
+      );
+    });
+
     it(`should schedule ICE restart but cancel it if connection recovers in the meantime`, () => {
       vi.spyOn(publisher, 'restartIce').mockResolvedValue();
       vi.useFakeTimers();

package/src/rtc/__tests__/Subscriber.test.ts

@@ -11,8 +11,10 @@ import {
   ErrorCode,
   PeerType,
   TrackType,
+  WebsocketReconnectStrategy,
 } from '../../gen/video/sfu/models/models';
 import { NegotiationError } from '../NegotiationError';
+import { ReconnectReason } from '../types';
 import { IceTrickleBuffer } from '../IceTrickleBuffer';
 import { StreamClient } from '../../coordinator/connection/client';
 
@@ -62,6 +64,7 @@ describe('Subscriber', () => {
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     vi.clearAllMocks();
     vi.resetModules();
     subscriber.dispose();
@@ -97,7 +100,14 @@ describe('Subscriber', () => {
       });
     });
 
+    const simulatePriorIceConnected = () => {
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'connected';
+      subscriber['onIceConnectionStateChange']();
+    };
+
     it(`should perform ICE restart when connection state changes to 'failed'`, () => {
+      simulatePriorIceConnected();
       vi.spyOn(subscriber, 'restartIce').mockResolvedValue();
       // @ts-expect-error - private field
       subscriber['pc'].iceConnectionState = 'failed';
@@ -106,6 +116,7 @@ describe('Subscriber', () => {
     });
 
     it(`should perform ICE restart when connection state changes to 'disconnected'`, () => {
+      simulatePriorIceConnected();
       vi.spyOn(subscriber, 'restartIce').mockResolvedValue();
       vi.useFakeTimers();
       // @ts-expect-error - private field
@@ -115,6 +126,51 @@ describe('Subscriber', () => {
       expect(subscriber.restartIce).toHaveBeenCalled();
     });
 
+    it(`does NOT perform ICE restart when ICE never connected and state goes to 'failed' — emits REJOIN with 'ice_never_connected'`, () => {
+      vi.spyOn(subscriber, 'restartIce').mockResolvedValue();
+      subscriber['onReconnectionNeeded'] = vi.fn();
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'failed';
+      subscriber['onIceConnectionStateChange']();
+      expect(subscriber.restartIce).not.toHaveBeenCalled();
+      expect(subscriber['onReconnectionNeeded']).toHaveBeenCalledWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.ICE_NEVER_CONNECTED,
+        PeerType.SUBSCRIBER,
+      );
+    });
+
+    it(`isStable() returns true only when ICE is connected/completed and connectionState is connected`, () => {
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'connected';
+      // @ts-expect-error - private field
+      subscriber['pc'].connectionState = 'connected';
+      expect(subscriber.isStable()).toBe(true);
+
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'completed';
+      expect(subscriber.isStable()).toBe(true);
+
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'disconnected';
+      expect(subscriber.isStable()).toBe(false);
+
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'new';
+      expect(subscriber.isStable()).toBe(false);
+    });
+
+    it(`iceHasEverConnected tracks lifetime connectivity`, () => {
+      expect(subscriber['iceHasEverConnected']).toBe(false);
+      simulatePriorIceConnected();
+      expect(subscriber['iceHasEverConnected']).toBe(true);
+      // going disconnected does not reset the flag
+      // @ts-expect-error - private field
+      subscriber['pc'].iceConnectionState = 'disconnected';
+      subscriber['onIceConnectionStateChange']();
+      expect(subscriber['iceHasEverConnected']).toBe(true);
+    });
+
     it(`should throw NegotiationError when SFU returns an error`, async () => {
       sfuClient.iceRestart = vi.fn().mockResolvedValue({
         response: {

package/src/rtc/index.ts

@@ -1,5 +1,6 @@
 export * from './codecs';
 export * from './Dispatcher';
+export * from './NegotiationError';
 export * from './IceTrickleBuffer';
 export * from './Publisher';
 export * from './Subscriber';

package/src/rtc/types.ts

@@ -10,18 +10,55 @@ import { Dispatcher } from './Dispatcher';
 import type { OptimalVideoLayer } from './layers';
 import type { ClientPublishOptions } from '../types';
 
+/**
+ * Canonical reasons the SDK uses to trigger a reconnection. Free-form strings
+ * are still accepted at the callback boundary (e.g. when forwarding an SFU
+ * error message), but only the members below influence reconnect-loop
+ * behavior. In particular, `Call.reconnect` programmatically inspects
+ * `ICE_NEVER_CONNECTED` to drive the unsupported-network detector — pass a
+ * canonical member when you want the SDK to react to the reason; pass a
+ * free-form string when the value is purely diagnostic.
+ */
+export const ReconnectReason = {
+  /** ICE never reached `connected`/`completed`, escalate to REJOIN. */
+  ICE_NEVER_CONNECTED: 'ice_never_connected',
+  /** RTCPeerConnection.connectionState became `failed`. */
+  CONNECTION_FAILED: 'connection_failed',
+  /** `restartIce()` rejected. */
+  RESTART_ICE_FAILED: 'restart_ice_failed',
+  /** SFU `goAway` event, migrate to a new SFU. */
+  GO_AWAY: 'go_away',
+  /** Network came back online after going offline. */
+  NETWORK_BACK_ONLINE: 'network_back_online',
+  /** SFU error event with no descriptive message. */
+  SFU_ERROR: 'sfu_error',
+} as const;
+
+export type ReconnectReason =
+  | (typeof ReconnectReason)[keyof typeof ReconnectReason]
+  | (string & {});
+
 export type OnReconnectionNeeded = (
   kind: WebsocketReconnectStrategy,
-  reason: string,
+  reason: ReconnectReason,
   peerType: PeerType,
 ) => void;
 
+/**
+ * Fires the first time a peer connection's ICE transport reaches
+ * `connected` or `completed` during its lifetime. Used by `Call` to reset
+ * the "ICE never connected" failure counter only when WebRTC has actually
+ * recovered, not merely when the SFU join handshake succeeded.
+ */
+export type OnIceConnected = (peerType: PeerType) => void;
+
 export type BasePeerConnectionOpts = {
   sfuClient: StreamSfuClient;
   state: CallState;
   connectionConfig?: RTCConfiguration;
   dispatcher: Dispatcher;
   onReconnectionNeeded?: OnReconnectionNeeded;
+  onIceConnected?: OnIceConnected;
   tag: string;
   enableTracing: boolean;
   iceRestartDelay?: number;