livekit-client 1.7.0 → 1.8.0

package/src/room/RTCEngine.ts

@@ -40,6 +40,7 @@ import type { SimulcastTrackInfo } from './track/LocalVideoTrack';
 import type { TrackPublishOptions, VideoCodec } from './track/options';
 import { Track } from './track/Track';
 import {
+  isCloud,
   isWeb,
   Mutex,
   sleep,
@@ -47,6 +48,7 @@ import {
   supportsSetCodecPreferences,
   supportsTransceiver,
 } from './utils';
+import { RegionUrlProvider } from './RegionUrlProvider';
 
 const lossyDataChannel = '_lossy';
 const reliableDataChannel = '_reliable';
@@ -84,6 +86,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
   private reliableDC?: RTCDataChannel;
 
+  private dcBufferStatus: Map<DataPacket_Kind, boolean>;
+
   // @ts-ignore noUnusedLocals
   private reliableDCSub?: RTCDataChannel;
 
@@ -134,8 +138,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
   private closingLock: Mutex;
 
+  private dataProcessLock: Mutex;
+
   private shouldFailNext: boolean = false;
 
+  private regionUrlProvider?: RegionUrlProvider;
+
   constructor(private options: InternalRoomOptions) {
     super();
     this.client = new SignalClient();
@@ -143,6 +151,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.reconnectPolicy = this.options.reconnectPolicy;
     this.registerOnLineListener();
     this.closingLock = new Mutex();
+    this.dataProcessLock = new Mutex();
+    this.dcBufferStatus = new Map([
+      [DataPacket_Kind.LOSSY, true],
+      [DataPacket_Kind.RELIABLE, true],
+    ]);
   }
 
   async join(
@@ -506,6 +519,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     // handle datachannel errors
     this.lossyDC.onerror = this.handleDataError;
     this.reliableDC.onerror = this.handleDataError;
+
+    // set up dc buffer threshold, set to 64kB (otherwise 0 by default)
+    this.lossyDC.bufferedAmountLowThreshold = 65535;
+    this.reliableDC.bufferedAmountLowThreshold = 65535;
+
+    // handle buffer amount low events
+    this.lossyDC.onbufferedamountlow = this.handleBufferedAmountLow;
+    this.reliableDC.onbufferedamountlow = this.handleBufferedAmountLow;
   }
 
   private handleDataChannel = async ({ channel }: RTCDataChannelEvent) => {
@@ -524,22 +545,28 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   };
 
   private handleDataMessage = async (message: MessageEvent) => {
-    // decode
-    let buffer: ArrayBuffer | undefined;
-    if (message.data instanceof ArrayBuffer) {
-      buffer = message.data;
-    } else if (message.data instanceof Blob) {
-      buffer = await message.data.arrayBuffer();
-    } else {
-      log.error('unsupported data type', message.data);
-      return;
-    }
-    const dp = DataPacket.decode(new Uint8Array(buffer));
-    if (dp.value?.$case === 'speaker') {
-      // dispatch speaker updates
-      this.emit(EngineEvent.ActiveSpeakersUpdate, dp.value.speaker.speakers);
-    } else if (dp.value?.$case === 'user') {
-      this.emit(EngineEvent.DataPacketReceived, dp.value.user, dp.kind);
+    // make sure to respect incoming data message order by processing message events one after the other
+    const unlock = await this.dataProcessLock.lock();
+    try {
+      // decode
+      let buffer: ArrayBuffer | undefined;
+      if (message.data instanceof ArrayBuffer) {
+        buffer = message.data;
+      } else if (message.data instanceof Blob) {
+        buffer = await message.data.arrayBuffer();
+      } else {
+        log.error('unsupported data type', message.data);
+        return;
+      }
+      const dp = DataPacket.decode(new Uint8Array(buffer));
+      if (dp.value?.$case === 'speaker') {
+        // dispatch speaker updates
+        this.emit(EngineEvent.ActiveSpeakersUpdate, dp.value.speaker.speakers);
+      } else if (dp.value?.$case === 'user') {
+        this.emit(EngineEvent.DataPacketReceived, dp.value.user, dp.kind);
+      }
+    } finally {
+      unlock();
     }
   };
 
@@ -555,6 +582,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     }
   };
 
