feat: Automatically recover from frozen live streams (#2569)

- Closes: #2099
2026-07-07 21:37:24 -07:00
parent 9f956fe89f
commit fb1bbc739e
73 changed files with 3321 additions and 364 deletions
@@ -0,0 +1,264 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  FRAME_STALL_SECONDS,
+  FrameStallWatchdog,
+  type FrameStallWatchdogConfig,
+} from '../../../src/components-lib/media-player/frame-stall-watchdog';
+
+const STALL_MS = FRAME_STALL_SECONDS * 1000;
+
+const createConfig = (
+  overrides?: Partial<FrameStallWatchdogConfig>,
+): FrameStallWatchdogConfig => ({
+  isPlaybackExpected: vi.fn().mockReturnValue(true),
+  startSource: vi.fn().mockReturnValue(true),
+  stopSource: vi.fn(),
+  ...overrides,
+});
+
+// @vitest-environment jsdom
+describe('FrameStallWatchdog', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('source lifecycle', () => {
+    it('should start the source only on the first subscriber', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+
+      watchdog.subscribe(vi.fn());
+      watchdog.subscribe(vi.fn());
+
+      expect(config.startSource).toHaveBeenCalledTimes(1);
+    });
+
+    it('should stop the source only on the last unsubscribe', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+
+      const unsubscribeFirst = watchdog.subscribe(vi.fn());
+      const unsubscribeSecond = watchdog.subscribe(vi.fn());
+
+      unsubscribeFirst();
+      expect(config.stopSource).not.toHaveBeenCalled();
+
+      unsubscribeSecond();
+      expect(config.stopSource).toHaveBeenCalledTimes(1);
+    });
+
+    it('should default to an always-available source needing no teardown', () => {
+      const watchdog = new FrameStallWatchdog({ isPlaybackExpected: () => true });
+      const callback = vi.fn();
+
+      const unsubscribe = watchdog.subscribe(callback);
+      vi.advanceTimersByTime(STALL_MS);
+      unsubscribe(); // no stopSource configured -> no throw
+
+      expect(callback).toHaveBeenCalledWith(false);
+    });
+  });
+
+  describe('stall detection', () => {
+    it('should report stalled when no frame arrives within the window', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith(false);
+    });
+
+    it('should stay live while frames keep arriving within the window', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      for (let i = 0; i < 5; i++) {
+        vi.advanceTimersByTime(STALL_MS - 1000);
+        watchdog.notifyFrame();
+      }
+      vi.advanceTimersByTime(STALL_MS - 1000);
+
+      // Confirmed live on the first frame, and never stalled thereafter.
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith(true);
+    });
+
+    it('should report live again once a frame arrives after a stall', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      vi.advanceTimersByTime(STALL_MS);
+      expect(callback).toHaveBeenNthCalledWith(1, false);
+
+      watchdog.notifyFrame();
+      expect(callback).toHaveBeenNthCalledWith(2, true);
+    });
+
+    it('should not report stalled while the source is legitimately idle', () => {
+      const config = createConfig({
+        isPlaybackExpected: vi.fn().mockReturnValue(false),
+      });
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('should re-arm while idle so a freeze that becomes actionable later is caught', () => {
+      const isPlaybackExpected = vi.fn().mockReturnValue(false);
+      const config = createConfig({ isPlaybackExpected });
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+
+      // Idle window: no stall reported, but the watchdog re-arms rather than
+      // stopping.
+      vi.advanceTimersByTime(STALL_MS);
+      expect(callback).not.toHaveBeenCalled();
+
+      // The source becomes actionable while still frozen (holding a frame), with
+      // no new frame to kick the timer. The re-armed timer catches the freeze on
+      // the next window.
+      isPlaybackExpected.mockReturnValue(true);
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith(false);
+    });
+
+    it('should broadcast a stall to every subscriber', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const first = vi.fn();
+      const second = vi.fn();
+
+      watchdog.subscribe(first);
+      watchdog.subscribe(second);
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(first).toHaveBeenCalledTimes(1);
+      expect(first).toHaveBeenCalledWith(false);
+      expect(second).toHaveBeenCalledTimes(1);
+      expect(second).toHaveBeenCalledWith(false);
+    });
+
+    it('should not report live merely on subscribing before any frame', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      // Unconfirmed until a real frame arrives: subscribing alone does not
+      // report live.
+      watchdog.subscribe(callback);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('should confirm live on the first frame but not re-notify on the next', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      watchdog.notifyFrame();
+      watchdog.notifyFrame();
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith(true);
+    });
+  });
+
+  describe('no available source', () => {
+    it('should never report stalled when the source is unavailable', () => {
+      const config = createConfig({ startSource: vi.fn().mockReturnValue(false) });
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(callback).not.toHaveBeenCalled();
+      expect(config.isPlaybackExpected).not.toHaveBeenCalled();
+    });
+
+    it('should ignore notifyFrame when the source is unavailable', () => {
+      const config = createConfig({ startSource: vi.fn().mockReturnValue(false) });
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      watchdog.subscribe(callback);
+      watchdog.notifyFrame();
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('should not stop a source that was never started on unsubscribe', () => {
+      const config = createConfig({ startSource: vi.fn().mockReturnValue(false) });
+      const watchdog = new FrameStallWatchdog(config);
+
+      const unsubscribe = watchdog.subscribe(vi.fn());
+      unsubscribe();
+
+      expect(config.stopSource).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('teardown', () => {
+    it('should not report a stall after the last subscriber leaves', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      const callback = vi.fn();
+
+      const unsubscribe = watchdog.subscribe(callback);
+      unsubscribe();
+      vi.advanceTimersByTime(STALL_MS);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('should stop cleanly if the last subscriber unsubscribes during a recovery notification', () => {
+      const config = createConfig();
+      const watchdog = new FrameStallWatchdog(config);
+      let unsubscribe: () => void = () => {};
+      const callback = vi.fn((isLive: boolean) => {
+        if (isLive) {
+          unsubscribe();
+        }
+      });
+
+      unsubscribe = watchdog.subscribe(callback);
+
+      // Stall -> callback(false)
+      vi.advanceTimersByTime(STALL_MS);
+
+      // Recovery -> callback(true) -> unsubscribe -> stop
+      watchdog.notifyFrame();
+
+      expect(config.stopSource).toHaveBeenCalledTimes(1);
+
+      // The timer armed by notifyFrame must have been stopped, so no further
+      // stall fires with no subscribers.
+      callback.mockClear();
+      vi.advanceTimersByTime(STALL_MS);
+      expect(callback).not.toHaveBeenCalled();
+    });
+  });
+});