livekit-client 2.18.10 → 2.19.1

package/src/room/Room.ts

@@ -48,6 +48,7 @@ import { PacketTrailerManager } from '../packetTrailer/PacketTrailerManager';
 import { isPacketTrailerSupported } from '../packetTrailer/utils';
 import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
+import { CLIENT_PROTOCOL_DEFAULT } from '../version';
 import { BackOffStrategy } from './BackOffStrategy';
 import DeviceManager from './DeviceManager';
 import RTCEngine, { DataChannelKind, type RegionStrategy } from './RTCEngine';
@@ -81,7 +82,14 @@ import LocalParticipant from './participant/LocalParticipant';
 import Participant from './participant/Participant';
 import { type ConnectionQuality, ParticipantKind } from './participant/Participant';
 import RemoteParticipant from './participant/RemoteParticipant';
-import { MAX_PAYLOAD_BYTES, RpcError, type RpcInvocationData, byteLength } from './rpc';
+import {
+  RPC_REQUEST_DATA_STREAM_TOPIC,
+  RPC_RESPONSE_DATA_STREAM_TOPIC,
+  RpcClientManager,
+  RpcError,
+  type RpcInvocationData,
+  RpcServerManager,
+} from './rpc';
 import CriticalTimers from './timers';
 import LocalAudioTrack from './track/LocalAudioTrack';
 import type LocalTrack from './track/LocalTrack';
@@ -221,7 +229,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private outgoingDataTrackManager: OutgoingDataTrackManager;
 
-  private rpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>> = new Map();
+  private rpcClientManager: RpcClientManager;
+
+  private rpcServerManager: RpcServerManager;
 
   get hasE2EESetup(): boolean {
     return this.e2eeManager !== undefined;
@@ -301,15 +311,36 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
           .finally(() => this.outgoingDataTrackManager.handlePacketSendComplete(handle));
       });
 
+    this.registerRpcDataStreamHandler();
+
+    this.rpcClientManager = new RpcClientManager(
+      this.log,
+      this.outgoingDataStreamManager,
+      this.getRemoteParticipantClientProtocol,
+      () => this.engine.latestJoinResponse?.serverInfo?.version,
+    );
+    this.rpcClientManager.on('sendDataPacket', ({ packet }) => {
+      this.engine?.sendDataPacket(packet, DataChannelKind.RELIABLE);
+    });
+    this.rpcServerManager = new RpcServerManager(
+      this.log,
+      this.outgoingDataStreamManager,
+      this.getRemoteParticipantClientProtocol,
+    );
+    this.rpcServerManager.on('sendDataPacket', ({ packet }) => {
+      this.engine?.sendDataPacket(packet, DataChannelKind.RELIABLE);
+    });
+
     this.disconnectLock = new Mutex();
     this.localParticipant = new LocalParticipant(
       '',
       '',
       this.engine,
       this.options,
-      this.rpcHandlers,
       this.outgoingDataStreamManager,
       this.outgoingDataTrackManager,
+      this.rpcClientManager,
+      this.rpcServerManager,
     );
 
     this.setupPacketTrailer();
@@ -342,18 +373,34 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
 
     if (isWeb()) {
-      const abortController = new AbortController();
-
-      // in order to catch device changes prior to room connection we need to register the event in the constructor
-      navigator.mediaDevices?.addEventListener?.('devicechange', this.handleDeviceChange, {
-        signal: abortController.signal,
-      });
+      const cleanupController = new AbortController();
+      let onDeviceChange: () => void;
 
       if (Room.cleanupRegistry) {
+        // Wrap the listener in a WeakRef closure so navigator.mediaDevices does not
+        // strongly retain the Room. When the user drops their Room ref, the
+        // FinalizationRegistry callback aborts the controller and removes the listener.
+        const roomRef = new WeakRef(this);
+        onDeviceChange = () => {
+          const self = roomRef.deref();
+          if (!self) {
+            return;
+          }
+          self.handleDeviceChange();
+        };
         Room.cleanupRegistry.register(this, () => {
-          abortController.abort();
+          cleanupController.abort();
         });
+      } else {
+        // Legacy browsers without WeakRef/FinalizationRegistry: fall back to a
+        // direct listener (matches pre-#1944 behavior).
+        onDeviceChange = this.handleDeviceChange;
       }
+
+      // in order to catch device changes prior to room connection we need to register the event in the constructor
+      navigator.mediaDevices?.addEventListener?.('devicechange', onDeviceChange, {
+        signal: cleanupController.signal,
+      });
     }
   }
 
