livekit-client 2.22.2 → 2.22.4

package/src/e2ee/E2eeManager.test.ts

@@ -0,0 +1,196 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { LogLevel, getWorkerLogLevelListenerCount, setLogLevel, workerLogger } from '../logger';
+import Room from '../room/Room';
+import { E2EEManager } from './E2eeManager';
+import { BaseKeyProvider } from './KeyProvider';
+
+/**
+ * Install just enough of the DOM to let isE2EESupported() return true so
+ * setup() doesn't throw.
+ */
+function installE2EEShims() {
+  const w = window as unknown as Record<string, any>;
+  if (typeof w.RTCRtpSender === 'undefined') {
+    w.RTCRtpSender = class {};
+  }
+  w.RTCRtpSender.prototype.createEncodedStreams = () => {};
+}
+
+class FakeWorker {
+  postMessage = vi.fn();
+
+  onmessage: unknown = null;
+
+  onerror: unknown = null;
+
+  levelMessages(): LogLevel[] {
+    return this.postMessage.mock.calls
+      .map(([m]) => m)
+      .filter((m: any) => m?.kind === 'setLogLevel')
+      .map((m: any) => m.data.level);
+  }
+}
+
+function makeManager() {
+  installE2EEShims();
+  const room = new Room();
+  const worker = new FakeWorker();
+  const manager = new E2EEManager(
+    { keyProvider: new BaseKeyProvider({ sharedKey: true }), worker: worker as unknown as Worker },
+    false,
+  );
+  return { room, worker, manager };
+}
+
+describe('E2EEManager log-level listener lifecycle', () => {
+  const startingLevel = workerLogger.getLevel();
+  const startingCount = getWorkerLogLevelListenerCount();
+
+  afterEach(() => {
+    setLogLevel(startingLevel);
+  });
+
+  it('forwards level changes to the worker while subscribed', () => {
+    const { room, worker, manager } = makeManager();
+    manager.setup(room);
+    worker.postMessage.mockClear();
+
+    setLogLevel(LogLevel.debug);
+
+    expect(worker.levelMessages()).toEqual([LogLevel.debug]);
+    manager.dispose();
+  });
+
+  it('dispose() removes the listener and stops forwarding', () => {
+    const { room, worker, manager } = makeManager();
+    manager.setup(room);
+    manager.dispose();
+    worker.postMessage.mockClear();
+
+    setLogLevel(LogLevel.warn);
+
+    expect(worker.postMessage).not.toHaveBeenCalled();
+    expect(getWorkerLogLevelListenerCount()).toBe(startingCount);
+  });
+
+  it('re-setup with a new room does not stack listeners', () => {
+    const { worker, manager } = makeManager();
+    const roomA = new Room();
+    const roomB = new Room();
+    manager.setup(roomA);
+    const countAfterFirst = getWorkerLogLevelListenerCount();
+    manager.setup(roomB);
+    expect(getWorkerLogLevelListenerCount()).toBe(countAfterFirst);
+
+    worker.postMessage.mockClear();
+    setLogLevel(LogLevel.debug);
+    expect(worker.levelMessages()).toEqual([LogLevel.debug]); // exactly one delivery
+
+    manager.dispose();
+  });
+
+  it('dispose() is idempotent', () => {
+    const { room, manager } = makeManager();
+    manager.setup(room);
+    manager.dispose();
+    manager.dispose();
+    expect(getWorkerLogLevelListenerCount()).toBe(startingCount);
+  });
+
+  it('dispose() rejects pending encrypt/decrypt futures and clears both maps', async () => {
+    const { room, manager } = makeManager();
+    manager.setup(room);
+
+    const encrypting = manager.encryptData(new Uint8Array([1, 2, 3]) as any);
+    const decrypting = manager.handleEncryptedData(
+      new Uint8Array([4, 5, 6]) as any,
+      new Uint8Array([7, 8, 9]) as any,
+      'peer',
+      0,
+    );
+
+    const priv = manager as unknown as {
+      encryptDataRequests: Map<string, unknown>;
+      decryptDataRequests: Map<string, unknown>;
+    };
+    expect(priv.encryptDataRequests.size).toBe(1);
+    expect(priv.decryptDataRequests.size).toBe(1);
+
+    manager.dispose();
+
+    await expect(encrypting).rejects.toThrow(/disposed/);
+    await expect(decrypting).rejects.toThrow(/disposed/);
+    expect(priv.encryptDataRequests.size).toBe(0);
+    expect(priv.decryptDataRequests.size).toBe(0);
+
+    // Second dispose while maps are empty must not throw.
+    expect(() => manager.dispose()).not.toThrow();
+  });
+});
+
+/**
+ * GC-path test. Flaky by construction — FinalizationRegistry callbacks are
+ * best-effort. Skipped unless vitest is run with `--expose-gc`:
+ *
+ *   NODE_OPTIONS="--expose-gc" pnpm exec vitest run src/e2ee/E2eeManager.test.ts
+ *
+ * Deliberately bypasses `manager.setup(room)`. `new Room()` on its own is not
+ * collectable in this test environment (device-change listeners, timers), and
+ * that leak is not what this test is about — it would only mask what we
+ * actually want to verify: that the log-level listener wiring holds nothing
+ * strongly.
+ */
+describe('E2EEManager GC cleanup', () => {
+  const startingLevel = workerLogger.getLevel();
+
+  beforeEach(() => {
+    installE2EEShims();
+  });
+
+  afterEach(() => {
+    setLogLevel(startingLevel);
+  });
+
+  it.skipIf(!(globalThis as any).gc)(
+    'releases the log-level listener when the manager is garbage collected',
+    async () => {
+      const before = getWorkerLogLevelListenerCount();
+
+      // Construct + subscribe in an IIFE so nothing lives on the test's stack.
+      // Direct call to the private subscription — no Room, no leaky graph.
+      const managerRef = ((): WeakRef<E2EEManager> => {
+        const worker = new FakeWorker();
+        const manager = new E2EEManager(
+          {
+            keyProvider: new BaseKeyProvider({ sharedKey: true }),
+            worker: worker as unknown as Worker,
+          },
+          false,
+        );
+        (manager as unknown as { subscribeToLogLevelChanges(): void }).subscribeToLogLevelChanges();
+        expect(getWorkerLogLevelListenerCount()).toBe(before + 1);
+        return new WeakRef(manager);
+      })();
+
+      // Full major GC + macrotask yield in a loop, with allocation pressure to
+      // force the major sweep FinalizationRegistry needs.
+      //
+      // Crucial: do NOT call `managerRef.deref()` inside the loop. Per spec,
+      // `WeakRef.prototype.deref` keeps the referent alive until the end of the
+      // current job — calling it in the check would pin the manager forever.
+      // Read the listener count (which does not touch the referent) instead.
+      const gc = (globalThis as any).gc as (opts?: { type?: 'major'; execution?: 'sync' }) => void;
+      for (let i = 0; i < 50; i++) {
+        // eslint-disable-next-line no-void
+        void new Array(100_000).fill({ i });
+        gc({ type: 'major', execution: 'sync' });
+        await new Promise((r) => setImmediate(r));
+        if (getWorkerLogLevelListenerCount() === before) break;
+      }
+
+      // Diagnostic: separate "manager wasn't collected" from "FR didn't fire".
+      expect(managerRef.deref(), 'manager was not collected — strong ref leaked').toBeUndefined();
+      expect(getWorkerLogLevelListenerCount()).toBe(before);
+    },
+  );
+});

