@stream-io/video-client 2.0.0-beta.0 → 2.0.0-beta.1

package/src/ringing/__tests__/reconcileRingState.test.ts

@@ -0,0 +1,330 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fromPartial } from '@total-typescript/shoehorn';
+import { reconcileRingState } from '../reconcileRingState';
+import { CallingState, ClientState } from '../../store';
+import {
+  CallResponse,
+  CallSessionResponse,
+  MemberResponse,
+} from '../../gen/coordinator';
+import { Call } from '../../Call';
+import { StreamClient } from '../../coordinator/connection/client';
+import type { JoinSource } from '../../reporting';
+import { ClientEventReporter } from '../../reporting';
+import { settled } from '../../helpers/concurrency';
+
+describe('reconcileRingState', () => {
+  describe('acceptance', () => {
+    it('ignores an acceptance by the current user', async () => {
+      const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+      setSession(call, { accepted_by: { m1: timestamp() } });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.join).not.toHaveBeenCalled();
+    });
+
+    it('joins the call for the caller once a callee has accepted', async () => {
+      const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+      setSession(call, { accepted_by: { m2: timestamp() } });
+
+      expect(await reconcile(call)).toBe(true);
+      expect(call.join).toHaveBeenCalledWith({ joinSource: 'ring-ws' });
+    });
+
+    it('reports the poller as the source when the poll found the acceptance', async () => {
+      const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+      setSession(call, { accepted_by: { m2: timestamp() } });
+
+      expect(await reconcile(call, 'ring-poll-api')).toBe(true);
+      expect(call.join).toHaveBeenCalledWith({ joinSource: 'ring-poll-api' });
+    });
+
+    it('is not terminal when the join fails, so a retry can follow', async () => {
+      const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+      setSession(call, { accepted_by: { m2: timestamp() } });
+      vi.mocked(call.join).mockRejectedValueOnce(new Error('transient'));
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.join).toHaveBeenCalled();
+      expect(call.leave).not.toHaveBeenCalled();
+    });
+
+    it('does not join another callee when someone else accepts', async () => {
+      const call = ringingCall({ currentUserId: 'm2', createdById: 'm0' });
+      setSession(call, { accepted_by: { m1: timestamp() } });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.join).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('rejection', () => {
+    it('cancels the call once every callee has rejected', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm1',
+        members: ['m1', 'm2', 'm3'],
+      });
+      setSession(call, {
+        rejected_by: { m2: timestamp(), m3: timestamp() },
+      });
+
+      expect(await reconcile(call)).toBe(true);
+      expect(call.leave).toHaveBeenCalledWith({
+        reject: true,
+        reason: 'cancel',
+        message: 'ring: everyone rejected',
+      });
+    });
+
+    it('is not terminal when leaving fails, so a retry can follow', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm1',
+        members: ['m1', 'm2'],
+      });
+      setSession(call, { rejected_by: { m2: timestamp() } });
+      vi.mocked(call.leave).mockRejectedValueOnce(new Error('transient'));
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.leave).toHaveBeenCalled();
+    });
+
+    it('keeps ringing while only one callee has rejected', async () => {
+      const call = ringingCall({
+        currentUserId: 'm0',
+        createdById: 'm0',
+        members: ['m0', 'm1', 'm2'],
+      });
+      setSession(call, { rejected_by: { m2: timestamp() } });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.leave).not.toHaveBeenCalled();
+    });
+
+    it('leaves a callee once the caller has cancelled', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm0',
+        members: ['m0', 'm1', 'm2'],
+      });
+      setSession(call, { rejected_by: { m0: timestamp() } });
+
+      expect(await reconcile(call)).toBe(true);
+      expect(call.leave).toHaveBeenCalledWith({
+        reason: 'ended',
+        message: 'ring: creator rejected',
+      });
+    });
+
+    it('keeps a callee ringing while another callee rejects', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm0',
+        members: ['m0', 'm1', 'm2'],
+      });
+      setSession(call, { rejected_by: { m2: timestamp() } });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.leave).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('missed', () => {
+    it('keeps ringing when every callee is marked missed before auto-cancel', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm1',
+        members: ['m1', 'm2', 'm3'],
+      });
+      setSession(call, {
+        missed_by: { m2: timestamp(), m3: timestamp() },
+      });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.leave).not.toHaveBeenCalled();
+    });
+
+    it('keeps ringing when callees are split between rejected and missed', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm1',
+        members: ['m1', 'm2', 'm3'],
+      });
+      setSession(call, {
+        rejected_by: { m2: timestamp() },
+        missed_by: { m3: timestamp() },
+      });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.leave).not.toHaveBeenCalled();
+    });
+
+    it('keeps ringing while one callee can still accept', async () => {
+      const call = ringingCall({
+        currentUserId: 'm1',
+        createdById: 'm1',
+        members: ['m1', 'm2', 'm3'],
+      });
+      setSession(call, { missed_by: { m2: timestamp() } });
+
+      expect(await reconcile(call)).toBe(false);
+      expect(call.leave).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('ended call', () => {
+    it('leaves without rejecting, even when the call was accepted', async () => {
+      const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+      setSession(call, {
+        accepted_by: { m2: timestamp() },
+        ended_at: timestamp(),
+      });
+
+      expect(await reconcile(call)).toBe(true);
+      expect(call.join).not.toHaveBeenCalled();
+      expect(call.leave).toHaveBeenCalledWith({
+        reject: false,
+        reason: 'ended',
+        message: 'ring: call ended',
+      });
+    });
+
+    it('leaves when the call itself has ended', async () => {
+      const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+      setSession(call, {});
+      call.state.setEndedAt(new Date());
+
+      expect(await reconcile(call)).toBe(true);
+      expect(call.leave).toHaveBeenCalledWith({
+        reject: false,
+        reason: 'ended',
+        message: 'ring: call ended',
+      });
+    });
+  });
+
+  it('is terminal once the call is no longer ringing', async () => {
+    const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+    setSession(call, { accepted_by: { m2: timestamp() } });
+    call.state.setCallingState(CallingState.JOINED);
+
+    expect(await reconcile(call)).toBe(true);
+    expect(call.join).not.toHaveBeenCalled();
+    expect(call.leave).not.toHaveBeenCalled();
+  });
+
+  // Pins the ordering the state-driven reconciler depends on: `Call.setup`
+  // registers `updateFromEvent` as an `all` listener, and `dispatchEvent`
+  // drains those before the typed ring handlers. Reconciling from state would
+  // silently read the previous session if either side changed.
+  it('sees the event data on the state by the time a ring handler runs', async () => {
+    const call = ringingCall({ currentUserId: 'm1', createdById: 'm1' });
+    await call.setup();
+    call.state.setCallingState(CallingState.RINGING);
+
+    call.streamClient.dispatchEvent(
+      fromPartial({
+        type: 'call.accepted',
+        call_cid: call.cid,
+        created_at: new Date().toISOString(),
+        user: { id: 'm2' },
+        call: {
+          ...callResponse('m1'),
+          session: {
+            id: 'session-1',
+            accepted_by: { m2: timestamp() },
+            rejected_by: {},
+            missed_by: {},
+            participants: [],
+            participants_count_by_role: {},
+          },
+        },
+      }),
+    );
+    await settled(call['joinLeaveConcurrencyTag']);
+
+    expect(call.join).toHaveBeenCalledWith({ joinSource: 'ring-ws' });
+  });
+
+  it('keeps ringing when the call has no members yet', async () => {
+    const call = ringingCall({
+      currentUserId: 'm1',
+      createdById: 'm1',
+      members: [],
+    });
+    setSession(call, {});
+
+    expect(await reconcile(call)).toBe(false);
+    expect(call.leave).not.toHaveBeenCalled();
+  });
+});
+
+// the source only matters for the caller's join, so default it and let the
+// tests that assert on it pass their own
+const reconcile = (call: Call, joinSource: JoinSource = 'ring-ws') =>
+  reconcileRingState(call, joinSource);
+
+const timestamp = () => new Date().toISOString();
+
+const callResponse = (createdById: string) =>
+  fromPartial<CallResponse>({
+    id: '12345',
+    type: 'development',
+    cid: 'development:12345',
+    created_by: { id: createdById },
+    blocked_user_ids: [],
+    egress: {},
+    settings: {
+      ring: {
+        auto_cancel_timeout_ms: 30_000,
+        incoming_call_timeout_ms: 30_000,
+        missed_call_timeout_ms: 30_000,
+      },
+      screensharing: { target_resolution: undefined },
+    },
+  });
+
+const setSession = (call: Call, session: Partial<CallSessionResponse>) => {
+  call.state['sessionSubject'].next(
+    fromPartial({
+      accepted_by: {},
+      rejected_by: {},
+      missed_by: {},
+      ...session,
+    }),
+  );
+};
+
+const ringingCall = ({
+  currentUserId,
+  createdById,
+  members = [currentUserId, 'm2'],
+}: {
+  currentUserId: string;
+  createdById: string;
+  members?: string[];
+}) => {
+  const store = new ClientState();
+  store.setConnectedUser(fromPartial({ id: currentUserId }));
+  const streamClient = new StreamClient('api-key');
+  const call = new Call({
+    type: 'development',
+    id: '12345',
+    clientState: store,
+    streamClient,
+    clientEventReporter: new ClientEventReporter({ streamClient }),
+    ringing: true,
+  });
+
+  call.state.updateFromCallResponse(callResponse(createdById));
+  call.state.setMembers(
+    members.map((userId) => fromPartial<MemberResponse>({ user_id: userId })),
+  );
+  call.state.setCallingState(CallingState.RINGING);
+
+  vi.spyOn(call, 'join').mockResolvedValue(undefined);
+  vi.spyOn(call, 'leave').mockResolvedValue(undefined);
+
+  return call;
+};

