@stream-io/video-client 1.48.0 → 1.50.0

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

@@ -37,70 +37,13 @@ describe('DynascaleManager', () => {
       clientStore: new StreamVideoWriteableStateStore(),
     });
     call.setSortParticipantsBy(noopComparator());
-    dynascaleManager = new DynascaleManager(
-      call.state,
-      call.speaker,
-      call.tracer,
-    );
+    dynascaleManager = call.dynascaleManager;
   });
 
   afterEach(() => {
     call.leave();
   });
 
-  describe('visibility tracking', () => {
-    it('should track element visibility visibility', () => {
-      let visibilityHandler: any;
-      vi.spyOn(dynascaleManager.viewportTracker, 'observe').mockImplementation(
-        (el, handler) => {
-          visibilityHandler = handler;
-          return vi.fn();
-        },
-      );
-
-      // @ts-expect-error incomplete data
-      call.state.updateOrAddParticipant('session-id', {
-        userId: 'user-id',
-        sessionId: 'session-id',
-        publishedTracks: [],
-      });
-
-      const element = document.createElement('div');
-      const untrack = dynascaleManager.trackElementVisibility(
-        element,
-        'session-id',
-        'videoTrack',
-      );
-
-      expect(visibilityHandler).toBeDefined();
-      expect(dynascaleManager.viewportTracker.observe).toHaveBeenCalledWith(
-        element,
-        expect.any(Function),
-      );
-
-      // test becoming visible
-      visibilityHandler({ isIntersecting: true });
-      expect(
-        call.state.findParticipantBySessionId('session-id')
-          ?.viewportVisibilityState?.videoTrack,
-      ).toBe(VisibilityState.VISIBLE);
-
-      // test becoming invisible
-      visibilityHandler({ isIntersecting: false });
-      expect(
-        call.state.findParticipantBySessionId('session-id')
-          ?.viewportVisibilityState?.videoTrack,
-      ).toBe(VisibilityState.INVISIBLE);
-
-      // test track reset
-      untrack();
-      expect(
-        call.state.findParticipantBySessionId('session-id')
-          ?.viewportVisibilityState?.videoTrack,
-      ).toBe(VisibilityState.UNKNOWN);
-    });
-  });
-
   describe('element binding', () => {
     let videoElement: globalThis.HTMLVideoElement;
 
@@ -619,10 +562,13 @@ describe('DynascaleManager', () => {
       });
     });
 