package/src/e2ee/E2eeManager.ts

@@ -3,7 +3,7 @@ import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
 import type { FrameMetadata } from '../frameMetadata/types';
 import { hasFrameMetadataPublishOptions } from '../frameMetadata/utils';
-import log, { LogLevel, workerLogger } from '../logger';
+import { LogLevel, LoggerNames, getLogger, onWorkerLogLevelChanged, workerLogger } from '../logger';
 import type RTCEngine from '../room/RTCEngine';
 import type Room from '../room/Room';
 import { ConnectionState } from '../room/Room';
@@ -25,6 +25,7 @@ import {
 import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import type { BaseKeyProvider } from './KeyProvider';
 import { E2EE_FLAG, E2EE_TRACK_ID } from './constants';
+import { CryptorError, CryptorErrorReason } from './errors';
 import { type E2EEManagerCallbacks, EncryptionEvent, KeyProviderEvent } from './events';
 import type {
   DecryptDataRequestMessage,
@@ -62,6 +63,7 @@ export interface BaseE2EEManager {
     keyIndex: number,
   ): Promise<DecryptDataResponseMessage['data']>;
   on<E extends keyof E2EEManagerCallbacks>(event: E, listener: E2EEManagerCallbacks[E]): this;
+  dispose?(): void;
 }
 
 /**
@@ -87,6 +89,29 @@ export class E2EEManager
 
   private dataChannelEncryptionEnabled: boolean;
 
+  private unsubscribeLogLevel?: () => void;
+
+  private log = getLogger(LoggerNames.E2EE, () => this.logContext);
+
+  get logContext() {
+    return {
+      room: this.room?.name,
+      participant: this.room?.localParticipant.identity,
+    };
+  }
+
+  /**
+   * Runs a cleanup callback once this manager is garbage collected. Lets the
+   * log-level listener (held in a module-global Set on the main-thread logger)
+   * fall out of scope even when the consumer forgets to call `dispose()`.
+   */
+  private static disposeRegistry =
+    typeof FinalizationRegistry !== 'undefined' &&
+    typeof WeakRef !== 'undefined' &&
+    new FinalizationRegistry((cleanup: () => void) => {
+      cleanup();
+    });
+
   constructor(options: E2EEManagerOptions, dcEncryptionEnabled: boolean) {
     super();
     this.keyProvider = options.keyProvider;
@@ -112,7 +137,7 @@ export class E2EEManager
         'tried to setup end-to-end encryption on an unsupported browser',
       );
     }
