@stream-io/video-client 1.54.0 → 1.55.0

package/src/rtc/Subscriber.ts

@@ -1,7 +1,11 @@
 import { BasePeerConnection } from './BasePeerConnection';
-import { BasePeerConnectionOpts } from './types';
+import { BasePeerConnectionOpts, ReconnectReason } from './types';
 import { NegotiationError } from './NegotiationError';
-import { PeerType, TrackType } from '../gen/video/sfu/models/models';
+import {
+  PeerType,
+  TrackType,
+  WebsocketReconnectStrategy,
+} from '../gen/video/sfu/models/models';
 import { SubscriberOffer } from '../gen/video/sfu/event/events';
 import { toTrackType, trackTypeToParticipantStreamKey } from './helpers/tracks';
 import { pushToIfMissing, removeFromIfPresent } from '../helpers/array';
@@ -14,6 +18,15 @@ import { enableStereo, removeCodecsExcept } from './helpers/sdp';
  * @internal
  */
 export class Subscriber extends BasePeerConnection {
+  /**
+   * Remote streams received from the SFU. For a self-sub case
+   * we need to be able to distinguish between the local capture stream.
+   * The map will never contain local streams so we can safely use it to
+   * check if the stream is remote and dispose it when needed.
+   */
+  private trackedStreams?: WeakSet<MediaStream>;
+  private negotiationFailures = 0;
+
   /**
    * Constructs a new `Subscriber` instance.
    */
@@ -22,9 +35,25 @@ export class Subscriber extends BasePeerConnection {
     this.pc.addEventListener('track', this.handleOnTrack);
 
     this.on('subscriberOffer', async (subscriberOffer) => {
-      return this.negotiate(subscriberOffer).catch((err) => {
-        this.logger.error(`Negotiation failed.`, err);
-      });
+      try {
+        const result = await this.negotiate(subscriberOffer);
+        this.negotiationFailures = 0;
+        return result;
+      } catch (err: any) {
+        const message = 'subscriber.negotiationFailed';
+        this.tracer?.trace(message, err.message);
+        this.logger.warn(message, err);
+
+        const failures = ++this.negotiationFailures;
+        if (failures < 3) return this.tryRestartIce();
+
+        this.logger.error(`negotiation failed ${failures} times, rejoining`);
+        this.onReconnectionNeeded?.(
+          WebsocketReconnectStrategy.REJOIN,
+          ReconnectReason.SUBSCRIBER_NEGOTIATION_FAILED,
+          this.peerType,
+        );
+      }
     });
   }
 
@@ -44,13 +73,11 @@ export class Subscriber extends BasePeerConnection {
   restartIce = async () => {
     this.logger.debug('Restarting ICE connection');
     if (this.pc.signalingState === 'have-remote-offer') {
-      this.logger.debug('ICE restart is already in progress');
+      this.logger.debug('ICE negotiation is already in progress');
       return;
     }
     if (this.pc.connectionState === 'new') {
-      this.logger.debug(
-        `ICE connection is not yet established, skipping restart.`,
-      );
+      this.logger.debug(`ICE connection not yet established, skipping restart`);
       return;
     }
     const previousIsIceRestarting = this.isIceRestarting;
@@ -75,6 +102,7 @@ export class Subscriber extends BasePeerConnection {
     const participantToUpdate = this.state.participants.find(
       (p) => p.trackLookupPrefix === trackId,
     );
+    const isSelfSub = !!participantToUpdate?.isLocalParticipant;
     this.logger.debug(
       `[onTrack]: Got remote ${rawTrackType} track for userId: ${participantToUpdate?.userId}`,
       track.id,
@@ -108,6 +136,11 @@ export class Subscriber extends BasePeerConnection {
 
     this.trackIdToTrackType.set(track.id, trackType);
 
+    if (isSelfSub) {
+      this.trackedStreams ??= new WeakSet<MediaStream>();
+      this.trackedStreams.add(primaryStream);
+    }
+
     if (!participantToUpdate) {
       this.logger.warn(
         `[onTrack]: Received track for unknown participant: ${trackId}`,
@@ -128,6 +161,13 @@ export class Subscriber extends BasePeerConnection {
       return;
     }
 
+    // Self-sub loopback audio routes to the speaker by default, which
+    // would echo the local user's voice. Default-mute here; consumers
+    // (the loopback recording hook) re-enable explicitly when needed.
+    if (isSelfSub && e.track.kind === 'audio') {
+      e.track.enabled = false;
+    }
+
     // get the previous stream to dispose it later
     // usually this happens during migration, when the stream is replaced
     // with a new one but the old one is still in the state
@@ -138,8 +178,15 @@ export class Subscriber extends BasePeerConnection {
       [streamKindProp]: primaryStream,
     });
 
-    // now, dispose the previous stream if it exists
     if (previousStream) {
+      if (isSelfSub && !this.trackedStreams?.has(previousStream)) {
+        // this is the local capture stream, we don't want to dispose it
+        this.logger.debug(
+          `[onTrack]: Skipping cleanup of previous ${e.track.kind} stream for userId: ${participantToUpdate.userId} because it is not tracked`,
+        );
+        return;
+      }
+
       this.logger.info(
         `[onTrack]: Cleaning up previous remote ${track.kind} tracks for userId: ${participantToUpdate.userId}`,
       );
@@ -172,34 +219,48 @@ export class Subscriber extends BasePeerConnection {
   };
 
   private negotiate = async (subscriberOffer: SubscriberOffer) => {
-    await this.pc.setRemoteDescription({
-      type: 'offer',
-      sdp: subscriberOffer.sdp,
-    });
+    // The generation currently committed on the peer connection. If this
+    // negotiation fails and rolls back, the buffer is restored to it.
+    const previousSdp = this.pc.currentRemoteDescription?.sdp;
+    try {
+      await this.pc.setRemoteDescription({
+        type: 'offer',
+        sdp: subscriberOffer.sdp,
+      });
 
-    this.addTrickledIceCandidates();
-
-    const answer = await this.pc.createAnswer();
-    if (answer.sdp) {
-      answer.sdp = enableStereo(subscriberOffer.sdp, answer.sdp);
-      const { dangerouslyForceCodec, subscriberFmtpLine } =
-        this.clientPublishOptions || {};
-      if (dangerouslyForceCodec) {
-        answer.sdp = removeCodecsExcept(
-          answer.sdp,
-          dangerouslyForceCodec,
-          subscriberFmtpLine,
-        );
-      }
-    }
-    await this.pc.setLocalDescription(answer);
+      this.addTrickledIceCandidates();
 
-    await this.sfuClient.sendAnswer({
-      peerType: PeerType.SUBSCRIBER,
-      sdp: answer.sdp || '',
-      negotiationId: subscriberOffer.negotiationId,
-    });
+      const answer = await this.pc.createAnswer();
+      if (answer.sdp) {
+        answer.sdp = enableStereo(subscriberOffer.sdp, answer.sdp);
+        const { dangerouslyForceCodec, subscriberFmtpLine } =
+          this.clientPublishOptions || {};
+        if (dangerouslyForceCodec) {
+          answer.sdp = removeCodecsExcept(
+            answer.sdp,
+            dangerouslyForceCodec,
+            subscriberFmtpLine,
+          );
+        }
+      }
+      await this.pc.setLocalDescription(answer);
 
-    this.isIceRestarting = false;
+      await this.sfuClient.sendAnswer({
+        peerType: PeerType.SUBSCRIBER,
+        sdp: answer.sdp || '',
+        negotiationId: subscriberOffer.negotiationId,
+      });
+    } catch (err) {
+      if (this.pc.signalingState === 'have-remote-offer') {
+        await this.pc.setRemoteDescription({ type: 'rollback' }).catch((e) => {
+          this.logger.warn('Failed to rollback after negotiation error', e);
+        });
+        const { iceTrickleBuffer } = this.sfuClient;
+        iceTrickleBuffer.updateActiveGeneration(this.peerType, previousSdp);
+      }
+      throw err;
+    } finally {
+      this.isIceRestarting = false;
+    }
   };
 }

package/src/rtc/__tests__/Call.reconnect.test.ts

@@ -818,43 +818,6 @@ describe('Call reconnect wiring (PC event → leave)', () => {
     expect(publisher.restartIce).toHaveBeenCalled();
   });
 
-  /**
-   * Scenario 4 (manual smoke equivalent: drop only the signal WS while the
-   * publisher PC stays `connected`): the FAST path should NOT call
-   * `publisher.restartIce()` because the PC is stable.
-   */
-  it('FAST path skips publisher.restartIce when publisher PC is stable', async () => {
-    const publisher = makePublisherWiredToCall();
-    // @ts-expect-error private field
-    publisher['pc'].iceConnectionState = 'connected';
-    publisher['onIceConnectionStateChange']();
-    // @ts-expect-error private field
-    publisher['pc'].connectionState = 'connected';
-
-    // pretend the publisher has tracks so isPublishing() would return true
-    vi.spyOn(publisher, 'isPublishing').mockReturnValue(true);
-    const restartIceSpy = vi.spyOn(publisher, 'restartIce').mockResolvedValue();
-    const setSfuSpy = vi.spyOn(publisher, 'setSfuClient');
-    call['publisher'] = publisher;
-
-    // mimic the FAST branch in doJoin: restoreICE is the gateway
-    const publisherIsStable = call['publisher']?.isStable() ?? true;
-    const includePublisher =
-      !!call['publisher']?.isPublishing() && !publisherIsStable;
-    await call['restoreICE'](sfuClient, {
-      includeSubscriber: false,
-      includePublisher,
-    });
-
-    expect(includePublisher).toBe(false);
-    expect(setSfuSpy).toHaveBeenCalledWith(sfuClient); // wire still updated
-    expect(restartIceSpy).not.toHaveBeenCalled(); // but NO ICE restart
-  });
-
-  /**
-   * Counterpart to the above: when the publisher PC is NOT stable (e.g.,
-   * `disconnected`), the FAST path SHOULD still issue an ICE restart.
-   */
   it('FAST path DOES call publisher.restartIce when publisher PC is unstable', async () => {
     const publisher = makePublisherWiredToCall();
     // @ts-expect-error private field
@@ -869,15 +832,8 @@ describe('Call reconnect wiring (PC event → leave)', () => {
     const restartIceSpy = vi.spyOn(publisher, 'restartIce').mockResolvedValue();
     call['publisher'] = publisher;
 
-    const publisherIsStable = call['publisher']?.isStable() ?? true;
-    const includePublisher =
-      !!call['publisher']?.isPublishing() && !publisherIsStable;
-    await call['restoreICE'](sfuClient, {
-      includeSubscriber: false,
-      includePublisher,
-    });
+    await call['restoreICE'](sfuClient, { includeSubscriber: false });
 
-    expect(includePublisher).toBe(true);
     expect(restartIceSpy).toHaveBeenCalled();
   });
 
@@ -998,6 +954,50 @@ describe('Call reconnect wiring (PC event → leave)', () => {
   });
 });
 
+/**
+ * `handleSfuSignalClose` is the bridge from a dead signal WS to the reconnect
+ * loop. A reconnect swaps in a fresh SFU client, but the old socket can still
+ * fire a (delayed) `close` later. Such stragglers must be ignored: only the
+ * currently-active client may drive a reconnect.
+ */
+describe('Call.handleSfuSignalClose superseded-client guard', () => {
+  let call: Call;
+
+  beforeEach(() => {
+    call = makeCall();
+    vi.spyOn(call, 'leave').mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('ignores a signal close from a superseded SFU client', () => {
+    call.state.setCallingState(CallingState.JOINED);
+    const reconnectSpy = vi
+      .spyOn(call as unknown as { reconnect: () => Promise<void> }, 'reconnect')
+      .mockResolvedValue(undefined);
+
+    const currentClient = { isLeaving: false, isClosingClean: false };
+    const supersededClient = { isLeaving: false, isClosingClean: false };
+    (call as unknown as { sfuClient: unknown }).sfuClient = currentClient;
+
+    // a close from a client that is no longer active must not reconnect
+    call['handleSfuSignalClose'](
+      supersededClient as unknown as StreamSfuClient,
+      '1006 ',
+    );
+    expect(reconnectSpy).not.toHaveBeenCalled();
+
+    // the active client's close still drives a reconnect
+    call['handleSfuSignalClose'](
+      currentClient as unknown as StreamSfuClient,
+      '1006 ',
+    );
+    expect(reconnectSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
 /**
  * `leave()` runs after both the success path (end of `joinFlow`) and the
  * giveUpAndLeave path. Only the success path resets `reconnectStrategy` /

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

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import { IceTrickleBuffer } from '../IceTrickleBuffer';
+import { PeerType } from '../../gen/video/sfu/models/models';
+
+// The generation is carried via `usernameFragment` (the key getCandidateUfrag
+// reads); the candidate-string `ufrag` token path has its own helper tests.
+const trickle = (
+  ufrag: string | undefined,
+  candidate: string,
+  peerType = PeerType.SUBSCRIBER,
+) => ({
+  peerType,
+  iceCandidate: JSON.stringify(
+    ufrag ? { usernameFragment: ufrag, candidate } : { candidate },
+  ),
+});
+
+const sdp = (ufrag: string) =>
+  `v=0\r\na=ice-ufrag:${ufrag}\r\na=ice-pwd:pwd\r\n`;
+
+const collect = (
+  observable: IceTrickleBuffer['subscriber']['candidates'],
+): RTCIceCandidateInit[] => {
+  const seen: RTCIceCandidateInit[] = [];
+  observable.subscribe((c) => seen.push(c)).unsubscribe();
+  return seen;
+};
+
+describe('IceTrickleBuffer', () => {
+  it('emits buffered candidates of the active generation to a new subscriber', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.push(trickle('u1', 'a'));
+    buffer.push(trickle('u1', 'b'));
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([
+      { usernameFragment: 'u1', candidate: 'a' },
+      { usernameFragment: 'u1', candidate: 'b' },
+    ]);
+  });
+
+  it('emits live candidates of the active generation', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+    const seen: RTCIceCandidateInit[] = [];
+    buffer.subscriber.candidates.subscribe((c) => seen.push(c));
+
+    buffer.push(trickle('u1', 'a'));
+
+    expect(seen).toEqual([{ usernameFragment: 'u1', candidate: 'a' }]);
+  });
+
+  it('drops superseded-generation candidates once the generation advances', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u0'));
+    buffer.push(trickle('u0', 'old'));
+
+    // ICE restart -> new generation
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+    buffer.push(trickle('u1', 'new'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([
+      { usernameFragment: 'u1', candidate: 'new' },
+    ]);
+  });
+
+  it('holds future-generation candidates until their generation becomes active', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+    // a candidate for a not-yet-applied generation arrives early (trickle race)
+    buffer.push(trickle('u2', 'future'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([]);
+
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u2'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([
+      { usernameFragment: 'u2', candidate: 'future' },
+    ]);
+  });
+
+  it('emits candidates without a generation marker (fail-open)', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+    buffer.push(trickle(undefined, 'no-generation'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([
+      { candidate: 'no-generation' },
+    ]);
+  });
+
+  it('emits all candidates when no active generation is set (fail-open)', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.push(trickle('u1', 'a'));
+    buffer.push(trickle('u2', 'b'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([
+      { usernameFragment: 'u1', candidate: 'a' },
+      { usernameFragment: 'u2', candidate: 'b' },
+    ]);
+  });
+
+  it('keeps subscriber and publisher generations independent', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.push(trickle('u1', 'sub', PeerType.SUBSCRIBER));
+    buffer.push(trickle('p1', 'pub', PeerType.PUBLISHER_UNSPECIFIED));
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+    buffer.updateActiveGeneration(PeerType.PUBLISHER_UNSPECIFIED, sdp('p1'));
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([
+      { usernameFragment: 'u1', candidate: 'sub' },
+    ]);
+    expect(collect(buffer.publisher.candidates)).toEqual([
+      { usernameFragment: 'p1', candidate: 'pub' },
+    ]);
+  });
+
+  it('dispose clears retained candidates', () => {
+    const buffer = new IceTrickleBuffer();
+    buffer.updateActiveGeneration(PeerType.SUBSCRIBER, sdp('u1'));
+    buffer.push(trickle('u1', 'a'));
+
+    buffer.dispose();
+
+    expect(collect(buffer.subscriber.candidates)).toEqual([]);
+  });
+});

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

@@ -525,37 +525,6 @@ describe('Publisher', () => {
       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';
@@ -1634,6 +1603,7 @@ describe('Publisher', () => {
                 {
                   publishOptionId: publishOption.id,
                   trackType: TrackType.VIDEO,
+                  degradationPreference: DegradationPreference.UNSPECIFIED,
                   layers: [
                     {
                       name: 'q',
@@ -1728,6 +1698,7 @@ describe('Publisher', () => {
                 {
                   publishOptionId: publishOption.id,
                   trackType: TrackType.VIDEO,
+                  degradationPreference: DegradationPreference.UNSPECIFIED,
                   layers: [
                     {
                       name: 'q',