livekit-client 2.15.16 → 2.16.1

package/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,10 +961,8 @@ 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,
         ),
       };
@@ -982,16 +970,15 @@ export class SignalClient {
       // 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,
           );
     }
   }

package/src/api/utils.ts

@@ -14,7 +14,7 @@ export function createValidateUrl(rtcWsUrl: string) {
   return appendUrlPath(urlObj, 'validate');
 }
 
-function ensureTrailingSlash(path: string) {
+export function ensureTrailingSlash(path: string) {
   return path.endsWith('/') ? path : `${path}/`;
 }
 

package/src/connectionHelper/checks/turn.ts

@@ -1,4 +1,6 @@
 import { SignalClient } from '../../api/SignalClient';
+import { RegionUrlProvider } from '../../room/RegionUrlProvider';
+import { isCloud } from '../../room/utils';
 import { Checker } from './Checker';
 
 export class TURNCheck extends Checker {
@@ -7,6 +9,11 @@ export class TURNCheck extends Checker {
   }
 
   async perform(): Promise<void> {
+    if (isCloud(new URL(this.url))) {
+      this.appendMessage('Using region specific url');
+      this.url =
+        (await new RegionUrlProvider(this.url, this.token).getNextBestRegionUrl()) ?? this.url;
+    }
     const signalClient = new SignalClient();
     const joinRes = await signalClient.join(this.url, this.token, {
       autoSubscribe: true,

package/src/connectionHelper/checks/websocket.ts

@@ -1,5 +1,7 @@
-import { ServerInfo_Edition } from '@livekit/protocol';
+import { JoinResponse, ServerInfo_Edition } from '@livekit/protocol';
 import { SignalClient } from '../../api/SignalClient';
+import { RegionUrlProvider } from '../../room/RegionUrlProvider';
+import { isCloud } from '../../room/utils';
 import { Checker } from './Checker';
 
 export class WebSocketCheck extends Checker {
@@ -13,16 +15,43 @@ export class WebSocketCheck extends Checker {
     }
 
     let signalClient = new SignalClient();
-    const joinRes = await signalClient.join(this.url, this.token, {
-      autoSubscribe: true,
-      maxRetries: 0,
-      e2eeEnabled: false,
-      websocketTimeout: 15_000,
-      singlePeerConnection: false,
-    });
-    this.appendMessage(`Connected to server, version ${joinRes.serverVersion}.`);
-    if (joinRes.serverInfo?.edition === ServerInfo_Edition.Cloud && joinRes.serverInfo?.region) {
-      this.appendMessage(`LiveKit Cloud: ${joinRes.serverInfo?.region}`);
+    let joinRes: JoinResponse | undefined;
+    try {
+      joinRes = await signalClient.join(this.url, this.token, {
+        autoSubscribe: true,
+        maxRetries: 0,
+        e2eeEnabled: false,
+        websocketTimeout: 15_000,
+        singlePeerConnection: false,
+      });
+    } catch (e: any) {
+      if (isCloud(new URL(this.url))) {
+        this.appendMessage(
+          `Initial connection failed with error ${e.message}. Retrying with region fallback`,
+        );
+        const regionProvider = new RegionUrlProvider(this.url, this.token);
+        const regionUrl = await regionProvider.getNextBestRegionUrl();
+        if (regionUrl) {
+          joinRes = await signalClient.join(regionUrl, this.token, {
+            autoSubscribe: true,
+            maxRetries: 0,
+            e2eeEnabled: false,
+            websocketTimeout: 15_000,
+            singlePeerConnection: false,
+          });
+          this.appendMessage(
+            `Fallback to region worked. To avoid initial connections failing, ensure you're calling room.prepareConnection() ahead of time`,
+          );
+        }
+      }
+    }
+    if (joinRes) {
+      this.appendMessage(`Connected to server, version ${joinRes.serverVersion}.`);
+      if (joinRes.serverInfo?.edition === ServerInfo_Edition.Cloud && joinRes.serverInfo?.region) {
+        this.appendMessage(`LiveKit Cloud: ${joinRes.serverInfo?.region}`);
+      }
+    } else {
+      this.appendError(`Websocket connection could not be established`);
     }
     await signalClient.close();
   }

package/src/e2ee/E2eeManager.ts

@@ -68,9 +68,11 @@ export class E2EEManager
 
   private keyProvider: BaseKeyProvider;
 
-  private decryptDataRequests: Map<string, Future<DecryptDataResponseMessage['data']>> = new Map();
+  private decryptDataRequests: Map<string, Future<DecryptDataResponseMessage['data'], Error>> =
+    new Map();
 
-  private encryptDataRequests: Map<string, Future<EncryptDataResponseMessage['data']>> = new Map();
+  private encryptDataRequests: Map<string, Future<EncryptDataResponseMessage['data'], Error>> =
+    new Map();
 
   private dataChannelEncryptionEnabled: boolean;
 
@@ -322,7 +324,7 @@ export class E2EEManager
         participantIdentity: this.room!.localParticipant.identity,
       },
     };
-    const future = new Future<EncryptDataResponseMessage['data']>();
+    const future = new Future<EncryptDataResponseMessage['data'], Error>();
     future.onFinally = () => {
       this.encryptDataRequests.delete(uuid);
     };
@@ -351,7 +353,7 @@ export class E2EEManager
         keyIndex,
       },
     };
-    const future = new Future<DecryptDataResponseMessage['data']>();
+    const future = new Future<DecryptDataResponseMessage['data'], Error>();
     future.onFinally = () => {
       this.decryptDataRequests.delete(uuid);
     };

package/src/options.ts

@@ -87,9 +87,9 @@ export interface InternalRoomOptions {
 
   webAudioMix: boolean | WebAudioSettings;
 
-  // /**
-  //  * @deprecated Use `encryption` field instead.
-  //  */
+  /**
+   * @deprecated Use `encryption` field instead.
+   */
   e2ee?: E2EEOptions;
 
   /**
@@ -111,7 +111,7 @@ export interface InternalRoomOptions {
 /**
  * Options for when creating a new room
  */
-export interface RoomOptions extends Partial<Omit<InternalRoomOptions, 'encryption'>> {}
+export interface RoomOptions extends Partial<InternalRoomOptions> {}
 
 /**
  * @internal

package/src/room/PCTransport.ts

@@ -1,8 +1,8 @@
 import { Mutex } from '@livekit/mutex';
 import { EventEmitter } from 'events';
-import type { MediaDescription, SessionDescription } from 'sdp-transform';
 import { parse, write } from 'sdp-transform';
 import { debounce } from 'ts-debounce';
+import type { MediaDescription, SessionDescription } from 'sdp-transform';
 import log, { LoggerNames, getLogger } from '../logger';
 import { NegotiationError, UnexpectedConnectionState } from './errors';
 import type { LoggerOptions } from './types';

package/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;
         }
       }

package/src/room/RTCEngine.ts

@@ -62,6 +62,7 @@ import {
   ConnectionError,
   ConnectionErrorReason,
   NegotiationError,
+  SignalReconnectError,
   TrackInvalidError,
   UnexpectedConnectionState,
 } from './errors';
@@ -92,6 +93,8 @@ const reliableDataChannel = '_reliable';
 const minReconnectWait = 2 * 1000;
 const leaveReconnect = 'leave-reconnect';
 const reliabeReceiveStateTTL = 30_000;
+const lossyDataChannelBufferThresholdMin = 8 * 1024;
+const lossyDataChannelBufferThresholdMax = 256 * 1024;
 
 enum PCState {
   New,
@@ -203,6 +206,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
   private reliableReceivedState: TTLMap<string, number> = new TTLMap(reliabeReceiveStateTTL);
 
+  private lossyDataStatCurrentBytes: number = 0;
+
+  private lossyDataStatByterate: number = 0;
+
+  private lossyDataStatInterval: ReturnType<typeof setInterval> | undefined;
+
+  private lossyDataDropCount: number = 0;
+
   private midToTrackId: { [key: string]: string } = {};
 
   /** used to indicate whether the browser is currently waiting to reconnect */
@@ -312,6 +323,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.removeAllListeners();
       this.deregisterOnLineListener();
       this.clearPendingReconnect();
+      this.cleanupLossyDataStats();
       await this.cleanupPeerConnections();
       await this.cleanupClient();
     } finally {
@@ -347,6 +359,16 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.reliableReceivedState.clear();
   }
 
+  cleanupLossyDataStats() {
+    this.lossyDataStatByterate = 0;
+    this.lossyDataStatCurrentBytes = 0;
+    if (this.lossyDataStatInterval) {
+      clearInterval(this.lossyDataStatInterval);
+      this.lossyDataStatInterval = undefined;
+    }
+    this.lossyDataDropCount = 0;
+  }
+
   async cleanupClient() {
     await this.client.close();
     this.client.resetCallbacks();
@@ -360,10 +382,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] = {
@@ -569,6 +588,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onTokenRefresh = (token: string) => {
       this.token = token;
+      this.regionUrlProvider?.updateToken(token);
     };
 
     this.client.onRemoteMuteChanged = (trackSid: string, muted: boolean) => {
@@ -712,6 +732,22 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     // handle buffer amount low events
     this.lossyDC.onbufferedamountlow = this.handleBufferedAmountLow;
     this.reliableDC.onbufferedamountlow = this.handleBufferedAmountLow;
+
+    this.cleanupLossyDataStats();
+    this.lossyDataStatInterval = setInterval(() => {
+      this.lossyDataStatByterate = this.lossyDataStatCurrentBytes;
+      this.lossyDataStatCurrentBytes = 0;
+
+      const dc = this.dataChannelForKind(DataPacket_Kind.LOSSY);
+      if (dc) {
+        // control buffered latency to ~100ms
+        const threshold = this.lossyDataStatByterate / 10;
+        dc.bufferedAmountLowThreshold = Math.min(
+          Math.max(threshold, lossyDataChannelBufferThresholdMin),
+          lossyDataChannelBufferThresholdMax,
+        );
+      }
+    }, 1000);
   }
 
   private handleDataChannel = async ({ channel }: RTCDataChannelEvent) => {
@@ -1190,10 +1226,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}`);
     }
   }
 
@@ -1251,7 +1284,6 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         }),
       },
     });
-
     await this.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
   }
 
@@ -1285,7 +1317,21 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     const dc = this.dataChannelForKind(kind);
     if (dc) {
       if (kind === DataPacket_Kind.RELIABLE) {
+        await this.waitForBufferStatusLow(kind);
         this.reliableMessageBuffer.push({ data: msg, sequence: packet.sequence });
+      } else {
+        // lossy channel, drop messages to reduce latency
+        if (!this.isBufferStatusLow(kind)) {
+          this.lossyDataDropCount += 1;
+          if (this.lossyDataDropCount % 100 === 0) {
+            this.log.warn(
+              `dropping lossy data channel messages, total dropped: ${this.lossyDataDropCount}`,
+              this.logContext,
+            );
+          }
+          return;
+        }
+        this.lossyDataStatCurrentBytes += msg.byteLength;
       }
 
       if (this.attemptingReconnect) {
@@ -1311,6 +1357,13 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   private updateAndEmitDCBufferStatus = (kind: DataPacket_Kind) => {
+    if (kind === DataPacket_Kind.RELIABLE) {
+      const dc = this.dataChannelForKind(kind);
+      if (dc) {
+        this.reliableMessageBuffer.alignBufferedAmount(dc.bufferedAmount);
+      }
+    }
+
     const status = this.isBufferStatusLow(kind);
     if (typeof status !== 'undefined' && status !== this.dcBufferStatus.get(kind)) {
       this.dcBufferStatus.set(kind, status);
@@ -1321,9 +1374,6 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   private isBufferStatusLow = (kind: DataPacket_Kind): boolean | undefined => {
     const dc = this.dataChannelForKind(kind);
     if (dc) {
-      if (kind === DataPacket_Kind.RELIABLE) {
-        this.reliableMessageBuffer.alignBufferedAmount(dc.bufferedAmount);
-      }
       return dc.bufferedAmount <= dc.bufferedAmountLowThreshold;
     }
   };
@@ -1357,10 +1407,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;
@@ -1401,9 +1448,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,
     );
   }
 
@@ -1693,8 +1739,6 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 }
 
-class SignalReconnectError extends Error {}
-
 export type EngineEventCallbacks = {
   connected: (joinResp: JoinResponse) => void;
   disconnected: (reason?: DisconnectReason) => void;