livekit-client 2.18.10 → 2.19.0

package/dist/ts4.2/room/participant/RemoteParticipant.d.ts

@@ -22,6 +22,10 @@ export default class RemoteParticipant extends Participant {
      * const track = await remoteParticipant.dataTracks.getDeferred("data track name"); */
     dataTracks: DeferrableMap<RemoteDataTrack['info']['name'], RemoteDataTrack>;
     signalClient: SignalClient;
+    /** A version number indicating the set of features that the report participant's client supports.
+     * @internal
+     **/
+    clientProtocol: number;
     private volumeMap;
     private audioOutput?;
     /** @internal */
@@ -31,7 +35,7 @@ export default class RemoteParticipant extends Participant {
         remoteParticipant: string;
     };
     /** @internal */
-    constructor(signalClient: SignalClient, sid: string, identity?: string, name?: string, metadata?: string, attributes?: Record<string, string>, loggerOptions?: LoggerOptions, kind?: ParticipantKind, remoteDataTracks?: Array<RemoteDataTrack>);
+    constructor(signalClient: SignalClient, sid: string, identity?: string, name?: string, metadata?: string, attributes?: Record<string, string>, loggerOptions?: LoggerOptions, kind?: ParticipantKind, remoteDataTracks?: Array<RemoteDataTrack>, clientProtocol?: number);
     protected addTrackPublication(publication: RemoteTrackPublication): void;
     getTrackPublication(source: Track.Source): RemoteTrackPublication | undefined;
     getTrackPublicationByName(name: string): RemoteTrackPublication | undefined;

package/dist/ts4.2/room/rpc/client/RpcClientManager.d.ts

@@ -0,0 +1,43 @@
+import type TypedEmitter from 'typed-emitter';
+import type { StructuredLogger } from '../../../logger';
+import type { TextStreamReader } from '../../data-stream/incoming/StreamReader';
+import type OutgoingDataStreamManager from '../../data-stream/outgoing/OutgoingDataStreamManager';
+import type Participant from '../../participant/Participant';
+import type { PerformRpcParams } from '../utils';
+import { RpcError } from '../utils';
+import type { RpcClientManagerCallbacks } from './events';
+declare const RpcClientManager_base: new () => TypedEmitter<RpcClientManagerCallbacks>;
+/**
+ * Manages the client (caller) side of RPC: sending requests, tracking pending
+ * ack/response state, and handling incoming ack/response packets.
+ * @internal
+ */
+export default class RpcClientManager extends RpcClientManager_base {
+    private log;
+    private outgoingDataStreamManager;
+    private getRemoteParticipantClientProtocol;
+    private getServerVersion;
+    private pendingAcks;
+    private pendingResponses;
+    constructor(log: StructuredLogger, outgoingDataStreamManager: OutgoingDataStreamManager, getRemoteParticipantClientProtocol: (identity: Participant['identity']) => number, getServerVersion: () => string | undefined);
+    performRpc({ destinationIdentity, method, payload, responseTimeout: responseTimeoutMs, }: PerformRpcParams): Promise<[
+        id: string,
+        completionPromise: Promise<string>
+    ]>;
+    private publishRpcRequest;
+    /**
+     * Handle an incoming data stream containing an RPC response payload.
+     * @internal
+     */
+    handleIncomingDataStream(reader: TextStreamReader, senderIdentity: Participant['identity'], attributes: Record<string, string>): Promise<void>;
+    /** @internal */
+    handleIncomingRpcResponseSuccess(requestId: string, payload: string): void;
+    /** @internal */
+    handleIncomingRpcResponseFailure(requestId: string, error: RpcError): void;
+    /** @internal */
+    handleIncomingRpcAck(requestId: string): void;
+    /** @internal */
+    handleParticipantDisconnected(participantIdentity: string): void;
+}
+export {};
+//# sourceMappingURL=RpcClientManager.d.ts.map

package/dist/ts4.2/room/rpc/client/events.d.ts

@@ -0,0 +1,8 @@
+import type { DataPacket } from '@livekit/protocol';
+export type EventSendDataPacket = {
+    packet: DataPacket;
+};
+export type RpcClientManagerCallbacks = {
+    sendDataPacket: (event: EventSendDataPacket) => void;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/ts4.2/room/rpc/index.d.ts

@@ -0,0 +1,7 @@
+export { default as RpcClientManager } from './client/RpcClientManager';
+export type { RpcClientManagerCallbacks } from './client/events';
+export { default as RpcServerManager } from './server/RpcServerManager';
+export type { RpcServerManagerCallbacks } from './server/events';
+export type { PerformRpcParams, RpcInvocationData } from './utils';
+export { RPC_REQUEST_DATA_STREAM_TOPIC, RPC_RESPONSE_DATA_STREAM_TOPIC, RpcRequestAttrs, RpcError, byteLength, truncateBytes } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/ts4.2/room/rpc/server/RpcServerManager.d.ts

@@ -0,0 +1,44 @@
+import { RpcRequest } from '@livekit/protocol';
+import type TypedEmitter from 'typed-emitter';
+import type { StructuredLogger } from '../../../logger';
+import type { TextStreamReader } from '../../data-stream/incoming/StreamReader';
+import type OutgoingDataStreamManager from '../../data-stream/outgoing/OutgoingDataStreamManager';
+import type Participant from '../../participant/Participant';
+import type { RpcInvocationData } from '../utils';
+import type { RpcServerManagerCallbacks } from './events';
+declare const RpcServerManager_base: new () => TypedEmitter<RpcServerManagerCallbacks>;
+/**
+ * Manages the server (handler) side of RPC: processing incoming requests,
+ * managing registered method handlers, and sending responses.
+ * @internal
+ */
+export default class RpcServerManager extends RpcServerManager_base {
+    private log;
+    private outgoingDataStreamManager;
+    private getRemoteParticipantClientProtocol;
+    private rpcHandlers;
+    constructor(log: StructuredLogger, outgoingDataStreamManager: OutgoingDataStreamManager, getRemoteParticipantClientProtocol: (identity: Participant['identity']) => number);
+    registerRpcMethod(method: string, handler: (data: RpcInvocationData) => Promise<string>): void;
+    unregisterRpcMethod(method: string): void;
+    /**
+     * Handle an incoming RPCRequest message containing a payload.
+     * This handles "version 1" of rpc requests.
+     * @internal
+     */
+    handleIncomingRpcRequest(callerIdentity: string, rpcRequest: RpcRequest): Promise<void>;
+    /**
+     * Handle an incoming data stream containing a RPC request payload.
+     * This handles "version 2" of rpc requests.
+     * @internal
+     */
+    handleIncomingDataStream(reader: TextStreamReader, callerIdentity: Participant['identity'], dataStreamAttrs: Record<string, string>): Promise<void>;
+    private publishRpcAck;
+    private publishRpcResponsePacket;
+    /**
+     * Send a successful RPC response payload, choosing the transport based on
+     * the caller's client protocol version.
+     */
+    private publishRpcResponse;
+}
+export {};
+//# sourceMappingURL=RpcServerManager.d.ts.map

package/dist/ts4.2/room/rpc/server/events.d.ts

@@ -0,0 +1,8 @@
+import type { DataPacket } from '@livekit/protocol';
+export type EventSendDataPacket = {
+    packet: DataPacket;
+};
+export type RpcServerManagerCallbacks = {
+    sendDataPacket: (event: EventSendDataPacket) => void;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/ts4.2/room/{rpc.d.ts → rpc/utils.d.ts}

@@ -49,6 +49,7 @@ export declare class RpcError extends Error {
     static MAX_DATA_BYTES: number;
     code: number;
     data?: string;
+    cause?: unknown;
     /**
      * Creates an error object with the given code and message, plus an optional data payload.
      *
@@ -56,7 +57,9 @@ export declare class RpcError extends Error {
      *
      * Error codes 1001-1999 are reserved for built-in errors (see RpcError.ErrorCode for their meanings).
      */
-    constructor(code: number, message: string, data?: string);
+    constructor(code: number, message: string, data?: string, options?: {
+        cause?: unknown;
+    });
     /**
      * @internal
      */
@@ -87,9 +90,36 @@ export declare class RpcError extends Error {
      *
      * @internal
      */
-    static builtIn(key: keyof typeof RpcError.ErrorCode, data?: string): RpcError;
+    static builtIn(key: keyof typeof RpcError.ErrorCode, data?: string, options?: {
+        cause?: unknown;
+    }): RpcError;
 }
-export declare const MAX_PAYLOAD_BYTES = 15360;
+export declare const MAX_V1_PAYLOAD_BYTES = 15360;
+/**
+ * Topic used for v2 RPC request data streams.
+ * @internal
+ */
+export declare const RPC_REQUEST_DATA_STREAM_TOPIC = "lk.rpc_request";
+/**
+ * Topic used for v2 RPC response data streams.
+ * @internal
+ */
+export declare const RPC_RESPONSE_DATA_STREAM_TOPIC = "lk.rpc_response";
+/** @internal */
+export declare enum RpcRequestAttrs {
+    RPC_REQUEST_ID = "lk.rpc_request_id",
+    RPC_REQUEST_METHOD = "lk.rpc_request_method",
+    RPC_REQUEST_RESPONSE_TIMEOUT_MS = "lk.rpc_request_response_timeout_ms",
+    RPC_REQUEST_VERSION = "lk.rpc_request_version"
+}
+/** Initial version of rpc which uses RpcRequest / RpcResponse messages.
+ * @internal
+ **/
+export declare const RPC_VERSION_V1 = 1;
+/** Rpc version backed by data streams instead of RpcRequest / RpcResponse.
+ * @internal
+ **/
+export declare const RPC_VERSION_V2 = 2;
 /**
  * @internal
  */
@@ -98,4 +128,4 @@ export declare function byteLength(str: string): number;
  * @internal
  */
 export declare function truncateBytes(str: string, maxBytes: number): string;
-//# sourceMappingURL=rpc.d.ts.map
+//# sourceMappingURL=utils.d.ts.map

package/dist/ts4.2/version.d.ts

@@ -1,3 +1,11 @@
 export declare const version: string;
 export declare const protocolVersion = 17;
+/** Initial client protocol. */
+export declare const CLIENT_PROTOCOL_DEFAULT = 0;
+/** Replaces RPC v1 protocol with a v2 data streams based one to support unlimited request /
+ * response payload length. */
+export declare const CLIENT_PROTOCOL_DATA_STREAM_RPC = 1;
+/** The client protocol version indicates what level of support that the client has for
+ * client <-> client api interactions. */
+export declare const clientProtocol = 1;
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.18.10",
+  "version": "2.19.0",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",

package/src/room/RTCEngine.ts

@@ -26,7 +26,6 @@ import {
   Room as RoomModel,
   RoomMovedResponse,
   RpcAck,
-  RpcResponse,
   ServerInfo,
   SessionDescription,
   SignalTarget,
@@ -79,7 +78,6 @@ import {
   UnexpectedConnectionState,
 } from './errors';
 import { EngineEvent } from './events';
-import { RpcError } from './rpc';
 import CriticalTimers from './timers';
 import type LocalTrack from './track/LocalTrack';
 import type LocalTrackPublication from './track/LocalTrackPublication';
@@ -1464,30 +1462,6 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     });
   };
 
-  /** @internal */
-  async publishRpcResponse(
-    destinationIdentity: string,
-    requestId: string,
-    payload: string | null,
-    error: RpcError | null,
-  ) {
-    const packet = new DataPacket({
-      destinationIdentities: [destinationIdentity],
-      kind: DataPacket_Kind.RELIABLE,
-      value: {
-        case: 'rpcResponse',
-        value: new RpcResponse({
-          requestId,
-          value: error
-            ? { case: 'error', value: error.toProto() }
-            : { case: 'payload', value: payload ?? '' },
-        }),
-      },
-    });
-
-    await this.sendDataPacket(packet, DataChannelKind.RELIABLE);
-  }
-
   /** @internal */
   async publishRpcAck(destinationIdentity: string, requestId: string) {
     const packet = new DataPacket({

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();
@@ -400,12 +431,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 +440,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);
   }
 
   /**
@@ -1873,7 +1899,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 +2043,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 +2136,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 +2481,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;