@stream-io/video-client 1.59.1 → 1.61.0

package/src/events/callEventHandlers.ts

@@ -1,12 +1,11 @@
 import { Call } from '../Call';
+import { reconcileRingState } from '../ringing';
 import { Dispatcher } from '../rtc';
 import {
   handleRemoteSoftMute,
   watchAudioLevelChanged,
-  watchCallAccepted,
   watchCallEnded,
   watchCallGrantsUpdated,
-  watchCallRejected,
   watchConnectionQualityChanged,
   watchDominantSpeakerChanged,
   watchInboundStateNotification,
@@ -21,16 +20,6 @@ import {
   watchTrackPublished,
   watchTrackUnpublished,
 } from '../events';
-import {
-  AllCallEvents,
-  AllClientCallEvents,
-  CallEventListener,
-} from '../coordinator/connection/types';
-
-type RingCallEvents = Extract<
-  AllClientCallEvents,
-  'call.accepted' | 'call.rejected' | 'call.missed'
->;
 
 /**
  * Registers the default event handlers for a call during its lifecycle.
@@ -83,19 +72,19 @@ export const registerEventHandlers = (call: Call, dispatcher: Dispatcher) => {
  * @param call the call to register event handlers for.
  */
 export const registerRingingCallEventHandlers = (call: Call) => {
-  const coordinatorRingEvents: {
-    [key in RingCallEvents]: (
-      call: Call,
-    ) => CallEventListener<AllCallEvents[key]>;
-  } = {
-    'call.accepted': watchCallAccepted(call),
-    'call.rejected': watchCallRejected(call),
+  const reconcile = () => {
+    reconcileRingState(call, 'ring-ws').catch((err) => {
+      call.logger.error('Failed to reconcile the ring state', err);
+    });
   };
 
-  const eventHandlers = Object.keys(coordinatorRingEvents).map((event) => {
-    const eventName = event as RingCallEvents;
-    return call.on(eventName, coordinatorRingEvents[eventName]);
-  });
+  // each event needs its own closure. `call.missed` is deliberately absent:
+  // nothing in the reconciler acts on `missed_by`, so the auto-drop owns the
+  // "nobody answered" case until the server-owned ring timeout lands.
+  const eventHandlers = [
+    call.on('call.accepted', () => reconcile()),
+    call.on('call.rejected', () => reconcile()),
+  ];
 
   return () => {
     eventHandlers.forEach((unsubscribe) => unsubscribe());

package/src/gen/coordinator/index.ts

@@ -5130,6 +5130,73 @@ export interface GetCallResponse {
    */
   own_capabilities: Array<OwnCapability>;
 }
+/**
+ * The ring state of a call session: who accepted, rejected, or missed the ring.
+ * @export
+ * @interface GetCallRingStateResponse
+ */
+export interface GetCallRingStateResponse {
+  /**
+   * Users that accepted the call, mapped to when they accepted
+   * @type {{ [key: string]: string; }}
+   * @memberof GetCallRingStateResponse
+   */
+  accepted_by: { [key: string]: string };
+  /**
+   * The CID of the call
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  call_cid: string;
+  /**
+   * When the call ended
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  call_ended_at?: string;
+  /**
+   * The user that created the call, i.e. the caller
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  created_by_user_id: string;
+  /**
+   * Duration of the request in milliseconds
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  duration: string;
+  /**
+   * Users that missed the call, mapped to when they were marked as missed
+   * @type {{ [key: string]: string; }}
+   * @memberof GetCallRingStateResponse
+   */
+  missed_by: { [key: string]: string };
+  /**
+   * Users that rejected the call, mapped to when they rejected
+   * @type {{ [key: string]: string; }}
+   * @memberof GetCallRingStateResponse
+   */
+  rejected_by: { [key: string]: string };
+  /**
+   * When the call session ended
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  session_ended_at?: string;
+  /**
+   * The call session this state belongs to, empty when the call has never rung
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  session_id: string;
+  /**
+   * When the call session started
+   * @type {string}
+   * @memberof GetCallRingStateResponse
+   */
+  session_started_at?: string;
+}
 /**
  * Basic response information
  * @export

package/src/reporting/ClientEventReporter.ts

@@ -45,6 +45,13 @@ export type ReportedIceState = 'CONNECTED' | 'FAILED' | 'NOT_CONNECTED';
 export type JoinReason =
   'first-attempt' | 'network-available' | 'migration' | 'full-rejoin';
 
+/**
+ * What triggered an automatic join, reported as `source` on the call's
+ * CoordinatorJoin events. `ring-ws` is a ring WebSocket event, `ring-poll-api`
+ * is the ring state poller.
+ */
+export type JoinSource = 'ring-ws' | 'ring-poll-api';
+
 export type ClientEventStandardCode =
   | 'CLIENT_ABORTED'
   | 'BACKEND_LEAVE'
@@ -67,6 +74,9 @@ export type ClientEventReporterOptions = {
   enabled?: boolean;
 };
 
+// TODO OL: update OpenAPI
+type ReportedClientEvent = ClientEvent & { source?: JoinSource };
+
 type StageError = {
   reason: string;
   code: string;
@@ -78,6 +88,7 @@ type StagePairState = {
   startedAt: number;
   joinAttemptIdSnapshot?: string;
   joinReasonSnapshot?: JoinReason;
+  joinSourceSnapshot?: JoinSource;
   userIdSnapshot?: string;
   lastError?: StageError;
 };
@@ -104,6 +115,7 @@ export class ClientEventReporter {
   private callContexts = new Map<string, CallReportContext>();
   private joinAttemptIds = new Map<string, string>();
   private joinReasons = new Map<string, JoinReason>();
+  private joinSources = new Map<string, JoinSource>();
   private coordinatorPairs = new Map<string, StagePairState>();
   private wsPairs = new Map<string, StagePairState>();
 
@@ -238,6 +250,7 @@ export class ClientEventReporter {
     this.callContexts.delete(cid);
     this.joinAttemptIds.delete(cid);
     this.joinReasons.delete(cid);
+    this.joinSources.delete(cid);
     this.coordinatorPairs.delete(cid);
     this.wsPairs.delete(cid);
 
@@ -269,15 +282,22 @@ export class ClientEventReporter {
 
   withJoinLifecycle = async <T>(
     cid: string,
-    joinReason: JoinReason,
+    options: { joinReason: JoinReason; joinSource?: JoinSource },
     op: () => Promise<T>,
   ): Promise<T> => {
+    const { joinReason, joinSource } = options;
+
+    if (joinSource) this.joinSources.set(cid, joinSource);
+    else this.joinSources.delete(cid);
+
     this.startCorrelation(cid, joinReason);
     try {
       return await op();
     } catch (err) {
       this.closeCallPairs(cid);
       throw err;
+    } finally {
+      this.joinSources.delete(cid);
     }
   };
 
@@ -436,6 +456,7 @@ export class ClientEventReporter {
         startedAt: Date.now(),
         joinAttemptIdSnapshot: this.joinAttemptIds.get(cid),
         joinReasonSnapshot: this.joinReasons.get(cid),
+        joinSourceSnapshot: this.joinSources.get(cid),
       };
       this.coordinatorPairs.set(cid, pair);
       this.sendForCall(cid, {
@@ -443,6 +464,7 @@ export class ClientEventReporter {
         ...(pair.joinReasonSnapshot && {
           join_reason: pair.joinReasonSnapshot,
         }),
+        ...(pair.joinSourceSnapshot && { source: pair.joinSourceSnapshot }),
         event_type: 'initiated',
       });
     }
@@ -457,6 +479,7 @@ export class ClientEventReporter {
       ...this.buildCommon(cid, 'CoordinatorJoin', pair),
       ...this.sessionIdField(cid),
       ...(pair.joinReasonSnapshot && { join_reason: pair.joinReasonSnapshot }),
+      ...(pair.joinSourceSnapshot && { source: pair.joinSourceSnapshot }),
       event_type: 'completed',
       outcome: 'success',
       retry_count_attempt: pair.attempts - 1,
@@ -476,6 +499,7 @@ export class ClientEventReporter {
       ...this.buildCommon(cid, 'CoordinatorJoin', pair),
       ...this.sessionIdField(cid),
       ...(pair.joinReasonSnapshot && { join_reason: pair.joinReasonSnapshot }),
+      ...(pair.joinSourceSnapshot && { source: pair.joinSourceSnapshot }),
       event_type: 'completed',
       outcome: 'failure',
       retry_count_attempt: pair.attempts - 1,
@@ -705,17 +729,19 @@ export class ClientEventReporter {
     };
   };
 
-  private send = (body: ClientEvent) => {
+  private send = (body: ReportedClientEvent) => {
     if (!this.enabled) return;
     void this.sendWithRetry(body);
   };
 
-  private sendForCall = (cid: string, body: ClientEvent) => {
+  private sendForCall = (cid: string, body: ReportedClientEvent) => {
     if (!this.callContexts.has(cid)) return;
     this.send(body);
   };
 
-  private sendWithRetry = async (body: ClientEvent): Promise<boolean> => {
+  private sendWithRetry = async (
+    body: ReportedClientEvent,
+  ): Promise<boolean> => {
     for (let attempt = 0; attempt < 5; attempt++) {
       try {
         await this.streamClient.doAxiosRequest<

package/src/reporting/__tests__/ClientEventReporter.test.ts

@@ -39,6 +39,12 @@ const iceEvent = (
 
 describe('ClientEventReporter', () => {
   const cid = 'default:call-1';
+  const callContext: CallReportContext = {
+    callType: 'default',
+    callId: 'call-1',
+    getCallSessionId: () => 'session-1',
+    getSfuId: () => 'sfu-1',
+  };
   let doAxiosRequest: ReturnType<typeof vi.fn>;
   let reporter: ClientEventReporter;
   let connectId: string;
@@ -72,13 +78,7 @@ describe('ClientEventReporter', () => {
     reporter = new ClientEventReporter({ streamClient });
     connectId = reporter.startCoordinatorConnection('user-1');
 
-    const ctx: CallReportContext = {
-      callType: 'default',
-      callId: 'call-1',
-      getCallSessionId: () => 'session-1',
-      getSfuId: () => 'sfu-1',
-    };
-    reporter.registerCall(cid, ctx);
+    reporter.registerCall(cid, callContext);
   });
 
   it('emits an initiated then a completed event on success', async () => {
@@ -117,6 +117,183 @@ describe('ClientEventReporter', () => {
     expect(events[1]).toMatchObject({ join_reason: 'migration' });
   });
 
+  it('carries the joinSource across the whole join lifecycle', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-poll-api' },
+      () => reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok')),
+    );
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({
+      event_type: 'initiated',
+      join_reason: 'first-attempt',
+      source: 'ring-poll-api',
+    });
+    expect(events[1]).toMatchObject({
+      event_type: 'completed',
+      outcome: 'success',
+      source: 'ring-poll-api',
+    });
+  });
+
+  it('carries the joinSource on a failed join', async () => {
+    await expect(
+      reporter.withJoinLifecycle(
+        cid,
+        { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+        () =>
+          reporter.track(cid, 'CoordinatorJoin', () =>
+            Promise.reject(new Error('boom')),
+          ),
+      ),
+    ).rejects.toThrow('boom');
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({ source: 'ring-ws' });
+    expect(events[1]).toMatchObject({
+      event_type: 'completed',
+      outcome: 'failure',
+      source: 'ring-ws',
+    });
+  });
+
+  it('omits the source key entirely when the join has none', async () => {
+    await reporter.withJoinLifecycle(cid, { joinReason: 'first-attempt' }, () =>
+      reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok')),
+    );
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect('source' in events[0]).toBe(false);
+    expect('source' in events[1]).toBe(false);
+  });
+
+  // the regression that matters: a reconnect must not inherit the ring source
+  // of the join that came before it
+  it('does not carry a ring source into a later reconnect', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+      () => reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok')),
+    );
+    doAxiosRequest.mockClear();
+
+    await reporter.withJoinLifecycle(cid, { joinReason: 'full-rejoin' }, () =>
+      reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok')),
+    );
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({ join_reason: 'full-rejoin' });
+    expect('source' in events[0]).toBe(false);
+    expect('source' in events[1]).toBe(false);
+  });
+
+  // `Call.join`'s retry loop restores the pre-join state between attempts, so a
+  // reconnect can open its own lifecycle while the join's is still on the
+  // stack. The inner one must not inherit the outer one's source.
+  it('does not leak the joinSource into a nested sourceless lifecycle', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+      () =>
+        reporter.withJoinLifecycle(cid, { joinReason: 'full-rejoin' }, () =>
+          reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok')),
+        ),
+    );
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({ join_reason: 'full-rejoin' });
+    expect('source' in events[0]).toBe(false);
+    expect('source' in events[1]).toBe(false);
+  });
+
+  // a fast reconnect reports CoordinatorJoin without a join lifecycle, so the
+  // source has to be gone by the time the lifecycle ends
+  it('does not carry the joinSource into a join reported outside the lifecycle', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+      () => reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok')),
+    );
+    doAxiosRequest.mockClear();
+
+    await reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok'));
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect('source' in events[0]).toBe(false);
+    expect('source' in events[1]).toBe(false);
+  });
+
+  // `Call.join` re-correlates mid-loop when it forces an SFU switch; those
+  // later attempts are still the same ring-caused join
+  it('keeps the joinSource across a mid-lifecycle re-correlation', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+      async () => {
+        await expect(
+          reporter.track(cid, 'CoordinatorJoin', () =>
+            Promise.reject(new Error('boom')),
+          ),
+        ).rejects.toThrow('boom');
+        reporter.startCorrelation(cid, 'first-attempt');
+        await reporter.track(cid, 'CoordinatorJoin', () =>
+          Promise.resolve('ok'),
+        );
+      },
+    );
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(4);
+    expect(events.every((e) => e.source === 'ring-ws')).toBe(true);
+    expect(events[0].join_attempt_id).not.toBe(events[3].join_attempt_id);
+  });
+
+  it('drops the joinSource when the call is unregistered', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+      () => Promise.resolve('ok'),
+    );
+    reporter.unregisterCall(cid);
+    reporter.registerCall(cid, callContext);
+    doAxiosRequest.mockClear();
+
+    reporter.startCorrelation(cid, 'first-attempt');
+    await reporter.track(cid, 'CoordinatorJoin', () => Promise.resolve('ok'));
+    await flush();
+
+    const events = postedEvents().filter((e) => e.stage === 'CoordinatorJoin');
+    expect(events).toHaveLength(2);
+    expect('source' in events[0]).toBe(false);
+  });
+
+  it('reports the source only on CoordinatorJoin', async () => {
+    await reporter.withJoinLifecycle(
+      cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-ws' },
+      () => reporter.track(cid, 'WSJoin', () => Promise.resolve('ok')),
+    );
+    await flush();
+
+    const others = postedEvents().filter((e) => e.stage !== 'CoordinatorJoin');
+    expect(others.length).toBeGreaterThan(0);
+    expect(others.some((e) => 'source' in e)).toBe(false);
+  });
+
   it('folds in-stage retries into a single pair', async () => {
     reporter.startCorrelation(cid, 'first-attempt');
     await expect(

package/src/ringing/RingStatePoller.ts

@@ -0,0 +1,177 @@
+import type { Call } from '../Call';
+import { reconcileRingState } from './reconcileRingState';
+import { CallingState } from '../store';
+import { createSubscription } from '../store/rxUtils';
+import { getTimers } from '../timers';
+import {
+  ErrorFromResponse,
+  type RingStatePollingOptions,
+} from '../coordinator/connection/types';
+import { videoLoggerSystem } from '../logger';
+
+// `doJoin` restores the previous calling state when a join fails, so JOINING can
+// go back to RINGING. Only a state the ring cannot return from ends the poller.
+const ringIsOver = (callingState: CallingState) =>
+  callingState !== CallingState.RINGING &&
+  callingState !== CallingState.JOINING;
+
+/**
+ * Polls the coordinator for the outcome of a ring the current user started.
+ *
+ * `call.accepted`, `call.rejected` and `call.missed` are delivered best-effort,
+ * with no store-and-forward, so a caller that drops one is left on a ringing
+ * screen while the callee is already in the call. After a quiet period this
+ * reads the ring state until a terminal outcome or the end of the ring window.
+ */
+export class RingStatePoller {
+  private readonly logger = videoLoggerSystem.getLogger('RingStatePoller');
+  private readonly call: Call;
+  private readonly startAfterMs: number;
+  private readonly intervalMs: number;
+  private sessionId: string | undefined;
+  private deadlineAt: number = 0;
+  private idleTimeoutId: number | undefined;
+  private intervalId: number | undefined;
+  private stopped: boolean = false;
+  private wasPolling: boolean = false;
+  private inFlight: boolean = false;
+  private unsubscribe: Array<() => void> = [];
+
+  constructor(call: Call, options: RingStatePollingOptions = {}) {
+    this.call = call;
+    this.startAfterMs = options.startAfterMs ?? 15_000;
+    this.intervalMs = options.intervalMs ?? 5_000;
+  }
+
+  /**
+   * Starts polling. Does nothing when the call has no session yet.
+   */
+  start = () => {
+    if (this.stopped || this.sessionId) return;
+    if (this.call.state.callingState !== CallingState.RINGING) return;
+
+    // captured once: `call.ended` clears the call's current session
+    const sessionId = this.call.state.session?.id;
+    if (!sessionId) {
+      this.logger.warn('the call has no session');
+      return;
+    }
+    this.sessionId = sessionId;
+
+    const ring = this.call.state.settings?.ring;
+    const maxDurationMs =
+      ring?.auto_cancel_timeout_ms || ring?.missed_call_timeout_ms || 30_000;
+    this.deadlineAt = Date.now() + maxDurationMs;
+
+    // an incoming event proves the socket is alive, so the quiet period starts
+    // over: in a group ring a single rejection does not settle the ring.
+    this.unsubscribe.push(
+      this.call.on('call.accepted', () => this.armIdleWindow()),
+      this.call.on('call.rejected', () => this.armIdleWindow()),
+      this.call.on('call.missed', () => this.armIdleWindow()),
+      // the ring is over, whichever way it went. Joining an accepted call
+      // never goes through `leave`, so this is the only signal for it.
+      createSubscription(this.call.state.callingState$, (callingState) => {
+        if (ringIsOver(callingState)) this.stop();
+      }),
+    );
+
+    this.armIdleWindow();
+  };
+
+  /**
+   * Pauses polling, keeping the captured session, the deadline and the event
+   * subscriptions. Resuming does not extend the ring window.
+   */
+  pause = () => {
+    if (this.stopped) return;
+    this.wasPolling = this.intervalId !== undefined;
+    const timers = getTimers();
+    timers.clearTimeout(this.idleTimeoutId);
+    timers.clearInterval(this.intervalId);
+    this.idleTimeoutId = undefined;
+    this.intervalId = undefined;
+  };
+
+  /**
+   * Resumes a paused poller. Goes straight back to polling if it was already
+   * past the quiet period, so a pause does not buy the ring another one.
+   */
+  resume = () => {
+    if (this.stopped || !this.sessionId) return;
+    if (this.idleTimeoutId !== undefined || this.intervalId !== undefined) {
+      return;
+    }
+    if (!this.wasPolling) {
+      this.armIdleWindow();
+      return;
+    }
+    this.intervalId = getTimers().setInterval(this.runTick, this.intervalMs);
+    this.runTick();
+  };
+
+  /**
+   * Stops polling. The poller cannot be restarted.
+   */
+  stop = () => {
+    if (this.stopped) return;
+    this.stopped = true;
+    const timers = getTimers();
+    timers.clearTimeout(this.idleTimeoutId);
+    timers.clearInterval(this.intervalId);
+    this.idleTimeoutId = undefined;
+    this.intervalId = undefined;
+    this.unsubscribe.forEach((off) => off());
+    this.unsubscribe = [];
+  };
+
+  private armIdleWindow = () => {
+    if (this.stopped) return;
+    const timers = getTimers();
+    timers.clearTimeout(this.idleTimeoutId);
+    timers.clearInterval(this.intervalId);
+    this.intervalId = undefined;
+    this.idleTimeoutId = timers.setTimeout(() => {
+      this.idleTimeoutId = undefined;
+      if (this.stopped) return;
+      this.intervalId = timers.setInterval(this.runTick, this.intervalMs);
+      this.runTick();
+    }, this.startAfterMs);
+  };
+
+  private runTick = () => {
+    this.tick().catch((err) => {
+      this.logger.warn('Failed to poll the ring state', err);
+    });
+  };
+
+  private tick = async () => {
+    if (this.stopped || this.inFlight || !this.sessionId) return;
+    const { callingState } = this.call.state;
+    if (ringIsOver(callingState) || Date.now() >= this.deadlineAt) {
+      this.stop();
+      return;
+    }
+    // mid-join: nothing to reconcile until we know whether it succeeded
+    if (callingState !== CallingState.RINGING) return;
+
+    this.inFlight = true;
+    try {
+      const ringState = await this.call.getRingState(this.sessionId);
+      if (this.stopped) return;
+      this.call.state.updateFromRingState(ringState);
+      if (await reconcileRingState(this.call, 'ring-poll-api')) this.stop();
+    } catch (err) {
+      // a missing session, or one of another call, will never resolve
+      const status = err instanceof ErrorFromResponse ? err.status : undefined;
+      if (status === 400 || status === 404) {
+        this.logger.warn('Stopped polling the ring state', err);
+        this.stop();
+      } else {
+        this.logger.debug('Failed to poll the ring state', err);
+      }
+    } finally {
+      this.inFlight = false;
+    }
+  };
+}