livekit-client 2.5.10 → 2.6.1

package/src/room/participant/LocalParticipant.test.ts

@@ -0,0 +1,304 @@
+import { DataPacket, DataPacket_Kind } from '@livekit/protocol';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { InternalRoomOptions } from '../../options';
+import type RTCEngine from '../RTCEngine';
+import { RpcError } from '../rpc';
+import LocalParticipant from './LocalParticipant';
+import { ParticipantKind } from './Participant';
+import RemoteParticipant from './RemoteParticipant';
+
+describe('LocalParticipant', () => {
+  describe('registerRpcMethod', () => {
+    let localParticipant: LocalParticipant;
+    let mockEngine: RTCEngine;
+    let mockRoomOptions: InternalRoomOptions;
+    let mockSendDataPacket: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      mockSendDataPacket = vi.fn();
+      mockEngine = {
+        client: {
+          sendUpdateLocalMetadata: vi.fn(),
+        },
+        on: vi.fn().mockReturnThis(),
+        sendDataPacket: mockSendDataPacket,
+      } as unknown as RTCEngine;
+
+      mockRoomOptions = {} as InternalRoomOptions;
+
+      localParticipant = new LocalParticipant(
+        'test-sid',
+        'test-identity',
+        mockEngine,
+        mockRoomOptions,
+      );
+    });
+
+    it('should register an RPC method handler', async () => {
+      const methodName = 'testMethod';
+      const handler = vi.fn().mockResolvedValue('test response');
+
+      localParticipant.registerRpcMethod(methodName, handler);
+
+      const mockCaller = new RemoteParticipant(
+        {} as any,
+        'remote-sid',
+        'remote-identity',
+        'Remote Participant',
+        '',
+        undefined,
+        ParticipantKind.STANDARD,
+      );
+
+      await localParticipant.handleIncomingRpcRequest(
+        mockCaller.identity,
+        'test-request-id',
+        methodName,
+        'test payload',
+        5000,
+        1,
+      );
+
+      expect(handler).toHaveBeenCalledWith({
+        requestId: 'test-request-id',
+        callerIdentity: mockCaller.identity,
+        payload: 'test payload',
+        responseTimeout: 5000,
+      });
+
+      // Check if sendDataPacket was called twice (once for ACK and once for response)
+      expect(mockSendDataPacket).toHaveBeenCalledTimes(2);
+
+      // Check if the first call was for ACK
+      expect(mockSendDataPacket.mock.calls[0][0].value.case).toBe('rpcAck');
+      expect(mockSendDataPacket.mock.calls[0][1]).toBe(DataPacket_Kind.RELIABLE);
+
+      // Check if the second call was for response
+      expect(mockSendDataPacket.mock.calls[1][0].value.case).toBe('rpcResponse');
+      expect(mockSendDataPacket.mock.calls[1][1]).toBe(DataPacket_Kind.RELIABLE);
+    });
+
+    it('should catch and transform unhandled errors in the RPC method handler', async () => {
+      const methodName = 'errorMethod';
+      const errorMessage = 'Test error';
+      const handler = vi.fn().mockRejectedValue(new Error(errorMessage));
+
+      localParticipant.registerRpcMethod(methodName, handler);
+
+      const mockCaller = new RemoteParticipant(
+        {} as any,
+        'remote-sid',
+        'remote-identity',
+        'Remote Participant',
+        '',
+        undefined,
+        ParticipantKind.STANDARD,
+      );
+
+      await localParticipant.handleIncomingRpcRequest(
+        mockCaller.identity,
+        'test-error-request-id',
+        methodName,
+        'test payload',
+        5000,
+        1,
+      );
+
+      expect(handler).toHaveBeenCalledWith({
+        requestId: 'test-error-request-id',
+        callerIdentity: mockCaller.identity,
+        payload: 'test payload',
+        responseTimeout: 5000,
+      });
+
+      // Check if sendDataPacket was called twice (once for ACK and once for error response)
+      expect(mockSendDataPacket).toHaveBeenCalledTimes(2);
+
+      // Check if the second call was for error response
+      const errorResponse = mockSendDataPacket.mock.calls[1][0].value.value.value.value;
+      expect(errorResponse.code).toBe(RpcError.ErrorCode.APPLICATION_ERROR);
+    });
+
+    it('should pass through RpcError thrown by the RPC method handler', async () => {
+      const methodName = 'rpcErrorMethod';
+      const errorCode = 101;
+      const errorMessage = 'some-error-message';
+      const handler = vi.fn().mockRejectedValue(new RpcError(errorCode, errorMessage));
+
+      localParticipant.registerRpcMethod(methodName, handler);
+
+      const mockCaller = new RemoteParticipant(
+        {} as any,
+        'remote-sid',
+        'remote-identity',
+        'Remote Participant',
+        '',
+        undefined,
+        ParticipantKind.STANDARD,
+      );
+
+      await localParticipant.handleIncomingRpcRequest(
+        mockCaller.identity,
+        'test-rpc-error-request-id',
+        methodName,
+        'test payload',
+        5000,
+        1,
+      );
+
+      expect(handler).toHaveBeenCalledWith({
+        requestId: 'test-rpc-error-request-id',
+        callerIdentity: mockCaller.identity,
+        payload: 'test payload',
+        responseTimeout: 5000,
+      });
+
+      // Check if sendDataPacket was called twice (once for ACK and once for error response)
+      expect(mockSendDataPacket).toHaveBeenCalledTimes(2);
+
+      // Check if the second call was for error response
+      const errorResponse = mockSendDataPacket.mock.calls[1][0].value.value.value.value;
+      expect(errorResponse.code).toBe(errorCode);
+      expect(errorResponse.message).toBe(errorMessage);
+    });
+  });
+
+  describe('performRpc', () => {
+    let localParticipant: LocalParticipant;
+    let mockRemoteParticipant: RemoteParticipant;
+    let mockEngine: RTCEngine;
+    let mockRoomOptions: InternalRoomOptions;
+    let mockSendDataPacket: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      mockSendDataPacket = vi.fn();
+      mockEngine = {
+        client: {
+          sendUpdateLocalMetadata: vi.fn(),
+        },
+        on: vi.fn().mockReturnThis(),
+        sendDataPacket: mockSendDataPacket,
+      } as unknown as RTCEngine;
+
+      mockRoomOptions = {} as InternalRoomOptions;
+
+      localParticipant = new LocalParticipant(
+        'local-sid',
+        'local-identity',
+        mockEngine,
+        mockRoomOptions,
+      );
+
+      mockRemoteParticipant = new RemoteParticipant(
+        {} as any,
+        'remote-sid',
+        'remote-identity',
+        'Remote Participant',
+        '',
+        undefined,
+        ParticipantKind.STANDARD,
+      );
+    });
+
+    it('should send RPC request and receive successful response', async () => {
+      const method = 'testMethod';
+      const payload = 'testPayload';
+      const responsePayload = 'responsePayload';
+
+      mockSendDataPacket.mockImplementationOnce((packet: DataPacket) => {
+        const requestId = packet.value.value.id;
+        setTimeout(() => {
+          localParticipant.handleIncomingRpcAck(requestId);
+          setTimeout(() => {
+            localParticipant.handleIncomingRpcResponse(requestId, responsePayload, null);
+          }, 10);
+        }, 10);
+      });
+
+      const result = await localParticipant.performRpc({
+        destinationIdentity: mockRemoteParticipant.identity,
+        method,
+        payload,
+      });
+
+      expect(mockSendDataPacket).toHaveBeenCalledTimes(1);
+      expect(result).toBe(responsePayload);
+    });
+
+    it('should handle RPC request timeout', async () => {
+      const method = 'timeoutMethod';
+      const payload = 'timeoutPayload';
+
+      const timeout = 50;
+
+      const resultPromise = localParticipant.performRpc({
+        destinationIdentity: mockRemoteParticipant.identity,
+        method,
+        payload,
+        responseTimeout: timeout,
+      });
+
+      mockSendDataPacket.mockImplementationOnce(() => {
+        return new Promise((resolve) => {
+          setTimeout(resolve, timeout + 10);
+        });
+      });
+
+      const startTime = Date.now();
+
+      await expect(resultPromise).rejects.toThrow('Response timeout');
+
+      const elapsedTime = Date.now() - startTime;
+      expect(elapsedTime).toBeGreaterThanOrEqual(timeout);
+      expect(elapsedTime).toBeLessThan(timeout + 50); // Allow some margin for test execution
+
+      expect(mockSendDataPacket).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle RPC error response', async () => {
+      const method = 'errorMethod';
+      const payload = 'errorPayload';
+      const errorCode = 101;
+      const errorMessage = 'Test error message';
+
+      mockSendDataPacket.mockImplementationOnce((packet: DataPacket) => {
+        const requestId = packet.value.value.id;
+        setTimeout(() => {
+          localParticipant.handleIncomingRpcAck(requestId);
+          localParticipant.handleIncomingRpcResponse(
+            requestId,
+            null,
+            new RpcError(errorCode, errorMessage),
+          );
+        }, 10);
+      });
+
+      await expect(
+        localParticipant.performRpc({
+          destinationIdentity: mockRemoteParticipant.identity,
+          method,
+          payload,
+        }),
+      ).rejects.toThrow(errorMessage);
+    });
+
+    it('should handle participant disconnection during RPC request', async () => {
+      const method = 'disconnectMethod';
+      const payload = 'disconnectPayload';
+
+      mockSendDataPacket.mockImplementationOnce(() => Promise.resolve());
+
+      const resultPromise = localParticipant.performRpc({
+        destinationIdentity: mockRemoteParticipant.identity,
+        method,
+        payload,
+      });
+
+      // Simulate a small delay before disconnection
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      localParticipant.handleParticipantDisconnected(mockRemoteParticipant.identity);
+
+      await expect(resultPromise).rejects.toThrow('Recipient disconnected');
+    });
+  });
+});

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(