livekit-client 2.22.2 → 2.22.4

package/src/e2ee/worker/FrameCryptor.ts

@@ -1,6 +1,7 @@
 // TODO code inspired by https://github.com/webrtc/samples/blob/gh-pages/src/content/insertable-streams/endtoend-encryption/js/worker.js
 import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
+import { getErrorDescription } from '../../api/utils';
 import {
   appendPacketTrailerToEncodedFrame,
   processPacketTrailer,
@@ -22,6 +23,7 @@ import type {
   RatchetResult,
 } from '../types';
 import { deriveKeys, isVideoFrame, needsRbspUnescaping, parseRbsp, writeRbsp } from '../utils';
+import { ErrorRateLimiter } from './ErrorRateLimiter';
 import type { ParticipantKeyHandler } from './ParticipantKeyHandler';
 import { processNALUsForEncryption } from './naluUtils';
 import { identifySifPayload } from './sifPayload';
@@ -111,18 +113,7 @@ export class FrameCryptor extends BaseFrameCryptor {
 
   private frameMetadataFrameId = 0;
 
-  /**
-   * Throttling mechanism for decryption errors to prevent memory leaks
-   */
-  private lastErrorTimestamp: Map<string, number> = new Map();
-
-  private errorCounts: Map<string, number> = new Map();
-
-  private readonly ERROR_THROTTLE_MS = 1000; // Emit error at most once per second
-
-  private readonly MAX_ERRORS_PER_MINUTE = 5; // Maximum errors to emit per minute per key
-
-  private readonly ERROR_WINDOW_MS = 60000; // 1 minute window
+  private errorLimiter = new ErrorRateLimiter();
 
   private undecryptedTrackTimeout?: ReturnType<typeof setTimeout>;
 
@@ -196,8 +187,7 @@ export class FrameCryptor extends BaseFrameCryptor {
     clearTimeout(this.undecryptedTrackTimeout);
     this.undecryptedTrackTimeout = undefined;
     this.participantIdentity = undefined;
-    this.lastErrorTimestamp = new Map();
-    this.errorCounts = new Map();
+    this.errorLimiter.reset();
   }
 
   isEnabled() {
@@ -421,64 +411,24 @@ export class FrameCryptor extends BaseFrameCryptor {
     this.sifTrailer = trailer;
   }
 
-  /**
-   * Checks if we should emit an error based on throttling rules to prevent memory leaks
-   * @param errorKey - unique key identifying the error context
-   * @returns true if the error should be emitted, false otherwise
-   */
-  private shouldEmitError(errorKey: string): boolean {
-    const now = Date.now();
-    const lastErrorTime = this.lastErrorTimestamp.get(errorKey) ?? 0;
-    const errorCount = this.errorCounts.get(errorKey) ?? 0;
-
-    // Reset count if we're in a new time window
-    if (now - lastErrorTime > this.ERROR_WINDOW_MS) {
-      this.errorCounts.set(errorKey, 0);
-      this.lastErrorTimestamp.set(errorKey, now);
-      return true;
-    }
-
-    // Check if we've exceeded the throttle time
-    if (now - lastErrorTime < this.ERROR_THROTTLE_MS) {
-      return false;
-    }
-
-    // Check if we've exceeded the max errors per window
-    if (errorCount >= this.MAX_ERRORS_PER_MINUTE) {
-      // Only log a warning once when hitting the limit
-      if (errorCount === this.MAX_ERRORS_PER_MINUTE) {
-        workerLogger.warn(`Suppressing further decryption errors for ${this.participantIdentity}`, {
-          ...this.logContext,
-          errorKey,
-        });
-        this.errorCounts.set(errorKey, errorCount + 1);
-      }
-      return false;
-    }
-
-    // Update tracking
-    this.lastErrorTimestamp.set(errorKey, now);
-    this.errorCounts.set(errorKey, errorCount + 1);
-    return true;
-  }
-
-  /**
-   * Emits a throttled error to prevent memory leaks from repeated decryption failures
-   * @param error - the CryptorError to emit
-   */
   private emitThrottledError(error: CryptorError) {
     const errorKey = `${this.participantIdentity}-${error.reason}-decrypt`;
+    const emit = this.errorLimiter.shouldEmit(errorKey, () => {
+      workerLogger.warn(`Suppressing further decryption errors for ${this.participantIdentity}`, {
+        ...this.logContext,
+        errorKey,
+      });
+    });
+    if (!emit) return;
 
-    if (this.shouldEmitError(errorKey)) {
-      const errorCount = this.errorCounts.get(errorKey) ?? 0;
-      if (errorCount > 1) {
-        workerLogger.debug(`Decryption error (${errorCount} occurrences in window)`, {
-          ...this.logContext,
-          reason: CryptorErrorReason[error.reason],
-        });
-      }
-      this.emit(CryptorEvent.Error, error);
+    const count = this.errorLimiter.countFor(errorKey);
+    if (count > 1) {
+      workerLogger.debug(`Decryption error (${count} occurrences in window)`, {
+        ...this.logContext,
+        reason: CryptorErrorReason[error.reason],
+      });
     }
+    this.emit(CryptorEvent.Error, error);
   }
 
   /**
@@ -587,7 +537,7 @@ export class FrameCryptor extends BaseFrameCryptor {
         return controller.enqueue(encodedFrame);
       } catch (e: any) {
         // TODO: surface this to the app.
-        workerLogger.error(e);
+        workerLogger.error(`error while encrypting`, { ...this.logContext, error: e });
       }
     } else {
       workerLogger.debug('failed to encrypt, emitting error', this.logContext);
@@ -858,7 +808,7 @@ export class FrameCryptor extends BaseFrameCryptor {
         }
       } else {
         throw new CryptorError(
-          `Decryption failed: ${error.message}`,
+          `Decryption failed: ${getErrorDescription(error, 'decryption')}`,
           CryptorErrorReason.InvalidKey,
           this.participantIdentity,
         );

package/src/e2ee/worker/e2ee.worker.ts

@@ -18,6 +18,7 @@ import type {
   ScriptTransformOptions,
 } from '../types';
 import { DataCryptor } from './DataCryptor';
+import { ErrorRateLimiter } from './ErrorRateLimiter';
 import { FrameCryptor, encryptionEnabledMap } from './FrameCryptor';
 import { ParticipantKeyHandler } from './ParticipantKeyHandler';
 
@@ -36,8 +37,21 @@ let keyProviderOptions: KeyProviderOptions = KEY_PROVIDER_DEFAULTS;
 
 let rtpMap: Map<number, VideoCodec> = new Map();
 
+const dataDecryptErrorLimiter = new ErrorRateLimiter();
+
 workerLogger.setDefaultLevel('info');
 
+// Forward worker log calls to the main thread so they reach any
+// setLogExtension consumer installed there. The main-thread workerLogger
+// re-emits them, which invokes both the console and the extension.
+workerLogger.methodFactory = (methodName) => (msg, context) => {
+  postMessage({
+    kind: 'log',
+    data: { level: methodName, msg, context },
+  });
+};
+workerLogger.setLevel(workerLogger.getLevel());
+
 onmessage = (ev) => {
   messageQueue.run(async () => {
     const { kind, data }: E2EEWorkerMessage = ev.data;
@@ -45,7 +59,7 @@ onmessage = (ev) => {
     switch (kind) {
       case 'init':
         workerLogger.setLevel(data.loglevel);
-        workerLogger.info('worker initialized');
+        workerLogger.info('e2ee worker initialized');
         keyProviderOptions = data.keyProviderOptions;
         useSharedKey = !!data.keyProviderOptions.sharedKey;
         // acknowledge init successful
@@ -55,6 +69,9 @@ onmessage = (ev) => {
         };
         postMessage(ackMsg);
         break;
+      case 'setLogLevel':
+        workerLogger.setLevel(data.level);
+        break;
       case 'enable':
         setEncryptionEnabled(data.enabled, data.participantIdentity);
         workerLogger.info(
@@ -96,11 +113,6 @@ onmessage = (ev) => {
           data.payload,
           getParticipantKeyHandler(data.participantIdentity),
         );
-        console.log('encrypted payload', {
-          original: data.payload,
-          encrypted: encryptedPayload,
-          iv,
-        });
         postMessage({
           kind: 'encryptDataResponse',
           data: {
@@ -125,12 +137,23 @@ onmessage = (ev) => {
             data: { payload: decryptedPayload, uuid: data.uuid },
           } satisfies DecryptDataResponseMessage);
         } catch (error) {
-          // Send error back to main thread with uuid so it can reject the corresponding promise
-          workerLogger.error('DataCryptor decryption failed', {
-            error,
-            participantIdentity: data.participantIdentity,
-            uuid: data.uuid,
+          // Send error back to main thread with uuid so it can reject the corresponding promise.
+          // The error response must always be posted so the awaiting future resolves; only the
+          // log is throttled to avoid flooding when a broken key keeps producing failures.
+          const errorKey = `${data.participantIdentity}-datadecrypt`;
+          const shouldLog = dataDecryptErrorLimiter.shouldEmit(errorKey, () => {
+            workerLogger.warn(
+              `Suppressing further data decryption errors for ${data.participantIdentity}`,
+              { errorKey },
+            );
           });
+          if (shouldLog) {
+            workerLogger.error('DataCryptor decryption failed', {
+              error,
+              participantIdentity: data.participantIdentity,
+              uuid: data.uuid,
+            });
+          }
           postMessage({
             kind: 'error',
             data: {

package/src/logger.ts

@@ -131,3 +131,25 @@ export function setLogExtension(extension: LogExtension, logger?: StructuredLogg
 }
 
 export const workerLogger = log.getLogger(LoggerNames.E2EE) as StructuredLogger;
+
+const workerLogLevelListeners = new Set<(level: LogLevel) => void>();
+
+const originalWorkerSetLevel = workerLogger.setLevel.bind(workerLogger);
+workerLogger.setLevel = ((level: log.LogLevelDesc, persist?: boolean) => {
+  originalWorkerSetLevel(level, persist);
+  const numeric = workerLogger.getLevel() as LogLevel;
+  workerLogLevelListeners.forEach((cb) => cb(numeric));
+}) as typeof workerLogger.setLevel;
+
+/** @internal Subscribe to workerLogger level changes (so E2EE workers can be kept in sync). */
+export function onWorkerLogLevelChanged(cb: (level: LogLevel) => void): () => void {
+  workerLogLevelListeners.add(cb);
+  return () => {
+    workerLogLevelListeners.delete(cb);
+  };
+}
+
+/** @internal Test-only accessor: current number of workerLogger level listeners. */
+export function getWorkerLogLevelListenerCount(): number {
+  return workerLogLevelListeners.size;
+}

package/src/options.ts

@@ -166,6 +166,22 @@ export interface InternalRoomConnectOptions {
    */
   rtcConfig?: RTCConfiguration;
 
+  /**
+   * when the server runs ICE lite, asks it to use a full ICE agent for this participant.
+   * this is a server-side setting that the server may ignore, defaults to false
+   */
+  disableIceLite: boolean;
+
+  /**
+   * whether the SFU may pause subscribed video tracks when this participant's downstream
+   * connection is congested, so that other tracks can continue to stream smoothly.
+   * paused tracks resume automatically when conditions allow, and `RoomEvent.TrackStreamStateChanged`
+   * fires on each transition.
+   * when left undefined, the server's default applies (the project setting on LiveKit Cloud,
+   * or `rtc.congestion_control.allow_pause` when self-hosting)
+   */
+  subscriberAllowPause?: boolean;
+
   /** specifies how often an initial join connection is allowed to retry (only applicable if server is not reachable) */
   maxRetries: number;
 

package/src/room/PCTransport.test.ts

@@ -2,11 +2,15 @@ import { type MediaDescription, parse } from 'sdp-transform';
 import { describe, expect, it } from 'vitest';
 import {
   applyVideoStartBitrate,
+  computeConnectionStartBitrate,
+  computeTrackStartBitrate,
   conformBundledCodecFmtp,
   ensureAudioNackAndStereo,
   ensureVideoDDExtension,
   extractStereoAndNackAudioFromOffer,
+  findTrackCodecPayload,
   fmtpConfigHasParam,
+  isDuplicateAnswer,
   placeholderMidsFromTransceivers,
 } from './PCTransport';
 import { ddExtensionURI } from './utils';
@@ -61,9 +65,7 @@ a=recvonly
 a=rtpmap:49 H265/90000
 a=fmtp:49 level-id=180;profile-id=1;tier-flag=0;tx-mode=SRST`;
 
-describe('video start bitrate', () => {
-  it('applies the bitrate only to the section whose msid track ID matches the cid', () => {
-    const { media } = parse(`v=0
+const TWO_VIDEO_SECTIONS = `v=0
 o=- 0 0 IN IP4 127.0.0.1
 s=-
 t=0 0
@@ -79,15 +81,159 @@ c=IN IP4 0.0.0.0
 a=mid:1
 a=sendonly
 a=msid:PA_remote|camera camera-cid
-a=rtpmap:96 VP8/90000`);
+a=rtpmap:96 VP8/90000`;
 
-    for (const section of media) {
-      applyVideoStartBitrate(section, 'camera-cid', 'VP8', 1_000);
-    }
+// The same bundle after the screen share is unpublished: `unpublishTrack` sets the
+// transceiver to `inactive`, but the section keeps its `a=msid`, so it still matches the
+// append-only trackBitrates entry. Only the camera is still sending.
+const UNPUBLISHED_SCREEN_SHARE = `v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+a=group:BUNDLE 0 1
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:0
+a=inactive
+a=msid:PA_remote|camera other-track
+a=rtpmap:96 VP8/90000
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:1
+a=sendonly
+a=msid:PA_remote|camera camera-cid
+a=rtpmap:96 VP8/90000`;
+
+// The legacy `addTrack` fallback (no `addTransceiver` support) reuses a transceiver instead
+// of creating a sendonly one, so the published camera lands on a `sendrecv` section. Mid 1
+// omits the direction attribute entirely, which SDP also defaults to sendrecv. Both send.
+const LEGACY_ADD_TRACK_SECTIONS = `v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+a=group:BUNDLE 0 1
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:0
+a=sendrecv
+a=msid:PA_remote|camera camera-cid
+a=rtpmap:96 VP8/90000
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:1
+a=msid:PA_remote|camera other-track
+a=rtpmap:96 VP8/90000`;
+
+describe('video start bitrate', () => {
+  it('matches only the section whose msid track ID matches the cid', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    expect(findTrackCodecPayload(media[0], 'camera-cid', 'VP8')).toBeUndefined();
+    expect(findTrackCodecPayload(media[1], 'camera-cid', 'VP8')).toBe(96);
+    // Section belongs to the track but does not offer the codec.
+    expect(findTrackCodecPayload(media[1], 'camera-cid', 'AV1')).toBe(0);
+  });
+
+  it('applies the bitrate only to the section it is given', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    applyVideoStartBitrate(media[1], 96, 900);
 
     expect(fmtpOf(media, '0', 96)).toBeUndefined();
     expect(paramSet(fmtpOf(media, '1', 96)!)).toContain('x-google-start-bitrate=900');
   });
+
+  it('caps camera at 1 Mbps but leaves screen share uncapped', () => {
+    const camera = { cid: 'c', codec: 'VP8', maxbr: 3_000 };
+    const screenShare = { ...camera, isScreenShare: true };
+
+    expect(computeTrackStartBitrate(camera)).toBe(1_000);
+    expect(computeTrackStartBitrate(screenShare)).toBe(2_700);
+  });
+
+  it('gives no hint below the 300 kbps target floor', () => {
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 299 })).toBeUndefined();
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 300 })).toBe(270);
+  });
+
+  it('uses one connection-level value: the largest hint across video sections', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    const startBitrate = computeConnectionStartBitrate(media, [
+      { cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 },
+      { cid: 'other-track', codec: 'VP8', maxbr: 3_000, isScreenShare: true },
+    ]);
+
+    expect(startBitrate).toBe(2_700);
+  });
+
+  it('ignores registered tracks with no section in the current SDP', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    const startBitrate = computeConnectionStartBitrate(media, [
+      { cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 },
+      // Stale entry: trackBitrates is append-only and outlives an unpublish.
+      { cid: 'unpublished-cid', codec: 'VP8', maxbr: 8_000, isScreenShare: true },
+    ]);
+
+    expect(startBitrate).toBe(900);
+  });
+
+  it('ignores a section that stopped sending but kept its msid', () => {
+    const trackBitrates = [
+      { cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 },
+      { cid: 'other-track', codec: 'VP8', maxbr: 8_000, isScreenShare: true },
+    ];
+
+    // While both send, the uncapped screen share wins the connection-level max.
+    expect(computeConnectionStartBitrate(parse(TWO_VIDEO_SECTIONS).media, trackBitrates)).toBe(
+      7_200,
+    );
+    // Once it is unpublished its entry is stale, so only the capped camera counts. Both
+    // directions a removed sender can land on are excluded: `inactive` from a sendonly
+    // transceiver, `recvonly` from the sendrecv one the addTrack fallback reuses.
+    expect(
+      computeConnectionStartBitrate(parse(UNPUBLISHED_SCREEN_SHARE).media, trackBitrates),
+    ).toBe(900);
+    expect(
+      computeConnectionStartBitrate(
+        parse(UNPUBLISHED_SCREEN_SHARE.replace('a=inactive', 'a=recvonly')).media,
+        trackBitrates,
+      ),
+    ).toBe(900);
+  });
+
+  it('gives no connection value when no section maps to a published track', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    expect(computeConnectionStartBitrate(media, [])).toBeUndefined();
+  });
+
+  it('counts sendrecv and direction-less sections, which still send local media', () => {
+    // The legacy addTrack fallback never produces `sendonly`, so a strict match on it would
+    // leave those clients with no hint at all.
+    const { media } = parse(LEGACY_ADD_TRACK_SECTIONS);
+
+    expect(
+      computeConnectionStartBitrate(media, [{ cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 }]),
+    ).toBe(900);
+    expect(
+      computeConnectionStartBitrate(media, [
+        { cid: 'other-track', codec: 'VP8', maxbr: 2_000, isScreenShare: true },
+      ]),
+    ).toBe(1_800);
+  });
+
+  it('leaves the hint unset when only non-sending sections match', () => {
+    // Nothing is published, so the one-shot hint must not be consumed on a dead section.
+    const { media } = parse(UNPUBLISHED_SCREEN_SHARE);
+
+    expect(
+      computeConnectionStartBitrate(media, [
+        { cid: 'other-track', codec: 'VP8', maxbr: 8_000, isScreenShare: true },
+      ]),
+    ).toBeUndefined();
+  });
 });
 
 describe('placeholderMidsFromTransceivers', () => {
@@ -390,3 +536,33 @@ a=extmap:3 ${ddExtensionURI}`);
     expect(ddOf(sdp.media, '1')).toBe(12);
   });
 });
