@stream-io/video-client 1.57.0 → 1.59.0

package/src/helpers/__tests__/concurrency.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import {
   hasPending,
+  singleFlight,
   withCancellation,
   withoutConcurrency,
 } from '../concurrency';
@@ -168,6 +169,79 @@ it('keeps track of pending promises', async () => {
   expect(hasPending(tag)).toBeFalsy();
 });
 
+describe('single flight', () => {
+  it('shares an in-flight promise for the wrapped function', async () => {
+    const [run1, resolve1] = mockAsyncFn('promise1');
+    const run = singleFlight(run1);
+
+    const ready1 = run();
+    const ready2 = run();
+
+    expect(ready2).toBe(ready1);
+    expect(log).toMatchObject(['promise1 start']);
+
+    resolve1();
+    await expect(Promise.all([ready1, ready2])).resolves.toEqual([
+      undefined,
+      undefined,
+    ]);
+    expect(log).toMatchObject(['promise1 start', 'promise1 end']);
+  });
+
+  it('allows a new execution after the in-flight promise settles', async () => {
+    const [run1, resolve1] = mockAsyncFn('promise1');
+    const run = singleFlight(run1);
+
+    const ready1 = run();
+    resolve1();
+    await ready1;
+
+    const ready2 = run();
+    expect(ready2).not.toBe(ready1);
+
+    resolve1();
+    await ready2;
+    expect(log).toMatchObject([
+      'promise1 start',
+      'promise1 end',
+      'promise1 start',
+      'promise1 end',
+    ]);
+  });
+
+  it('does not share promises across different wrapped functions', async () => {
+    const [runTom, resolveTom] = mockAsyncFn('tom');
+    const [runJerry, resolveJerry] = mockAsyncFn('jerry');
+    const tom = singleFlight(runTom);
+    const jerry = singleFlight(runJerry);
+
+    const readyTom = tom();
+    const readyJerry = jerry();
+
+    expect(readyJerry).not.toBe(readyTom);
+    expect(log).toMatchObject(['tom start', 'jerry start']);
+
+    resolveTom();
+    resolveJerry();
+    await Promise.all([readyTom, readyJerry]);
+  });
+
+  it('shares the first call arguments while a call is in flight', async () => {
+    const run = singleFlight(async (value: string) => {
+      log.push(`${value} start`);
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      log.push(`${value} end`);
+      return value;
+    });
+
+    await expect(Promise.all([run('first'), run('second')])).resolves.toEqual([
+      'first',
+      'first',
+    ]);
+    expect(log).toMatchObject(['first start', 'first end']);
+  });
+});
+
 describe('cancelation', () => {
   it('cancels promises mid-action', async () => {
     const tag = Symbol();

package/src/helpers/__tests__/loopback.test.ts

@@ -0,0 +1,367 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { BehaviorSubject } from 'rxjs';
+import { fromPartial } from '@total-typescript/shoehorn';
+import {
+  DEFAULT_LOOPBACK_RECORDING_DURATION_MS,
+  LoopbackStreamsTimeoutError,
+  MAX_LOOPBACK_RECORDING_DURATION_MS,
+  MIN_LOOPBACK_RECORDING_DURATION_MS,
+  clampLoopbackRecordingDuration,
+  getLoopbackStreams,
+  getLoopbackTracks,
+  waitForLoopbackStreams,
+  withLoopbackAudioEnabled,
+} from '../loopback';
+import type { Call } from '../../Call';
+import type { StreamVideoParticipant } from '../../types';
+
+const track = (kind: 'audio' | 'video', id = `${kind}-track`) =>
+  fromPartial<MediaStreamTrack>({ id, kind, enabled: false });
+
+const streamOf = (...tracks: MediaStreamTrack[]) =>
+  fromPartial<MediaStream>({
+    getAudioTracks: () => tracks.filter((t) => t.kind === 'audio'),
+    getVideoTracks: () => tracks.filter((t) => t.kind === 'video'),
+  });
+
+/** Streams the fake subscriber reports as SFU echoes. */
+const echoedStreams = new WeakSet<MediaStream>();
+
+/** A stream as it would arrive over the subscriber connection. */
+const echoOf = (...tracks: MediaStreamTrack[]) => {
+  const stream = streamOf(...tracks);
+  echoedStreams.add(stream);
+  return stream;
+};
+
+const participantWith = (streams: {
+  audioStream?: MediaStream;
+  videoStream?: MediaStream;
+}) => fromPartial<StreamVideoParticipant>(streams);
+
+const buildCall = (initial?: { participant?: StreamVideoParticipant }) => {
+  const participant$ = new BehaviorSubject<StreamVideoParticipant | undefined>(
+    initial?.participant,
+  );
+
+  const call = fromPartial<Call>({
+    state: {
+      get localParticipant() {
+        return participant$.getValue();
+      },
+      localParticipant$: participant$.asObservable(),
+    },
+    subscriber: {
+      isSelfSubscribedStream: (stream: MediaStream | undefined) =>
+        !!stream && echoedStreams.has(stream),
+    },
+  });
+
+  return { call, participant$ };
+};
+
+describe('getLoopbackStreams', () => {
+  const { call } = buildCall();
+
+  it('reads the streams the subscriber echoed back', () => {
+    const loopbackVideo = echoOf(track('video', 'loopback-video'));
+    const loopbackAudio = echoOf(track('audio', 'loopback-audio'));
+
+    const result = getLoopbackStreams(
+      call,
+      participantWith({
+        videoStream: loopbackVideo,
+        audioStream: loopbackAudio,
+      }),
+    );
+
+    expect(result.loopbackVideoStream).toBe(loopbackVideo);
+    expect(result.loopbackAudioStream).toBe(loopbackAudio);
+  });
+
+  it('ignores the capture streams the publishing path writes', () => {
+    const result = getLoopbackStreams(
+      call,
+      participantWith({
+        videoStream: streamOf(track('video')),
+        audioStream: streamOf(track('audio')),
+      }),
+    );
+
+    expect(result.loopbackVideoStream).toBeUndefined();
+    expect(result.loopbackAudioStream).toBeUndefined();
+  });
+
+  it('handles a missing participant', () => {
+    const result = getLoopbackStreams(call, undefined);
+    expect(result.loopbackVideoStream).toBeUndefined();
+    expect(result.loopbackAudioStream).toBeUndefined();
+  });
+
+  it('handles a call without a subscriber connection', () => {
+    const result = getLoopbackStreams(
+      fromPartial<Call>({}),
+      participantWith({ audioStream: echoOf(track('audio')) }),
+    );
+    expect(result.loopbackAudioStream).toBeUndefined();
+  });
+});
+
+describe('getLoopbackTracks', () => {
+  const { call } = buildCall();
+  const videoStream = echoOf(track('video', 'loopback-video'));
+  const audioStream = echoOf(track('audio', 'loopback-audio'));
+
+  it('resolves both tracks when present', () => {
+    const result = getLoopbackTracks(
+      call,
+      participantWith({ videoStream, audioStream }),
+      true,
+    );
+
+    expect(result?.audioTrack?.id).toBe('loopback-audio');
+    expect(result?.videoTrack?.id).toBe('loopback-video');
+  });
+
+  it('returns undefined while audio is missing', () => {
+    const result = getLoopbackTracks(
+      call,
+      participantWith({ videoStream }),
+      true,
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined while video is missing and video is required', () => {
+    const result = getLoopbackTracks(
+      call,
+      participantWith({ audioStream }),
+      true,
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined while only the capture streams are assigned', () => {
+    const result = getLoopbackTracks(
+      call,
+      participantWith({
+        audioStream: streamOf(track('audio')),
+        videoStream: streamOf(track('video')),
+      }),
+      true,
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it('resolves on audio alone when includeVideo is false', () => {
+    const result = getLoopbackTracks(
+      call,
+      participantWith({ audioStream }),
+      false,
+    );
+
+    expect(result?.audioTrack?.id).toBe('loopback-audio');
+    expect(result?.videoTrack).toBeUndefined();
+  });
+});
+
+describe('waitForLoopbackStreams', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const loopbackAudio = echoOf(track('audio', 'loopback-audio'));
+  const loopbackVideo = echoOf(track('video', 'loopback-video'));
+
+  it('resolves from the synchronous snapshot without waiting', async () => {
+    const { call } = buildCall({
+      participant: participantWith({
+        audioStream: loopbackAudio,
+        videoStream: loopbackVideo,
+      }),
+    });
+
+    const result = await waitForLoopbackStreams(call, {
+      includeVideo: true,
+      signal: new AbortController().signal,
+    });
+
+    expect(result?.audioTrack?.id).toBe('loopback-audio');
+  });
+
+  it('resolves once the echoed streams replace the capture ones', async () => {
+    const { call, participant$ } = buildCall({
+      participant: participantWith({
+        audioStream: streamOf(track('audio')),
+        videoStream: streamOf(track('video')),
+      }),
+    });
+
+    const pending = waitForLoopbackStreams(call, {
+      includeVideo: true,
+      signal: new AbortController().signal,
+    });
+
+    participant$.next(
+      participantWith({
+        audioStream: loopbackAudio,
+        videoStream: loopbackVideo,
+      }),
+    );
+
+    await expect(pending).resolves.toMatchObject({
+      audioTrack: { id: 'loopback-audio' },
+      videoTrack: { id: 'loopback-video' },
+    });
+  });
+
+  it('resolves null when the signal aborts', async () => {
+    const { call } = buildCall();
+    const controller = new AbortController();
+
+    const pending = waitForLoopbackStreams(call, {
+      includeVideo: true,
+      signal: controller.signal,
+    });
+    controller.abort();
+
+    await expect(pending).resolves.toBeNull();
+  });
+
+  it('resolves null when the signal is already aborted', async () => {
+    const { call } = buildCall();
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      waitForLoopbackStreams(call, {
+        includeVideo: true,
+        signal: controller.signal,
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it('rejects with a timeout error once timeoutMs elapses', async () => {
+    vi.useFakeTimers();
+    const { call } = buildCall();
+
+    const pending = waitForLoopbackStreams(call, {
+      includeVideo: true,
+      signal: new AbortController().signal,
+      timeoutMs: 1000,
+    });
+
+    vi.advanceTimersByTime(1000);
+
+    await expect(pending).rejects.toBeInstanceOf(LoopbackStreamsTimeoutError);
+  });
+
+  it('stops observing after resolving, and ignores later emissions', async () => {
+    vi.useFakeTimers();
+    const { call, participant$ } = buildCall({
+      participant: participantWith({
+        audioStream: streamOf(track('audio')),
+        videoStream: streamOf(track('video')),
+      }),
+    });
+
+    const pending = waitForLoopbackStreams(call, {
+      includeVideo: false,
+      signal: new AbortController().signal,
+      timeoutMs: 1000,
+    });
+
+    participant$.next(participantWith({ audioStream: loopbackAudio }));
+    await expect(pending).resolves.toMatchObject({
+      audioTrack: { id: 'loopback-audio' },
+    });
+
+    expect(participant$.observed).toBe(false);
+    expect(() => {
+      participant$.next(undefined);
+      vi.advanceTimersByTime(5000);
+    }).not.toThrow();
+  });
+
+  it('stops observing after aborting', async () => {
+    const { call, participant$ } = buildCall();
+    const controller = new AbortController();
+
+    const pending = waitForLoopbackStreams(call, {
+      includeVideo: true,
+      signal: controller.signal,
+    });
+    controller.abort();
+    await pending;
+
+    expect(participant$.observed).toBe(false);
+  });
+});
+
+describe('withLoopbackAudioEnabled', () => {
+  it('enables the audio track for the duration and restores it', async () => {
+    const audioTrack = track('audio');
+    let enabledDuringCall = false;
+
+    await withLoopbackAudioEnabled({ audioTrack }, async () => {
+      enabledDuringCall = audioTrack.enabled;
+    });
+
+    expect(enabledDuringCall).toBe(true);
+    expect(audioTrack.enabled).toBe(false);
+  });
+
+  it('restores the previous value when the callback throws', async () => {
+    const audioTrack = track('audio');
+
+    await expect(
+      withLoopbackAudioEnabled({ audioTrack }, async () => {
+        throw new Error('boom');
+      }),
+    ).rejects.toThrow('boom');
+
+    expect(audioTrack.enabled).toBe(false);
+  });
+
+  it('restores a previously-enabled track to enabled', async () => {
+    const audioTrack = fromPartial<MediaStreamTrack>({
+      id: 'audio-track',
+      kind: 'audio',
+      enabled: true,
+    });
+
+    await withLoopbackAudioEnabled({ audioTrack }, async () => {});
+
+    expect(audioTrack.enabled).toBe(true);
+  });
+
+  it('is a no-op without an audio track, and still returns the value', async () => {
+    await expect(
+      withLoopbackAudioEnabled({}, async () => 'result'),
+    ).resolves.toBe('result');
+  });
+});
+
+describe('clampLoopbackRecordingDuration', () => {
+  it('raises durations below the minimum', () => {
+    expect(clampLoopbackRecordingDuration(0)).toBe(
+      MIN_LOOPBACK_RECORDING_DURATION_MS,
+    );
+  });
+
+  it('lowers durations above the maximum', () => {
+    expect(clampLoopbackRecordingDuration(10 * 60 * 1000)).toBe(
+      MAX_LOOPBACK_RECORDING_DURATION_MS,
+    );
+  });
+
+  it('keeps in-range durations', () => {
+    expect(
+      clampLoopbackRecordingDuration(DEFAULT_LOOPBACK_RECORDING_DURATION_MS),
+    ).toBe(DEFAULT_LOOPBACK_RECORDING_DURATION_MS);
+  });
+
+  it('rounds fractional durations', () => {
+    expect(clampLoopbackRecordingDuration(10_000.6)).toBe(10_001);
+  });
+});

package/src/helpers/concurrency.ts

@@ -45,6 +45,30 @@ export const withCancellation = createRunner(wrapWithCancellation);
 
 const pendingPromises = new Map<TagKey, PendingPromise>();
 
+/**
+ * Wraps an async function so concurrent calls share the in-flight promise
+ * instead of queueing another execution.
+ *
+ * @param cb Async function to wrap.
+ * @returns Wrapped async function.
+ */
+export function singleFlight<P extends unknown[], T>(
+  cb: (...args: P) => Promise<T>,
+): (...args: P) => Promise<T> {
+  let pending: Promise<T> | undefined;
+  return (...args: P): Promise<T> => {
+    if (pending) return pending;
+
+    const promise = cb(...args).finally(() => {
+      if (pending === promise) {
+        pending = undefined;
+      }
+    });
+    pending = promise;
+    return promise;
+  };
+}
+
 export function hasPending(tag: TagKey) {
   return pendingPromises.has(tag);
 }

package/src/helpers/ensureExhausted.ts

@@ -1,5 +1,7 @@
 import { videoLoggerSystem } from '../logger';
 
-export const ensureExhausted = (x: never, message: string) => {
-  videoLoggerSystem.getLogger('helpers').warn(message, x);
+export const ensureExhausted = (x: never, message?: string) => {
+  if (message) {
+    videoLoggerSystem.getLogger('helpers').warn(message, x);
+  }
 };

package/src/helpers/loopback.ts

@@ -0,0 +1,200 @@
+import { Subscription } from 'rxjs';
+import type { Call } from '../Call';
+import type { StreamVideoParticipant } from '../types';
+
+/** Default loopback stream wait timeout. */
+export const LOOPBACK_STREAMS_WAIT_TIMEOUT_MS = 10 * 1000;
+
+/** Default loopback recording duration. */
+export const DEFAULT_LOOPBACK_RECORDING_DURATION_MS = 10 * 1000;
+
+/** Shortest permitted loopback recording duration. */
+export const MIN_LOOPBACK_RECORDING_DURATION_MS = 5 * 1000;
+
+/** Longest permitted loopback recording duration. */
+export const MAX_LOOPBACK_RECORDING_DURATION_MS = 2 * 60 * 1000;
+
+/** SFU-echoed streams on the local participant. */
+export type LoopbackStreams = {
+  loopbackVideoStream?: MediaStream;
+  loopbackAudioStream?: MediaStream;
+};
+
+/** SFU-echoed tracks on the local participant. */
+export type LoopbackTracks = {
+  audioTrack?: MediaStreamTrack;
+  videoTrack?: MediaStreamTrack;
+};
+
+/** Thrown when loopback tracks do not arrive in time. */
+export class LoopbackStreamsTimeoutError extends Error {
+  constructor() {
+    super(
+      'Timed out waiting for loopback streams. Ensure the call was joined ' +
+        'with `allowOwnTracksLoopback: true` and that the SFU is configured ' +
+        'to echo self-sub tracks.',
+    );
+    this.name = 'LoopbackStreamsTimeoutError';
+  }
+}
+
+/**
+ * Returns the streams on the given participant that the SFU echoed back to us,
+ * ignoring the local capture streams the publishing path writes to the same
+ * fields.
+ */
+export const getLoopbackStreams = (
+  call: Call | undefined,
+  participant: StreamVideoParticipant | undefined,
+): LoopbackStreams => {
+  const { subscriber } = call ?? {};
+  const { audioStream, videoStream } = participant ?? {};
+  return {
+    loopbackVideoStream: subscriber?.isSelfSubscribedStream(videoStream)
+      ? videoStream
+      : undefined,
+    loopbackAudioStream: subscriber?.isSelfSubscribedStream(audioStream)
+      ? audioStream
+      : undefined,
+  };
+};
+
+/**
+ * Returns loopback tracks when all required tracks are present.
+ *
+ * Prefer {@link waitForLoopbackStreams}, which observes call state until the
+ * tracks arrive. This is the synchronous snapshot it is built from.
+ *
+ * @internal
+ */
+export const getLoopbackTracks = (
+  call: Call | undefined,
+  participant: StreamVideoParticipant | undefined,
+  includeVideo: boolean,
+): LoopbackTracks | undefined => {
+  if (!participant) return undefined;
+
+  const { loopbackAudioStream, loopbackVideoStream } = getLoopbackStreams(
+    call,
+    participant,
+  );
+
+  const audioTrack = loopbackAudioStream?.getAudioTracks()[0];
+  const videoTrack = includeVideo
+    ? loopbackVideoStream?.getVideoTracks()[0]
+    : undefined;
+
+  if (!audioTrack || (includeVideo && !videoTrack)) {
+    return undefined;
+  }
+
+  return { audioTrack, videoTrack };
+};
+
+export type WaitForLoopbackStreamsOptions = {
+  /** Whether video is required. Audio is always required. */
+  includeVideo: boolean;
+  /** Aborts the wait. */
+  signal: AbortSignal;
+  /** Defaults to {@link LOOPBACK_STREAMS_WAIT_TIMEOUT_MS}. */
+  timeoutMs?: number;
+};
+
+/** Waits for the requested loopback tracks. */
+export const waitForLoopbackStreams = (
+  call: Call,
+  opts: WaitForLoopbackStreamsOptions,
+): Promise<LoopbackTracks | null> => {
+  const callState = call.state;
+  const {
+    includeVideo,
+    signal,
+    timeoutMs = LOOPBACK_STREAMS_WAIT_TIMEOUT_MS,
+  } = opts;
+
+  return new Promise((resolve, reject) => {
+    const initial = getLoopbackTracks(
+      call,
+      callState.localParticipant,
+      includeVideo,
+    );
+    if (initial) {
+      resolve(initial);
+      return;
+    }
+
+    if (signal.aborted) {
+      resolve(null);
+      return;
+    }
+
+    let settled = false;
+    const subscriptions = new Subscription();
+
+    const cleanup = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutId);
+      signal.removeEventListener('abort', onAbort);
+      subscriptions.unsubscribe();
+    };
+
+    const onAbort = () => {
+      cleanup();
+      resolve(null);
+    };
+
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      reject(new LoopbackStreamsTimeoutError());
+    }, timeoutMs);
+
+    signal.addEventListener('abort', onAbort);
+
+    subscriptions.add(
+      callState.localParticipant$.subscribe((participant) => {
+        const ready = getLoopbackTracks(call, participant, includeVideo);
+        if (ready) {
+          cleanup();
+          resolve(ready);
+        }
+      }),
+    );
+  });
+};
+
+/** Enables loopback audio while `fn` runs, then restores it. */
+export const withLoopbackAudioEnabled = async <T>(
+  tracks: LoopbackTracks,
+  fn: () => Promise<T>,
+): Promise<T> => {
+  const restore = enableLoopbackAudio(tracks);
+  try {
+    return await fn();
+  } finally {
+    restore();
+  }
+};
+
+/** Enables loopback audio and returns a restore function. */
+export const enableLoopbackAudio = (tracks: LoopbackTracks): (() => void) => {
+  const { audioTrack } = tracks;
+  const previous = audioTrack?.enabled ?? false;
+  if (audioTrack) {
+    audioTrack.enabled = true;
+  }
+  return () => {
+    if (audioTrack) {
+      audioTrack.enabled = previous;
+    }
+  };
+};
+
+/** Clamps and rounds a loopback recording duration. */
+export const clampLoopbackRecordingDuration = (durationMs: number): number =>
+  Math.round(
+    Math.min(
+      MAX_LOOPBACK_RECORDING_DURATION_MS,
+      Math.max(MIN_LOOPBACK_RECORDING_DURATION_MS, durationMs),
+    ),
+  );