livekit-client 2.5.9 → 2.6.0

package/src/room/participant/LocalParticipant.ts

@@ -9,6 +9,9 @@ import {
   ParticipantPermission,
   RequestResponse,
   RequestResponse_Reason,
+  RpcAck,
+  RpcRequest,
+  RpcResponse,
   SimulcastCodec,
   SipDTMF,
   SubscribedQualityUpdate,
@@ -29,6 +32,13 @@ import {
   UnexpectedConnectionState,
 } from '../errors';
 import { EngineEvent, ParticipantEvent, TrackEvent } from '../events';
+import {
+  MAX_PAYLOAD_BYTES,
+  type PerformRpcParams,
+  RpcError,
+  type RpcInvocationData,
+  byteLength,
+} from '../rpc';
 import LocalAudioTrack from '../track/LocalAudioTrack';
 import LocalTrack from '../track/LocalTrack';
 import LocalTrackPublication from '../track/LocalTrackPublication';
@@ -54,6 +64,7 @@ import {
 import type { ChatMessage, DataPublishOptions } from '../types';
 import {
   Future,
+  compareVersions,
   isE2EESimulcastSupported,
   isFireFox,
   isSVCCodec,
@@ -119,6 +130,18 @@ export default class LocalParticipant extends Participant {
 
   private enabledPublishVideoCodecs: Codec[] = [];
 
+  private rpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>> = new Map();
+
+  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) {
     super(sid, identity, undefined, undefined, {
@@ -187,7 +210,8 @@ export default class LocalParticipant extends Participant {
       .on(EngineEvent.LocalTrackUnpublished, this.handleLocalTrackUnpublished)
       .on(EngineEvent.SubscribedQualityUpdate, this.handleSubscribedQualityUpdate)
       .on(EngineEvent.Disconnected, this.handleDisconnected)
-      .on(EngineEvent.SignalRequestResponse, this.handleSignalRequestResponse);
+      .on(EngineEvent.SignalRequestResponse, this.handleSignalRequestResponse)
+      .on(EngineEvent.DataPacketReceived, this.handleDataPacket);
   }
 
   private handleReconnecting = () => {
@@ -221,6 +245,38 @@ export default class LocalParticipant extends Participant {
     }
   };
 
+  private handleDataPacket = (packet: DataPacket) => {
+    switch (packet.value.case) {
+      case 'rpcRequest':
+        let rpcRequest = packet.value.value as RpcRequest;
+        this.handleIncomingRpcRequest(
+          packet.participantIdentity,
+          rpcRequest.id,
+          rpcRequest.method,
+          rpcRequest.payload,
+          rpcRequest.responseTimeoutMs,
+          rpcRequest.version,
+        );
+        break;
+      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.
@@ -1415,6 +1471,121 @@ export default class LocalParticipant extends Participant {
     return msg;
   }
 
+  /**
+   * Initiate an RPC call to a remote participant
+   * @param params - Parameters for initiating the RPC call, see {@link PerformRpcParams}
+   * @returns A promise that resolves with the response payload or rejects with an error.
+   * @throws Error on failure. Details in `message`.
+   */
+  async performRpc({
+    destinationIdentity,
+    method,
+    payload,
+    responseTimeout = 10000,
+  }: PerformRpcParams): Promise<string> {
+    const maxRoundTripLatency = 2000;
+
+    return new Promise(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 id = crypto.randomUUID();
+      await this.publishRpcRequest(
+        destinationIdentity,
+        id,
+        method,
+        payload,
+        responseTimeout - maxRoundTripLatency,
+      );
+
+      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)) {
+            console.warn('RPC response received before ack', id);
+            this.pendingAcks.delete(id);
+            clearTimeout(ackTimeoutId);
+          }
+
+          if (responseError) {
+            reject(responseError);
+          } else {
+            resolve(responsePayload ?? '');
+          }
+        },
+        participantIdentity: destinationIdentity,
+      });
+    });
+  }
+
+  /**
+   * Establishes the participant as a receiver for calls of the specified RPC method.
+   * Will overwrite any existing callback for the same method.
+   *
+   * @param method - The name of the indicated RPC method
+   * @param handler - Will be invoked when an RPC request for this method is received
+   * @returns A promise that resolves when the method is successfully registered
+   *
+   * @example
+   * ```typescript
+   * room.localParticipant?.registerRpcMethod(
+   *   'greet',
+   *   async (data: RpcInvocationData) => {
+   *     console.log(`Received greeting from ${data.callerIdentity}: ${data.payload}`);
+   *     return `Hello, ${data.callerIdentity}!`;
+   *   }
+   * );
+   * ```
+   *
+   * The handler should return a Promise that resolves to a string.
+   * If unable to respond within `responseTimeout`, the request will result in an error on the caller's side.
+   *
+   * You may throw errors of type `RpcError` with a string `message` in the handler,
+   * and they will be received on the caller's side with the message intact.
+   * 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>) {
+    this.rpcHandlers.set(method, handler);
+  }
+
+  /**
+   * Unregisters a previously registered RPC method.
+   *
+   * @param method - The name of the RPC method to unregister
+   */
+  unregisterRpcMethod(method: string) {
+    this.rpcHandlers.delete(method);
+  }
+
   /**
    * Control who can subscribe to LocalParticipant's published tracks.
    *
@@ -1443,6 +1614,174 @@ 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);
+    }
+  }
+
+  private async handleIncomingRpcRequest(
+    callerIdentity: string,
+    requestId: string,
+    method: string,
+    payload: string,
+    responseTimeout: number,
+    version: number,
+  ) {
+    await this.publishRpcAck(callerIdentity, requestId);
+
+    if (version !== 1) {
+      await this.publishRpcResponse(
+        callerIdentity,
+        requestId,
+        null,
+        RpcError.builtIn('UNSUPPORTED_VERSION'),
+      );
+      return;
+    }
+
+    const handler = this.rpcHandlers.get(method);
+
+    if (!handler) {
+      await this.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');
+        console.warn(`RPC Response payload too large for ${method}`);
+      } else {
+        responsePayload = response;
+      }
+    } catch (error) {
+      if (error instanceof RpcError) {
+        responseError = error;
+      } else {
+        console.warn(
+          `Uncaught error returned by RPC handler for ${method}. Returning APPLICATION_ERROR instead.`,
+          error,
+        );
+        responseError = RpcError.builtIn('APPLICATION_ERROR');
+      }
+    }
+    await this.publishRpcResponse(callerIdentity, requestId, responsePayload, responseError);
+  }
+
+  /** @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, DataPacket_Kind.RELIABLE);
+  }
+
+  /** @internal */
+  private 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.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+  }
+
+  /** @internal */
+  private async publishRpcAck(destinationIdentity: string, requestId: string) {
+    const packet = new DataPacket({
+      destinationIdentities: [destinationIdentity],
+      kind: DataPacket_Kind.RELIABLE,
+      value: {
+        case: 'rpcAck',
+        value: new RpcAck({
+          requestId,
+        }),
+      },
+    });
+
+    await this.engine.sendDataPacket(packet, DataPacket_Kind.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/rpc.ts

@@ -0,0 +1,172 @@
+// 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 */
+export interface PerformRpcParams {
+  /** The `identity` of the destination participant */
+  destinationIdentity: string;
+  /** The method name to call */
+  method: string;
+  /** The method payload */
+  payload: string;
+  /** Timeout for receiving a response after initial connection (milliseconds). Default: 10000 */
+  responseTimeout?: number;
+}
+
+/**
+ * Data passed to method handler for incoming RPC invocations
+ */
+export interface RpcInvocationData {
+  /**
+   * The unique request ID. Will match at both sides of the call, useful for debugging or logging.
+   */
+  requestId: string;
+
+  /**
+   * The unique participant identity of the caller.
+   */
+  callerIdentity: string;
+
+  /**
+   * The payload of the request. User-definable format, typically JSON.
+   */
+  payload: string;
+
+  /**
+   * The maximum time the caller will wait for a response.
+   */
+  responseTimeout: number;
+}
+
+/**
+ * Specialized error handling for RPC methods.
+ *
+ * Instances of this type, when thrown in a method handler, will have their `message`
+ * serialized and sent across the wire. The sender will receive an equivalent error on the other side.
+ *
+ * Built-in types are included but developers may use any string, with a max length of 256 bytes.
+ */
+
+export class RpcError extends Error {
+  static MAX_MESSAGE_BYTES = 256;
+
+  static MAX_DATA_BYTES = 15360; // 15 KB
+
+  code: number;
+
+  data?: string;
+
+  /**
+   * Creates an error object with the given code and message, plus an optional data payload.
+   *
+   * If thrown in an RPC method handler, the error will be sent back to the caller.
+   *
+   * Error codes 1001-1999 are reserved for built-in errors (see RpcError.ErrorCode for their meanings).
+   */
+  constructor(code: number, message: string, data?: string) {
+    super(message);
+    this.code = code;
+    this.message = truncateBytes(message, RpcError.MAX_MESSAGE_BYTES);
+    this.data = data ? truncateBytes(data, RpcError.MAX_DATA_BYTES) : undefined;
+  }
+
+  /**
+   * @internal
+   */
+  static fromProto(proto: RpcError_Proto) {
+    return new RpcError(proto.code, proto.message, proto.data);
+  }
+
+  /**
+   * @internal
+   */
+  toProto() {
+    return new RpcError_Proto({
+      code: this.code as number,
+      message: this.message,
+      data: this.data,
+    });
+  }
+
+  static ErrorCode = {
+    APPLICATION_ERROR: 1500,
+    CONNECTION_TIMEOUT: 1501,
+    RESPONSE_TIMEOUT: 1502,
+    RECIPIENT_DISCONNECTED: 1503,
+    RESPONSE_PAYLOAD_TOO_LARGE: 1504,
+    SEND_FAILED: 1505,
+
+    UNSUPPORTED_METHOD: 1400,
+    RECIPIENT_NOT_FOUND: 1401,
+    REQUEST_PAYLOAD_TOO_LARGE: 1402,
+    UNSUPPORTED_SERVER: 1403,
+    UNSUPPORTED_VERSION: 1404,
+  } as const;
+
+  /**
+   * @internal
+   */
+  static ErrorMessage: Record<keyof typeof RpcError.ErrorCode, string> = {
+    APPLICATION_ERROR: 'Application error in method handler',
+    CONNECTION_TIMEOUT: 'Connection timeout',
+    RESPONSE_TIMEOUT: 'Response timeout',
+    RECIPIENT_DISCONNECTED: 'Recipient disconnected',
+    RESPONSE_PAYLOAD_TOO_LARGE: 'Response payload too large',
+    SEND_FAILED: 'Failed to send',
+
+    UNSUPPORTED_METHOD: 'Method not supported at destination',
+    RECIPIENT_NOT_FOUND: 'Recipient not found',
+    REQUEST_PAYLOAD_TOO_LARGE: 'Request payload too large',
+    UNSUPPORTED_SERVER: 'RPC not supported by server',
+    UNSUPPORTED_VERSION: 'Unsupported RPC version',
+  } as const;
+
+  /**
+   * Creates an error object from the code, with an auto-populated message.
+   *
+   * @internal
+   */
+  static builtIn(key: keyof typeof RpcError.ErrorCode, data?: string): RpcError {
+    return new RpcError(RpcError.ErrorCode[key], RpcError.ErrorMessage[key], data);
+  }
+}
+
+/*
+ * Maximum payload size for RPC requests and responses. If a payload exceeds this size,
+ * 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
+
+/**
+ * @internal
+ */
+export function byteLength(str: string): number {
+  const encoder = new TextEncoder();
+  return encoder.encode(str).length;
+}
+
+/**
+ * @internal
+ */
+export function truncateBytes(str: string, maxBytes: number): string {
+  if (byteLength(str) <= maxBytes) {
+    return str;
+  }
+
+  let low = 0;
+  let high = str.length;
+  const encoder = new TextEncoder();
+
+  while (low < high) {
+    const mid = Math.floor((low + high + 1) / 2);
+    if (encoder.encode(str.slice(0, mid)).length <= maxBytes) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return str.slice(0, low);
+}

package/src/room/track/LocalTrack.ts

@@ -1,10 +1,11 @@
+import { Mutex } from '@livekit/mutex';
 import { debounce } from 'ts-debounce';
 import { getBrowser } from '../../utils/browserParser';
 import DeviceManager from '../DeviceManager';
 import { DeviceUnsupportedError, TrackInvalidError } from '../errors';
 import { TrackEvent } from '../events';
 import type { LoggerOptions } from '../types';
-import { Mutex, compareVersions, isMobile, sleep } from '../utils';
+import { compareVersions, isMobile, sleep } from '../utils';
 import { Track, attachToElement, detachTrack } from './Track';
 import type { VideoCodec } from './options';
 import type { TrackProcessor } from './processor/types';

package/src/room/track/LocalVideoTrack.ts

@@ -1,3 +1,4 @@
+import { Mutex } from '@livekit/mutex';
 import {
   VideoQuality as ProtoVideoQuality,
   SubscribedCodec,
@@ -10,7 +11,7 @@ import { ScalabilityMode } from '../participant/publishUtils';
 import type { VideoSenderStats } from '../stats';
 import { computeBitrate, monitorFrequency } from '../stats';
 import type { LoggerOptions } from '../types';
-import { Mutex, isFireFox, isMobile, isWeb, unwrapConstraint } from '../utils';
+import { isFireFox, isMobile, isWeb, unwrapConstraint } from '../utils';
 import LocalTrack from './LocalTrack';
 import { Track, VideoQuality } from './Track';
 import type { VideoCaptureOptions, VideoCodec } from './options';

package/src/room/track/options.ts

@@ -398,19 +398,19 @@ export namespace AudioPresets {
     maxBitrate: 12_000,
   };
   export const speech: AudioPreset = {
-    maxBitrate: 20_000,
+    maxBitrate: 24_000,
   };
   export const music: AudioPreset = {
-    maxBitrate: 32_000,
+    maxBitrate: 48_000,
   };
   export const musicStereo: AudioPreset = {
-    maxBitrate: 48_000,
+    maxBitrate: 64_000,
   };
   export const musicHighQuality: AudioPreset = {
-    maxBitrate: 64_000,
+    maxBitrate: 96_000,
   };
   export const musicHighQualityStereo: AudioPreset = {
-    maxBitrate: 96_000,
+    maxBitrate: 128_000,
   };
 }
 

package/src/room/track/utils.ts

@@ -9,7 +9,6 @@ import {
   type ScreenShareCaptureOptions,
   type VideoCaptureOptions,
   type VideoCodec,
-  videoCodecs,
 } from './options';
 import type { AudioTrack } from './types';
 
@@ -188,11 +187,7 @@ export function screenCaptureToDisplayMediaStreamOptions(
 }
 
 export function mimeTypeToVideoCodecString(mimeType: string) {
-  const codec = mimeType.split('/')[1].toLowerCase() as VideoCodec;
-  if (!videoCodecs.includes(codec)) {
-    throw Error(`Video codec not supported: ${codec}`);
-  }
-  return codec;
+  return mimeType.split('/')[1].toLowerCase() as VideoCodec;
 }
 
 export function getTrackPublicationInfo<T extends TrackPublication>(

package/src/room/utils.ts

@@ -454,44 +454,6 @@ export function createAudioAnalyser(
   return { calculateVolume, analyser, cleanup };
 }
 
-/**
- * @internal
- */
-export class Mutex {
-  private _locking: Promise<void>;
-
-  private _locks: number;
-
-  constructor() {
-    this._locking = Promise.resolve();
-    this._locks = 0;
-  }
-
-  isLocked() {
-    return this._locks > 0;
-  }
-
-  lock() {
-    this._locks += 1;
-
-    let unlockNext: () => void;
-
-    const willLock = new Promise<void>(
-      (resolve) =>
-        (unlockNext = () => {
-          this._locks -= 1;
-          resolve();
-        }),
-    );
-
-    const willUnlock = this._locking.then(() => unlockNext);
-
-    this._locking = this._locking.then(() => willLock);
-
-    return willUnlock;
-  }
-}
-
 export function isVideoCodec(maybeCodec: string): maybeCodec is VideoCodec {
   return videoCodecs.includes(maybeCodec as VideoCodec);
 }

package/src/utils/AsyncQueue.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { assert, describe, expect, it } from 'vitest';
 import { sleep } from '../room/utils';
 import { AsyncQueue } from './AsyncQueue';
 
@@ -49,7 +49,7 @@ describe('asyncQueue', () => {
         task2Executed = true;
       })
       .catch(() => {
-        fail('task 2 should not have thrown');
+        assert.fail('task 2 should not have thrown');
       });
 
     expect(task1threw).toBeTruthy();

package/src/utils/AsyncQueue.ts

@@ -1,4 +1,4 @@
-import { Mutex } from '../room/utils';
+import { Mutex } from '@livekit/mutex';
 
 type QueueTask<T> = () => PromiseLike<T>;