livekit-client 2.22.1 → 2.22.3

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';
@@ -12,6 +12,7 @@ import { EngineEvent, ParticipantEvent, RoomEvent } from '../room/events';
 import type RemoteTrack from '../room/track/RemoteTrack';
 import RemoteVideoTrack from '../room/track/RemoteVideoTrack';
 import type { Track } from '../room/track/Track';
+import type { TrackPublication } from '../room/track/TrackPublication';
 import type { TrackPublishOptions, VideoCodec } from '../room/track/options';
 import { mimeTypeToVideoCodecString } from '../room/track/utils';
 import {
@@ -23,7 +24,8 @@ import {
 } from '../room/utils';
 import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import type { BaseKeyProvider } from './KeyProvider';
-import { E2EE_FLAG } from './constants';
+import { E2EE_FLAG, E2EE_TRACK_ID } from './constants';
+import { CryptorError, CryptorErrorReason } from './errors';
 import { type E2EEManagerCallbacks, EncryptionEvent, KeyProviderEvent } from './events';
 import type {
   DecryptDataRequestMessage,
@@ -61,6 +63,7 @@ export interface BaseE2EEManager {
     keyIndex: number,
   ): Promise<DecryptDataResponseMessage['data']>;
   on<E extends keyof E2EEManagerCallbacks>(event: E, listener: E2EEManagerCallbacks[E]): this;
+  dispose?(): void;
 }
 
 /**
@@ -86,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;
@@ -111,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);
@@ -124,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);
   }
 
@@ -145,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);
     }
@@ -155,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':
@@ -234,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);
   };
 
@@ -279,20 +376,14 @@ export class E2EEManager
 
   private setupEventListeners(room: Room, keyProvider: BaseKeyProvider) {
     room.on(RoomEvent.TrackPublished, (pub, participant) =>
-      this.setParticipantCryptorEnabled(
-        pub.trackInfo!.encryption !== Encryption_Type.NONE,
-        participant.identity,
-      ),
+      this.setParticipantCryptorEnabledForPublication(pub, participant.identity),
     );
     room
       .on(RoomEvent.ConnectionStateChanged, (state) => {
         if (state === ConnectionState.Connected) {
           room.remoteParticipants.forEach((participant) => {
             participant.trackPublications.forEach((pub) => {
-              this.setParticipantCryptorEnabled(
-                pub.trackInfo!.encryption !== Encryption_Type.NONE,
-                participant.identity,
-              );
+              this.setParticipantCryptorEnabledForPublication(pub, participant.identity);
             });
           });
         }
@@ -482,6 +573,28 @@ export class E2EEManager
     this.worker.postMessage(msg);
   }
 
+  /**
+   * Derive the participant's encryption state from one of its publications.
+   * Publications without trackInfo are skipped rather than thrown on: throwing
+   * inside the forEach above would leave every remaining participant without an
+   * encryption state, and a cryptor with unknown state can no longer decrypt.
+   */
+  private setParticipantCryptorEnabledForPublication(
+    pub: TrackPublication,
+    participantIdentity: string,
+  ) {
+    if (!pub.trackInfo) {
+      this.log.warn('skipping e2ee enabled update for publication without trackInfo', {
+        trackSid: pub.trackSid,
+      });
+      return;
+    }
+    this.setParticipantCryptorEnabled(
+      pub.trackInfo.encryption !== Encryption_Type.NONE,
+      participantIdentity,
+    );
+  }
+
   private setupE2EEReceiver(track: RemoteTrack, remoteId: string, trackInfo?: TrackInfo) {
     if (!track.receiver) {
       return;
@@ -504,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(
@@ -541,21 +654,27 @@ export class E2EEManager
         codec,
         hasPacketTrailer,
       };
-      // @ts-ignore
       receiver.transform = new RTCRtpScriptTransform(this.worker, options);
     } else {
-      if (E2EE_FLAG in receiver && codec) {
-        // update track-specific state when the transceiver is reused
+      if (E2EE_FLAG in receiver && E2EE_TRACK_ID in receiver) {
+        // The transceiver is being reused for a new track. We cannot set up a new
+        // pipeline from here: this receiver's encoded streams were transferred to
+        // the worker on first setup and a transferred stream can't be transferred
+        // again, while createEncodedStreams() may only be called once per receiver.
+        // So hand the worker the new track/participant and let it re-point (and if
+        // necessary rebuild) the cryptor that still owns those streams.
         const msg: UpdateCodecMessage = {
           kind: 'updateCodec',
           data: {
             trackId,
+            previousTrackId: receiver[E2EE_TRACK_ID] as string,
             codec,
             participantIdentity,
             hasPacketTrailer,
           },
         };
         this.worker.postMessage(msg);
+        receiver[E2EE_TRACK_ID] = trackId;
         return;
       }
       // @ts-ignore
@@ -582,7 +701,6 @@ export class E2EEManager
           trackId: trackId,
           codec,
           participantIdentity: participantIdentity,
-          isReuse: E2EE_FLAG in receiver,
           hasPacketTrailer,
         },
       };
@@ -591,6 +709,8 @@ export class E2EEManager
 
     // @ts-ignore
     receiver[E2EE_FLAG] = true;
+    // @ts-ignore
+    receiver[E2EE_TRACK_ID] = trackId;
   }
 
   /**
@@ -613,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,
@@ -625,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 = {
@@ -636,7 +756,6 @@ export class E2EEManager
           codec,
           trackId,
           participantIdentity: this.room.localParticipant.identity,
-          isReuse: false,
           hasPacketTrailer: hasFrameMetadataPublishOptions(frameMetadata),
           packetTrailer: frameMetadata,
         },

package/src/e2ee/constants.ts

@@ -29,6 +29,12 @@ export const IV_LENGTH = 12;
 // flag set to indicate that e2ee has been setup for sender/receiver;
 export const E2EE_FLAG = 'lk_e2ee';
 
+/**
+ * trackId a receiver's/sender's encoded stream pipeline was last set up for.
+ * Needed to recover the right cryptor when a transceiver gets reused.
+ */
+export const E2EE_TRACK_ID = 'lk_e2ee_track_id';
+
 export const SALT = 'LKFrameEncryptionKey';
 
 export const KEY_PROVIDER_DEFAULTS: KeyProviderOptions = {