+  private handleBufferedAmountLow = (event: Event) => {
+    const channel = event.currentTarget as RTCDataChannel;
+    const channelKind =
+      channel.maxRetransmits === 0 ? DataPacket_Kind.LOSSY : DataPacket_Kind.RELIABLE;
+
+    this.updateAndEmitDCBufferStatus(channelKind);
+  };
+
   private setPreferredCodec(
     transceiver: RTCRtpTransceiver,
     kind: Track.Kind,
@@ -730,6 +765,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     log.debug(`reconnecting in ${delay}ms`);
 
     this.clearReconnectTimeout();
+    if (this.url && this.token && isCloud(new URL(this.url))) {
+      this.regionUrlProvider = new RegionUrlProvider(this.url, this.token);
+    }
     this.reconnectTimeout = CriticalTimers.setTimeout(
       () => this.attemptReconnect(disconnectReason),
       delay,
@@ -801,46 +839,62 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     return null;
   }
 
-  private async restartConnection() {
-    if (!this.url || !this.token) {
-      // permanent failure, don't attempt reconnection
-      throw new UnexpectedConnectionState('could not reconnect, url or token not saved');
-    }
+  private async restartConnection(regionUrl?: string) {
+    try {
+      if (!this.url || !this.token) {
+        // permanent failure, don't attempt reconnection
+        throw new UnexpectedConnectionState('could not reconnect, url or token not saved');
+      }
 
-    log.info(`reconnecting, attempt: ${this.reconnectAttempts}`);
-    this.emit(EngineEvent.Restarting);
+      log.info(`reconnecting, attempt: ${this.reconnectAttempts}`);
+      this.emit(EngineEvent.Restarting);
 
-    if (this.client.isConnected) {
-      await this.client.sendLeave();
-    }
-    await this.client.close();
-    this.primaryPC = undefined;
-    this.publisher?.close();
-    this.publisher = undefined;
-    this.subscriber?.close();
-    this.subscriber = undefined;
-
-    let joinResponse: JoinResponse;
-    try {
-      if (!this.signalOpts) {
-        log.warn('attempted connection restart, without signal options present');
+      if (this.client.isConnected) {
+        await this.client.sendLeave();
+      }
+      await this.client.close();
+      this.primaryPC = undefined;
+      this.publisher?.close();
+      this.publisher = undefined;
+      this.subscriber?.close();
+      this.subscriber = undefined;
+
+      let joinResponse: JoinResponse;
+      try {
+        if (!this.signalOpts) {
+          log.warn('attempted connection restart, without signal options present');
+          throw new SignalReconnectError();
+        }
+        // in case a regionUrl is passed, the region URL takes precedence
+        joinResponse = await this.join(regionUrl ?? this.url, this.token, this.signalOpts);
+      } catch (e) {
+        if (e instanceof ConnectionError && e.reason === ConnectionErrorReason.NotAllowed) {
+          throw new UnexpectedConnectionState('could not reconnect, token might be expired');
+        }
         throw new SignalReconnectError();
       }
-      joinResponse = await this.join(this.url, this.token, this.signalOpts);
-    } catch (e) {
-      throw new SignalReconnectError();
-    }
 
-    if (this.shouldFailNext) {
-      this.shouldFailNext = false;
-      throw new Error('simulated failure');
-    }
-
-    await this.waitForPCConnected();
-    this.client.setReconnected();
+      if (this.shouldFailNext) {
+        this.shouldFailNext = false;
+        throw new Error('simulated failure');
+      }
 
-    // reconnect success
-    this.emit(EngineEvent.Restarted, joinResponse);
+      await this.waitForPCReconnected();
+      this.client.setReconnected();
+      this.regionUrlProvider?.resetAttempts();
+      // reconnect success
+      this.emit(EngineEvent.Restarted, joinResponse);
+    } catch (error) {
+      const nextRegionUrl = await this.regionUrlProvider?.getNextBestRegionUrl();
+      if (nextRegionUrl) {
+        await this.restartConnection(nextRegionUrl);
+        return;
+      } else {
+        // no more regions to try (or we're not on cloud)
+        this.regionUrlProvider?.resetAttempts();
+        throw error;
+      }
+    }
   }
 
   private async resumeConnection(reason?: ReconnectReason): Promise<void> {
@@ -868,6 +922,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       if (e instanceof Error) {
         message = e.message;
       }
+      if (e instanceof ConnectionError && e.reason === ConnectionErrorReason.NotAllowed) {
+        throw new UnexpectedConnectionState('could not reconnect, token might be expired');
+      }
       throw new SignalReconnectError(message);
     }
     this.emit(EngineEvent.SignalResumed);
@@ -884,7 +941,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       await this.publisher.createAndSendOffer({ iceRestart: true });
     }
 
-    await this.waitForPCConnected();
+    await this.waitForPCReconnected();
     this.client.setReconnected();
 
     // recreate publish datachannel if it's id is null
@@ -897,7 +954,45 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.emit(EngineEvent.Resumed);
   }
 
-  async waitForPCConnected() {
+  async waitForPCInitialConnection(timeout?: number, abortController?: AbortController) {
+    if (this.pcState === PCState.Connected) {
+      return;
+    }
+    if (this.pcState !== PCState.New) {
+      throw new UnexpectedConnectionState(
+        'Expected peer connection to be new on initial connection',
+      );
+    }
+    return new Promise<void>((resolve, reject) => {
+      const abortHandler = () => {
+        log.warn('closing engine');
+        CriticalTimers.clearTimeout(connectTimeout);
+
+        reject(
+          new ConnectionError(
+            'room connection has been cancelled',
+            ConnectionErrorReason.Cancelled,
+          ),
+        );
+      };
+      if (abortController?.signal.aborted) {
+        abortHandler();
+      }
+      abortController?.signal.addEventListener('abort', abortHandler);
+      const onConnected = () => {
+        CriticalTimers.clearTimeout(connectTimeout);
+        abortController?.signal.removeEventListener('abort', abortHandler);
+        resolve();
+      };
+      const connectTimeout = CriticalTimers.setTimeout(() => {
+        this.off(EngineEvent.Connected, onConnected);
+        reject(new ConnectionError('could not establish pc connection'));
+      }, timeout ?? this.peerConnectionTimeout);
+      this.once(EngineEvent.Connected, onConnected);
+    });
+  }
+
+  async waitForPCReconnected() {
     const startTime = Date.now();
     let now = startTime;
     this.pcState = PCState.Reconnecting;
@@ -934,13 +1029,29 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     // make sure we do have a data connection
     await this.ensurePublisherConnected(kind);
 
-    if (kind === DataPacket_Kind.LOSSY && this.lossyDC) {
-      this.lossyDC.send(msg);
-    } else if (kind === DataPacket_Kind.RELIABLE && this.reliableDC) {
-      this.reliableDC.send(msg);
+    const dc = this.dataChannelForKind(kind);
+    if (dc) {
+      dc.send(msg);
     }
+
+    this.updateAndEmitDCBufferStatus(kind);
   }
 
+  private updateAndEmitDCBufferStatus = (kind: DataPacket_Kind) => {
+    const status = this.isBufferStatusLow(kind);
+    if (typeof status !== 'undefined' && status !== this.dcBufferStatus.get(kind)) {
+      this.dcBufferStatus.set(kind, status);
+      this.emit(EngineEvent.DCBufferStatusChanged, status, kind);
+    }
+  };
+
+  private isBufferStatusLow = (kind: DataPacket_Kind): boolean | undefined => {
+    const dc = this.dataChannelForKind(kind);
+    if (dc) {
+      return dc.bufferedAmount <= dc.bufferedAmountLowThreshold;
+    }
+  };
+
   /**
    * @internal
    */
@@ -1146,4 +1257,5 @@ export type EngineEventCallbacks = {
   activeSpeakersUpdate: (speakers: Array<SpeakerInfo>) => void;
   dataPacketReceived: (userPacket: UserPacket, kind: DataPacket_Kind) => void;
   transportsCreated: (publisher: PCTransport, subscriber: PCTransport) => void;
+  dcBufferStatusChanged: (isLow: boolean, kind: DataPacket_Kind) => void;
 };

package/src/room/ReconnectPolicy.ts

@@ -22,4 +22,6 @@ export interface ReconnectContext {
    * Reason for retrying
    */
   readonly retryReason?: Error;
+
+  readonly serverUrl?: string;
 }

package/src/room/RegionUrlProvider.ts

@@ -0,0 +1,73 @@
+import type { RegionInfo, RegionSettings } from '../proto/livekit_rtc';
+import { ConnectionError, ConnectionErrorReason } from './errors';
+import log from '../logger';
+import { isCloud } from './utils';
+
+export class RegionUrlProvider {
+  private serverUrl: URL;
+
+  private token: string;
+
+  private regionSettings: RegionSettings | undefined;
+
+  private lastUpdateAt: number = 0;
+
+  private settingsCacheTime = 3_000;
+
+  private attemptedRegions: RegionInfo[] = [];
+
+  constructor(url: string, token: string) {
+    this.serverUrl = new URL(url);
+    this.token = token;
+  }
+
+  isCloud() {
+    return isCloud(this.serverUrl);
+  }
+
+  async getNextBestRegionUrl(abortSignal?: AbortSignal) {
+    if (!this.isCloud()) {
+      throw Error('region availability is only supported for LiveKit Cloud domains');
+    }
+    if (!this.regionSettings || Date.now() - this.lastUpdateAt > this.settingsCacheTime) {
+      this.regionSettings = await this.fetchRegionSettings(abortSignal);
+    }
+    const regionsLeft = this.regionSettings.regions.filter(
+      (region) => !this.attemptedRegions.find((attempted) => attempted.url === region.url),
+    );
+    if (regionsLeft.length > 0) {
+      const nextRegion = regionsLeft[0];
+      this.attemptedRegions.push(nextRegion);
+      log.debug(`next region: ${nextRegion.region}`);
+      return nextRegion.url;
+    } else {
+      return null;
+    }
+  }
+
+  resetAttempts() {
+    this.attemptedRegions = [];
+  }
+
+  private async fetchRegionSettings(signal?: AbortSignal) {
+    const regionSettingsResponse = await fetch(`${getCloudConfigUrl(this.serverUrl)}/regions`, {
+      headers: { authorization: `Bearer ${this.token}` },
+      signal,
+    });
+    if (regionSettingsResponse.ok) {
+      const regionSettings = (await regionSettingsResponse.json()) as RegionSettings;
+      this.lastUpdateAt = Date.now();
+      return regionSettings;
+    } else {
+      throw new ConnectionError(
+        `Could not fetch region settings: ${regionSettingsResponse.statusText}`,
+        regionSettingsResponse.status === 401 ? ConnectionErrorReason.NotAllowed : undefined,
+        regionSettingsResponse.status,
+      );
+    }
+  }
+}
+
+function getCloudConfigUrl(serverUrl: URL) {
+  return `${serverUrl.protocol.replace('ws', 'http')}//${serverUrl.host}/settings`;
+}