-    log.info('setting up e2ee');
+    this.log.info('setting up e2ee');
     if (room !== this.room) {
       this.room = room;
       this.setupEventListeners(room, this.keyProvider);
@@ -125,19 +150,89 @@ export class E2EEManager
         },
       };
       if (this.worker) {
-        log.info(`initializing worker`, { worker: this.worker });
+        this.log.info(`initializing worker`, { worker: this.worker });
         this.worker.onmessage = this.onWorkerMessage;
         this.worker.onerror = this.onWorkerError;
         this.worker.postMessage(msg);
+        this.subscribeToLogLevelChanges();
       }
     }
   }
 
+  /**
+   * Subscribe the current worker to main-thread `workerLogger` level changes,
+   * without strongly retaining `this` or `this.worker` from the module-global
+   * listener Set on the logger. See {@link disposeRegistry}.
+   */
+  private subscribeToLogLevelChanges() {
+    // Guard against duplicate registration on re-setup.
+    this.unsubscribeLogLevel?.();
+
+    let unsub: (() => void) | undefined;
+    if (E2EEManager.disposeRegistry) {
+      // Modern engines: hold the worker weakly so the module-global listener Set
+      // on the logger can't retain this manager, and clean up the entry on GC.
+      const workerRef = new WeakRef(this.worker);
+      unsub = onWorkerLogLevelChanged((level) => {
+        const worker = workerRef.deref();
+        if (!worker) {
+          unsub?.();
+          return;
+        }
+        worker.postMessage({ kind: 'setLogLevel', data: { level } });
+      });
+      E2EEManager.disposeRegistry.register(this, unsub, this);
+    } else {
+      // Safari <14.1 and similar: no WeakRef. Fall back to a strong reference;
+      // the leak lives until the consumer calls `dispose()`.
+      const worker = this.worker;
+      unsub = onWorkerLogLevelChanged((level) => {
+        worker.postMessage({ kind: 'setLogLevel', data: { level } });
+      });
+    }
+    this.unsubscribeLogLevel = unsub;
+  }
+
+  /**
+   * @internal
+   * Release the log-level subscription, reject any pending encrypt/decrypt
+   * futures, and detach the worker message handlers. The worker itself is
+   * caller-owned and is not terminated. Idempotent.
+   */
+  dispose() {
+    this.unsubscribeLogLevel?.();
+    this.unsubscribeLogLevel = undefined;
+    if (E2EEManager.disposeRegistry) {
+      E2EEManager.disposeRegistry.unregister(this);
+    }
+
+    // Reject pending futures BEFORE detaching worker handlers, so any late
+    // response can't resolve one after we've cut the pipe. Each future's
+    // `onFinally` deletes its own map entry, so both maps drain themselves.
+    // Snapshot before iterating in case a rejection handler mutates the map.
+    const disposalError = new CryptorError(
+      'E2EEManager disposed',
+      CryptorErrorReason.InternalError,
+    );
+    for (const future of [...this.encryptDataRequests.values()]) {
+      future.reject?.(disposalError);
+    }
+    for (const future of [...this.decryptDataRequests.values()]) {
+      future.reject?.(disposalError);
+    }
+
+    if (this.worker) {
+      this.worker.onmessage = null;
+      this.worker.onerror = null;
+    }
+    this.removeAllListeners();
+  }
+
   /**
    * @internal
    */
   setParticipantCryptorEnabled(enabled: boolean, participantIdentity: string) {
-    log.debug(`set e2ee to ${enabled} for participant ${participantIdentity}`);
+    this.log.debug(`set e2ee to ${enabled} for participant ${participantIdentity}`);
     this.postEnable(enabled, participantIdentity);
   }
 