package/src/ringing/__tests__/resolveOwnRingOutcome.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { fromPartial } from '@total-typescript/shoehorn';
+import {
+  type OwnRingOutcomeInput,
+  resolveOwnRingOutcome,
+} from '../resolveOwnRingOutcome';
+import { CallingState } from '../../store';
+import { CallSessionResponse } from '../../gen/coordinator';
+
+const ME = 'm1';
+const timestamp = () => new Date().toISOString();
+
+describe('resolveOwnRingOutcome', () => {
+  const resolve = (overrides: Partial<OwnRingOutcomeInput> = {}) =>
+    resolveOwnRingOutcome({
+      currentUserId: ME,
+      callingState: CallingState.RINGING,
+      ...overrides,
+      session: fromPartial<CallSessionResponse>({
+        accepted_by: {},
+        rejected_by: {},
+        missed_by: {},
+        ...overrides.session,
+      }),
+    });
+
+  it('reports nothing while nobody has acted', () => {
+    expect(resolve()).toEqual({ settledByMe: false });
+  });
+
+  it('reports nothing for another user accepting or rejecting', () => {
+    const outcome = resolve({
+      session: fromPartial({
+        accepted_by: { m2: timestamp() },
+        rejected_by: { m3: timestamp() },
+      }),
+    });
+
+    expect(outcome).toEqual({ settledByMe: false });
+  });
+
+  it('leaves when the ring was answered on another device', () => {
+    const outcome = resolve({
+      session: fromPartial({ accepted_by: { [ME]: timestamp() } }),
+    });
+
+    expect(outcome).toEqual({
+      settledByMe: true,
+      leaveReason: 'answeredElsewhere',
+    });
+  });
+
+  it('does not leave when this device is the one that accepted', () => {
+    const outcome = resolve({
+      callingState: CallingState.JOINING,
+      session: fromPartial({ accepted_by: { [ME]: timestamp() } }),
+    });
+
+    // the drop no longer has to fire, but this device is joining, not leaving
+    expect(outcome).toEqual({ settledByMe: true, leaveReason: undefined });
+  });
+
+  it('leaves when the current user rejected', () => {
+    const outcome = resolve({
+      session: fromPartial({ rejected_by: { [ME]: timestamp() } }),
+    });
+
+    expect(outcome).toEqual({ settledByMe: true, leaveReason: 'rejected' });
+  });
+
+  it('prefers the answered-elsewhere reason over a rejection', () => {
+    const outcome = resolve({
+      session: fromPartial({
+        accepted_by: { [ME]: timestamp() },
+        rejected_by: { [ME]: timestamp() },
+      }),
+    });
+
+    expect(outcome).toEqual({
+      settledByMe: true,
+      leaveReason: 'answeredElsewhere',
+    });
+  });
+
+  it('reports nothing without a connected user', () => {
+    const outcome = resolve({
+      currentUserId: undefined,
+      session: fromPartial({ rejected_by: { [ME]: timestamp() } }),
+    });
+
+    expect(outcome).toEqual({ settledByMe: false });
+  });
+
+  it('reports nothing without a session', () => {
+    expect(
+      resolveOwnRingOutcome({
+        session: undefined,
+        currentUserId: ME,
+        callingState: CallingState.RINGING,
+      }),
+    ).toEqual({ settledByMe: false });
+  });
+});