@@ -400,12 +447,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
    * Other errors thrown in your handler will not be transmitted as-is, and will instead arrive to the caller as `1500` ("Application Error").
    */
   registerRpcMethod(method: string, handler: (data: RpcInvocationData) => Promise<string>) {
-    if (this.rpcHandlers.has(method)) {
-      throw Error(
-        `RPC handler already registered for method ${method}, unregisterRpcMethod before trying to register again`,
-      );
-    }
-    this.rpcHandlers.set(method, handler);
+    this.rpcServerManager.registerRpcMethod(method, handler);
   }
 
   /**
@@ -414,7 +456,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
    * @param method - The name of the RPC method to unregister
    */
   unregisterRpcMethod(method: string) {
-    this.rpcHandlers.delete(method);
+    this.rpcServerManager.unregisterRpcMethod(method);
   }
 
   /**
@@ -729,6 +771,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   static cleanupRegistry =
     typeof FinalizationRegistry !== 'undefined' &&
+    typeof WeakRef !== 'undefined' &&
     new FinalizationRegistry((cleanup: () => void) => {
       cleanup();
     });
@@ -1873,7 +1916,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     });
     this.emit(RoomEvent.ParticipantDisconnected, participant);
     participant.setDisconnected();
-    this.localParticipant?.handleParticipantDisconnected(participant.identity);
+    this.rpcClientManager.handleParticipantDisconnected(participant.identity);
   }
 
   // updates are sent only when there's a change to speaker ordering
@@ -2017,14 +2060,31 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       this.handleDataStream(packet, encryptionType);
     } else if (packet.value.case === 'rpcRequest') {
       const rpc = packet.value.value;
-      this.handleIncomingRpcRequest(
-        packet.participantIdentity,
-        rpc.id,
-        rpc.method,
-        rpc.payload,
-        rpc.responseTimeoutMs,
-        rpc.version,
-      );
+      this.rpcServerManager.handleIncomingRpcRequest(packet.participantIdentity, rpc);
+    } else if (packet.value.case === 'rpcResponse') {
+      const rpcResponse = packet.value.value;
+      switch (rpcResponse.value.case) {
+        case 'payload':
+          this.rpcClientManager.handleIncomingRpcResponseSuccess(
+            rpcResponse.requestId,
+            rpcResponse.value.value,
+          );
+          break;
+        case 'error':
+          this.rpcClientManager.handleIncomingRpcResponseFailure(
+            rpcResponse.requestId,
+            RpcError.fromProto(rpcResponse.value.value),
+          );
+          break;
+        default:
+          this.log.warn(
+            `Unknown rpcResponse.value.case: ${rpcResponse.value.case}`,
+            this.logContext,
+          );
+          break;
+      }
+    } else if (packet.value.case === 'rpcAck') {
+      this.rpcClientManager.handleIncomingRpcAck(packet.value.value.requestId);
     }
   };
 
@@ -2093,68 +2153,6 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.incomingDataStreamManager.handleDataStreamPacket(packet, encryptionType);
   };
 
-  private async handleIncomingRpcRequest(
-    callerIdentity: string,
-    requestId: string,
-    method: string,
-    payload: string,
-    responseTimeout: number,
-    version: number,
-  ) {
-    await this.engine.publishRpcAck(callerIdentity, requestId);
-
-    if (version !== 1) {
-      await this.engine.publishRpcResponse(
-        callerIdentity,
-        requestId,
-        null,
-        RpcError.builtIn('UNSUPPORTED_VERSION'),
-      );
-      return;
-    }
-
-    const handler = this.rpcHandlers.get(method);
-
-    if (!handler) {
-      await this.engine.publishRpcResponse(
-        callerIdentity,
-        requestId,
-        null,
-        RpcError.builtIn('UNSUPPORTED_METHOD'),
-      );
-      return;
-    }
-
-    let responseError: RpcError | null = null;
-    let responsePayload: string | null = null;
-
-    try {
-      const response = await handler({
-        requestId,
-        callerIdentity,
-        payload,
-        responseTimeout,
-      });
-      if (byteLength(response) > MAX_PAYLOAD_BYTES) {
-        responseError = RpcError.builtIn('RESPONSE_PAYLOAD_TOO_LARGE');
-        this.log.warn(`RPC Response payload too large for ${method}`);
-      } else {
-        responsePayload = response;
-      }
-    } catch (error) {
-      if (error instanceof RpcError) {
-        responseError = error;
-      } else {
-        this.log.warn(
-          `Uncaught error returned by RPC handler for ${method}. Returning APPLICATION_ERROR instead.`,
-          error,
-        );
-        responseError = RpcError.builtIn('APPLICATION_ERROR');
-      }
-    }
-    await this.engine.publishRpcResponse(callerIdentity, requestId, responsePayload, responseError);
-  }
-
   bufferedSegments: Map<string, TranscriptionSegmentModel> = new Map();
 
   private handleAudioPlaybackStarted = () => {
@@ -2500,6 +2498,27 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  private getRemoteParticipantClientProtocol = (identity: Participant['identity']) => {
+    return this.remoteParticipants.get(identity)?.clientProtocol ?? CLIENT_PROTOCOL_DEFAULT;
+  };
+
+  private registerRpcDataStreamHandler() {
+    this.incomingDataStreamManager.registerTextStreamHandler(
+      RPC_REQUEST_DATA_STREAM_TOPIC,
+      async (reader, { identity }) => {
+        const attributes = reader.info.attributes ?? {};
+        await this.rpcServerManager.handleIncomingDataStream(reader, identity, attributes);
+      },
+    );
+    this.incomingDataStreamManager.registerTextStreamHandler(
+      RPC_RESPONSE_DATA_STREAM_TOPIC,
+      async (reader, { identity }) => {
+        const attributes = reader.info.attributes ?? {};
+        await this.rpcClientManager.handleIncomingDataStream(reader, identity, attributes);
+      },
+    );
+  }
+
   private registerConnectionReconcile() {
     this.clearConnectionReconcile();
     let consecutiveFailures = 0;

package/src/room/participant/LocalParticipant.ts

@@ -13,9 +13,6 @@ import {
   ParticipantInfo,
   RequestResponse,
   RequestResponse_Reason,
-  RpcAck,
-  RpcRequest,
-  RpcResponse,
   SimulcastCodec,
   SipDTMF,
   SubscribedQualityUpdate,
@@ -54,11 +51,11 @@ import {
 } from '../errors';
 import { EngineEvent, ParticipantEvent, TrackEvent } from '../events';
 import {
-  MAX_PAYLOAD_BYTES,
   type PerformRpcParams,
+  RpcClientManager,
   RpcError,
   type RpcInvocationData,
-  byteLength,
+  RpcServerManager,
 } from '../rpc';
 import LocalAudioTrack from '../track/LocalAudioTrack';
 import LocalTrack from '../track/LocalTrack';
@@ -94,7 +91,6 @@ import {
 } from '../types';
 import {
   Future,
-  compareVersions,
   isAudioTrack,
   isE2EESimulcastSupported,
   isFireFox,
@@ -162,12 +158,14 @@ export default class LocalParticipant extends Participant {
 
   private firstActiveAgent?: RemoteParticipant;
 
-  private rpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>>;
-
   private roomOutgoingDataStreamManager: OutgoingDataStreamManager;
 
   private roomOutgoingDataTrackManager: OutgoingDataTrackManager;
 
+  private rpcClientManager: RpcClientManager;
+
+  private rpcServerManager: RpcServerManager;
+
   private pendingSignalRequests: Map<
     number,
     {
@@ -179,25 +177,16 @@ export default class LocalParticipant extends Participant {
 
   private enabledPublishVideoCodecs: Codec[] = [];
 
-  private pendingAcks = new Map<string, { resolve: () => void; participantIdentity: string }>();
-
-  private pendingResponses = new Map<
-    string,
-    {
-      resolve: (payload: string | null, error: RpcError | null) => void;
-      participantIdentity: string;
-    }
-  >();
-
   /** @internal */
   constructor(
     sid: string,
     identity: string,
     engine: RTCEngine,
     options: InternalRoomOptions,
-    roomRpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>>,
     roomOutgoingDataStreamManager: OutgoingDataStreamManager,
     roomOutgoingDataTrackManager: OutgoingDataTrackManager,
+    rpcClientManager: RpcClientManager,
+    rpcServerManager: RpcServerManager,
   ) {
     super(sid, identity, undefined, undefined, undefined, {
       loggerName: options.loggerName,
@@ -215,9 +204,10 @@ export default class LocalParticipant extends Participant {
       ['audiooutput', 'default'],
     ]);
     this.pendingSignalRequests = new Map();
-    this.rpcHandlers = roomRpcHandlers;
     this.roomOutgoingDataStreamManager = roomOutgoingDataStreamManager;
     this.roomOutgoingDataTrackManager = roomOutgoingDataTrackManager;
+    this.rpcClientManager = rpcClientManager;
+    this.rpcServerManager = rpcServerManager;
   }
 
   get lastCameraError(): Error | undefined {
@@ -277,8 +267,7 @@ export default class LocalParticipant extends Participant {
       .on(EngineEvent.LocalTrackUnpublished, this.handleLocalTrackUnpublished)
       .on(EngineEvent.SubscribedQualityUpdate, this.handleSubscribedQualityUpdate)
       .on(EngineEvent.Closing, this.handleClosing)
-      .on(EngineEvent.SignalRequestResponse, this.handleSignalRequestResponse)
-      .on(EngineEvent.DataPacketReceived, this.handleDataPacket);
+      .on(EngineEvent.SignalRequestResponse, this.handleSignalRequestResponse);
   }
 
   private handleReconnecting = () => {
@@ -362,27 +351,6 @@ export default class LocalParticipant extends Participant {
     }
   };
 
-  private handleDataPacket = (packet: DataPacket) => {
-    switch (packet.value.case) {
-      case 'rpcResponse':
-        let rpcResponse = packet.value.value as RpcResponse;
-        let payload: string | null = null;
-        let error: RpcError | null = null;
-
-        if (rpcResponse.value.case === 'payload') {
-          payload = rpcResponse.value.value;
-        } else if (rpcResponse.value.case === 'error') {
-          error = RpcError.fromProto(rpcResponse.value.value);
-        }
-        this.handleIncomingRpcResponse(rpcResponse.requestId, payload, error);
-        break;
-      case 'rpcAck':
-        let rpcAck = packet.value.value as RpcAck;
-        this.handleIncomingRpcAck(rpcAck.requestId);
-        break;
-    }
-  };
-
   /**
    * Sets and updates the metadata of the local participant.
    * Note: this requires `canUpdateOwnMetadata` permission.
@@ -1883,69 +1851,9 @@ export default class LocalParticipant extends Participant {
    * @returns A promise that resolves with the response payload or rejects with an error.
    * @throws Error on failure. Details in `message`.
    */
-  performRpc({
-    destinationIdentity,
-    method,
-    payload,
-    responseTimeout = 15000,
-  }: PerformRpcParams): TypedPromise<string, RpcError> {
-    const maxRoundTripLatency = 7000;
-    const minEffectiveTimeout = maxRoundTripLatency + 1000;
-
-    return new TypedPromise<string, RpcError>(async (resolve, reject) => {
-      if (byteLength(payload) > MAX_PAYLOAD_BYTES) {
-        reject(RpcError.builtIn('REQUEST_PAYLOAD_TOO_LARGE'));
-        return;
-      }
-
-      if (
-        this.engine.latestJoinResponse?.serverInfo?.version &&
-        compareVersions(this.engine.latestJoinResponse?.serverInfo?.version, '1.8.0') < 0
-      ) {
-        reject(RpcError.builtIn('UNSUPPORTED_SERVER'));
-        return;
-      }
-
-      const effectiveTimeout = Math.max(responseTimeout, minEffectiveTimeout);
-      const id = crypto.randomUUID();
-      await this.publishRpcRequest(destinationIdentity, id, method, payload, effectiveTimeout);
-
-      const ackTimeoutId = setTimeout(() => {
-        this.pendingAcks.delete(id);
-        reject(RpcError.builtIn('CONNECTION_TIMEOUT'));
-        this.pendingResponses.delete(id);
-        clearTimeout(responseTimeoutId);
-      }, maxRoundTripLatency);
-
-      this.pendingAcks.set(id, {
-        resolve: () => {
-          clearTimeout(ackTimeoutId);
-        },
-        participantIdentity: destinationIdentity,
-      });
-
-      const responseTimeoutId = setTimeout(() => {
-        this.pendingResponses.delete(id);
-        reject(RpcError.builtIn('RESPONSE_TIMEOUT'));
-      }, responseTimeout);
-
-      this.pendingResponses.set(id, {
-        resolve: (responsePayload: string | null, responseError: RpcError | null) => {
-          clearTimeout(responseTimeoutId);
-          if (this.pendingAcks.has(id)) {
-            this.log.warn('RPC response received before ack', id);
-            this.pendingAcks.delete(id);
-            clearTimeout(ackTimeoutId);
-          }
-
-          if (responseError) {
-            reject(responseError);
-          } else {
-            resolve(responsePayload ?? '');
-          }
-        },
-        participantIdentity: destinationIdentity,
-      });
+  performRpc(params: PerformRpcParams): TypedPromise<string, RpcError> {
+    return this.rpcClientManager.performRpc(params).then(([_id, completionPromise]) => {
+      return completionPromise;
     });
   }
 
@@ -1953,20 +1861,14 @@ export default class LocalParticipant extends Participant {
    * @deprecated use `room.registerRpcMethod` instead
    */
   registerRpcMethod(method: string, handler: (data: RpcInvocationData) => Promise<string>) {
-    if (this.rpcHandlers.has(method)) {
-      this.log.warn(
-        `you're overriding the RPC handler for method ${method}, in the future this will throw an error`,
-      );
-    }
-
-    this.rpcHandlers.set(method, handler);
+    this.rpcServerManager.registerRpcMethod(method, handler);
   }
 
   /**
    * @deprecated use `room.unregisterRpcMethod` instead
    */
   unregisterRpcMethod(method: string) {
-    this.rpcHandlers.delete(method);
+    this.rpcServerManager.unregisterRpcMethod(method);
   }
 
   /**
@@ -1997,72 +1899,6 @@ export default class LocalParticipant extends Participant {
     }
   }
 
-  private handleIncomingRpcAck(requestId: string) {
-    const handler = this.pendingAcks.get(requestId);
-    if (handler) {
-      handler.resolve();
-      this.pendingAcks.delete(requestId);
-    } else {
-      console.error('Ack received for unexpected RPC request', requestId);
-    }
-  }
-
-  private handleIncomingRpcResponse(
-    requestId: string,
-    payload: string | null,
-    error: RpcError | null,
-  ) {
-    const handler = this.pendingResponses.get(requestId);
-    if (handler) {
-      handler.resolve(payload, error);
-      this.pendingResponses.delete(requestId);
-    } else {
-      console.error('Response received for unexpected RPC request', requestId);
-    }
-  }
-
-  /** @internal */
-  private async publishRpcRequest(
-    destinationIdentity: string,
-    requestId: string,
-    method: string,
-    payload: string,
-    responseTimeout: number,
-  ) {
-    const packet = new DataPacket({
-      destinationIdentities: [destinationIdentity],
-      kind: DataPacket_Kind.RELIABLE,
-      value: {
-        case: 'rpcRequest',
-        value: new RpcRequest({
-          id: requestId,
-          method,
-          payload,
-          responseTimeoutMs: responseTimeout,
-          version: 1,
-        }),
-      },
-    });
-
-    await this.engine.sendDataPacket(packet, DataChannelKind.RELIABLE);
-  }
-
-  /** @internal */
-  handleParticipantDisconnected(participantIdentity: string) {
-    for (const [id, { participantIdentity: pendingIdentity }] of this.pendingAcks) {
-      if (pendingIdentity === participantIdentity) {
-        this.pendingAcks.delete(id);
-      }
-    }
-
-    for (const [id, { participantIdentity: pendingIdentity, resolve }] of this.pendingResponses) {
-      if (pendingIdentity === participantIdentity) {
-        resolve(null, RpcError.builtIn('RECIPIENT_DISCONNECTED'));
-        this.pendingResponses.delete(id);
-      }
-    }
-  }
-
   /** @internal */
   setEnabledPublishCodecs(codecs: Codec[]) {
     this.enabledPublishVideoCodecs = codecs.filter(

package/src/room/participant/RemoteParticipant.ts

@@ -6,6 +6,7 @@ import type {
 } from '@livekit/protocol';
 import type { SignalClient } from '../../api/SignalClient';
 import { DeferrableMap } from '../../utils/deferrable-map';
+import { CLIENT_PROTOCOL_DEFAULT } from '../../version';
 import RemoteDataTrack from '../data-track/RemoteDataTrack';
 import type IncomingDataTrackManager from '../data-track/incoming/IncomingDataTrackManager';
 import { DataTrackInfo } from '../data-track/types';
@@ -41,6 +42,11 @@ export default class RemoteParticipant extends Participant {
 
   signalClient: SignalClient;
 
+  /** A version number indicating the set of features that the report participant's client supports.
+   * @internal
+   **/
+  clientProtocol: number;
+
   private volumeMap: Map<Track.Source, number>;
 
   private audioOutput?: AudioOutputOptions;
@@ -65,6 +71,7 @@ export default class RemoteParticipant extends Participant {
         const info = DataTrackInfo.from(dti);
         return new RemoteDataTrack(info, manager, { publisherIdentity: pi.identity });
       }),
+      pi.clientProtocol,
     );
   }
 
@@ -87,6 +94,7 @@ export default class RemoteParticipant extends Participant {
     loggerOptions?: LoggerOptions,
     kind: ParticipantKind = ParticipantKind.STANDARD,
     remoteDataTracks: Array<RemoteDataTrack> = [],
+    clientProtocol: number = CLIENT_PROTOCOL_DEFAULT,
   ) {
     super(sid, identity || '', name, metadata, attributes, loggerOptions, kind);
     this.signalClient = signalClient;
@@ -99,6 +107,7 @@ export default class RemoteParticipant extends Participant {
       }),
     );
     this.volumeMap = new Map();
+    this.clientProtocol = clientProtocol;
   }
 
   protected addTrackPublication(publication: RemoteTrackPublication) {