@stream-io/video-client 1.60.0 → 1.61.1

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

@@ -26,6 +26,7 @@ import { TransceiverCache } from '../TransceiverCache';
 import { promiseWithResolvers } from '../../helpers/promise';
 import { settled } from '../../helpers/concurrency';
 import { isFirefox } from '../../helpers/browsers';
+import { isReactNative } from '../../helpers/platforms';
 
 vi.mock('../../StreamSfuClient', () => {
   console.log('MOCKING StreamSfuClient');
@@ -40,6 +41,12 @@ vi.mock('../../helpers/browsers', async (importOriginal) => {
   return { ...actual, isFirefox: vi.fn().mockReturnValue(false) };
 });
 
+vi.mock('../../helpers/platforms', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../../helpers/platforms')>();
+  return { ...actual, isReactNative: vi.fn().mockReturnValue(false) };
+});
+
 describe('Publisher', () => {
   const sessionId = 'session-id-test';
   let publisher: Publisher;
@@ -106,6 +113,208 @@ describe('Publisher', () => {
   });
 
   describe('Publishing', () => {
+    describe('E2EE initialization failures', () => {
+      afterEach(() => {
+        vi.mocked(isReactNative).mockReturnValue(false);
+      });
+
+      const setup = async () => {
+        await publisher.dispose();
+        const e2ee = { encrypt: vi.fn(), decrypt: vi.fn() };
+        publisher = new Publisher(
+          {
+            sfuClient,
+            dispatcher,
+            state,
+            tag: 'test',
+            enableTracing: false,
+            e2ee,
+          },
+          [
+            fromPartial<PublishOption>({
+              id: 1,
+              trackType: TrackType.VIDEO,
+              codec: { name: 'vp9' },
+            }),
+          ],
+        );
+        const transceivers: RTCRtpTransceiver[] = [];
+        vi.mocked(publisher['pc'].addTransceiver).mockImplementation((kind) => {
+          expect(kind).toBe('video');
+          const transceiver = new RTCRtpTransceiver();
+          vi.mocked(transceiver.sender.replaceTrack).mockImplementation(
+            async (track) => {
+              expect(e2ee.encrypt).toHaveBeenCalledWith(
+                transceiver.sender,
+                'vp9',
+                'VIDEO',
+              );
+              Object.assign(transceiver.sender, { track });
+            },
+          );
+          transceivers.push(transceiver);
+          return transceiver;
+        });
+        const track = new MediaStreamTrack();
+        vi.mocked(track.clone).mockImplementation(() => new MediaStreamTrack());
+        const realNegotiate = publisher['negotiate'];
+        const negotiate = vi.fn<Publisher['negotiate']>().mockResolvedValue();
+        publisher['negotiate'] = negotiate;
+        return { e2ee, transceivers, track, negotiate, realNegotiate };
+      };
+
+      it.each([
+        'encrypt',
+        'getParameters',
+        'setParameters',
+        'replaceTrack',
+      ] as const)(
+        'retires the sender after %s fails and attaches encryption on retry',
+        async (failurePoint) => {
+          const { e2ee, transceivers, track, negotiate } = await setup();
+          const error = new Error('initialization failed');
+          e2ee.encrypt.mockImplementationOnce((sender: RTCRtpSender) => {
+            expect(sender.track).toBeNull();
+            if (failurePoint === 'encrypt') throw error;
+            if (failurePoint === 'getParameters') {
+              vi.mocked(sender.getParameters).mockImplementationOnce(() => {
+                throw error;
+              });
+            } else {
+              vi.mocked(sender[failurePoint]).mockRejectedValueOnce(error);
+            }
+          });
+          await expect(publisher.publish(track, TrackType.VIDEO)).rejects.toBe(
+            error,
+          );
+          const failed = transceivers[0];
+          expect(failed.sender.track).toBeNull();
+          expect(failed.stop).toHaveBeenCalledOnce();
+          expect(publisher['transceiverCache'].items()).toHaveLength(0);
+          expect(publisher['clonedTracks'].size).toBe(0);
+          expect(negotiate).not.toHaveBeenCalled();
+
+          await publisher.publish(track, TrackType.VIDEO);
+          expect(transceivers).toHaveLength(2);
+          expect(e2ee.encrypt).toHaveBeenLastCalledWith(
+            transceivers[1].sender,
+            'vp9',
+            'VIDEO',
+          );
+          expect(transceivers[1].sender.track).not.toBeNull();
+          expect(publisher['transceiverCache'].indexOf(failed)).toBe(-1);
+          expect(publisher['transceiverCache'].indexOf(transceivers[1])).toBe(
+            0,
+          );
+          expect(negotiate).toHaveBeenCalledOnce();
+        },
+      );
+
+      it('keeps the mid index of a retired sender that reached an m-section', async () => {
+        const { e2ee, transceivers, track } = await setup();
+        const error = new Error('initialization failed');
+        e2ee.encrypt.mockImplementationOnce((sender: RTCRtpSender) => {
+          Object.assign(transceivers[0], { mid: '0' });
+          vi.mocked(sender.replaceTrack).mockRejectedValueOnce(error);
+        });
+        await expect(publisher.publish(track, TrackType.VIDEO)).rejects.toBe(
+          error,
+        );
+        expect(publisher['transceiverCache'].items()).toHaveLength(0);
+        expect(publisher['transceiverCache'].indexOf(transceivers[0])).toBe(0);
+
+        await publisher.publish(track, TrackType.VIDEO);
+        expect(publisher['transceiverCache'].indexOf(transceivers[1])).toBe(1);
+      });
+
+      it('reports the initialization failure even when cleanup throws', async () => {
+        const { e2ee, transceivers, track } = await setup();
+        const error = new Error('initialization failed');
+        e2ee.encrypt.mockImplementationOnce(() => {
+          vi.mocked(transceivers[0].stop).mockImplementationOnce(() => {
+            throw new Error('peer connection is closed');
+          });
+          throw error;
+        });
+        await expect(publisher.publish(track, TrackType.VIDEO)).rejects.toBe(
+          error,
+        );
+        expect(publisher['transceiverCache'].items()).toHaveLength(0);
+        expect(publisher['clonedTracks'].size).toBe(0);
+      });
+
+      it('leaves the cloned track alone on React Native', async () => {
+        vi.mocked(isReactNative).mockReturnValue(true);
+        const { e2ee, transceivers, track } = await setup();
+        const error = new Error('initialization failed');
+        e2ee.encrypt.mockImplementationOnce(() => {
+          throw error;
+        });
+        await expect(publisher.publish(track, TrackType.VIDEO)).rejects.toBe(
+          error,
+        );
+        const [clone] = publisher['clonedTracks'];
+        expect(clone.stop).not.toHaveBeenCalled();
+        expect(transceivers[0].stop).toHaveBeenCalledOnce();
+        expect(publisher['transceiverCache'].items()).toHaveLength(0);
+      });
+
+      it('reuses an encrypted sender when only negotiation failed', async () => {
+        const { e2ee, transceivers, track, negotiate } = await setup();
+        const error = new Error('negotiation failed');
+        negotiate.mockRejectedValueOnce(error);
+        await expect(publisher.publish(track, TrackType.VIDEO)).rejects.toBe(
+          error,
+        );
+        expect(transceivers[0].sender.track).not.toBeNull();
+        expect(transceivers[0].stop).not.toHaveBeenCalled();
+        await publisher.publish(track, TrackType.VIDEO);
+        expect(transceivers).toHaveLength(1);
+        expect(e2ee.encrypt).toHaveBeenCalledOnce();
+        expect(negotiate).toHaveBeenCalledTimes(2);
+      });
+
+      it('has no media to expose if ICE restart negotiates during parameter setup', async () => {
+        const { e2ee, transceivers, track, negotiate, realNegotiate } =
+          await setup();
+        negotiate.mockImplementation(realNegotiate);
+        publisher['publishOptions'].push(
+          fromPartial<PublishOption>({
+            id: 2,
+            trackType: TrackType.VIDEO,
+            codec: { name: 'vp9' },
+          }),
+        );
+        sfuClient.setPublisher = vi
+          .fn()
+          .mockResolvedValue({ response: { sdp: 'answer-sdp' } });
+        const parameters = promiseWithResolvers<void>();
+        e2ee.encrypt
+          .mockImplementationOnce(() => {})
+          .mockImplementationOnce((sender: RTCRtpSender) => {
+            vi.mocked(sender.setParameters).mockReturnValueOnce(
+              parameters.promise,
+            );
+          });
+        const publish = publisher.publish(track, TrackType.VIDEO);
+        await vi.waitFor(() => expect(e2ee.encrypt).toHaveBeenCalledTimes(2));
+        const [published, pending] = transceivers;
+        expect(pending.sender.track).toBeNull();
+        expect(pending.sender.replaceTrack).not.toHaveBeenCalled();
+
+        await publisher.restartIce();
+        const restart = vi.mocked(sfuClient.setPublisher).mock.calls[1][0];
+        expect(restart.tracks.map((t) => t.trackId)).toEqual([
+          published.sender.track!.id,
+        ]);
+
+        parameters.resolve();
+        await publish;
+        expect(pending.sender.track).not.toBeNull();
+        expect(sfuClient.setPublisher).toHaveBeenCalledTimes(3);
+      });
+    });
+
     it('should throw when publishing ended tracks', async () => {
       const track = new MediaStreamTrack();
       // @ts-expect-error readonly field
@@ -722,6 +931,56 @@ describe('Publisher', () => {
       );
     });
 
+    it.each(['checking', 'failed'] as const)(
+      `connection-state 'failed' before ICE connects emits ICE_NEVER_CONNECTED when ICE is '%s'`,
+      async (iceState) => {
+        vi.spyOn(publisher, 'restartIce').mockResolvedValue();
+        publisher['onReconnectionNeeded'] = vi.fn();
+        // @ts-expect-error readonly field
+        publisher['pc'].iceConnectionState = iceState;
+        // @ts-expect-error readonly field
+        publisher['pc'].connectionState = 'failed';
+
+        // No ICE state-change event precedes the aggregate failure.
+        await publisher['onConnectionStateChange']();
+
+        expect(publisher.restartIce).not.toHaveBeenCalled();
+        expect(
+          publisher['onReconnectionNeeded'],
+        ).toHaveBeenCalledExactlyOnceWith(
+          WebsocketReconnectStrategy.REJOIN,
+          ReconnectReason.ICE_NEVER_CONNECTED,
+          PeerType.PUBLISHER_UNSPECIFIED,
+        );
+      },
+    );
+
+    it(`connection-state 'failed' cancels the pre-connect watchdog`, async () => {
+      vi.useFakeTimers();
+      publisher['onReconnectionNeeded'] = vi.fn();
+      const watchdogMs = publisher['iceRestartDelay'] * 2;
+
+      // @ts-expect-error readonly field
+      publisher['pc'].iceConnectionState = 'disconnected';
+      publisher['onIceConnectionStateChange']();
+      expect(publisher['preConnectStuckTimeout']).toBeDefined();
+      expect(publisher['onReconnectionNeeded']).not.toHaveBeenCalled();
+
+      // Keep ICE disconnected so an uncanceled watchdog would reconnect again.
+      // @ts-expect-error readonly field
+      publisher['pc'].connectionState = 'failed';
+      await publisher['onConnectionStateChange']();
+
+      expect(publisher['preConnectStuckTimeout']).toBeUndefined();
+      expect(publisher['onReconnectionNeeded']).toHaveBeenCalledExactlyOnceWith(
+        WebsocketReconnectStrategy.REJOIN,
+        ReconnectReason.ICE_NEVER_CONNECTED,
+        PeerType.PUBLISHER_UNSPECIFIED,
+      );
+      await vi.advanceTimersByTimeAsync(watchdogMs + 100);
+      expect(publisher['onReconnectionNeeded']).toHaveBeenCalledTimes(1);
+    });
+
     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

package/src/rtc/__tests__/mocks/webrtc.mocks.ts

@@ -60,6 +60,7 @@ const RTCRtpTransceiverMock = vi.fn(function (): Partial<RTCRtpTransceiver> {
       transform: null,
     },
     setCodecPreferences: vi.fn(),
+    stop: vi.fn(),
     mid: '',
   };
 });

package/src/rtc/e2ee/E2EEManager.ts

@@ -5,7 +5,16 @@
  * attaching their own encoded transform in these two methods.
  */
 export interface E2EEManager {
-  /** `trackType` only groups perf stats, keeping a camera and screen share apart. */
+  /**
+   * Synchronously attach a transform that encrypts the sender's outgoing frames.
+   * Must support a sender without a track, and throw if attachment fails.
+   *
+   * `sender.track` is always null here: the track is attached only after this
+   * returns, so implementations must not read it. Use `codec` and `trackType`
+   * instead.
+   *
+   * `trackType` only groups perf stats, keeping a camera and screen share apart.
+   */
   encrypt(sender: RTCRtpSender, codec?: string, trackType?: string): void;
   /** `trackType` only groups perf stats, keeping a peer's audio and video apart. */
   decrypt(receiver: RTCRtpReceiver, userId: string, trackType?: string): void;

package/src/rtc/e2ee/EncryptionManager.ts

@@ -263,9 +263,9 @@ export class EncryptionManager
     }
 
     if ((this.piped ??= new WeakSet()).has(target)) return;
-    this.piped.add(target);
     // @ts-expect-error createEncodedStreams is not in the standard typedefs
     const { readable, writable } = target.createEncodedStreams();
+    this.piped.add(target);
     this.worker.postMessage(
       { type: 'cmd.setup_transform', ...options, readable, writable },
       [readable, writable],

package/src/rtc/e2ee/SPEC.md

@@ -79,7 +79,7 @@ await call.join();
 - **Removal comes in per-epoch and per-user forms, and the names must stay distinct.** `removeKey(userId, keyIndex)` retires one epoch; `removeAllKeys(userId)` revokes the participant entirely. Do not render these as overloads of one name: dropping the index argument would then silently mean "revoke everything", which is the opposite of the caller's intent and impossible to catch in review.
 - **Every key operation's outcome is tabulated in Appendix B.** Implement the edge cases (removing the latest or active epoch, a failed import, an absent index) from that table rather than from prose.
 - **Join request carries `e2ee: true`** so the backend knows the call is encrypted.
-- The internal attach points (`encrypt(sender, codec, trackType)` / `decrypt(receiver, userId, trackType)`) are called by the RTC layer, not by apps. Keeping them behind a small interface lets an integrator plug in a different scheme (e.g. SFrame).
+- The internal attach points (`encrypt(sender, codec, trackType)` / `decrypt(receiver, userId, trackType)`) are called by the RTC layer, not by apps. The publisher creates an E2EE sender without a track and attaches media only after `encrypt` returns and sender parameters succeed. `encrypt` must synchronously attach the transform or throw, and must support a sender whose `track` is null. A failed initialization retires that transceiver so retries cannot bypass attachment. Keeping these points behind a small interface lets an integrator plug in a different scheme (e.g. SFrame).
 
 ---
 

package/src/types.ts

@@ -458,7 +458,17 @@ type StreamRNVideoSDKEndCallReason =
   | 'unknown';
 
 type StreamRNVideoSDKCallingX = {
-  joinCall: (call: Call, activeCalls: Call[]) => Promise<void>;
+  /**
+   * @param isCancelled - polled around the bridge's waits: registration is
+   *   skipped, or undone, when it returns true. Supplied by the join attempt
+   *   because the call's own state cannot distinguish a fresh join starting
+   *   from `LEFT` from an abandoned one that reached `LEFT` while waiting.
+   */
+  joinCall: (
+    call: Call,
+    activeCalls: Call[],
+    isCancelled?: () => boolean,
+  ) => Promise<void>;
   endCall: (
     call: Call,
     reason?: StreamRNVideoSDKEndCallReason,
@@ -468,8 +478,34 @@ type StreamRNVideoSDKCallingX = {
   unwireAudioEngineSubscription: () => void;
 };
 
+/**
+ * React Native's preparation and cleanup for a ringing call's join.
+ *
+ * A ringing call is joined by the SDK rather than by app code, so there is no
+ * point at which the app holds the call and can still set it up. These are that
+ * point, and the matching release.
+ */
+type StreamRNVideoSDKRingingCallLifecycle = {
+  /**
+   * Runs the app's pre-join setup and resolves once it is done, bounded by a
+   * deadline. Rejecting fails the join closed rather than joining with nothing
+   * installed.
+   */
+  beforeJoin: (call: Call) => Promise<void>;
+
+  /**
+   * The join failed terminally. Ends the ringing flow and releases what the
+   * setup installed. Never rejects, so the original join error survives.
+   */
+  onJoinFailed: (call: Call) => Promise<void>;
+
+  /** The call has ended; release whatever the pre-join hook installed. */
+  onLeave: (call: Call) => void;
+};
+
 export type StreamRNVideoSDKGlobals = {
   callingX: StreamRNVideoSDKCallingX;
+  ringingCallLifecycle: StreamRNVideoSDKRingingCallLifecycle;
   callManager: {
     /**
      * Sets up the in call manager.