livekit-client 2.18.4 → 2.18.6

package/src/room/RTCEngine.ts

@@ -21,6 +21,7 @@ import {
   PublishDataTrackResponse,
   ReconnectReason,
   type ReconnectResponse,
+  type RegionSettings,
   RequestResponse,
   Room as RoomModel,
   RoomMovedResponse,
@@ -62,7 +63,6 @@ import { TTLMap } from '../utils/ttlmap';
 import PCTransport, { PCEvents } from './PCTransport';
 import { PCTransportManager, PCTransportState } from './PCTransportManager';
 import type { ReconnectContext, ReconnectPolicy } from './ReconnectPolicy';
-import { DEFAULT_MAX_AGE_MS, type RegionUrlProvider } from './RegionUrlProvider';
 import { DataTrackInfo } from './data-track/types';
 import { roomConnectOptionDefaults } from './defaults';
 import {
@@ -86,6 +86,7 @@ import type { TrackPublishOptions, VideoCodec } from './track/options';
 import { getTrackPublicationInfo } from './track/utils';
 import type { LoggerOptions } from './types';
 import {
+  Future,
   isCompressionStreamSupported,
   isVideoCodec,
   isVideoTrack,
@@ -222,7 +223,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
   private shouldFailOnV1Path: boolean = false;
 
-  private regionUrlProvider?: RegionUrlProvider;
+  private regionStrategy?: RegionStrategy;
 
   private log = log;
 
@@ -249,6 +250,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   /** used to indicate whether the browser is currently waiting to reconnect */
   private isWaitingForNetworkReconnect: boolean = false;
 
+  private bufferStatusLowClosingFuture = new Future<never, UnexpectedConnectionState>();
+
   constructor(private options: InternalRoomOptions) {
     super();
     this.log = getLogger(options.loggerName ?? LoggerNames.Engine);
@@ -282,6 +285,13 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.client.onParticipantUpdate = (updates) =>
       this.emit(EngineEvent.ParticipantUpdate, updates);
     this.client.onJoined = (joinResponse) => this.emit(EngineEvent.Joined, joinResponse);
+
+    this.on(EngineEvent.Closing, () => {
+      this.bufferStatusLowClosingFuture.reject?.(new UnexpectedConnectionState('engine closed'));
+    });
+    // Swallow the rejection at the source so it doesn't surface as an unhandled promise rejection
+    // when no waitForBufferStatusLow callers are attached.
+    this.bufferStatusLowClosingFuture.promise.catch(() => {});
   }
 
   /** @internal */
@@ -332,7 +342,6 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         this.shouldFailOnV1Path = false;
         throw ConnectionError.serviceNotFound('Simulated v1 path failure', 'v0-rtc');
       }
-      log.warn('joining signal with ', url);
       const joinResponse = await this.client.join(
         url,
         token,
@@ -469,6 +478,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   async cleanupClient() {
     await this.client.close();
     this.client.resetCallbacks();
+    // Any in-flight addTrack requests are orphaned by the signal reconnect — the new session
+    // won't deliver `trackPublishedResponse` for them, so reject the pending resolvers and
+    // clear the map. Otherwise a subsequent `addTrack` call with the same client id (e.g. a
+    // publish retry after a `NegotiationError`) throws `TrackInvalidError`.
+    for (const cid of Object.keys(this.pendingTrackResolvers)) {
+      this.pendingTrackResolvers[cid].reject();
+    }
+    this.pendingTrackResolvers = {};
   }
 
   addTrack(req: AddTrackRequest): Promise<TrackInfo> {
@@ -532,8 +549,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   /* @internal */
-  setRegionUrlProvider(provider: RegionUrlProvider) {
-    this.regionUrlProvider = provider;
+  setRegionStrategy(strategy: RegionStrategy | undefined) {
+    this.regionStrategy = strategy;
   }
 
   private async configure(joinResponse?: JoinResponse, useSinglePeerConnection?: boolean) {
@@ -684,7 +701,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onTokenRefresh = (token: string) => {
       this.token = token;
-      this.regionUrlProvider?.updateToken(token);
+      this.emit(EngineEvent.TokenRefreshed, token);
     };
 
     this.client.onRemoteMuteChanged = (trackSid: string, muted: boolean) => {
@@ -726,13 +743,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onLeave = (leave: LeaveRequest) => {
       this.log.debug('client leave request', { ...this.logContext, reason: leave?.reason });
-      if (leave.regions && this.regionUrlProvider) {
+      if (leave.regions) {
         this.log.debug('updating regions', this.logContext);
-        this.regionUrlProvider.setServerReportedRegions({
-          updatedAtInMs: Date.now(),
-          maxAgeInMs: DEFAULT_MAX_AGE_MS,
-          regionSettings: leave.regions,
-        });
+        this.emit(EngineEvent.ServerRegionsReported, leave.regions);
       }
       switch (leave.action) {
         case LeaveRequest_Action.DISCONNECT:
@@ -1137,10 +1150,10 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.log.debug(`reconnecting in ${delay}ms`, this.logContext);
 
     this.clearReconnectTimeout();
-    if (this.token && this.regionUrlProvider) {
+    if (this.token) {
       // token may have been refreshed, we do not want to recreate the regionUrlProvider
       // since the current engine may have inherited a regional url
-      this.regionUrlProvider.updateToken(this.token);
+      this.emit(EngineEvent.TokenRefreshed, this.token);
     }
     this.reconnectTimeout = CriticalTimers.setTimeout(
       () =>
@@ -1273,17 +1286,17 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         throw new SignalReconnectError('Signal connection got severed during reconnect');
       }
 
-      this.regionUrlProvider?.resetAttempts();
+      this.regionStrategy?.resetAttempts();
       // reconnect success
       this.emit(EngineEvent.Restarted);
     } catch (error) {
-      const nextRegionUrl = await this.regionUrlProvider?.getNextBestRegionUrl();
+      const nextRegionUrl = await this.regionStrategy?.getNextUrl();
       if (nextRegionUrl) {
         await this.restartConnection(nextRegionUrl);
         return;
       } else {
         // no more regions to try (or we're not on cloud)
-        this.regionUrlProvider?.resetAttempts();
+        this.regionStrategy?.resetAttempts();
         throw error;
       }
     }
@@ -1578,23 +1591,15 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       if (this.isBufferStatusLow(kind)) {
         resolve();
       } else {
-        const onClosing = () => reject(new UnexpectedConnectionState('engine closed'));
-        this.once(EngineEvent.Closing, onClosing);
         const dc = this.dataChannelForKind(kind);
         if (!dc) {
           reject(new UnexpectedConnectionState(`DataChannel not found, kind: ${kind}`));
           return;
         }
-        dc.addEventListener(
-          'bufferedamountlow',
-          () => {
-            this.off(EngineEvent.Closing, onClosing);
-            resolve();
-          },
-          {
-            once: true,
-          },
-        );
+        this.bufferStatusLowClosingFuture.promise.catch((e) => reject(e));
+        dc.addEventListener('bufferedamountlow', () => resolve(), {
+          once: true,
+        });
       }
     });
   }
@@ -2023,8 +2028,15 @@ export type EngineEventCallbacks = {
   dataTrackSubscriberHandles: (event: DataTrackSubscriberHandles) => void;
   dataTrackPacketReceived: (packet: Uint8Array) => void;
   joined: (joinResponse: JoinResponse) => void;
+  tokenRefreshed: (token: string) => void;
+  serverRegionsReported: (regions: RegionSettings) => void;
 };
 
+export interface RegionStrategy {
+  getNextUrl(abortSignal?: AbortSignal): Promise<string | null>;
+  resetAttempts(): void;
+}
+
 function applyUserDataCompat(newObj: DataPacket, oldObj: UserPacket) {
   const participantIdentity = newObj.participantIdentity
     ? newObj.participantIdentity

package/src/room/RegionUrlProvider.ts

@@ -189,6 +189,13 @@ export class RegionUrlProvider {
 
   updateToken(token: string) {
     this.token = token;
+    const url = this.getServerUrl();
+    const settings = RegionUrlProvider.cache.get(url.hostname);
+    RegionUrlProvider.scheduleRefetch(
+      this.serverUrl,
+      this.token,
+      settings?.maxAgeInMs ?? DEFAULT_MAX_AGE_MS,
+    );
   }
 
   isCloud() {

package/src/room/Room.ts

@@ -47,8 +47,8 @@ import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import { BackOffStrategy } from './BackOffStrategy';
 import DeviceManager from './DeviceManager';
-import RTCEngine, { DataChannelKind } from './RTCEngine';
-import { RegionUrlProvider } from './RegionUrlProvider';
+import RTCEngine, { DataChannelKind, type RegionStrategy } from './RTCEngine';
+import { DEFAULT_MAX_AGE_MS, RegionUrlProvider } from './RegionUrlProvider';
 import IncomingDataStreamManager from './data-stream/incoming/IncomingDataStreamManager';
 import {
   type ByteStreamHandler,
@@ -668,6 +668,16 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
           }),
         );
         this.incomingDataTrackManager.receiveSfuPublicationUpdates(mapped);
+      })
+      .on(EngineEvent.TokenRefreshed, (token) => {
+        this.regionUrlProvider?.updateToken(token);
+      })
+      .on(EngineEvent.ServerRegionsReported, (regions) => {
+        this.regionUrlProvider?.setServerReportedRegions({
+          regionSettings: regions,
+          updatedAtInMs: Date.now(),
+          maxAgeInMs: DEFAULT_MAX_AGE_MS,
+        });
       });
 
     if (this.localParticipant) {
@@ -681,6 +691,14 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  private createRegionStrategy(): RegionStrategy {
+    return {
+      getNextUrl: async (signal?: AbortSignal) =>
+        this.regionUrlProvider ? this.regionUrlProvider.getNextBestRegionUrl(signal) : null,
+      resetAttempts: () => this.regionUrlProvider?.resetAttempts(),
+    };
+  }
+
   /**
    * getLocalDevices abstracts navigator.mediaDevices.enumerateDevices.
    * In particular, it requests device permissions by default if needed
@@ -965,7 +983,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       this.maybeCreateEngine();
     }
     if (this.regionUrlProvider?.isCloud()) {
-      this.engine.setRegionUrlProvider(this.regionUrlProvider);
+      this.engine.setRegionStrategy(this.createRegionStrategy());
     }
 
     this.acquireAudioContext();

package/src/room/data-track/packet/index.test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { DataTrackPacket, DataTrackPacketHeader, FrameMarker } from '.';
 import { DataTrackHandle } from '../handle';
 import { DataTrackTimestamp, WrapAroundUnsignedInt } from '../utils';
-import { EXT_FLAG_SHIFT } from './constants';
+import { EXT_FLAG_SHIFT, EXT_WORDS_INDICATOR_SIZE } from './constants';
 import {
   DataTrackE2eeExtension,
   DataTrackExtensionTag,
@@ -72,7 +72,7 @@ describe('DataTrackPacket', () => {
 
       const packet = new DataTrackPacket(header, payloadBytes);
 
-      expect(packet.toBinaryLengthBytes()).toStrictEqual(74);
+      expect(packet.toBinaryLengthBytes()).toStrictEqual(72);
       expect(packet.toBinary()).toStrictEqual(
         new Uint8Array([
           0xc, // Version 0, final, extension
@@ -120,8 +120,6 @@ describe('DataTrackPacket', () => {
           17,
 
           0, // Extension padding
-          0,
-          0,
 
           0xfa, // Payload
           0xfa,
@@ -174,7 +172,7 @@ describe('DataTrackPacket', () => {
 
       const packet = new DataTrackPacket(header, payloadBytes);
 
-      expect(packet.toBinaryLengthBytes()).toStrictEqual(62);
+      expect(packet.toBinaryLengthBytes()).toStrictEqual(64);
       expect(packet.toBinary()).toStrictEqual(
         new Uint8Array([
           0x14, // Version 0, start, extension
@@ -190,7 +188,7 @@ describe('DataTrackPacket', () => {
           0,
           104,
           0, // RTP oriented extension words (big endian)
-          3,
+          4,
 
           // E2ee extension
           1, // ID 1
@@ -210,6 +208,8 @@ describe('DataTrackPacket', () => {
           0x3c,
 
           0, // Extension padding
+          0,
+          0,
 
           0xfa, // Payload
           0xfa,
@@ -350,8 +350,8 @@ describe('DataTrackPacket', () => {
       const packetBytes = new Uint8Array([
         ...VALID_PACKET_BYTES,
 
-        0, // Extension word (big endian)
-        1,
+        0, // Extension word (big endian) — data_budget = (0+1)*4 - 2 = 2, but no data follows
+        0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag - should have ext word indicator here
 
@@ -409,7 +409,7 @@ describe('DataTrackPacket', () => {
         0, // Extension words (big endian)
         extensionWords,
 
-        ...new Array((extensionWords + 1) /* RTP oriented extension words */ * 4).fill(0), // Padding
+        ...new Array((extensionWords + 1) * 4 - EXT_WORDS_INDICATOR_SIZE).fill(0), // Padding
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 
@@ -423,11 +423,11 @@ describe('DataTrackPacket', () => {
         ...VALID_PACKET_BYTES,
 
         0, // RTP oriented extension words (big endian)
-        3,
+        4,
 
         // E2ee extension
         1, // ID 1
-        12, // Length 12
+        13, // Length 13
         0xfa, // Key index
         0x3c, // Iv array
         0x3c,
@@ -443,6 +443,8 @@ describe('DataTrackPacket', () => {
         0x3c,
 
         0, // Padding
+        0,
+        0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 
@@ -465,7 +467,7 @@ describe('DataTrackPacket', () => {
 
         // User timestamp extension
         2, // ID 2
-        7, // Length 7
+        8, // Length 8
         0x44, // Timestamp (big endian)
         0x11,
         0x22,
@@ -474,9 +476,6 @@ describe('DataTrackPacket', () => {
         0x11,
         0x88,
         0x11,
-
-        0, // Padding
-        0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 
@@ -505,11 +504,9 @@ describe('DataTrackPacket', () => {
         0x4,
         0x5,
         0x6,
-        0x0,
 
         0x0, // Padding
         0x0,
-        0x0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 
@@ -525,12 +522,10 @@ describe('DataTrackPacket', () => {
       const packetBytes = new Uint8Array([
         ...VALID_PACKET_BYTES,
 
-        0, // RTP oriented extension words (big endian)
+        0, // RTP oriented extension words (big endian, data_budget = 2)
         0,
 
-        0x0, // Padding, missing one byte
-        0x0,
-        0x0,
+        0x0, // Only 1 byte, but 2 needed
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 

package/src/room/data-track/packet/index.ts

@@ -65,8 +65,8 @@ export class DataTrackPacketHeader extends Serializable {
 
   private extensionsMetrics() {
     const lengthBytes = this.extensions.toBinaryLengthBytes();
-    const lengthWords = Math.ceil(lengthBytes / 4);
-    const paddingLengthBytes = lengthWords * 4 - lengthBytes;
+    const lengthWords = Math.ceil((EXT_WORDS_INDICATOR_SIZE + lengthBytes) / 4);
+    const paddingLengthBytes = lengthWords * 4 - EXT_WORDS_INDICATOR_SIZE - lengthBytes;
 
     return { lengthBytes, lengthWords, paddingLengthBytes };
   }
@@ -242,7 +242,7 @@ export class DataTrackPacketHeader extends Serializable {
       // potentially unintuitive so I wanted to call it out.
       const extensionWords = rtpOrientedExtensionWords + 1;
 
-      let extensionLengthBytes = 4 * extensionWords;
+      let extensionLengthBytes = 4 * extensionWords - EXT_WORDS_INDICATOR_SIZE;
 
       if (byteIndex + extensionLengthBytes > dataView.byteLength) {
         throw DataTrackDeserializeError.headerOverrun();

package/src/room/events.ts

@@ -631,6 +631,8 @@ export enum EngineEvent {
   DataTrackSubscriberHandles = 'dataTrackSubscriberHandles',
   DataTrackPacketReceived = 'dataTrackPacketReceived',
   Joined = 'joined',
+  TokenRefreshed = 'tokenRefreshed',
+  ServerRegionsReported = 'serverRegionsReported',
 }
 
 export enum TrackEvent {

package/src/room/participant/LocalParticipant.ts

@@ -39,6 +39,7 @@ import { defaultVideoCodec } from '../defaults';
 import {
   DeviceUnsupportedError,
   LivekitError,
+  NegotiationError,
   PublishTrackError,
   SignalRequestError,
   TrackInvalidError,
@@ -656,11 +657,12 @@ export default class LocalParticipant extends Participant {
       if (track && track.track) {
         // screenshare cannot be muted, unpublish instead
         if (source === Track.Source.ScreenShare) {
-          track = await this.unpublishTrack(track.track);
+          const unpublishPromises = [this.unpublishTrack(track.track)];
           const screenAudioTrack = this.getTrackPublication(Track.Source.ScreenShareAudio);
           if (screenAudioTrack && screenAudioTrack.track) {
-            this.unpublishTrack(screenAudioTrack.track);
+            unpublishPromises.push(this.unpublishTrack(screenAudioTrack.track));
           }
+          [track] = await Promise.all(unpublishPromises);
         } else {
           await track.mute();
         }
@@ -806,10 +808,42 @@ export default class LocalParticipant extends Participant {
     return this.publishOrRepublishTrack(track, options);
   }
 
+  /**
+   * Waits for the engine's next `Restarted` event. Unlike `engine.waitForRestarted`, this does
+   * not short-circuit when `pcState === Connected` — at the point this is called (right after a
+   * `NegotiationError`) the PC transport is still connected, but `fullReconnectOnNext` has been
+   * set and `attemptReconnect` is queued via setTimeout. We need to wait for that restart to
+   * actually complete (which clears `pendingTrackResolvers` via `cleanupClient`) before retrying.
+   */
+  private waitForNextEngineRestart(timeoutMs = 15_000): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.engine.off(EngineEvent.Restarted, onRestarted);
+        this.engine.off(EngineEvent.Closing, onClosing);
+      };
+      const onRestarted = () => {
+        cleanup();
+        resolve();
+      };
+      const onClosing = () => {
+        cleanup();
+        reject(new Error('engine closed before restart completed'));
+      };
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error('timed out waiting for engine restart'));
+      }, timeoutMs);
+      this.engine.once(EngineEvent.Restarted, onRestarted);
+      this.engine.once(EngineEvent.Closing, onClosing);
+    });
+  }
+
   private async publishOrRepublishTrack(
     track: LocalTrack | MediaStreamTrack,
     options?: TrackPublishOptions,
     isRepublish = false,
+    hasRetriedAfterNegotiationError = false,
   ): Promise<LocalTrackPublication> {
     if (isLocalAudioTrack(track)) {
       track.setAudioContext(this.audioContext);
@@ -978,6 +1012,15 @@ export default class LocalParticipant extends Participant {
       const publication = await publishPromise;
       return publication;
     } catch (e) {
+      if (!hasRetriedAfterNegotiationError && e instanceof NegotiationError) {
+        this.log.warn('negotiation due to track publish failed, retrying after reconnect', {
+          ...this.logContext,
+          error: e,
+        });
+        this.pendingPublishPromises.delete(track);
+        await this.waitForNextEngineRestart();
+        return await this.publishOrRepublishTrack(track, options, isRepublish, true);
+      }
       throw e;
     } finally {
       this.pendingPublishPromises.delete(track);
@@ -1272,7 +1315,11 @@ export default class LocalParticipant extends Participant {
         resolve(ti);
       } catch (err) {
         if (track.sender && this.engine.pcManager?.publisher) {
-          this.engine.pcManager.publisher.removeTrack(track.sender);
+          try {
+            this.engine.pcManager.publisher.removeTrack(track.sender);
+          } catch (e) {
+            this.log.error(e, this.logContext);
+          }
           await this.engine.negotiate().catch((negotiateErr) => {
             this.log.error(
               'failed to negotiate after removing track due to failed add track request',
@@ -1333,6 +1380,17 @@ export default class LocalParticipant extends Participant {
     publication.options = opts;
     track.sid = ti.sid;
 
+    // keep publish options on the video track so that it can recompute encoding
+    // parameters when the MediaStreamTrack is restarted (e.g. after switching cameras).
+    // Seed the dimensions we encoded at publish time so the first no-op restart
+    // (e.g. unmute with unchanged constraints) can skip the recompute.
+    if (isLocalVideoTrack(track)) {
+      track.publishOptions = opts;
+      if (req.width && req.height) {
+        track.lastEncodedDimensions = { width: req.width, height: req.height };
+      }
+    }
+
     this.log.debug(`publishing ${track.kind} with encodings`, {
       ...this.logContext,
       encodings,
@@ -1587,13 +1645,20 @@ export default class LocalParticipant extends Participant {
             negotiationNeeded = true;
           }
         }
-        if (this.engine.removeTrack(trackSender)) {
+        try {
+          negotiationNeeded = this.engine.removeTrack(trackSender);
+        } catch (e) {
+          this.log.warn(e, this.logContext);
           negotiationNeeded = true;
         }
+
         if (isLocalVideoTrack(track)) {
           for (const [, trackInfo] of track.simulcastCodecs) {
             if (trackInfo.sender) {
-              if (this.engine.removeTrack(trackInfo.sender)) {
+              try {
+                negotiationNeeded = this.engine.removeTrack(trackInfo.sender);
+              } catch (e) {
+                this.log.warn(e, this.logContext);
                 negotiationNeeded = true;
               }
               trackInfo.sender = undefined;