+
+describe('isDuplicateAnswer', () => {
+  it('drops an answer while the same offer is still being answered', () => {
+    expect(isDuplicateAnswer(3, 3, 0, 'have-local-offer', false)).toBe(true);
+  });
+
+  it('drops a repeat of an unnumbered answer while the first is still applying', () => {
+    expect(isDuplicateAnswer(0, 0, 0, 'have-local-offer', false)).toBe(true);
+  });
+
+  it('drops an answer for an offer whose answer was already applied', () => {
+    expect(isDuplicateAnswer(3, undefined, 3, 'stable', false)).toBe(true);
+  });
+
+  it('accepts a retry after a failed apply: nothing in flight, nothing applied', () => {
+    expect(isDuplicateAnswer(3, undefined, 2, 'have-local-offer', false)).toBe(false);
+  });
+
+  it('accepts the answer for a new offer', () => {
+    expect(isDuplicateAnswer(4, undefined, 3, 'have-local-offer', false)).toBe(false);
+  });
+
+  it('without an offerId, drops an answer in stable', () => {
+    expect(isDuplicateAnswer(0, undefined, 0, 'stable', false)).toBe(true);
+  });
+
+  it('without an offerId, accepts the answer to a deferred initial offer', () => {
+    expect(isDuplicateAnswer(0, undefined, 0, 'stable', true)).toBe(false);
+  });
+});