livekit-client 2.18.10 → 2.19.0

package/src/room/rpc/server/RpcServerManager.ts

@@ -0,0 +1,293 @@
+import { DataPacket, DataPacket_Kind, RpcAck, RpcRequest, RpcResponse } from '@livekit/protocol';
+import EventEmitter from 'events';
+import type TypedEmitter from 'typed-emitter';
+import { type StructuredLogger } from '../../../logger';
+import { CLIENT_PROTOCOL_DATA_STREAM_RPC } from '../../../version';
+import { type TextStreamReader } from '../../data-stream/incoming/StreamReader';
+import type OutgoingDataStreamManager from '../../data-stream/outgoing/OutgoingDataStreamManager';
+import type Participant from '../../participant/Participant';
+import {
+  MAX_V1_PAYLOAD_BYTES,
+  RPC_RESPONSE_DATA_STREAM_TOPIC,
+  RPC_VERSION_V2,
+  RpcError,
+  type RpcInvocationData,
+  RpcRequestAttrs,
+  byteLength,
+} from '../utils';
+import type { RpcServerManagerCallbacks } from './events';
+
+/**
+ * Manages the server (handler) side of RPC: processing incoming requests,
+ * managing registered method handlers, and sending responses.
+ * @internal
+ */
+export default class RpcServerManager extends (EventEmitter as new () => TypedEmitter<RpcServerManagerCallbacks>) {
+  private log: StructuredLogger;
+
+  private outgoingDataStreamManager: OutgoingDataStreamManager;
+
+  private getRemoteParticipantClientProtocol: (identity: Participant['identity']) => number;
+
+  private rpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>> = new Map();
+
+  constructor(
+    log: StructuredLogger,
+    outgoingDataStreamManager: OutgoingDataStreamManager,
+    getRemoteParticipantClientProtocol: (identity: Participant['identity']) => number,
+  ) {
+    super();
+    this.log = log;
+    this.outgoingDataStreamManager = outgoingDataStreamManager;
+    this.getRemoteParticipantClientProtocol = getRemoteParticipantClientProtocol;
+  }
+
+  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);
+  }
+
+  unregisterRpcMethod(method: string) {
+    this.rpcHandlers.delete(method);
+  }
+
+  /**
+   * Handle an incoming RPCRequest message containing a payload.
+   * This handles "version 1" of rpc requests.
+   * @internal
+   */
+  async handleIncomingRpcRequest(callerIdentity: string, rpcRequest: RpcRequest) {
+    this.publishRpcAck(callerIdentity, rpcRequest.id);
+
+    if (rpcRequest.version !== 1) {
+      this.publishRpcResponsePacket(
+        callerIdentity,
+        rpcRequest.id,
+        null,
+        RpcError.builtIn('UNSUPPORTED_VERSION'),
+      );
+      return;
+    }
+
+    const handler = this.rpcHandlers.get(rpcRequest.method);
+
+    if (!handler) {
+      this.publishRpcResponsePacket(
+        callerIdentity,
+        rpcRequest.id,
+        null,
+        RpcError.builtIn('UNSUPPORTED_METHOD'),
+      );
+      return;
+    }
+
+    let response;
+    try {
+      response = await handler({
+        requestId: rpcRequest.id,
+        callerIdentity,
+        payload: rpcRequest.payload,
+        responseTimeout: rpcRequest.responseTimeoutMs,
+      });
+    } catch (error) {
+      let responseError;
+      if (error instanceof RpcError) {
+        responseError = error;
+      } else {
+        this.log.warn(
+          `Uncaught error returned by RPC handler for ${rpcRequest.method}. Returning APPLICATION_ERROR instead.`,
+          error,
+        );
+        responseError = RpcError.builtIn(
+          'APPLICATION_ERROR',
+          `Uncaught error: ${(error as Error)?.message ?? error}`,
+          { cause: error },
+        );
+      }
+
+      this.publishRpcResponsePacket(callerIdentity, rpcRequest.id, null, responseError);
+      return;
+    }
+
+    await this.publishRpcResponse(callerIdentity, rpcRequest.id, response ?? '');
+  }
+
+  /**
+   * Handle an incoming data stream containing a RPC request payload.
+   * This handles "version 2" of rpc requests.
+   * @internal
+   */
+  async handleIncomingDataStream(
+    reader: TextStreamReader,
+    callerIdentity: Participant['identity'],
+    dataStreamAttrs: Record<string, string>,
+  ) {
+    const requestId = dataStreamAttrs[RpcRequestAttrs.RPC_REQUEST_ID];
+    const method = dataStreamAttrs[RpcRequestAttrs.RPC_REQUEST_METHOD];
+    const responseTimeout = parseInt(
+      dataStreamAttrs[RpcRequestAttrs.RPC_REQUEST_RESPONSE_TIMEOUT_MS],
+      10,
+    );
+    const version = parseInt(dataStreamAttrs[RpcRequestAttrs.RPC_REQUEST_VERSION], 10);
+
+    if (!requestId || !method || Number.isNaN(responseTimeout) || Number.isNaN(version)) {
+      this.log.warn(
+        `RPC data stream malformed: ${RpcRequestAttrs.RPC_REQUEST_ID} / ${RpcRequestAttrs.RPC_REQUEST_METHOD} / ${RpcRequestAttrs.RPC_REQUEST_RESPONSE_TIMEOUT_MS} / ${RpcRequestAttrs.RPC_REQUEST_VERSION} not set.`,
+      );
+      this.publishRpcResponsePacket(
+        callerIdentity,
+        requestId,
+        null,
+        RpcError.builtIn('APPLICATION_ERROR', 'RPC data stream malformed'),
+      );
+      return;
+    }
+
+    this.publishRpcAck(callerIdentity, requestId);
+
+    if (version !== RPC_VERSION_V2) {
+      this.publishRpcResponsePacket(
+        callerIdentity,
+        requestId,
+        null,
+        RpcError.builtIn('UNSUPPORTED_VERSION'),
+      );
+      return;
+    }
+
+    let payload: string;
+    try {
+      payload = await reader.readAll();
+    } catch (e) {
+      this.log.warn(`Error reading RPC request payload: ${e}`);
+      this.publishRpcResponsePacket(
+        callerIdentity,
+        requestId,
+        null,
+        RpcError.builtIn('APPLICATION_ERROR', 'Error reading RPC request payload', { cause: e }),
+      );
+      return;
+    }
+
+    const handler = this.rpcHandlers.get(method);
+
+    if (!handler) {
+      this.publishRpcResponsePacket(
+        callerIdentity,
+        requestId,
+        null,
+        RpcError.builtIn('UNSUPPORTED_METHOD'),
+      );
+      return;
+    }
+
+    let response;
+    try {
+      response = await handler({
+        requestId,
+        callerIdentity,
+        payload,
+        responseTimeout,
+      });
+    } catch (error) {
+      let responseError;
+      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');
+      }
+
+      this.publishRpcResponsePacket(callerIdentity, requestId, null, responseError);
+      return;
+    }
+
+    await this.publishRpcResponse(callerIdentity, requestId, response ?? '');
+  }
+
+  private publishRpcAck(destinationIdentity: string, requestId: string) {
+    this.emit('sendDataPacket', {
+      packet: new DataPacket({
+        destinationIdentities: [destinationIdentity],
+        kind: DataPacket_Kind.RELIABLE,
+        value: {
+          case: 'rpcAck',
+          value: new RpcAck({
+            requestId,
+          }),
+        },
+      }),
+    });
+  }
+
+  private publishRpcResponsePacket(
+    destinationIdentity: string,
+    requestId: string,
+    payload: string | null,
+    error: RpcError | null,
+  ) {
+    this.emit('sendDataPacket', {
+      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 ?? '' },
+          }),
+        },
+      }),
+    });
+  }
+
+  /**
+   * Send a successful RPC response payload, choosing the transport based on
+   * the caller's client protocol version.
+   */
+  private async publishRpcResponse(
+    destinationIdentity: string,
+    requestId: string,
+    payload: string,
+  ) {
+    const callerClientProtocol = this.getRemoteParticipantClientProtocol(destinationIdentity);
+
+    if (callerClientProtocol >= CLIENT_PROTOCOL_DATA_STREAM_RPC) {
+      // Send response as a data stream
+      const writer = await this.outgoingDataStreamManager.streamText({
+        topic: RPC_RESPONSE_DATA_STREAM_TOPIC,
+        destinationIdentities: [destinationIdentity],
+        attributes: { [RpcRequestAttrs.RPC_REQUEST_ID]: requestId },
+      });
+      await writer.write(payload);
+      await writer.close();
+      return;
+    }
+
+    // Legacy client: enforce size limit and send uncompressed payload inline
+    const responseBytes = byteLength(payload);
+    if (responseBytes > MAX_V1_PAYLOAD_BYTES) {
+      this.log.warn(
+        `RPC Response payload too large for request ${requestId}. To send larger responses, consider updating the sending client.`,
+      );
+      this.publishRpcResponsePacket(
+        destinationIdentity,
+        requestId,
+        null,
+        RpcError.builtIn('RESPONSE_PAYLOAD_TOO_LARGE'),
+      );
+      return;
+    }
+
+    this.publishRpcResponsePacket(destinationIdentity, requestId, payload, null);
+  }
+}

