refactor: Centralize group call errors in custom GroupCallErrorBoundary

src/room/GroupCallErrorBoundary.test.tsx

@@ -0,0 +1,170 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { describe, expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { type ReactElement, type ReactNode } from "react";
+import { BrowserRouter } from "react-router-dom";
+import userEvent from "@testing-library/user-event";
+
+import { GroupCallErrorBoundary } from "./GroupCallErrorBoundary.tsx";
+import {
+  ConnectionLostError,
+  E2EENotSupportedError,
+  type ElementCallError,
+  InsufficientCapacityError,
+  MatrixRTCFocusMissingError,
+  UnknownCallError,
+} from "../utils/errors.ts";
+import { mockConfig } from "../utils/test.ts";
+
+test.each([
+  {
+    error: new MatrixRTCFocusMissingError("example.com"),
+    expectedTitle: "Call is not supported",
+  },
+  {
+    error: new ConnectionLostError(),
+    expectedTitle: "Connection lost",
+    expectedDescription: "You were disconnected from the call.",
+  },
+  {
+    error: new E2EENotSupportedError(),
+    expectedTitle: "Incompatible browser",
+    expectedDescription:
+      "Your web browser does not support encrypted calls. Supported browsers include Chrome, Safari, and Firefox 117+.",
+  },
+  {
+    error: new InsufficientCapacityError(),
+    expectedTitle: "Insufficient capacity",
+    expectedDescription:
+      "The server has reached its maximum capacity and you cannot join the call at this time. Try again later, or contact your server admin if the problem persists.",
+  },
+])(
+  "should report correct error for $expectedTitle",
+  async ({ error, expectedTitle, expectedDescription }) => {
+    const TestComponent = (): ReactNode => {
+      throw error;
+    };
+
+    const onErrorMock = vi.fn();
+    const { asFragment } = render(
+      <BrowserRouter>
+        <GroupCallErrorBoundary onError={onErrorMock}>
+          <TestComponent />
+        </GroupCallErrorBoundary>
+      </BrowserRouter>,
+    );
+
+    await screen.findByText(expectedTitle);
+    if (expectedDescription) {
+      expect(screen.queryByText(expectedDescription)).toBeInTheDocument();
+    }
+    expect(onErrorMock).toHaveBeenCalledWith(error);
+
+    expect(asFragment()).toMatchSnapshot();
+  },
+);
+
+test("should render the error page with link back to home", async () => {
+  const error = new MatrixRTCFocusMissingError("example.com");
+  const TestComponent = (): ReactNode => {
+    throw error;
+  };
+
+  const onErrorMock = vi.fn();
+  const { asFragment } = render(
+    <BrowserRouter>
+      <GroupCallErrorBoundary onError={onErrorMock}>
+        <TestComponent />
+      </GroupCallErrorBoundary>
+    </BrowserRouter>,
+  );
+
+  await screen.findByText("Call is not supported");
+  expect(screen.getByText(/Domain: example.com/i)).toBeInTheDocument();
+  expect(
+    screen.getByText(/Error Code: MISSING_MATRIX_RTC_FOCUS/i),
+  ).toBeInTheDocument();
+
+  await screen.findByRole("button", { name: "Return to home screen" });
+
+  expect(onErrorMock).toHaveBeenCalledOnce();
+  expect(onErrorMock).toHaveBeenCalledWith(error);
+
+  expect(asFragment()).toMatchSnapshot();
+});
+
+test("should have a reconnect button for ConnectionLostError", async () => {
+  const user = userEvent.setup();
+
+  const reconnectCallback = vi.fn();
+
+  const TestComponent = (): ReactNode => {
+    throw new ConnectionLostError();
+  };
+
+  const { asFragment } = render(
+    <BrowserRouter>
+      <GroupCallErrorBoundary
+        onError={vi.fn()}
+        recoveryActionHandler={reconnectCallback}
+      >
+        <TestComponent />
+      </GroupCallErrorBoundary>
+    </BrowserRouter>,
+  );
+
+  await screen.findByText("Connection lost");
+  await screen.findByRole("button", { name: "Reconnect" });
+  await screen.findByRole("button", { name: "Return to home screen" });
+
+  expect(asFragment()).toMatchSnapshot();
+
+  await user.click(screen.getByRole("button", { name: "Reconnect" }));
+
+  expect(reconnectCallback).toHaveBeenCalledOnce();
+  expect(reconnectCallback).toHaveBeenCalledWith("reconnect");
+});
+
+describe("Rageshake button", () => {
+  function setupTest(testError: ElementCallError): void {
+    mockConfig({
+      rageshake: {
+        submit_url: "https://rageshake.example.com.localhost",
+      },
+    });
+
+    const TestComponent = (): ReactElement => {
+      throw testError;
+    };
+
+    render(
+      <BrowserRouter>
+        <GroupCallErrorBoundary onError={vi.fn()}>
+          <TestComponent />
+        </GroupCallErrorBoundary>
+      </BrowserRouter>,
+    );
+  }
+
+  test("should show send rageshake button for unknown errors", () => {
+    setupTest(new UnknownCallError(new Error("FOO")));
+
+    expect(
+      screen.queryByRole("button", { name: "Send debug logs" }),
+    ).toBeInTheDocument();
+  });
+
+  test("should not show send rageshake button for call errors", () => {
+    setupTest(new E2EENotSupportedError());
+
+    expect(
+      screen.queryByRole("button", { name: "Send debug logs" }),
+    ).not.toBeInTheDocument();
+  });
+});

src/room/GroupCallErrorBoundary.tsx

@@ -0,0 +1,137 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { ErrorBoundary, type FallbackRender } from "@sentry/react";
+import {
+  type ComponentType,
+  type FC,
+  type ReactElement,
+  type ReactNode,
+  type SVGAttributes,
+  useCallback,
+} from "react";
+import { Trans, useTranslation } from "react-i18next";
+import {
+  ErrorIcon,
+  HostIcon,
+  OfflineIcon,
+  WebBrowserIcon,
+} from "@vector-im/compound-design-tokens/assets/web/icons";
+
+import {
+  ConnectionLostError,
+  ElementCallError,
+  ErrorCategory,
+  ErrorCode,
+  UnknownCallError,
+} from "../utils/errors.ts";
+import { FullScreenView } from "../FullScreenView.tsx";
+import { ErrorView } from "../ErrorView.tsx";
+
+export type CallErrorRecoveryAction = "reconnect"; // | "retry" ;
+
+export type RecoveryActionHandler = (action: CallErrorRecoveryAction) => void;
+
+interface ErrorPageProps {
+  error: ElementCallError;
+  recoveryActionHandler?: RecoveryActionHandler;
+  resetError: () => void;
+}
+
+const ErrorPage: FC<ErrorPageProps> = ({
+  error,
+  recoveryActionHandler,
+}: ErrorPageProps): ReactElement => {
+  const { t } = useTranslation();
+
+  // let title: string;
+  let icon: ComponentType<SVGAttributes<SVGElement>>;
+  switch (error.category) {
+    case ErrorCategory.CONFIGURATION_ISSUE:
+      icon = HostIcon;
+      break;
+    case ErrorCategory.NETWORK_CONNECTIVITY:
+      icon = OfflineIcon;
+      break;
+    case ErrorCategory.CLIENT_CONFIGURATION:
+      icon = WebBrowserIcon;
+      break;
+    default:
+      icon = ErrorIcon;
+  }
+
+  const actions: { label: string; onClick: () => void }[] = [];
+  if (error instanceof ConnectionLostError) {
+    actions.push({
+      label: t("call_ended_view.reconnect_button"),
+      onClick: () => recoveryActionHandler?.("reconnect"),
+    });
+  }
+
+  return (
+    <FullScreenView>
+      <ErrorView
+        Icon={icon}
+        title={error.localisedTitle}
+        rageshake={error.code == ErrorCode.UNKNOWN_ERROR}
+      >
+        <p>
+          {error.localisedMessage ?? (
+            <Trans
+              i18nKey="error.unexpected_ec_error"
+              components={[<b />, <code />]}
+              values={{ errorCode: error.code }}
+            />
+          )}
+        </p>
+        {actions &&
+          actions.map((action, index) => (
+            <button onClick={action.onClick} key={`action${index}`}>
+              {action.label}
+            </button>
+          ))}
+      </ErrorView>
+    </FullScreenView>
+  );
+};
+
+interface BoundaryProps {
+  children: ReactNode | (() => ReactNode);
+  recoveryActionHandler?: RecoveryActionHandler;
+  onError?: (error: unknown) => void;
+}
+
+export const GroupCallErrorBoundary = ({
+  recoveryActionHandler,
+  onError,
+  children,
+}: BoundaryProps): ReactElement => {
+  const fallbackRenderer: FallbackRender = useCallback(
+    ({ error, resetError }): ReactElement => {
+      const callError =
+        error instanceof ElementCallError
+          ? error
+          : new UnknownCallError(error instanceof Error ? error : new Error());
+      return (
+        <ErrorPage
+          error={callError}
+          resetError={resetError}
+          recoveryActionHandler={recoveryActionHandler}
+        />
+      );
+    },
+    [recoveryActionHandler],
+  );
+
+  return (
+    <ErrorBoundary
+      fallback={fallbackRenderer}
+      onError={(error) => onError?.(error)}
+      children={children}
+    />
+  );
+};

src/room/GroupCallView.tsx

@@ -7,7 +7,6 @@ Please see LICENSE in the repository root for full details.
 
 import {
   type FC,
-  type ReactElement,
   type ReactNode,
   useCallback,
   useEffect,
@@ -25,14 +24,7 @@ import {
   type MatrixRTCSession,
 } from "matrix-js-sdk/src/matrixrtc/MatrixRTCSession";
 import { JoinRule, type Room } from "matrix-js-sdk/src/matrix";
-import {
-  OfflineIcon,
-  WebBrowserIcon,
-} from "@vector-im/compound-design-tokens/assets/web/icons";
-import { useTranslation } from "react-i18next";
 import { useNavigate } from "react-router-dom";
-import { ErrorBoundary } from "@sentry/react";
-import { Button } from "@vector-im/compound-web";
 
 import type { IWidgetApiRequest } from "matrix-widget-api";
 import {
@@ -40,7 +32,6 @@ import {
   type JoinCallData,
   type WidgetHelpers,
 } from "../widget";
-import { ErrorPage, FullScreenView } from "../FullScreenView";
 import { LobbyView } from "./LobbyView";
 import { type MatrixInfo } from "./VideoPreview";
 import { CallEndedView } from "./CallEndedView";
@@ -63,15 +54,14 @@ import { useAudioContext } from "../useAudioContext";
 import { callEventAudioSounds } from "./CallEventAudioRenderer";
 import { useLatest } from "../useLatest";
 import { usePageTitle } from "../usePageTitle";
-import { ErrorView } from "../ErrorView";
 import {
-  ConnectionLostError,
+  E2EENotSupportedError,
   ElementCallError,
-  ErrorCategory,
   ErrorCode,
   RTCSessionError,
+  UnknownCallError,
 } from "../utils/errors.ts";
-import { ElementCallRichError } from "../RichError.tsx";
+import { GroupCallErrorBoundary } from "./GroupCallErrorBoundary.tsx";
 import {
   useNewMembershipManagerSetting as useNewMembershipManagerSetting,
   useSetting,
@@ -84,11 +74,6 @@ declare global {
   }
 }
 
-interface GroupCallErrorPageProps {
-  error: Error | unknown;
-  resetError: () => void;
-}
-
 interface Props {
   client: MatrixClient;
   isPasswordlessUser: boolean;
@@ -205,10 +190,8 @@ export const GroupCallView: FC<Props> = ({
         setError(e);
       } else {
         logger.error(`Unknown Error while entering RTC session`, e);
-        const error = new ElementCallError(
-          e instanceof Error ? e.message : "Unknown error",
-          ErrorCode.UNKNOWN_ERROR,
-          ErrorCategory.UNKNOWN,
+        const error = new UnknownCallError(
+          e instanceof Error ? e : new Error("Unknown error", { cause: e }),
         );
         setError(error);
       }
@@ -398,58 +381,9 @@ export const GroupCallView: FC<Props> = ({
   );
   const onShareClick = joinRule === JoinRule.Public ? onShareClickFn : null;
 
-  const { t } = useTranslation();
-
-  const errorPage = useMemo(() => {
-    function GroupCallErrorPage({
-      error,
-      resetError,
-    }: GroupCallErrorPageProps): ReactElement {
-      useEffect(() => {
-        if (rtcSession.isJoined()) onLeave("error");
-      }, [error]);
-
-      const onReconnect = useCallback(() => {
-        setLeft(false);
-        resetError();
-        enterRTCSessionOrError(
-          rtcSession,
-          perParticipantE2EE,
-          useNewMembershipManager,
-        ).catch((e) => {
-          logger.error("Error re-entering RTC session on reconnect", e);
-        });
-      }, [resetError]);
-
-      return error instanceof ConnectionLostError ? (
-        <FullScreenView>
-          <ErrorView
-            Icon={OfflineIcon}
-            title={t("error.connection_lost")}
-            rageshake
-          >
-            <p>{t("error.connection_lost_description")}</p>
-            <Button onClick={onReconnect}>
-              {t("call_ended_view.reconnect_button")}
-            </Button>
-          </ErrorView>
-        </FullScreenView>
-      ) : (
-        <ErrorPage error={error} />
-      );
-    }
-    return GroupCallErrorPage;
-  }, [t, rtcSession, onLeave, perParticipantE2EE, useNewMembershipManager]);
-
   if (!isE2EESupportedBrowser() && e2eeSystem.kind !== E2eeType.NONE) {
     // If we have a encryption system but the browser does not support it.
-    return (
-      <FullScreenView>
-        <ErrorView Icon={WebBrowserIcon} title={t("error.e2ee_unsupported")}>
-          <p>{t("error.e2ee_unsupported_description")}</p>
-        </ErrorView>
-      </FullScreenView>
-    );
+    throw new E2EENotSupportedError();
   }
 
   const shareModal = (
@@ -484,9 +418,9 @@ export const GroupCallView: FC<Props> = ({
   let body: ReactNode;
   if (error) {
     // If an ElementCallError was recorded, then create a component that will fail to render and throw
-    // an ElementCallRichError error. This will then be handled by the ErrorBoundary component.
+    // the error. This will then be handled by the ErrorBoundary component.
     const ErrorComponent = (): ReactNode => {
-      throw new ElementCallRichError(error);
+      throw enterRTCError;
     };
     body = <ErrorComponent />;
   } else if (isJoined) {
@@ -543,5 +477,27 @@ export const GroupCallView: FC<Props> = ({
     body = lobbyView;
   }
 
-  return <ErrorBoundary fallback={errorPage}>{body}</ErrorBoundary>;
+  return (
+    <GroupCallErrorBoundary
+      recoveryActionHandler={(action) => {
+        if (action == "reconnect") {
+          setLeft(false);
+          enterRTCSessionOrError(
+            rtcSession,
+            perParticipantE2EE,
+            useNewMembershipManager,
+          ).catch((e) => {
+            logger.error("Error re-entering RTC session", e);
+          });
+        }
+      }}
+      onError={
+        (/**error*/) => {
+          if (rtcSession.isJoined()) onLeave("error");
+        }
+      }
+    >
+      {body}
+    </GroupCallErrorBoundary>
+  );
 };