@@ -146,7 +241,7 @@ export class E2EEManager
    */
   setSifTrailer(trailer: NonSharedUint8Array) {
     if (!trailer || trailer.length === 0) {
-      log.warn("ignoring server sent trailer as it's empty");
+      this.log.warn("ignoring server sent trailer as it's empty");
     } else {
       this.postSifTrailer(trailer);
     }
@@ -156,25 +251,23 @@ export class E2EEManager
     const { kind, data } = ev.data;
     switch (kind) {
       case 'error':
-        log.error(data.error.message);
-
-        // If error has uuid, it's from an async operation (encrypt/decrypt)
-        // Reject the corresponding future
+        // If error has uuid, it's from an async operation (encrypt/decrypt).
+        // Reject the corresponding future and let the caller decide how to log/handle;
+        // logging here would duplicate whatever the caller does.
         if (data.uuid) {
           const decryptFuture = this.decryptDataRequests.get(data.uuid);
           if (decryptFuture?.reject) {
             decryptFuture.reject(data.error);
-            break; // Don't emit general error if it's handled by future
+            break;
           }
 
           const encryptFuture = this.encryptDataRequests.get(data.uuid);
           if (encryptFuture?.reject) {
             encryptFuture.reject(data.error);
-            break; // Don't emit general error if it's handled by future
+            break;
           }
         }
-
-        // Emit general error event for unhandled errors
+        this.log.error(data.error.message);
         this.emit(EncryptionEvent.EncryptionError, data.error, data.participantIdentity);
         break;
       case 'initAck':
@@ -235,13 +328,16 @@ export class E2EEManager
       case 'packetTrailerMetadata':
         this.handleFrameMetadata(data.trackId, data.rtpTimestamp, data.ssrc, data.metadata);
         break;
+      case 'log':
+        workerLogger[data.level](data.msg, data.context);
+        break;
       default:
         break;
     }
   };
 
   private onWorkerError = (ev: ErrorEvent) => {
-    log.error('e2ee worker encountered an error:', { error: ev.error });
+    this.log.error('e2ee worker encountered an error:', { error: ev.error });
     this.emit(EncryptionEvent.EncryptionError, ev.error, undefined);
   };
 