package/src/ringing/index.ts

@@ -0,0 +1,4 @@
+export * from './RingStatePoller';
+export * from './RingTimeout';
+export * from './reconcileRingState';
+export * from './resolveOwnRingOutcome';

package/src/ringing/reconcileRingState.ts

@@ -0,0 +1,108 @@
+import type { Call } from '../Call';
+import type { JoinSource } from '../reporting';
+import { CallingState } from '../store';
+import type { CallLeaveOptions } from '../types';
+
+/**
+ * Decides what a ringing call should do next, based on the current call state.
+ *
+ * The `call.accepted`, `call.rejected` and `call.missed` handlers and the ring
+ * state poller both run this. They differ only in how the state got there: the
+ * handlers rely on `CallState.updateFromEvent`, which runs before them, and the
+ * poller applies the polled ring state itself.
+ *
+ * @param call the call to reconcile.
+ * @param joinSource which of the two triggered this run, reported on the
+ * caller's join: `ring-ws` for the event handlers, `ring-poll-api` for the
+ * poller.
+ * @returns whether the ring reached a terminal state. A failed join is not
+ * terminal: the caller should keep trying while the ring is open.
+ */
+export const reconcileRingState = async (
+  call: Call,
+  joinSource: JoinSource,
+): Promise<boolean> => {
+  if (call.state.callingState !== CallingState.RINGING) return true;
+  return call.isCreatedByMe
+    ? reconcileAsCaller(call, joinSource)
+    : reconcileAsCallee(call);
+};
+
+const reconcileAsCaller = async (
+  call: Call,
+  joinSource: JoinSource,
+): Promise<boolean> => {
+  const { session, members, endedAt } = call.state;
+  const currentUserId = call.currentUserId;
+
+  // checked before `accepted_by`: an ended session cannot be joined
+  if (endedAt || session?.ended_at) {
+    call.logger.info('ring: the call has ended, leaving');
+    // `leave` reports the remote end to callingx off `reason: 'ended'`
+    return leave(call, {
+      reject: false,
+      reason: 'ended',
+      message: 'ring: call ended',
+    });
+  }
+
+  const acceptedBy = session?.accepted_by ?? {};
+  if (Object.keys(acceptedBy).some((userId) => userId !== currentUserId)) {
+    call.logger.info('ring: the call was accepted, joining');
+    try {
+      await call.join({ joinSource });
+    } catch (err) {
+      // `doJoin` restores the ringing state when a join fails, so the ring is
+      // still open. Report it unsettled and let the next poll retry.
+      call.logger.error('Failed to join an accepted call', err);
+      return false;
+    }
+    return true;
+  }
+
+  const otherMembers = members
+    .filter((member) => member.user_id !== currentUserId)
+    .map((member) => member.user_id);
+  if (otherMembers.length === 0) return false;
+
+  const rejectedBy = session?.rejected_by ?? {};
+  if (otherMembers.every((userId) => rejectedBy[userId])) {
+    call.logger.info('ring: everyone rejected, leaving');
+    return leave(call, {
+      reject: true,
+      reason: 'cancel',
+      message: 'ring: everyone rejected',
+    });
+  }
+
+  return false;
+};
+
+// the current user's own accept or reject, on this or another device, is
+// handled by `resolveOwnRingOutcome`, and `call.ended` by `watchCallEnded`.
+const reconcileAsCallee = async (call: Call): Promise<boolean> => {
+  const createdById = call.state.createdBy?.id;
+  const rejectedBy = call.state.session?.rejected_by ?? {};
+  if (createdById && rejectedBy[createdById]) {
+    call.logger.info('ring: the caller cancelled, leaving');
+    return leave(call, {
+      reason: 'ended',
+      message: 'ring: creator rejected',
+    });
+  }
+  return false;
+};
+
+// `false` when the call could not be left, so the ring stays open for a retry.
+const leave = async (
+  call: Call,
+  options: CallLeaveOptions,
+): Promise<boolean> => {
+  try {
+    await call.leave(options);
+    return true;
+  } catch (err) {
+    call.logger.error('Failed to leave a ringing call', err);
+    return false;
+  }
+};