package/src/room/rpc/server/events.ts

@@ -0,0 +1,9 @@
+import type { DataPacket } from '@livekit/protocol';
+
+export type EventSendDataPacket = {
+  packet: DataPacket;
+};
+
+export type RpcServerManagerCallbacks = {
+  sendDataPacket: (event: EventSendDataPacket) => void;
+};

package/src/room/{rpc.ts → rpc/utils.ts}

@@ -1,6 +1,3 @@
-// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
-//
-// SPDX-License-Identifier: Apache-2.0
 import { RpcError as RpcError_Proto } from '@livekit/protocol';
 
 /** Parameters for initiating an RPC call */
@@ -63,6 +60,9 @@ export class RpcError extends Error {
 
   data?: string;
 
+  // More info: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+  cause?: unknown;
+
   /**
    * Creates an error object with the given code and message, plus an optional data payload.
    *
@@ -70,11 +70,15 @@ export 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 }) {
     super(message);
     this.code = code;
     this.message = truncateBytes(message, RpcError.MAX_MESSAGE_BYTES);
     this.data = data ? truncateBytes(data, RpcError.MAX_DATA_BYTES) : undefined;
+
+    if (typeof options?.cause !== 'undefined') {
+      this.cause = options?.cause;
+    }
   }
 
   /**
@@ -133,16 +137,53 @@ export class RpcError extends Error {
    *
    * @internal
    */
-  static builtIn(key: keyof typeof RpcError.ErrorCode, data?: string): RpcError {
-    return new RpcError(RpcError.ErrorCode[key], RpcError.ErrorMessage[key], data);
+  static builtIn(
+    key: keyof typeof RpcError.ErrorCode,
+    data?: string,
+    options?: { cause?: unknown },
+  ): RpcError {
+    return new RpcError(RpcError.ErrorCode[key], RpcError.ErrorMessage[key], data, options);
   }
 }
 
 /*
- * Maximum payload size for RPC requests and responses. If a payload exceeds this size,
+ * Maximum payload size for RPC requests and responses for clients with a clientProtocol of less
+ * than CLIENT_PROTOCOL_DATA_STREAM_RPC.
+ *
+ * If a payload exceeds this size and the remote client does not support compression,
  * the RPC call will fail with a REQUEST_PAYLOAD_TOO_LARGE(1402) or RESPONSE_PAYLOAD_TOO_LARGE(1504) error.
  */
-export const MAX_PAYLOAD_BYTES = 15360; // 15 KB
+export const MAX_V1_PAYLOAD_BYTES = 15360; // 15 KB
+
+/**
+ * Topic used for v2 RPC request data streams.
+ * @internal
+ */
+export const RPC_REQUEST_DATA_STREAM_TOPIC = 'lk.rpc_request';
+
+/**
+ * Topic used for v2 RPC response data streams.
+ * @internal
+ */
+export const RPC_RESPONSE_DATA_STREAM_TOPIC = 'lk.rpc_response';
+
+/** @internal */
+export 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 const RPC_VERSION_V1 = 1;
+
+/** Rpc version backed by data streams instead of RpcRequest / RpcResponse.
+ * @internal
+ **/
+export const RPC_VERSION_V2 = 2;
 
 /**
  * @internal

package/src/room/utils.ts

@@ -10,7 +10,7 @@ import { type Throws } from '@livekit/throws-transformer/throws';
 import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import type { BrowserDetails } from '../utils/browserParser';
-import { protocolVersion, version } from '../version';
+import { clientProtocol, protocolVersion, version } from '../version';
 import { type ConnectionError, ConnectionErrorReason } from './errors';
 import type LocalParticipant from './participant/LocalParticipant';
 import type Participant from './participant/Participant';
@@ -382,6 +382,7 @@ export function getClientInfo(capabilities?: ClientInfo_Capability[]): ClientInf
     capabilities,
     sdk: ClientInfo_SDK.JS,
     protocol: protocolVersion,
+    clientProtocol,
     version,
   });
 

package/src/version.ts

@@ -2,3 +2,13 @@ import { version as v } from '../package.json';
 
 export const version = v;
 export const protocolVersion = 17;
+
+/** Initial client protocol. */
+export const CLIENT_PROTOCOL_DEFAULT = 0;
+/** Replaces RPC v1 protocol with a v2 data streams based one to support unlimited request /
+ * response payload length. */
+export 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 const clientProtocol = CLIENT_PROTOCOL_DATA_STREAM_RPC;

package/dist/src/room/rpc.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../../src/room/rpc.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE/D,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AAEH,qBAAa,QAAS,SAAQ,KAAK;IACjC,MAAM,CAAC,iBAAiB,SAAO;IAE/B,MAAM,CAAC,cAAc,SAAS;IAE9B,IAAI,EAAE,MAAM,CAAC;IAEb,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;IAOxD;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc;IAItC;;OAEG;IACH,OAAO;IAQP,MAAM,CAAC,SAAS;;;;;;;;;;;;MAaL;IAEX;;OAEG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,OAAO,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAazD;IAEX;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,OAAO,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ;CAG9E;AAMD,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmBnE"}