@stream-io/video-client 1.59.1 → 1.60.0

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, StreamVideoWriteableStateStore } 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 StreamVideoWriteableStateStore();
+  store.setConnectedUser(fromPartial({ id: currentUserId }));
+  const streamClient = new StreamClient('api-key');
+  const call = new Call({
+    type: 'development',
+    id: '12345',
+    clientStore: 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/stats/__tests__/utils.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { getStreamClientId } from '../utils';
+import { SdkType } from '../../gen/video/sfu/models/models';
+
+describe('getStreamClientId', () => {
+  const sdk = (type: SdkType) => ({
+    type,
+    major: '1',
+    minor: '43',
+    patch: '1',
+  });
+
+  it('names the React SDK', () => {
+    expect(getStreamClientId(sdk(SdkType.REACT))).toBe(
+      'stream-video-react-v1.43.1',
+    );
+  });
+
+  it('names the React Native SDK', () => {
+    expect(getStreamClientId(sdk(SdkType.REACT_NATIVE))).toBe(
+      'stream-video-react-native-v1.43.1',
+    );
+  });
+
+  it('falls back to the plain JS client for every other SDK type', () => {
+    expect(getStreamClientId(sdk(SdkType.PLAIN_JAVASCRIPT))).toBe(
+      'stream-video-js-v1.43.1',
+    );
+    expect(getStreamClientId(undefined)).toBe(
+      'stream-video-js-v0.0.0-development',
+    );
+  });
+});

package/src/stats/utils.ts

@@ -51,3 +51,18 @@ export const getSdkName = (sdk: Sdk | undefined) => {
 export const getSdkVersion = (sdk: Sdk | undefined) => {
   return sdk ? `${sdk.major}.${sdk.minor}.${sdk.patch}` : '0.0.0-development';
 };
+
+/**
+ * Returns the identifier the SFU receives in the `X-Stream-Client` header,
+ * e.g. `stream-video-react-v1.43.1`. Matches the format the coordinator
+ * already gets through the client's user agent.
+ */
+export const getStreamClientId = (sdk: Sdk | undefined) => {
+  const sdkPlatforms: Partial<Record<SdkType, string>> = {
+    [SdkType.REACT]: 'react',
+    [SdkType.REACT_NATIVE]: 'react-native',
+  };
+
+  const platform = (sdk && sdkPlatforms[sdk.type]) || 'js';
+  return `stream-video-${platform}-v${getSdkVersion(sdk)}`;
+};

package/src/store/CallState.ts

@@ -37,6 +37,7 @@ import {
   CallSessionParticipantLeftEvent,
   CallSessionResponse,
   CallSettingsResponse,
+  GetCallRingStateResponse,
   ClosedCaptionEvent,
   EgressResponse,
   MemberResponse,
@@ -1352,6 +1353,30 @@ export class CallState {
     this.setCurrentValue(this.thumbnailsSubject, call.thumbnails);
   };
 
+  /**
+   * Merges a polled ring state into the current session. Only the ring fields
+   * are touched: the endpoint does not return the session roster.
+   *
+   * @internal
+   *
+   * @param ringState the ring state as returned by the coordinator.
+   */
+  updateFromRingState = (ringState: GetCallRingStateResponse) => {
+    this.setCurrentValue(this.sessionSubject, (session) => {
+      if (!session || session.id !== ringState.session_id) return session;
+      return {
+        ...session,
+        accepted_by: ringState.accepted_by,
+        rejected_by: ringState.rejected_by,
+        missed_by: ringState.missed_by,
+        ended_at: ringState.session_ended_at ?? session.ended_at,
+      };
+    });
+    if (ringState.call_ended_at) {
+      this.setEndedAt(new Date(ringState.call_ended_at));
+    }
+  };
+
   /**
    * Updates the call state with the data received from the SFU server.
    *