Tag errors by name (#1764)

Author: lukasIO

.changeset/rotten-owls-reply.md

@@ -0,0 +1,5 @@
+---
+"livekit-client": patch
+---
+
+Tag errors by name

src/api/SignalClient.test.ts

@@ -1,4 +1,5 @@
 import {
+  DisconnectReason,
   JoinResponse,
   LeaveRequest,
   ReconnectResponse,
@@ -177,9 +178,12 @@ describe('SignalClient.connect', () => {
         websocketTimeout: 100,
       };
 
-      await expect(
-        signalClient.join('wss://test.livekit.io', 'test-token', shortTimeoutOptions),
-      ).rejects.toThrow(ConnectionError);
+      const error = await signalClient
+        .join('wss://test.livekit.io', 'test-token', shortTimeoutOptions)
+        .catch((e) => e);
+
+      expect(error).toBeInstanceOf(ConnectionError);
+      expect(error.reason).toBe(ConnectionErrorReason.Cancelled);
     });
   });
 
@@ -333,11 +337,7 @@ describe('SignalClient.connect', () => {
     });
 
     it('should handle ConnectionError from WebSocket rejection', async () => {
-      const customError = new ConnectionError(
-        'Custom error',
-        ConnectionErrorReason.InternalError,
-        500,
-      );
+      const customError = ConnectionError.internal('Custom error', { status: 500 });
 
       mockWebSocketStream({
         opened: Promise.reject(customError),
@@ -393,11 +393,9 @@ describe('SignalClient.connect', () => {
       await expect(
         signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions),
       ).rejects.toMatchObject(
-        new ConnectionError(
+        ConnectionError.leaveRequest(
           'Received leave request while trying to (re)connect',
-          ConnectionErrorReason.LeaveRequest,
-          undefined,
-          1,
+          DisconnectReason.CLIENT_INITIATED,
         ),
       );
     });
@@ -700,11 +698,7 @@ describe('SignalClient.handleConnectionError', () => {
   });
 
   it('should return ConnectionError as-is if it is already a ConnectionError', async () => {
-    const connectionError = new ConnectionError(
-      'Custom error',
-      ConnectionErrorReason.InternalError,
-      500,
-    );
+    const connectionError = ConnectionError.internal('Custom error');
 
     (global.fetch as any).mockResolvedValueOnce({
       status: 500,
@@ -737,7 +731,6 @@ describe('SignalClient.handleConnectionError', () => {
 
       expect(result).toBeInstanceOf(ConnectionError);
       expect(result.reason).toBe(ConnectionErrorReason.InternalError);
-      expect(result.status).toBe(500);
     }
   });
 
@@ -755,7 +748,7 @@ describe('SignalClient.handleConnectionError', () => {
   });
 
   it('should handle fetch throwing ConnectionError', async () => {
-    const fetchError = new ConnectionError('Fetch failed', ConnectionErrorReason.ServerUnreachable);
+    const fetchError = ConnectionError.serverUnreachable('Fetch failed');
     (global.fetch as any).mockRejectedValueOnce(fetchError);
 
     const handleMethod = (signalClient as any).handleConnectionError;

src/api/SignalClient.ts

@@ -45,7 +45,7 @@ import {
   protoInt64,
 } from '@livekit/protocol';
 import log, { LoggerNames, getLogger } from '../logger';
-import { ConnectionError, ConnectionErrorReason } from '../room/errors';
+import { ConnectionError } from '../room/errors';
 import CriticalTimers from '../room/timers';
 import type { LoggerOptions } from '../room/types';
 import { getClientInfo, isReactNative, sleep } from '../room/utils';
@@ -319,7 +319,7 @@ export class SignalClient {
             this.close();
           }
           cleanupAbortHandlers();
-          reject(target instanceof AbortSignal ? target.reason : target);
+          reject(ConnectionError.cancelled(reason));
         };
 
         abortSignal?.addEventListener('abort', abortHandler);
@@ -330,12 +330,7 @@ export class SignalClient {
         };
 
         const wsTimeout = setTimeout(() => {
-          abortHandler(
-            new ConnectionError(
-              'room connection has timed out (signal)',
-              ConnectionErrorReason.ServerUnreachable,
-            ),
-          );
+          abortHandler(ConnectionError.timeout('room connection has timed out (signal)'));
         }, opts.websocketTimeout);
 
         const handleSignalConnected = (
@@ -364,9 +359,8 @@ export class SignalClient {
             .then((closeInfo) => {
               if (this.isEstablishingConnection) {
                 reject(
-                  new ConnectionError(
+                  ConnectionError.internal(
                     `Websocket got closed during a (re)connection attempt: ${closeInfo.reason}`,
-                    ConnectionErrorReason.InternalError,
                   ),
                 );
               }
@@ -387,9 +381,8 @@ export class SignalClient {
             .catch((reason) => {
               if (this.isEstablishingConnection) {
                 reject(
-                  new ConnectionError(
+                  ConnectionError.internal(
                     `Websocket error during a (re)connection attempt: ${reason}`,
-                    ConnectionErrorReason.InternalError,
                   ),
                 );
               }
@@ -416,10 +409,7 @@ export class SignalClient {
           const firstMessage = await signalReader.read();
           signalReader.releaseLock();
           if (!firstMessage.value) {
-            throw new ConnectionError(
-              'no message received as first message',
-              ConnectionErrorReason.InternalError,
-            );
+            throw ConnectionError.internal('no message received as first message');
           }
 
           const firstSignalResponse = parseSignalResponse(firstMessage.value);
@@ -971,27 +961,24 @@ export class SignalClient {
     } else if (this.isEstablishingConnection && firstSignalResponse.message?.case === 'leave') {
       return {
         isValid: false,
-        error: new ConnectionError(
+        error: ConnectionError.leaveRequest(
           'Received leave request while trying to (re)connect',
-          ConnectionErrorReason.LeaveRequest,
-          undefined,
           firstSignalResponse.message.value.reason,
         ),
       };
     } else if (!isReconnect) {
       // non-reconnect case, should receive join response first
       return {
         isValid: false,
-        error: new ConnectionError(
+        error: ConnectionError.internal(
           `did not receive join response, got ${firstSignalResponse.message?.case} instead`,
-          ConnectionErrorReason.InternalError,
         ),
       };
     }
 
     return {
       isValid: false,
-      error: new ConnectionError('Unexpected first message', ConnectionErrorReason.InternalError),
+      error: ConnectionError.internal('Unexpected first message'),
     };
   }
 
@@ -1010,22 +997,20 @@ export class SignalClient {
       const resp = await fetch(validateUrl);
       if (resp.status.toFixed(0).startsWith('4')) {
         const msg = await resp.text();
-        return new ConnectionError(msg, ConnectionErrorReason.NotAllowed, resp.status);
+        return ConnectionError.notAllowed(msg, resp.status);
       } else if (reason instanceof ConnectionError) {
         return reason;
       } else {
-        return new ConnectionError(
+        return ConnectionError.internal(
           `Encountered unknown websocket error during connection: ${reason}`,
-          ConnectionErrorReason.InternalError,
-          resp.status,
+          { status: resp.status, statusText: resp.statusText },
         );
       }
     } catch (e) {
       return e instanceof ConnectionError
         ? e
-        : new ConnectionError(
+        : ConnectionError.serverUnreachable(
             e instanceof Error ? e.message : 'server was not reachable',
-            ConnectionErrorReason.ServerUnreachable,
           );
     }
   }

src/room/PCTransportManager.ts

@@ -3,7 +3,7 @@ import { SignalTarget } from '@livekit/protocol';
 import log, { LoggerNames, getLogger } from '../logger';
 import PCTransport, { PCEvents } from './PCTransport';
 import { roomConnectOptionDefaults } from './defaults';
-import { ConnectionError, ConnectionErrorReason } from './errors';
+import { ConnectionError } from './errors';
 import CriticalTimers from './timers';
 import type { LoggerOptions } from './types';
 import { sleep } from './utils';
@@ -345,12 +345,7 @@ export class PCTransportManager {
         this.log.warn('abort transport connection', this.logContext);
         CriticalTimers.clearTimeout(connectTimeout);
 
-        reject(
-          new ConnectionError(
-            'room connection has been cancelled',
-            ConnectionErrorReason.Cancelled,
-          ),
-        );
+        reject(ConnectionError.cancelled('room connection has been cancelled'));
       };
       if (abortController?.signal.aborted) {
         abortHandler();
@@ -359,23 +354,13 @@ export class PCTransportManager {
 
       const connectTimeout = CriticalTimers.setTimeout(() => {
         abortController?.signal.removeEventListener('abort', abortHandler);
-        reject(
-          new ConnectionError(
-            'could not establish pc connection',
-            ConnectionErrorReason.InternalError,
-          ),
-        );
+        reject(ConnectionError.internal('could not establish pc connection'));
       }, timeout);
 
       while (this.state !== PCTransportState.CONNECTED) {
         await sleep(50); // FIXME we shouldn't rely on `sleep` in the connection paths, as it invokes `setTimeout` which can be drastically throttled by browser implementations
         if (abortController?.signal.aborted) {
-          reject(
-            new ConnectionError(
-              'room connection has been cancelled',
-              ConnectionErrorReason.Cancelled,
-            ),
-          );
+          reject(ConnectionError.cancelled('room connection has been cancelled'));
           return;
         }
       }

src/room/RTCEngine.ts

@@ -381,10 +381,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       const publicationTimeout = setTimeout(() => {
         delete this.pendingTrackResolvers[req.cid];
         reject(
-          new ConnectionError(
-            'publication of local track timed out, no response from server',
-            ConnectionErrorReason.Timeout,
-          ),
+          ConnectionError.timeout('publication of local track timed out, no response from server'),
         );
       }, 10_000);
       this.pendingTrackResolvers[req.cid] = {
@@ -1228,10 +1225,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     } catch (e: any) {
       // TODO do we need a `failed` state here for the PC?
       this.pcState = PCState.Disconnected;
-      throw new ConnectionError(
-        `could not establish PC connection, ${e.message}`,
-        ConnectionErrorReason.InternalError,
-      );
+      throw ConnectionError.internal(`could not establish PC connection, ${e.message}`);
     }
   }
 
@@ -1412,10 +1406,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     const transport = subscriber ? this.pcManager.subscriber : this.pcManager.publisher;
     const transportName = subscriber ? 'Subscriber' : 'Publisher';
     if (!transport) {
-      throw new ConnectionError(
-        `${transportName} connection not set`,
-        ConnectionErrorReason.InternalError,
-      );
+      throw ConnectionError.internal(`${transportName} connection not set`);
     }
 
     let needNegotiation = false;
@@ -1456,9 +1447,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       await sleep(50);
     }
 
-    throw new ConnectionError(
+    throw ConnectionError.internal(
       `could not establish ${transportName} connection, state: ${transport.getICEConnectionState()}`,
-      ConnectionErrorReason.InternalError,
     );
   }
 

src/room/RegionUrlProvider.test.ts

@@ -180,8 +180,9 @@ describe('RegionUrlProvider', () => {
       const provider = new RegionUrlProvider('wss://test.livekit.cloud', 'token');
       fetchMock.mockResolvedValue(createMockResponse(401));
 
-      await expect(provider.fetchRegionSettings()).rejects.toThrow(ConnectionError);
-      await expect(provider.fetchRegionSettings()).rejects.toMatchObject({
+      const error = await provider.fetchRegionSettings().catch((e) => e);
+      expect(error).toBeInstanceOf(ConnectionError);
+      expect(error).toMatchObject({
         reason: ConnectionErrorReason.NotAllowed,
         status: 401,
       });
@@ -191,11 +192,9 @@ describe('RegionUrlProvider', () => {
       const provider = new RegionUrlProvider('wss://test.livekit.cloud', 'token');
       fetchMock.mockResolvedValue(createMockResponse(500));
 
-      await expect(provider.fetchRegionSettings()).rejects.toThrow(ConnectionError);
-      await expect(provider.fetchRegionSettings()).rejects.toMatchObject({
-        reason: ConnectionErrorReason.InternalError,
-        status: 500,
-      });
+      const error = await provider.fetchRegionSettings().catch((e) => e);
+      expect(error).toBeInstanceOf(ConnectionError);
+      expect(error.reason).toBe(ConnectionErrorReason.InternalError);
     });
 
     it('extracts max-age from Cache-Control header', async () => {
@@ -725,7 +724,7 @@ describe('RegionUrlProvider', () => {
 
       expect(error).toBeInstanceOf(ConnectionError);
       expect(error.reason).toBe(ConnectionErrorReason.ServerUnreachable);
-      expect(error.status).toBe(500);
+      expect(error.status).toBe(undefined);
       expect(error.message).toContain('Failed to fetch');
     });
 

src/room/RegionUrlProvider.ts

@@ -45,26 +45,27 @@ export class RegionUrlProvider {
         const regionSettings = (await regionSettingsResponse.json()) as RegionSettings;
         return { regionSettings, updatedAtInMs: Date.now(), maxAgeInMs };
       } else {
-        throw new ConnectionError(
-          `Could not fetch region settings: ${regionSettingsResponse.statusText}`,
-          regionSettingsResponse.status === 401
-            ? ConnectionErrorReason.NotAllowed
-            : ConnectionErrorReason.InternalError,
-          regionSettingsResponse.status,
-        );
+        if (regionSettingsResponse.status === 401) {
+          throw ConnectionError.notAllowed(
+            `Could not fetch region settings: ${regionSettingsResponse.statusText}`,
+            regionSettingsResponse.status,
+          );
+        } else {
+          throw ConnectionError.internal(
+            `Could not fetch region settings: ${regionSettingsResponse.statusText}`,
+          );
+        }
       }
     } catch (e: unknown) {
       if (e instanceof ConnectionError) {
         // rethrow connection errors
         throw e;
       } else if (signal?.aborted) {
-        throw new ConnectionError(`Region fetching was aborted`, ConnectionErrorReason.Cancelled);
+        throw ConnectionError.cancelled(`Region fetching was aborted`);
       } else {
-        // wrap other errors as connection errors (e.g. timeouts)
-        throw new ConnectionError(
+        // wrap other errors as connection errors
+        throw ConnectionError.serverUnreachable(
           `Could not fetch region settings, ${e instanceof Error ? `${e.name}: ${e.message}` : e}`,
-          ConnectionErrorReason.ServerUnreachable,
-          500, // using 500 as a catch-all manually set error code here
         );
       }
     } finally {