package/src/ringing/resolveOwnRingOutcome.ts

@@ -0,0 +1,58 @@
+import { CallingState } from '../store';
+import type { CallSessionResponse } from '../gen/coordinator';
+
+export type OwnRingOutcome = {
+  /**
+   * Whether the current user accepted or rejected the ring, on this device or
+   * on another one. Either way the ring no longer needs to time out.
+   */
+  settledByMe: boolean;
+
+  /**
+   * Set when this device should stop ringing and leave, carrying the reason to
+   * report to the native call UI.
+   */
+  leaveReason?: 'answeredElsewhere' | 'rejected';
+};
+
+export type OwnRingOutcomeInput = {
+  /** The call session to read the accept and reject maps from. */
+  session: CallSessionResponse | undefined;
+  /** The connected user, or `undefined` when there is none. */
+  currentUserId: string | undefined;
+  /** The current calling state. */
+  callingState: CallingState;
+};
+
+/**
+ * Decides what a ringing call should do about the current user's own accept or
+ * reject, which may have happened on another device.
+ *
+ * Accepting on *this* device also lands in `accepted_by`, so an acceptance only
+ * means another device took the call when this one is still ringing.
+ *
+ * Only meaningful for a ringing call; the caller checks that.
+ */
+export const resolveOwnRingOutcome = ({
+  session,
+  currentUserId,
+  callingState,
+}: OwnRingOutcomeInput): OwnRingOutcome => {
+  if (!currentUserId) return { settledByMe: false };
+
+  const acceptedByMe = Boolean(session?.accepted_by[currentUserId]);
+  const rejectedByMe = Boolean(session?.rejected_by[currentUserId]);
+  if (!acceptedByMe && !rejectedByMe) return { settledByMe: false };
+
+  const answeredElsewhere =
+    acceptedByMe && callingState === CallingState.RINGING;
+
+  return {
+    settledByMe: true,
+    leaveReason: answeredElsewhere
+      ? 'answeredElsewhere'
+      : rejectedByMe
+        ? 'rejected'
+        : undefined,
+  };
+};