-    it('audio: should register and unregister watchdog binding', () => {
-      const watchdog = dynascaleManager.audioBindingsWatchdog!;
-      const registerSpy = vi.spyOn(watchdog, 'register');
-      const unregisterSpy = vi.spyOn(watchdog, 'unregister');
+    it('audio: marks element blocked on NotAllowedError', async () => {
+      vi.useFakeTimers();
+      const audioElement = document.createElement('audio');
+      Object.defineProperty(audioElement, 'srcObject', { writable: true });
+      vi.spyOn(audioElement, 'play').mockRejectedValue(
+        new DOMException('', 'NotAllowedError'),
+      );
 
       // @ts-expect-error incomplete data
       call.state.updateOrAddParticipant('session-id', {
@@ -631,29 +577,34 @@ describe('DynascaleManager', () => {
         publishedTracks: [],
       });
 
-      const cleanup = dynascaleManager.bindAudioElement(
-        document.createElement('audio'),
+      const cleanup = call.bindAudioElement(
+        audioElement,
         'session-id',
         'audioTrack',
       );
 
-      expect(registerSpy).toHaveBeenCalledWith(
-        expect.any(HTMLAudioElement),
-        'session-id',
-        'audioTrack',
+      const mediaStream = new MediaStream();
+      call.state.updateParticipant('session-id', {
+        audioStream: mediaStream,
+      });
+
+      vi.runAllTimers();
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(getCurrentValue(call.blockedAudioTracker.autoplayBlocked$)).toBe(
+        true,
       );
 
       cleanup?.();
-
-      expect(unregisterSpy).toHaveBeenCalledWith('session-id', 'audioTrack');
     });
 
-    it('audio: should track blocked audio elements on NotAllowedError', async () => {
+    it('audio: unmarks blocked element on cleanup', async () => {
       vi.useFakeTimers();
       const audioElement = document.createElement('audio');
       Object.defineProperty(audioElement, 'srcObject', { writable: true });
-      const notAllowedError = new DOMException('', 'NotAllowedError');
-      vi.spyOn(audioElement, 'play').mockRejectedValue(notAllowedError);
+      vi.spyOn(audioElement, 'play').mockRejectedValue(
+        new DOMException('', 'NotAllowedError'),
+      );
 
       // @ts-expect-error incomplete data
       call.state.updateOrAddParticipant('session-id', {
@@ -662,34 +613,37 @@ describe('DynascaleManager', () => {
         publishedTracks: [],
       });
 
-      const cleanup = dynascaleManager.bindAudioElement(
+      const cleanup = call.bindAudioElement(
         audioElement,
         'session-id',
         'audioTrack',
       );
 
-      const mediaStream = new MediaStream();
       call.state.updateParticipant('session-id', {
-        audioStream: mediaStream,
+        audioStream: new MediaStream(),
       });
 
       vi.runAllTimers();
       await vi.advanceTimersByTimeAsync(0);
 
-      expect(getCurrentValue(dynascaleManager.autoplayBlocked$)).toBe(true);
+      expect(getCurrentValue(call.blockedAudioTracker.autoplayBlocked$)).toBe(
+        true,
+      );
 
       cleanup?.();
-      expect(getCurrentValue(dynascaleManager.autoplayBlocked$)).toBe(false);
+
+      expect(getCurrentValue(call.blockedAudioTracker.autoplayBlocked$)).toBe(
+        false,
+      );
     });
 
-    it('audio: should unblock audio elements on explicit resumeAudio call', async () => {
+    it('audio: unmarks blocked element when the audio stream is removed', async () => {
       vi.useFakeTimers();
       const audioElement = document.createElement('audio');
       Object.defineProperty(audioElement, 'srcObject', { writable: true });
-      const playSpy = vi
-        .spyOn(audioElement, 'play')
-        .mockRejectedValueOnce(new DOMException('', 'NotAllowedError'))
-        .mockResolvedValue(undefined);
+      vi.spyOn(audioElement, 'play').mockRejectedValue(
+        new DOMException('', 'NotAllowedError'),
+      );
 
       // @ts-expect-error incomplete data
       call.state.updateOrAddParticipant('session-id', {
@@ -698,39 +652,90 @@ describe('DynascaleManager', () => {
         publishedTracks: [],
       });
 
-      const cleanup = dynascaleManager.bindAudioElement(
+      const cleanup = call.bindAudioElement(
         audioElement,
         'session-id',
         'audioTrack',
       );
 
-      const mediaStream = new MediaStream();
       call.state.updateParticipant('session-id', {
-        audioStream: mediaStream,
+        audioStream: new MediaStream(),
       });
 
       vi.runAllTimers();
       await vi.advanceTimersByTimeAsync(0);
 
-      expect(getCurrentValue(dynascaleManager.autoplayBlocked$)).toBe(true);
+      expect(getCurrentValue(call.blockedAudioTracker.autoplayBlocked$)).toBe(
+        true,
+      );
 
-      await dynascaleManager.resumeAudio();
+      call.state.updateParticipant('session-id', { audioStream: undefined });
+
+      vi.runAllTimers();
       await vi.advanceTimersByTimeAsync(0);
 
-      expect(playSpy).toHaveBeenCalledTimes(2);
-      expect(getCurrentValue(dynascaleManager.autoplayBlocked$)).toBe(false);
+      expect(audioElement.srcObject).toBeNull();
+      expect(getCurrentValue(call.blockedAudioTracker.autoplayBlocked$)).toBe(
+        false,
+      );
 
       cleanup?.();
     });
 
-    it('audio: should clear blocked state when the audio stream is removed', async () => {
+    it('video: watchdog re-plays element after a pause event', async () => {
       vi.useFakeTimers();
-      const audioElement = document.createElement('audio');
-      Object.defineProperty(audioElement, 'srcObject', { writable: true });
-      vi.spyOn(audioElement, 'play').mockRejectedValue(
-        new DOMException('', 'NotAllowedError'),
+      Object.defineProperties(videoElement, {
+        paused: { writable: true, configurable: true },
+        readyState: { writable: true, configurable: true },
+      });
+      // @ts-expect-error simulate paused, ready-to-play element
+      videoElement.paused = true;
+      // @ts-expect-error simulate paused, ready-to-play element
+      videoElement.readyState = 4;
+      const play = vi.spyOn(videoElement, 'play').mockResolvedValue();
+
+      // @ts-expect-error incomplete data
+      call.state.updateOrAddParticipant('session-id', {
+        userId: 'user-id',
+        sessionId: 'session-id',
+        publishedTracks: [TrackType.VIDEO],
+      });
+
+      const cleanup = dynascaleManager.bindVideoElement(
+        videoElement,
+        'session-id',
+        'videoTrack',
       );
 
+      const mediaStream = new MediaStream();
+      call.state.updateParticipant('session-id', {
+        videoStream: mediaStream,
+      });
+      vi.runAllTimers();
+
+      const callsBeforePause = play.mock.calls.length;
+      videoElement.dispatchEvent(new Event('pause'));
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(play.mock.calls.length).toBeGreaterThan(callsBeforePause);
+
+      cleanup?.();
+    });
+
+    it('audio: watchdog re-plays element after pause when useWebAudio is false', async () => {
+      vi.useFakeTimers();
+      const audioElement = document.createElement('audio');
+      Object.defineProperties(audioElement, {
+        srcObject: { writable: true },
+        paused: { writable: true, configurable: true },
+        readyState: { writable: true, configurable: true },
+      });
+      // @ts-expect-error simulate paused, ready-to-play element
+      audioElement.paused = true;
+      // @ts-expect-error simulate paused, ready-to-play element
+      audioElement.readyState = 4;
+      const play = vi.spyOn(audioElement, 'play').mockResolvedValue();
+
       // @ts-expect-error incomplete data
       call.state.updateOrAddParticipant('session-id', {
         userId: 'user-id',
@@ -744,33 +749,78 @@ describe('DynascaleManager', () => {
         'audioTrack',
       );
 
-      const mediaStream = new MediaStream();
       call.state.updateParticipant('session-id', {
-        audioStream: mediaStream,
+        audioStream: new MediaStream(),
       });
-
       vi.runAllTimers();
+
+      const callsBeforePause = play.mock.calls.length;
+      audioElement.dispatchEvent(new Event('pause'));
       await vi.advanceTimersByTimeAsync(0);
 
-      expect(getCurrentValue(dynascaleManager.autoplayBlocked$)).toBe(true);
+      expect(play.mock.calls.length).toBeGreaterThan(callsBeforePause);
 
-      call.state.updateParticipant('session-id', {
-        audioStream: undefined,
+      cleanup?.();
+    });
+
+    it('audio: no watchdog attached when useWebAudio is true', async () => {
+      globalThis._isSafari = true;
+      dynascaleManager.setUseWebAudio(true);
+
+      vi.useFakeTimers();
+      const audioElement = document.createElement('audio');
+      Object.defineProperties(audioElement, {
+        srcObject: { writable: true },
+        paused: { writable: true, configurable: true },
+        readyState: { writable: true, configurable: true },
+      });
+      // @ts-expect-error simulate paused, ready-to-play element
+      audioElement.paused = true;
+      // @ts-expect-error simulate paused, ready-to-play element
+      audioElement.readyState = 4;
+      const play = vi.spyOn(audioElement, 'play').mockResolvedValue();
+
+      // @ts-expect-error incomplete data
+      call.state.updateOrAddParticipant('session-id', {
+        userId: 'user-id',
+        sessionId: 'session-id',
+        publishedTracks: [],
       });
 
+      const cleanup = dynascaleManager.bindAudioElement(
+        audioElement,
+        'session-id',
+        'audioTrack',
+      );
+
+      call.state.updateParticipant('session-id', {
+        audioStream: new MediaStream(),
+      });
       vi.runAllTimers();
+
+      audioElement.dispatchEvent(new Event('pause'));
       await vi.advanceTimersByTimeAsync(0);
 
-      expect(audioElement.srcObject).toBeNull();
-      expect(getCurrentValue(dynascaleManager.autoplayBlocked$)).toBe(false);
+      expect(play).not.toHaveBeenCalled();
 
       cleanup?.();
     });
 
-    it('audio: should warn when binding an already-bound session', () => {
-      const watchdog = dynascaleManager.audioBindingsWatchdog!;
-      // @ts-expect-error private property
-      const warnSpy = vi.spyOn(watchdog.logger, 'warn');
+    it('audio: watchdog defers to BlockedAudioTracker when element is blocked', async () => {
+      vi.useFakeTimers();
+      const audioElement = document.createElement('audio');
+      Object.defineProperties(audioElement, {
+        srcObject: { writable: true },
+        paused: { writable: true, configurable: true },
+        readyState: { writable: true, configurable: true },
+      });
+      // @ts-expect-error simulate paused, ready-to-play element
+      audioElement.paused = true;
+      // @ts-expect-error simulate paused, ready-to-play element
+      audioElement.readyState = 4;
+      vi.spyOn(audioElement, 'play').mockRejectedValue(
+        new DOMException('', 'NotAllowedError'),
+      );
 
       // @ts-expect-error incomplete data
       call.state.updateOrAddParticipant('session-id', {
@@ -779,27 +829,30 @@ describe('DynascaleManager', () => {
         publishedTracks: [],
       });
 
-      const audioElement1 = document.createElement('audio');
-      const audioElement2 = document.createElement('audio');
-
-      const cleanup1 = dynascaleManager.bindAudioElement(
-        audioElement1,
+      const cleanup = call.bindAudioElement(
+        audioElement,
         'session-id',
         'audioTrack',
       );
 
-      const cleanup2 = dynascaleManager.bindAudioElement(
-        audioElement2,
-        'session-id',
-        'audioTrack',
-      );
+      call.state.updateParticipant('session-id', {
+        audioStream: new MediaStream(),
+      });
+      vi.runAllTimers();
+      await vi.advanceTimersByTimeAsync(0);
 
-      expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('Audio element already bound'),
-      );
+      expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
 
-      cleanup1?.();
-      cleanup2?.();
+      const traceSpy = vi.spyOn(call.tracer, 'trace');
+      audioElement.dispatchEvent(new Event('pause'));
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(traceSpy).toHaveBeenCalledWith('mediaPlayback.recover.skipped', {
+        kind: 'audio',
+        reason: 'blocked',
+      });
+
+      cleanup?.();
     });
 
     it('video: should unsubscribe when element dimensions are zero', () => {

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

@@ -0,0 +1,180 @@
+/**
+ * @vitest-environment happy-dom
+ */
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from 'vitest';
+import { MediaPlaybackWatchdog } from '../MediaPlaybackWatchdog';
+import type { Tracer } from '../../stats';
+
+const createTracer = () => ({ trace: vi.fn() }) as unknown as Tracer;
+
+type FakeMediaState = {
+  srcObject?: MediaStream | null;
+  paused?: boolean;
+  readyState?: number;
+  ended?: boolean;
+};
+
+const createMediaElement = (
+  kind: 'audio' | 'video',
+  state: FakeMediaState = {},
+) => {
+  const el = document.createElement(kind) as HTMLMediaElement;
+  Object.defineProperty(el, 'srcObject', { writable: true });
+  Object.defineProperty(el, 'paused', { writable: true, configurable: true });
+  Object.defineProperty(el, 'readyState', {
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(el, 'ended', { writable: true, configurable: true });
+  el.srcObject = 'srcObject' in state ? state.srcObject : new MediaStream();
+  el.paused = state.paused ?? true;
+  el.readyState = state.readyState ?? 4;
+  el.ended = state.ended ?? false;
+  return el;
+};
+
+type SetupOpts = {
+  kind?: 'audio' | 'video';
+  state?: FakeMediaState;
+  isBlocked?: () => boolean;
+};
+
+describe('MediaPlaybackWatchdog', () => {
+  let tracer: Tracer;
+  let el: HTMLMediaElement;
+  let play: MockInstance;
+  let watchdog: MediaPlaybackWatchdog;
+
+  const setup = (opts: SetupOpts = {}) => {
+    watchdog?.dispose();
+    const kind = opts.kind ?? 'audio';
+    el = createMediaElement(kind, opts.state);
+    play = vi.spyOn(el, 'play').mockResolvedValue();
+    watchdog = new MediaPlaybackWatchdog({
+      element: el,
+      kind,
+      tracer,
+      isBlocked: opts.isBlocked,
+    });
+  };
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    tracer = createTracer();
+    setup();
+  });
+
+  afterEach(() => {
+    watchdog.dispose();
+    vi.useRealTimers();
+  });
+
+  it('calls play() after a pause event', async () => {
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(play).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries with backoff up to the attempt cap then stops', async () => {
+    setup({ kind: 'video' });
+    play.mockRejectedValue(new Error('nope'));
+
+    el.dispatchEvent(new Event('pause'));
+
+    // Drain all scheduled retries. retryInterval caps at 5000ms per attempt;
+    // 10 attempts is bounded by ~50s of fake time.
+    for (let i = 0; i < 20; i++) {
+      await vi.advanceTimersByTimeAsync(6000);
+    }
+
+    expect(play).toHaveBeenCalledTimes(10);
+  });
+
+  it('continues recovering on subsequent pause events after a successful resume', async () => {
+    play.mockRejectedValueOnce(new Error('fail-1'));
+
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(1);
+
+    // Drain the queued backoff retry, which now resolves.
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(play).toHaveBeenCalledTimes(2);
+
+    // Simulate the element actually starting to play.
+    el.dispatchEvent(new Event('playing'));
+
+    // A subsequent pause should still trigger a fresh recovery attempt.
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not attempt recovery when srcObject is null', async () => {
+    setup({ state: { srcObject: null } });
+
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).not.toHaveBeenCalled();
+  });
+
+  it('does not attempt recovery when isBlocked returns true', async () => {
+    setup({ isBlocked: () => true });
+
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).not.toHaveBeenCalled();
+  });
+
+  it('does not attempt recovery when the element is already playing', async () => {
+    setup({ state: { paused: false } });
+
+    // a routine `suspend` while the element is actually playing should not
+    // trigger a recovery attempt
+    el.dispatchEvent(new Event('suspend'));
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).not.toHaveBeenCalled();
+  });
+
+  it('does not attempt recovery when readyState is too low', async () => {
+    setup({ state: { readyState: 0 } });
+
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).not.toHaveBeenCalled();
+  });
+
+  it('dispose removes listeners and prevents further recovery', async () => {
+    watchdog.dispose();
+
+    el.dispatchEvent(new Event('pause'));
+    el.dispatchEvent(new Event('suspend'));
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).not.toHaveBeenCalled();
+  });
+
+  it('does not stack timers when pause fires multiple times before the first attempt', async () => {
+    el.dispatchEvent(new Event('pause'));
+    el.dispatchEvent(new Event('pause'));
+    el.dispatchEvent(new Event('suspend'));
+
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(play).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { SlidingWindowRateLimiter } from '../SlidingWindowRateLimiter';
+
+describe('SlidingWindowRateLimiter', () => {
+  it('allows up to the configured number of attempts inside the window', () => {
+    const limiter = new SlidingWindowRateLimiter(3, 1000);
+    expect(limiter.tryRegister(0)).toBe(true);
+    expect(limiter.tryRegister(10)).toBe(true);
+    expect(limiter.tryRegister(20)).toBe(true);
+    // fourth attempt inside the same window is denied
+    expect(limiter.tryRegister(30)).toBe(false);
+  });
+
+  it('prunes timestamps outside the rolling window so attempts after it pass', () => {
+    const limiter = new SlidingWindowRateLimiter(2, 1000);
+    expect(limiter.tryRegister(0)).toBe(true);
+    expect(limiter.tryRegister(500)).toBe(true);
+    expect(limiter.tryRegister(900)).toBe(false);
+    // at t=1501 cutoff=501, so both 0 and 500 fall out of window
+    expect(limiter.tryRegister(1501)).toBe(true);
+  });
+
+  it('reset() clears the attempt history', () => {
+    const limiter = new SlidingWindowRateLimiter(2, 1000);
+    limiter.tryRegister(0);
+    limiter.tryRegister(100);
+    expect(limiter.tryRegister(200)).toBe(false);
+    limiter.reset();
+    expect(limiter.tryRegister(300)).toBe(true);
+    expect(limiter.tryRegister(400)).toBe(true);
+    expect(limiter.tryRegister(500)).toBe(false);
+  });
+
+  it('setLimits() updates the budget and window in place', () => {
+    const limiter = new SlidingWindowRateLimiter(2, 1000);
+    limiter.tryRegister(0);
+    limiter.tryRegister(100);
+    expect(limiter.tryRegister(200)).toBe(false);
+    // raising the limit lets the next attempt through without reset
+    limiter.setLimits(5, 1000);
+    expect(limiter.tryRegister(300)).toBe(true);
+  });
+});