@livekit/rtc-node 0.10.3 → 0.11.0

package/src/participant.ts

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import { create } from '@bufbuild/protobuf';
 import { FfiClient, FfiHandle } from './ffi_client.js';
 import type { OwnedParticipant, ParticipantInfo, ParticipantKind } from './proto/participant_pb.js';
-import {
-  ChatMessage as ChatMessageModel,
+import type {
   PublishDataCallback,
   PublishDataResponse,
   PublishSipDtmfCallback,
@@ -26,23 +26,38 @@ import {
   UnpublishTrackResponse,
 } from './proto/room_pb.js';
 import {
-  EditChatMessageRequest,
-  TranscriptionSegment as ProtoTranscriptionSegment,
-  PublishDataRequest,
-  PublishSipDtmfRequest,
-  PublishTrackRequest,
-  PublishTranscriptionRequest,
-  SendChatMessageRequest,
-  SetLocalAttributesRequest,
-  SetLocalMetadataRequest,
-  SetLocalNameRequest,
-  UnpublishTrackRequest,
+  ChatMessageSchema,
+  EditChatMessageRequestSchema,
+  PublishDataRequestSchema,
+  PublishSipDtmfRequestSchema,
+  PublishTrackRequestSchema,
+  PublishTranscriptionRequestSchema,
+  SendChatMessageRequestSchema,
+  SetLocalAttributesRequestSchema,
+  SetLocalMetadataRequestSchema,
+  SetLocalNameRequestSchema,
+  UnpublishTrackRequestSchema,
 } from './proto/room_pb.js';
+import { TranscriptionSegmentSchema } from './proto/room_pb.js';
+import {
+  PerformRpcRequestSchema,
+  RegisterRpcMethodRequestSchema,
+  RpcMethodInvocationResponseRequestSchema,
+  UnregisterRpcMethodRequestSchema,
+} from './proto/rpc_pb.js';
+import type {
+  PerformRpcCallback,
+  PerformRpcResponse,
+  RegisterRpcMethodResponse,
+  RpcMethodInvocationResponseResponse,
+  UnregisterRpcMethodResponse,
+} from './proto/rpc_pb.js';
+import { type PerformRpcParams, RpcError, type RpcInvocationData } from './rpc.js';
 import type { LocalTrack } from './track.js';
 import type { RemoteTrackPublication, TrackPublication } from './track_publication.js';
 import { LocalTrackPublication } from './track_publication.js';
 import type { Transcription } from './transcription.js';
-import { ChatMessage } from './types.js';
+import type { ChatMessage } from './types.js';
 
 export abstract class Participant {
   /** @internal */
@@ -54,8 +69,8 @@ export abstract class Participant {
   trackPublications = new Map<string, TrackPublication>();
 
   constructor(owned_info: OwnedParticipant) {
-    this.info = owned_info.info;
-    this.ffi_handle = new FfiHandle(owned_info.handle.id);
+    this.info = owned_info.info!;
+    this.ffi_handle = new FfiHandle(owned_info.handle!.id);
   }
 
   get sid(): string {
@@ -100,10 +115,12 @@ export type DataPublishOptions = {
 };
 
 export class LocalParticipant extends Participant {
+  private rpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>> = new Map();
+
   trackPublications: Map<string, LocalTrackPublication> = new Map();
 
   async publishData(data: Uint8Array, options: DataPublishOptions) {
-    const req = new PublishDataRequest({
+    const req = create(PublishDataRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       dataPtr: FfiClient.instance.retrievePtr(data),
       dataLen: BigInt(data.byteLength),
@@ -126,7 +143,7 @@ export class LocalParticipant extends Participant {
   }
 
   async publishDtmf(code: number, digit: string) {
-    const req = new PublishSipDtmfRequest({
+    const req = create(PublishSipDtmfRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       code,
       digit,
@@ -146,19 +163,18 @@ export class LocalParticipant extends Participant {
   }
 
   async publishTranscription(transcription: Transcription) {
-    const req = new PublishTranscriptionRequest({
+    const req = create(PublishTranscriptionRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       participantIdentity: transcription.participantIdentity,
-      segments: transcription.segments.map(
-        (s) =>
-          new ProtoTranscriptionSegment({
-            id: s.id,
-            text: s.text,
-            startTime: s.startTime,
-            endTime: s.endTime,
-            final: s.final,
-            language: s.language,
-          }),
+      segments: transcription.segments.map((s) =>
+        create(TranscriptionSegmentSchema, {
+          id: s.id,
+          text: s.text,
+          startTime: s.startTime,
+          endTime: s.endTime,
+          final: s.final,
+          language: s.language,
+        }),
       ),
       trackId: transcription.trackSid,
     });
@@ -177,7 +193,7 @@ export class LocalParticipant extends Participant {
   }
 
   async updateMetadata(metadata: string) {
-    const req = new SetLocalMetadataRequest({
+    const req = create(SetLocalMetadataRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       metadata: metadata,
     });
@@ -192,6 +208,11 @@ export class LocalParticipant extends Participant {
   }
 
   /**
+   * Sends a chat message to participants in the room
+   *
+   * @param text - The text content of the chat message.
+   * @param destinationIdentities - An optional array of recipient identities to whom the message will be sent. If omitted, the message is broadcast to all participants.
+   * @param senderIdentity - An optional identity of the sender. If omitted, the default sender identity is used.
    *
    */
   async sendChatMessage(
@@ -199,7 +220,7 @@ export class LocalParticipant extends Participant {
     destinationIdentities?: Array<string>,
     senderIdentity?: string,
   ): Promise<ChatMessage> {
-    const req = new SendChatMessageRequest({
+    const req = create(SendChatMessageRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       message: text,
       destinationIdentities,
@@ -214,20 +235,15 @@ export class LocalParticipant extends Participant {
       return ev.message.case == 'chatMessage' && ev.message.value.asyncId == res.asyncId;
     });
 
-    if (cb.error) {
-      throw new Error(cb.error);
+    if (cb.message.case !== 'chatMessage') {
+      throw new Error(cb.message.value ?? 'Unknown Error');
     }
-    const { id, timestamp, editTimestamp, message } = cb.chatMessage;
+    const { id, timestamp, editTimestamp, message } = cb.message.value;
     return { id, timestamp: Number(timestamp), editTimestamp: Number(editTimestamp), message };
   }
 
   /**
-   * Sends a chat message to participants in the room
-   *
-   * @param text - The text content of the chat message.
-   * @param destinationIdentities - An optional array of recipient identities to whom the message will be sent. If omitted, the message is broadcast to all participants.
-   * @param senderIdentity - An optional identity of the sender. If omitted, the default sender identity is used.
-   *
+   * @experimental
    */
   async editChatMessage(
     editText: string,
@@ -235,13 +251,15 @@ export class LocalParticipant extends Participant {
     destinationIdentities?: Array<string>,
     senderIdentity?: string,
   ): Promise<ChatMessage> {
-    const req = new EditChatMessageRequest({
+    const req = create(EditChatMessageRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       editText,
-      originalMessage: new ChatMessageModel({
+      originalMessage: create(ChatMessageSchema, {
         ...originalMessage,
         timestamp: BigInt(originalMessage.timestamp),
-        editTimestamp: BigInt(originalMessage.editTimestamp),
+        editTimestamp: originalMessage.editTimestamp
+          ? BigInt(originalMessage.editTimestamp)
+          : undefined,
       }),
       destinationIdentities,
       senderIdentity,
@@ -255,15 +273,15 @@ export class LocalParticipant extends Participant {
       return ev.message.case == 'chatMessage' && ev.message.value.asyncId == res.asyncId;
     });
 
-    if (cb.error) {
-      throw new Error(cb.error);
+    if (cb.message.case !== 'chatMessage') {
+      throw new Error(cb.message.value ?? 'Unknown Error');
     }
-    const { id, timestamp, editTimestamp, message } = cb.chatMessage;
+    const { id, timestamp, editTimestamp, message } = cb.message.value;
     return { id, timestamp: Number(timestamp), editTimestamp: Number(editTimestamp), message };
   }
 
   async updateName(name: string) {
-    const req = new SetLocalNameRequest({
+    const req = create(SetLocalNameRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       name: name,
     });
@@ -278,9 +296,11 @@ export class LocalParticipant extends Participant {
   }
 
   async setAttributes(attributes: Record<string, string>) {
-    const req = new SetLocalAttributesRequest({
+    const req = create(SetLocalAttributesRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
-      attributes: attributes,
+      attributes: Array.from(Object.entries(attributes)).map(([key, value]) => {
+        return { key, value };
+      }),
     });
 
     const res = FfiClient.instance.request<SetLocalAttributesResponse>({
@@ -296,7 +316,7 @@ export class LocalParticipant extends Participant {
     track: LocalTrack,
     options: TrackPublishOptions,
   ): Promise<LocalTrackPublication> {
-    const req = new PublishTrackRequest({
+    const req = create(PublishTrackRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       trackHandle: track.ffi_handle.handle,
       options: options,
@@ -310,11 +330,11 @@ export class LocalParticipant extends Participant {
       return ev.message.case == 'publishTrack' && ev.message.value.asyncId == res.asyncId;
     });
 
-    if (cb.error) {
-      throw new Error(cb.error);
+    if (cb.message.case !== 'publication') {
+      throw new Error(cb.message.value ?? 'Unknown Error');
     }
 
-    const track_publication = new LocalTrackPublication(cb.publication);
+    const track_publication = new LocalTrackPublication(cb.message.value!);
     track_publication.track = track;
     this.trackPublications.set(track_publication.sid, track_publication);
 
@@ -322,7 +342,7 @@ export class LocalParticipant extends Participant {
   }
 
   async unpublishTrack(trackSid: string) {
-    const req = new UnpublishTrackRequest({
+    const req = create(UnpublishTrackRequestSchema, {
       localParticipantHandle: this.ffi_handle.handle,
       trackSid: trackSid,
     });
@@ -340,9 +360,153 @@ export class LocalParticipant extends Participant {
     }
 
     const pub = this.trackPublications.get(trackSid);
-    pub.track = undefined;
+    if (pub) {
+      pub.track = undefined;
+    }
     this.trackPublications.delete(trackSid);
   }
+
+  /**
+   * 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,
+  }: PerformRpcParams): Promise<string> {
+    const req = create(PerformRpcRequestSchema, {
+      localParticipantHandle: this.ffi_handle.handle,
+      destinationIdentity,
+      method,
+      payload,
+      responseTimeoutMs: responseTimeout,
+    });
+
+    const res = FfiClient.instance.request<PerformRpcResponse>({
+      message: { case: 'performRpc', value: req },
+    });
+
+    const cb = await FfiClient.instance.waitFor<PerformRpcCallback>((ev) => {
+      return ev.message.case === 'performRpc' && ev.message.value.asyncId === res.asyncId;
+    });
+
+    if (cb.error) {
+      throw RpcError.fromProto(cb.error);
+    }
+
+    return cb.payload;
+  }
+
+  /**
+   * 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}!`;
+   *   }
+   * );
+   * ```
+   *
+   * See {@link RpcInvocationData} for more details on invocation params.
+   *
+   * 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);
+
+    const req = create(RegisterRpcMethodRequestSchema, {
+      localParticipantHandle: this.ffi_handle.handle,
+      method,
+    });
+
+    FfiClient.instance.request<RegisterRpcMethodResponse>({
+      message: { case: 'registerRpcMethod', value: req },
+    });
+  }
+
+  /**
+   * Unregisters a previously registered RPC method.
+   *
+   * @param method - The name of the RPC method to unregister
+   */
+  unregisterRpcMethod(method: string) {
+    this.rpcHandlers.delete(method);
+
+    const req = create(UnregisterRpcMethodRequestSchema, {
+      localParticipantHandle: this.ffi_handle.handle,
+      method,
+    });
+
+    FfiClient.instance.request<UnregisterRpcMethodResponse>({
+      message: { case: 'unregisterRpcMethod', value: req },
+    });
+  }
+
+  /** @internal */
+  async handleRpcMethodInvocation(
+    invocationId: bigint,
+    method: string,
+    requestId: string,
+    callerIdentity: string,
+    payload: string,
+    responseTimeout: number,
+  ) {
+    let responseError: RpcError | null = null;
+    let responsePayload: string | null = null;
+
+    const handler = this.rpcHandlers.get(method);
+
+    if (!handler) {
+      responseError = RpcError.builtIn('UNSUPPORTED_METHOD');
+    } else {
+      try {
+        responsePayload = await handler({ requestId, callerIdentity, payload, responseTimeout });
+      } 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');
+        }
+      }
+    }
+
+    const req = create(RpcMethodInvocationResponseRequestSchema, {
+      localParticipantHandle: this.ffi_handle.handle,
+      invocationId,
+      error: responseError ? responseError.toProto() : undefined,
+      payload: responsePayload ?? undefined,
+    });
+
+    const res = FfiClient.instance.request<RpcMethodInvocationResponseResponse>({
+      message: { case: 'rpcMethodInvocationResponse', value: req },
+    });
+
+    if (res.error) {
+      console.warn(`error sending rpc method invocation response: ${res.error}`);
+    }
+  }
 }
 
 export class RemoteParticipant extends Participant {