fix: Clear stale media unavailable errors when a camera recovers (#2627)

- Closes: #2576
2026-07-28 21:21:50 -07:00
parent 231e3087b7
commit 15b08db3e8
49 changed files with 1128 additions and 229 deletions
@@ -219,6 +219,22 @@ describe('EntityAvailabilityDetector', () => {
    expect(detector.getVerdict()).toEqual({ state: 'unknown' });
  });

+  it('should re-check the entity when reset', () => {
+    // always_error makes the re-check produce a verdict immediately rather than
+    // waiting out the grace window.
+    const { detector, setEntityState } = setup({ alwaysError: true });
+    detector.subscribe();
+
+    // An entity that is already unavailable never fires a state change, so
+    // resetting must read it rather than wait to be told.
+    setEntityState('unavailable');
+    detector.reset();
+
+    expect(detector.getVerdict()).toEqual(
+      expect.objectContaining({ state: 'not_live', authority: 'hard' }),
+    );
+  });
+
  it('should do nothing on reset before subscribe', () => {
    const { detector, stateWatcher } = setup();

@@ -163,6 +163,26 @@ describe('MediaPlayerLivenessDetector', () => {
    expect(onChange).toHaveBeenCalledTimes(1);
  });

+  it('should discard a retained live verdict when watching resumes', async () => {
+    const { detector, onChange, loadMedia } = setup();
+    const { player, fireMediaPlayerLiveness } = createPlayer();
+    detector.subscribe();
+    loadMedia(player);
+    await callIntersectionHandler(true);
+    fireMediaPlayerLiveness(true);
+
+    // Away and back with nothing observed in between. The retained `live`
+    // describes the previous watch, so it must not survive into this one.
+    detector.unsubscribe();
+    onChange.mockClear();
+    detector.subscribe();
+    loadMedia(player);
+    await callIntersectionHandler(true);
+
+    expect(detector.getVerdict()).toEqual({ state: 'unknown' });
+    expect(onChange).toHaveBeenCalled();
+  });
+
  it('should not watch a player without the liveness capability', async () => {
    const { detector, onChange, loadMedia } = setup();
    const player = mock<MediaPlayerController>();
@@ -13,6 +13,19 @@ const createHostInDocument = (): HTMLElement => {

 // @vitest-environment jsdom
 describe('ProviderErrorDetector', () => {
+  it('should not report a change when reset', () => {
+    const host = createHostInDocument();
+    const onChange = vi.fn();
+    const detector = new ProviderErrorDetector(host, onChange);
+    detector.subscribe();
+    dispatchLiveErrorEvent(host);
+    onChange.mockClear();
+
+    detector.reset();
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
  it('should start unknown', () => {
    const detector = new ProviderErrorDetector(document.createElement('div'), vi.fn());

@@ -43,7 +56,7 @@ describe('ProviderErrorDetector', () => {

    dispatchLiveErrorEvent(host, {
      reason: 'unsupported',
-      detail: 'Codec not supported',
+      description: 'Codec not supported',
    });

    expect(detector.getVerdict()).toEqual({
@@ -23,6 +23,7 @@ import {
 } from '../../../test-utils';

 const ISSUE_TRIGGER_EVENT = 'advanced-camera-card:issue:trigger';
+const ISSUE_RESOLVE_EVENT = 'advanced-camera-card:issue:resolve';

 const setup = (options?: { targetID?: string | null }) => {
  const host = createLitElement();
@@ -41,11 +42,16 @@ const setup = (options?: { targetID?: string | null }) => {
    issueTriggers.push((ev as CustomEvent).detail),
  );

+  const issueResolves: unknown[] = [];
+  host.addEventListener(ISSUE_RESOLVE_EVENT, (ev) =>
+    issueResolves.push((ev as CustomEvent).detail),
+  );
+
  const failViaProviderError = (error?: LiveError): void => {
    dispatchLiveErrorEvent(host, error);
  };

-  return { host, controller, issueTriggers, failViaProviderError };
+  return { host, controller, issueTriggers, issueResolves, failViaProviderError };
 };

 const createPlayer = (): {
@@ -139,7 +145,9 @@ describe('StreamLivenessController', () => {
    const { controller, issueTriggers, failViaProviderError } = setup();
    controller.hostConnected();

-    failViaProviderError({ detail: 'Failed to start WebRTC stream: no candidates' });
+    failViaProviderError({
+      description: 'Failed to start WebRTC stream: no candidates',
+    });

    expect(controller.getFailure()).toEqual({
      reason: 'playback_error',
@@ -338,6 +346,129 @@ describe('StreamLivenessController', () => {
    vi.useRealTimers();
  });

+  describe('resolving the issue', () => {
+    const setupWithLiveStream = async () => {
+      const result = setup();
+      const { player, fireMediaPlayerLiveness } = createPlayer();
+
+      result.controller.hostConnected();
+      result.host.dispatchEvent(
+        createMediaLoadedInfoEvent({
+          info: createMediaLoadedInfo({ mediaPlayerController: player }),
+        }),
+      );
+      await callIntersectionHandler(true);
+
+      return { ...result, fireMediaPlayerLiveness };
+    };
+
+    it('should resolve when frames confirm the stream is flowing', async () => {
+      const { issueResolves, fireMediaPlayerLiveness } = await setupWithLiveStream();
+
+      fireMediaPlayerLiveness(true);
+
+      expect(issueResolves).toEqual([
+        { key: 'media_unavailable', targetID: 'camera.office' },
+      ]);
+    });
+
+    it('should not resolve while a hard failure exists', async () => {
+      const { issueResolves, failViaProviderError, fireMediaPlayerLiveness } =
+        await setupWithLiveStream();
+
+      // A provider has authoritatively condemned the stream. Frames continuing
+      // to arrive must not talk the card out of it.
+      failViaProviderError();
+      fireMediaPlayerLiveness(true);
+
+      expect(issueResolves).toEqual([]);
+    });
+
+    it('should not resolve without a target', async () => {
+      const result = setup({ targetID: null });
+      const { player, fireMediaPlayerLiveness } = createPlayer();
+
+      result.controller.hostConnected();
+      result.host.dispatchEvent(
+        createMediaLoadedInfoEvent({
+          info: createMediaLoadedInfo({ mediaPlayerController: player }),
+        }),
+      );
+      await callIntersectionHandler(true);
+      fireMediaPlayerLiveness(true);
+
+      expect(result.issueResolves).toEqual([]);
+    });
+
+    it('should not resolve on reconnect without fresh evidence', async () => {
+      const { controller, issueResolves, fireMediaPlayerLiveness } =
+        await setupWithLiveStream();
+      fireMediaPlayerLiveness(true);
+      issueResolves.length = 0;
+
+      // Away and back with nothing observed in between: the previous `live` is
+      // a memory of the old watch, not evidence about the new one.
+      controller.hostDisconnected();
+      controller.hostConnected();
+
+      expect(issueResolves).toEqual([]);
+    });
+
+    it('should not announce recovery for a stream that was reset away', async () => {
+      const { controller, issueResolves, fireMediaPlayerLiveness } =
+        await setupWithLiveStream();
+      fireMediaPlayerLiveness(true);
+      issueResolves.length = 0;
+
+      // The stream this `live` describes is being torn down, so resetting must
+      // not report it as recovered.
+      controller.reset();
+
+      expect(issueResolves).toEqual([]);
+    });
+
+    it('should not mix a stale live verdict with a freshly reset one', async () => {
+      const { controller, host, issueResolves, issueTriggers, failViaProviderError } =
+        setup();
+      const { player, fireMediaPlayerLiveness } = createPlayer();
+      controller.hostConnected();
+      host.dispatchEvent(
+        createMediaLoadedInfoEvent({
+          info: createMediaLoadedInfo({ mediaPlayerController: player }),
+        }),
+      );
+      await callIntersectionHandler(true);
+
+      // Frames say live, then a provider error condemns the stream. Both
+      // verdicts are held at once, by different detectors.
+      fireMediaPlayerLiveness(true);
+      failViaProviderError();
+      issueResolves.length = 0;
+      issueTriggers.length = 0;
+
+      // Resetting clears them in turn. If any detector announced part-way
+      // through, the cleared provider error would leave the stale `live`
+      // unopposed and the card would report a recovery that never happened.
+      controller.reset();
+
+      expect(issueResolves).toEqual([]);
+      expect(issueTriggers).toEqual([]);
+    });
+
+    it('should re-read the detectors once they have all been reset', async () => {
+      const { controller, host, fireMediaPlayerLiveness } = await setupWithLiveStream();
+      fireMediaPlayerLiveness(true);
+      vi.mocked(host.requestUpdate).mockClear();
+
+      controller.reset();
+
+      // Anything the detectors say while being reset is ignored, so this is the
+      // single read the controller makes once they are all done.
+      expect(host.requestUpdate).toHaveBeenCalledTimes(1);
+      expect(controller.isLive()).toBe(true);
+    });
+  });
+
  it('should report not live despite confirmed frames when always_error overrides', async () => {
    const host = createLitElement();
    document.body.append(host);
@@ -47,7 +47,7 @@ describe('ImageSurfaceController', () => {

    it('should have liveness when given liveness options', () => {
      const controller = new ImageSurfaceController(createLitElement(), () => null, {
-        livenessOptions: { isFrameExpected: () => true, stallWindowSeconds: 10 },
+        livenessOptions: { isFrameExpected: () => true, getStallAfterSeconds: () => 10 },
      });

      expect(controller.getMediaPlayer().subscribeLiveness).toBeDefined();
@@ -178,7 +178,8 @@ describe('Go2RTCSessionController', () => {
    const getControls = vi.fn(() => options?.controls ?? false);
    const mediaLoadedCallback = vi.fn();
    const surfaceCommittedCallback = vi.fn();
-    const errorCallback = vi.fn();
+    const streamErrorCallback = vi.fn();
+    const microphoneErrorCallback = vi.fn();

    const session = new Go2RTCSessionController(
      {
@@ -186,7 +187,8 @@ describe('Go2RTCSessionController', () => {
        getCardWideConfig: () => options?.cardWideConfig ?? null,
        mediaLoadedCallback,
        surfaceCommittedCallback,
-        errorCallback,
+        streamErrorCallback,
+        microphoneErrorCallback,
      },
      { createWebSocket, createBinarySource, createWebRTCSource, createVideoElement },
    );
@@ -201,7 +203,8 @@ describe('Go2RTCSessionController', () => {
      createBinarySource,
      createWebRTCSource,
      createWebSocket,
-      errorCallback,
+      streamErrorCallback,
+      microphoneErrorCallback,
      mediaLoadedCallback,
      offscreenVideos,
      session,
@@ -281,7 +284,8 @@ describe('Go2RTCSessionController', () => {
        surfaceCommittedCallback: vi.fn(),
        getCardWideConfig: () => null,
        mediaLoadedCallback: vi.fn(),
-        errorCallback: vi.fn(),
+        streamErrorCallback: vi.fn(),
+        microphoneErrorCallback: vi.fn(),
      });
      session.connect('ws://localhost:1/api/ws', createSurfaces().surfaces, ['mse']);
      session.reset();
@@ -536,6 +540,30 @@ describe('Go2RTCSessionController', () => {
      expect(webRTCOptions[0]?.microphoneStream).toBe(micStream);
    });

+    it('should report a microphone error without disturbing the stream', () => {
+      const {
+        session,
+        surfaces,
+        websockets,
+        webRTCOptions,
+        webRTCSources,
+        microphoneErrorCallback,
+        streamErrorCallback,
+      } = setup();
+      session.connect('http://host/api/ws?src=camera', surfaces, ['webrtc']);
+      websockets[0].fireOpen();
+
+      webRTCOptions[0]?.microphoneErrorCallback?.('InvalidStateError');
+
+      expect(microphoneErrorCallback).toHaveBeenCalledWith('InvalidStateError');
+
+      // The inbound video is unaffected by an outbound audio failure, so the
+      // source keeps running and the session neither escalates nor reconnects.
+      expect(streamErrorCallback).not.toHaveBeenCalled();
+      expect(webRTCSources[0].stop).not.toHaveBeenCalled();
+      expect(websockets).toHaveLength(1);
+    });
+
    it('should re-dispatch loaded media on an audio mute transition', () => {
      const peerConnection = new FakeRTCPeerConnection();
      const audioTransceiver = peerConnection.addTransceiver('audio', {
@@ -863,7 +891,8 @@ describe('Go2RTCSessionController', () => {
    });

    it('should escalate via the error callback after exhausting reconnect attempts', () => {
-      const { session, surfaces, websockets, createWebSocket, errorCallback } = setup();
+      const { session, surfaces, websockets, createWebSocket, streamErrorCallback } =
+        setup();
      session.connect('http://host/api/ws?src=camera', surfaces, ['mse']);

      // Each fresh connection closes before loading, consuming one reconnect
@@ -878,16 +907,17 @@ describe('Go2RTCSessionController', () => {
      websockets[3].fireClose();

      expect(createWebSocket).toHaveBeenCalledTimes(4);
-      expect(errorCallback).toHaveBeenCalledTimes(1);
+      expect(streamErrorCallback).toHaveBeenCalledTimes(1);

      // The socket dropped with no source reporting a cause.
-      expect(errorCallback).toHaveBeenCalledWith(null);
+      expect(streamErrorCallback).toHaveBeenCalledWith(null);
      vi.advanceTimersByTime(2 * 1000);
      expect(createWebSocket).toHaveBeenCalledTimes(4);
    });

    it('should escalate with the most recent source failure reason', () => {
-      const { session, surfaces, websockets, binaryContexts, errorCallback } = setup();
+      const { session, surfaces, websockets, binaryContexts, streamErrorCallback } =
+        setup();
      session.connect('http://host/api/ws?src=camera', surfaces, ['mse']);

      // Each attempt: the single binary source fails, which drains the mode
@@ -901,7 +931,7 @@ describe('Go2RTCSessionController', () => {
      websockets[3].fireOpen();
      binaryContexts[3].callbacks.failedCallback('unsupported');

-      expect(errorCallback).toHaveBeenCalledWith('unsupported');
+      expect(streamErrorCallback).toHaveBeenCalledWith('unsupported');
    });

    it('should reset the reconnect budget after a successful media load', () => {
@@ -911,7 +941,7 @@ describe('Go2RTCSessionController', () => {
        websockets,
        binaryContexts,
        createWebSocket,
-        errorCallback,
+        streamErrorCallback,
      } = setup();
      session.connect('http://host/api/ws?src=camera', surfaces, ['mse']);

@@ -933,7 +963,7 @@ describe('Go2RTCSessionController', () => {
        websockets[attempt + 1].fireOpen();
      }

-      expect(errorCallback).not.toHaveBeenCalled();
+      expect(streamErrorCallback).not.toHaveBeenCalled();
      expect(createWebSocket).toHaveBeenCalledTimes(6);
    });

@@ -1081,7 +1111,8 @@ describe('Go2RTCSessionController', () => {
          surfaceCommittedCallback: vi.fn(),
          getCardWideConfig: () => null,
          mediaLoadedCallback,
-          errorCallback: vi.fn(),
+          streamErrorCallback: vi.fn(),
+          microphoneErrorCallback: vi.fn(),
        },
        { createWebSocket, createBinarySource },
      );
@@ -1115,7 +1146,8 @@ describe('Go2RTCSessionController', () => {
          surfaceCommittedCallback: vi.fn(),
          getCardWideConfig: () => null,
          mediaLoadedCallback,
-          errorCallback: vi.fn(),
+          streamErrorCallback: vi.fn(),
+          microphoneErrorCallback: vi.fn(),
        },
        { createWebSocket, createWebRTCSource },
      );
@@ -1141,7 +1173,8 @@ describe('Go2RTCSessionController', () => {
          surfaceCommittedCallback: vi.fn(),
          getCardWideConfig: () => null,
          mediaLoadedCallback: vi.fn(),
-          errorCallback: vi.fn(),
+          streamErrorCallback: vi.fn(),
+          microphoneErrorCallback: vi.fn(),
        },
        { createWebSocket },
      );
@@ -1172,7 +1205,8 @@ describe('Go2RTCSessionController', () => {
          surfaceCommittedCallback: vi.fn(),
          getCardWideConfig: () => null,
          mediaLoadedCallback: vi.fn(),
-          errorCallback: vi.fn(),
+          streamErrorCallback: vi.fn(),
+          microphoneErrorCallback: vi.fn(),
        },
        { createWebSocket },
      );
@@ -1212,7 +1246,8 @@ describe('Go2RTCSessionController', () => {
          surfaceCommittedCallback: vi.fn(),
          getCardWideConfig: () => null,
          mediaLoadedCallback: vi.fn(),
-          errorCallback: vi.fn(),
+          streamErrorCallback: vi.fn(),
+          microphoneErrorCallback: vi.fn(),
        },
        { createWebSocket, createBinarySource, createWebRTCSource },
      );
@@ -29,11 +29,13 @@ describe('WebRTCStreamSource', () => {

    const pc = new FakeRTCPeerConnection();
    const createPeerConnection = vi.fn(() => pc.asPeerConnection());
+    const microphoneErrorCallback = vi.fn();
    const source = new WebRTCStreamSource(context, {
      createPeerConnection,
      createMediaStream: (tracks) =>
        new FakeMediaStream(tracks as unknown as FakeMediaStreamTrack[]).asMediaStream(),
      microphoneStream: options?.microphoneStream?.asMediaStream() ?? null,
+      microphoneErrorCallback,
    });

    return {
@@ -42,6 +44,7 @@ describe('WebRTCStreamSource', () => {
      createPeerConnection,
      failedCallback,
      loadedCallback,
+      microphoneErrorCallback,
      pc,
      source,
      video,
@@ -506,29 +509,77 @@ describe('WebRTCStreamSource', () => {
    });

    it('should do nothing before there is a peer connection', async () => {
-      const { source, failedCallback } = setup();
+      const { source, microphoneErrorCallback } = setup();
      await source.setMicrophoneStream(
        new FakeMediaStream([new FakeMediaStreamTrack('audio')]).asMediaStream(),
      );

-      expect(failedCallback).not.toHaveBeenCalled();
+      expect(microphoneErrorCallback).not.toHaveBeenCalled();
    });

-    it('should fail when a current replaceTrack rejects', async () => {
+    it.each([
+      [
+        'what the browser said when the rejection has a message',
+        new DOMException('The peer connection is closed', 'InvalidStateError'),
+        'The peer connection is closed',
+      ],
+      [
+        'the rejection type when there is no message to quote',
+        new DOMException('', 'InvalidStateError'),
+        'InvalidStateError',
+      ],
+      ['nothing when the rejection is not an object', 'nope', undefined],
+      [
+        'nothing when the rejection describes itself with neither',
+        { message: 5, name: 7 },
+        undefined,
+      ],
+    ] as const)(
+      'should report %s when a current replaceTrack rejects',
+      async (_summary, rejection, expected) => {
+        const { source, pc, microphoneErrorCallback } = setup();
+        source.start();
+        pc.getMicrophoneTransceiver().sender.replaceTrack.mockRejectedValue(rejection);
+        await source.setMicrophoneStream(
+          new FakeMediaStream([new FakeMediaStreamTrack('audio')]).asMediaStream(),
+        );
+
+        expect(microphoneErrorCallback).toHaveBeenCalledWith(expected);
+      },
+    );
+
+    it('should not fail the stream source when the microphone cannot attach', async () => {
      const { source, pc, failedCallback } = setup();
      source.start();
      pc.getMicrophoneTransceiver().sender.replaceTrack.mockRejectedValue(
-        new Error('replace failed'),
+        new DOMException('replace failed', 'InvalidStateError'),
      );
      await source.setMicrophoneStream(
        new FakeMediaStream([new FakeMediaStreamTrack('audio')]).asMediaStream(),
      );

-      expect(failedCallback).toHaveBeenCalledWith('two_way_audio_error');
+      // The inbound video is unaffected by an outbound audio failure, so the
+      // source must keep running rather than failing over to another one.
+      expect(failedCallback).not.toHaveBeenCalled();
+    });
+
+    it('should not report a rejection when detaching the microphone', async () => {
+      const stream = new FakeMediaStream([new FakeMediaStreamTrack('audio')]);
+      const { source, pc, microphoneErrorCallback } = setup({
+        microphoneStream: stream,
+      });
+      source.start();
+      pc.getMicrophoneTransceiver().sender.replaceTrack.mockRejectedValue(
+        new DOMException('The peer connection is closed', 'InvalidStateError'),
+      );
+      await source.setMicrophoneStream(null);
+
+      // Ignore the error, the user is not trying to be heard anyway.
+      expect(microphoneErrorCallback).not.toHaveBeenCalled();
    });

    it('should ignore a stale replaceTrack rejection after stop', async () => {
-      const { source, pc, failedCallback } = setup();
+      const { source, pc, microphoneErrorCallback } = setup();
      source.start();
      let rejectReplace: (reason: Error) => void = () => {};
      pc.getMicrophoneTransceiver().sender.replaceTrack.mockReturnValue(
@@ -543,7 +594,7 @@ describe('WebRTCStreamSource', () => {
      rejectReplace(new Error('replace failed'));
      await promise;

-      expect(failedCallback).not.toHaveBeenCalled();
+      expect(microphoneErrorCallback).not.toHaveBeenCalled();
    });
  });
 });
@@ -1,21 +1,20 @@
 import { describe, expect, it } from 'vitest';

-import { mapFailureReasonToIssueReason } from '../../../../../../src/components-lib/live/providers/go2rtc-experimental/utils/failure-reason';
+import { mapStreamFailureReasonToIssueReason } from '../../../../../../src/components-lib/live/providers/go2rtc-experimental/utils/stream-failure-reason';

-describe('mapFailureReasonToIssueReason', () => {
+describe('mapStreamFailureReasonToIssueReason', () => {
  it.each([
    ['connect_timeout', 'not_loading'],
    ['negotiation_timeout', 'not_loading'],
    ['media_error', 'playback_error'],
    ['buffer_overflow', 'playback_error'],
-    ['two_way_audio_error', 'two_way_audio_error'],
    ['server_error', 'server_error'],
    ['unsupported', 'unsupported'],
  ] as const)('should map %s to the %s cause', (reason, expected) => {
-    expect(mapFailureReasonToIssueReason(reason)).toBe(expected);
+    expect(mapStreamFailureReasonToIssueReason(reason)).toBe(expected);
  });

  it('should map a null reason to a generic playback error', () => {
-    expect(mapFailureReasonToIssueReason(null)).toBe('playback_error');
+    expect(mapStreamFailureReasonToIssueReason(null)).toBe('playback_error');
  });
 });
@@ -19,11 +19,11 @@ it('should forward the reason and detail as the event detail', () => {

  dispatchLiveErrorEvent(element, {
    reason: 'unsupported',
-    detail: 'Codec not supported',
+    description: 'Codec not supported',
  });
  expect(handler).toHaveBeenCalledWith(
    expect.objectContaining({
-      detail: { reason: 'unsupported', detail: 'Codec not supported' },
+      detail: { reason: 'unsupported', description: 'Codec not supported' },
    }),
  );
 });