@@ -488,8 +584,7 @@ export class E2EEManager
     participantIdentity: string,
   ) {
     if (!pub.trackInfo) {
-      log.warn('skipping e2ee enabled update for publication without trackInfo', {
-        participant: participantIdentity,
+      this.log.warn('skipping e2ee enabled update for publication without trackInfo', {
         trackSid: pub.trackSid,
       });
       return;
@@ -522,7 +617,7 @@ export class E2EEManager
 
   private setupE2EESender(track: Track, sender: RTCRtpSender) {
     if (!isLocalTrack(track) || !sender) {
-      if (!sender) log.warn('early return because sender is not ready');
+      if (!sender) this.log.warn('early return because sender is not ready');
       return;
     }
     this.handleSender(
@@ -638,7 +733,7 @@ export class E2EEManager
     }
 
     if (isScriptTransformSupportedForWorker()) {
-      log.info('initialize script transform');
+      this.log.info('initialize script transform');
       const options: ScriptTransformOptions = {
         kind: 'encode',
         participantIdentity: this.room.localParticipant.identity,
@@ -650,7 +745,7 @@ export class E2EEManager
       // @ts-ignore
       sender.transform = new RTCRtpScriptTransform(this.worker, options);
     } else {
-      log.info('initialize encoded streams');
+      this.log.info('initialize encoded streams');
       // @ts-ignore
       const senderStreams = sender.createEncodedStreams();
       const msg: EncodeMessage = {

package/src/e2ee/types.ts

@@ -176,6 +176,22 @@ export interface PTMetadataFromE2EEMessage extends BaseMessage {
   data: FrameMetadataPayload;
 }
 
+export interface LogMessage extends BaseMessage {
+  kind: 'log';
+  data: {
+    level: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+    msg: string;
+    context?: object;
+  };
+}
+
+export interface SetLogLevelMessage extends BaseMessage {
+  kind: 'setLogLevel';
+  data: {
+    level: LogLevel;
+  };
+}
+
 export type E2EEWorkerMessage =
   | InitMessage
   | SetKeyMessage
@@ -193,7 +209,9 @@ export type E2EEWorkerMessage =
   | DecryptDataResponseMessage
   | EncryptDataRequestMessage
   | EncryptDataResponseMessage
-  | PTMetadataFromE2EEMessage;
+  | PTMetadataFromE2EEMessage
+  | LogMessage
+  | SetLogLevelMessage;
 
 export type KeySet = { material: CryptoKey; encryptionKey: CryptoKey };
 

package/src/e2ee/worker/DataCryptor.ts

@@ -1,3 +1,4 @@
+import { getErrorDescription } from '../../api/utils';
 import { workerLogger } from '../../logger';
 import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { ENCRYPTION_ALGORITHM } from '../constants';
@@ -135,7 +136,7 @@ export class DataCryptor {
         }
       } else {
         throw new CryptorError(
-          `DataCryptor: Decryption failed: ${error.message}`,
+          `DataCryptor: Decryption failed: ${getErrorDescription(error, 'decryption')}`,
           CryptorErrorReason.InvalidKey,
           keys.participantIdentity,
         );

package/src/e2ee/worker/ErrorRateLimiter.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ErrorRateLimiter } from './ErrorRateLimiter';
+
+describe('ErrorRateLimiter', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000_000);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('emits first call, throttles the immediate next, then allows after throttle window', () => {
+    const l = new ErrorRateLimiter(1000, 60_000, 5);
+    expect(l.shouldEmit('k')).toBe(true);
+    vi.setSystemTime(1_000_500);
+    expect(l.shouldEmit('k')).toBe(false);
+    vi.setSystemTime(1_001_600);
+    expect(l.shouldEmit('k')).toBe(true);
+  });
+
+  it('caps at maxPerWindow and invokes onSuppress once', () => {
+    const l = new ErrorRateLimiter(0, 60_000, 3);
+    const onSuppress = vi.fn();
+    // one free emit on window reset (count stays 0), then increments to 3
+    expect(l.shouldEmit('k', onSuppress)).toBe(true);
+    expect(l.shouldEmit('k', onSuppress)).toBe(true);
+    expect(l.shouldEmit('k', onSuppress)).toBe(true);
+    expect(l.shouldEmit('k', onSuppress)).toBe(true);
+    // now count == 3 == max → suppressed, callback fires once
+    expect(l.shouldEmit('k', onSuppress)).toBe(false);
+    expect(l.shouldEmit('k', onSuppress)).toBe(false);
+    expect(onSuppress).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets count after windowMs', () => {
+    const l = new ErrorRateLimiter(0, 1000, 2);
+    l.shouldEmit('k');
+    l.shouldEmit('k');
+    l.shouldEmit('k');
+    expect(l.shouldEmit('k')).toBe(false);
+    vi.setSystemTime(1_003_000);
+    expect(l.shouldEmit('k')).toBe(true);
+  });
+
+  it('tracks keys independently', () => {
+    const l = new ErrorRateLimiter(1000);
+    expect(l.shouldEmit('a')).toBe(true);
+    expect(l.shouldEmit('b')).toBe(true);
+    expect(l.shouldEmit('a')).toBe(false);
+  });
+});

package/src/e2ee/worker/ErrorRateLimiter.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-key rate limiter for repeated errors. Prevents log/emit floods and the
+ * unbounded map growth that a per-event log would cause when a broken key
+ * keeps producing failures.
+ */
+export class ErrorRateLimiter {
+  private lastAt: Map<string, number> = new Map();
+
+  private counts: Map<string, number> = new Map();
+
+  constructor(
+    private readonly throttleMs: number = 1000,
+    private readonly windowMs: number = 60_000,
+    private readonly maxPerWindow: number = 5,
+  ) {}
+
+  reset() {
+    this.lastAt.clear();
+    this.counts.clear();
+  }
+
+  countFor(key: string): number {
+    return this.counts.get(key) ?? 0;
+  }
+
+  /**
+   * Returns true if the caller should emit for this key. Invokes `onSuppress`
+   * exactly once per window when the per-window limit is first crossed.
+   */
+  shouldEmit(key: string, onSuppress?: () => void): boolean {
+    const now = Date.now();
+    const last = this.lastAt.get(key) ?? 0;
+    const count = this.counts.get(key) ?? 0;
+
+    if (now - last > this.windowMs) {
+      this.counts.set(key, 0);
+      this.lastAt.set(key, now);
+      return true;
+    }
+    if (now - last < this.throttleMs) return false;
+    if (count >= this.maxPerWindow) {
+      if (count === this.maxPerWindow) {
+        onSuppress?.();
+        this.counts.set(key, count + 1);
+      }
+      return false;
+    }
+    this.lastAt.set(key, now);
+    this.counts.set(key, count + 1);
+    return true;
+  }
+}