@stream-io/video-client 1.59.1 → 1.60.0

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;
+    }
+  };
+}

package/src/ringing/RingTimeout.ts

@@ -0,0 +1,90 @@
+import type { Call } from '../Call';
+import { CallingState } from '../store';
+import { getTimers } from '../timers';
+import { videoLoggerSystem } from '../logger';
+
+/**
+ * Drops a call that has been ringing for too long: the caller cancels after
+ * `auto_cancel_timeout_ms`, a callee after `incoming_call_timeout_ms`.
+ *
+ * Either timeout being `0` means the call rings until something else settles it.
+ */
+export class RingTimeout {
+  private readonly call: Call;
+  private timeoutId: number | undefined;
+  private deadlineAt: number | undefined;
+  private stopped: boolean = false;
+
+  constructor(call: Call) {
+    this.call = call;
+  }
+
+  /**
+   * Schedules an auto-drop timeout based on the call settings.
+   * Applicable only for ringing calls.
+   */
+  start = () => {
+    if (this.stopped || this.timeoutId !== undefined) return;
+    // ignore if the call is not ringing
+    if (this.call.state.callingState !== CallingState.RINGING) return;
+
+    const ring = this.call.state.settings?.ring;
+    if (!ring) return;
+
+    const isCaller = this.call.isCreatedByMe;
+    const timeoutMs = isCaller
+      ? ring.auto_cancel_timeout_ms
+      : ring.incoming_call_timeout_ms;
+    // 0 means no auto-drop
+    if (timeoutMs <= 0) return;
+
+    const now = Date.now();
+    this.deadlineAt ??= now + timeoutMs;
+    const delayMs = Math.max(0, this.deadlineAt - now);
+    const timers = getTimers();
+    this.timeoutId = timers.setTimeout(() => {
+      this.timeoutId = undefined;
+      // A failed timeout-triggered leave can arm a fresh retry window.
+      this.deadlineAt = undefined;
+      if (this.stopped) return;
+      // the call might have stopped ringing by this point, e.g. it was already
+      // accepted and joined
+      if (this.call.state.callingState !== CallingState.RINGING) return;
+      this.call
+        .leave({
+          reject: true,
+          reason: 'timeout',
+          message: `ringing timeout - ${
+            isCaller
+              ? 'no one accepted'
+              : `user didn't interact with incoming call screen`
+          }`,
+        })
+        .catch((err) => {
+          videoLoggerSystem
+            .getLogger('RingTimeout')
+            .error('Failed to drop the call', err);
+        });
+    }, delayMs);
+  };
+
+  /**
+   * Pauses the timeout while preserving its original deadline.
+   */
+  pause = () => {
+    if (this.stopped || this.timeoutId === undefined) return;
+    getTimers().clearTimeout(this.timeoutId);
+    this.timeoutId = undefined;
+  };
+
+  /**
+   * Cancels a scheduled auto-drop timeout. It cannot be armed again.
+   */
+  stop = () => {
+    if (this.stopped) return;
+    this.stopped = true;
+    getTimers().clearTimeout(this.timeoutId);
+    this.timeoutId = undefined;
+    this.deadlineAt = undefined;
+  };
+}