package/src/rtc/Publisher.ts

@@ -150,7 +150,9 @@ export class Publisher extends BasePeerConnection {
     const sendEncodings = isSvcCodec(publishOption.codec?.name)
       ? toSvcEncodings(encodings)
       : encodings;
-    const transceiver = this.pc.addTransceiver(track, {
+    // An E2EE sender must never have media before its transform is attached,
+    // including when another track or an ICE restart negotiates this PC.
+    const transceiver = this.pc.addTransceiver(this.e2ee ? track.kind : track, {
       direction: 'sendonly',
       sendEncodings,
     });
@@ -161,23 +163,75 @@ export class Publisher extends BasePeerConnection {
     this.trackIdToTrackType.set(track.id, trackType);
     this.logger.debug(`Added ${TrackType[trackType]} transceiver`);
 
-    const params = transceiver.sender.getParameters();
-    params.degradationPreference =
-      toRTCDegradationPreference(publishOption.degradationPreference) ??
-      'maintain-framerate';
-    await transceiver.sender.setParameters(params);
     if (this.e2ee) {
-      this.e2ee.encrypt(
-        transceiver.sender,
-        publishOption.codec?.name.toLowerCase(),
-        TrackType[publishOption.trackType],
-      );
-      this.logger.debug('E2EE encryptor attached to sender');
+      await this.initEncryptedSender(transceiver, track, publishOption);
+    } else {
+      await this.setDegradationPreference(transceiver.sender, publishOption);
     }
 
     await this.negotiate();
   };
 
+  /**
+   * Attaches the encryptor, applies sender parameters, then attaches the track.
+   *
+   * `encrypt` must run before the first await: Chrome short-circuits a sender
+   * whose encoded streams aren't created in the task that created it, and the
+   * track goes on last so the sender has no media until both steps succeed.
+   */
+  private initEncryptedSender = async (
+    transceiver: RTCRtpTransceiver,
+    track: MediaStreamTrack,
+    publishOption: PublishOption,
+  ) => {
+    try {
+      const { sender } = transceiver;
+      const codec = publishOption.codec?.name.toLowerCase();
+      this.e2ee!.encrypt(sender, codec, TrackType[publishOption.trackType]);
+      this.logger.debug('E2EE encryptor attached to sender');
+      await this.setDegradationPreference(sender, publishOption);
+      await sender.replaceTrack(track);
+    } catch (err) {
+      this.retireTransceiver(transceiver, track);
+      throw err;
+    }
+  };
+
+  private setDegradationPreference = async (
+    sender: RTCRtpSender,
+    publishOption: PublishOption,
+  ) => {
+    const params = sender.getParameters();
+    params.degradationPreference =
+      toRTCDegradationPreference(publishOption.degradationPreference) ??
+      'maintain-framerate';
+    await sender.setParameters(params);
+  };
+
+  /**
+   * Discards a sender whose E2EE initialization failed.
+   *
+   * A partially initialized sender may carry no transform, so publish() must
+   * not reuse it: retiring it from the cache is what keeps a later publish or
+   * ICE restart from putting cleartext on the wire. Cleanup cannot throw, so
+   * the initialization failure is what reaches the caller.
+   */
+  private retireTransceiver = (
+    transceiver: RTCRtpTransceiver,
+    track: MediaStreamTrack,
+  ) => {
+    this.transceiverCache.remove(transceiver);
+    this.trackIdToTrackType.delete(track.id);
+    // on React Native a clone shares its native source, so stopping it here
+    // would stop the track the caller passed in. dispose() releases it.
+    if (!isReactNative()) this.stopTrack(track);
+    try {
+      transceiver.stop();
+    } catch (err) {
+      this.logger.debug('Failed to stop a retired transceiver', err);
+    }
+  };
+
   /**
    * Updates the transceiver with the given track and track type.
    */