@livekit/rtc-node 0.13.32 → 0.13.34

package/src/participant.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { Mutex } from '@livekit/mutex';
+import { type Mutex } from '@livekit/mutex';
 import {
   DisconnectReason,
   type OwnedParticipant,
@@ -10,13 +10,16 @@ import {
   type ParticipantKindDetail,
 } from '@livekit/rtc-ffi-bindings';
 import {
+  type ByteStreamOpenCallback,
+  ByteStreamOpenRequest,
+  type ByteStreamOpenResponse,
+  type ByteStreamWriterCloseCallback,
+  ByteStreamWriterCloseRequest,
+  type ByteStreamWriterCloseResponse,
+  type ByteStreamWriterWriteCallback,
+  ByteStreamWriterWriteRequest,
+  type ByteStreamWriterWriteResponse,
   ChatMessage as ChatMessageModel,
-  DataStream_ByteHeader,
-  DataStream_Chunk,
-  DataStream_Header,
-  DataStream_OperationType,
-  DataStream_TextHeader,
-  DataStream_Trailer,
   EditChatMessageRequest,
   TranscriptionSegment as ProtoTranscriptionSegment,
   type PublishDataCallback,
@@ -34,15 +37,6 @@ import {
   type SendChatMessageCallback,
   SendChatMessageRequest,
   type SendChatMessageResponse,
-  type SendStreamChunkCallback,
-  SendStreamChunkRequest,
-  type SendStreamChunkResponse,
-  type SendStreamHeaderCallback,
-  SendStreamHeaderRequest,
-  type SendStreamHeaderResponse,
-  type SendStreamTrailerCallback,
-  SendStreamTrailerRequest,
-  type SendStreamTrailerResponse,
   type SetLocalAttributesCallback,
   SetLocalAttributesRequest,
   type SetLocalAttributesResponse,
@@ -52,6 +46,23 @@ import {
   type SetLocalNameCallback,
   SetLocalNameRequest,
   type SetLocalNameResponse,
+  StreamByteOptions,
+  type StreamSendFileCallback,
+  StreamSendFileRequest,
+  type StreamSendFileResponse,
+  type StreamSendTextCallback,
+  StreamSendTextRequest,
+  type StreamSendTextResponse,
+  StreamTextOptions,
+  type TextStreamOpenCallback,
+  TextStreamOpenRequest,
+  type TextStreamOpenResponse,
+  type TextStreamWriterCloseCallback,
+  TextStreamWriterCloseRequest,
+  type TextStreamWriterCloseResponse,
+  type TextStreamWriterWriteCallback,
+  TextStreamWriterWriteRequest,
+  type TextStreamWriterWriteResponse,
   type TrackPublishOptions,
   type UnpublishTrackCallback,
   UnpublishTrackRequest,
@@ -71,12 +82,10 @@ import {
   UnregisterRpcMethodRequest,
 } from '@livekit/rtc-ffi-bindings';
 import type { PathLike } from 'node:fs';
-import { open, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 import {
-  type ByteStreamInfo,
   type ByteStreamOptions,
   ByteStreamWriter,
-  type TextStreamInfo,
   TextStreamWriter,
 } from './data_streams/index.js';
 import { FfiClient, FfiHandle } from './ffi_client.js';
@@ -87,9 +96,8 @@ import type { RemoteTrackPublication, TrackPublication } from './track_publicati
 import { LocalTrackPublication } from './track_publication.js';
 import type { Transcription } from './transcription.js';
 import type { ChatMessage } from './types.js';
-import { numberToBigInt, splitUtf8 } from './utils.js';
-
-const STREAM_CHUNK_SIZE = 15_000;
+import { byteStreamInfoFromProto, textStreamInfoFromProto } from './utils.js';
+import { numberToBigInt } from './utils.js';
 
 export abstract class Participant {
   /** @internal */
@@ -166,6 +174,14 @@ export class LocalParticipant extends Participant {
   // pending FfiClient.waitFor() listeners so they don't leak.
   private disconnectSignal: AbortSignal;
 
+  // Handle ids of data stream writers that have been opened but not yet
+  // closed. The FFI close request consumes the handle (take_handle), so an
+  // entry is removed as soon as a close is sent for it; whatever is left when
+  // the room disconnects is dropped by disposeOpenStreamWriters(). Only the
+  // ids are kept — wrapping them in FfiHandle would make GC drop a handle the
+  // close request already consumed.
+  private openStreamWriters = new Set<bigint>();
+
   trackPublications: Map<string, LocalTrackPublication> = new Map();
 
   constructor(info: OwnedParticipant, ffiEventLock: Mutex, disconnectSignal: AbortSignal) {
@@ -278,92 +294,70 @@ export class LocalParticipant extends Participant {
     streamId?: string;
     senderIdentity?: string;
   }): Promise<TextStreamWriter> {
-    const senderIdentity = options?.senderIdentity ?? this.identity;
-    const streamId = options?.streamId ?? crypto.randomUUID();
-    const destinationIdentities = options?.destinationIdentities;
-
-    const info: TextStreamInfo = {
-      streamId: streamId,
-      mimeType: 'text/plain',
-      topic: options?.topic ?? '',
-      timestamp: Date.now(),
-    };
-
-    const headerReq = new SendStreamHeaderRequest({
-      senderIdentity,
-      destinationIdentities,
+    const req = new TextStreamOpenRequest({
       localParticipantHandle: this.ffi_handle.handle,
-      header: new DataStream_Header({
-        streamId,
-        mimeType: info.mimeType,
-        topic: info.topic,
-        timestamp: numberToBigInt(info.timestamp),
+      options: new StreamTextOptions({
+        topic: options?.topic ?? '',
         attributes: options?.attributes,
-        contentHeader: {
-          case: 'textHeader',
-          value: new DataStream_TextHeader({
-            operationType: DataStream_OperationType.CREATE,
-            version: 0,
-            replyToStreamId: '',
-            generated: false,
-          }),
-        },
+        destinationIdentities: options?.destinationIdentities,
+        id: options?.streamId,
+        senderIdentity: options?.senderIdentity ?? this.identity,
       }),
     });
 
-    await this.sendStreamHeader(headerReq);
+    const res = FfiClient.instance.request<TextStreamOpenResponse>({
+      message: { case: 'textStreamOpen', value: req },
+    });
+
+    const cb = await FfiClient.instance.waitFor<TextStreamOpenCallback>(
+      (ev) => ev.message.case == 'textStreamOpen' && ev.message.value.asyncId == res.asyncId,
+      { signal: this.disconnectSignal },
+    );
 
-    let nextChunkId = 0;
-    const localHandle = this.ffi_handle.handle;
-    const sendTrailer = this.sendStreamTrailer;
-    const sendChunk = this.sendStreamChunk;
+    if (cb.result.case !== 'writer') {
+      throw new Error(cb.result.case === 'error' ? cb.result.value.description : 'unknown error');
+    }
+
+    const writerHandle = cb.result.value.handle!.id!;
+    const info = textStreamInfoFromProto(cb.result.value.info!);
+    this.openStreamWriters.add(writerHandle);
+
+    // Sends the close request at most once: it consumes the writer handle on
+    // the native side, so a second one would fail and, worse, the handle must
+    // no longer be dropped by disconnect cleanup.
+    const closeWriter = async (reason?: string) => {
+      if (!this.openStreamWriters.delete(writerHandle)) {
+        return;
+      }
+      await this.textStreamWriterClose(new TextStreamWriterCloseRequest({ writerHandle, reason }));
+    };
 
     const writableStream = new WritableStream<string>({
       // Implement the sink
-      async write(text) {
-        for (const textByteChunk of splitUtf8(text, STREAM_CHUNK_SIZE)) {
-          const chunkRequest = new SendStreamChunkRequest({
-            senderIdentity,
-            localParticipantHandle: localHandle,
-            destinationIdentities,
-            chunk: new DataStream_Chunk({
-              content: textByteChunk,
-              streamId,
-              chunkIndex: numberToBigInt(nextChunkId),
-            }),
+      write: async (text) => {
+        try {
+          await this.textStreamWriterWrite(
+            new TextStreamWriterWriteRequest({ writerHandle, text }),
+          );
+        } catch (err) {
+          // A rejected write leaves the writable stream errored, and an errored
+          // stream never runs the sink's close()/abort() — a later close() just
+          // rejects with this error. Close the native writer here so its handle
+          // isn't held for the lifetime of the process and peers get an
+          // end-of-stream instead of a stream that never terminates.
+          await closeWriter(err instanceof Error ? err.message : String(err ?? '')).catch(() => {
+            // Best-effort: the connection may already be gone.
           });
-
-          await sendChunk(chunkRequest);
-          nextChunkId += 1;
+          throw err;
         }
       },
-      async close() {
-        const trailerReq = new SendStreamTrailerRequest({
-          senderIdentity,
-          localParticipantHandle: localHandle,
-          destinationIdentities,
-          trailer: new DataStream_Trailer({
-            streamId,
-            reason: '',
-          }),
-        });
-        await sendTrailer(trailerReq);
-      },
-      // Send a trailer with the error reason so the remote side's stream
+      close: () => closeWriter(),
+      // Close the stream with the error reason so the remote side's stream
       // controller is closed instead of waiting for data that won't arrive.
-      async abort(err) {
+      abort: async (err) => {
         log.error(err, 'Sink Error');
         try {
-          const trailerReq = new SendStreamTrailerRequest({
-            senderIdentity,
-            localParticipantHandle: localHandle,
-            destinationIdentities,
-            trailer: new DataStream_Trailer({
-              streamId,
-              reason: err instanceof Error ? err.message : String(err ?? ''),
-            }),
-          });
-          await sendTrailer(trailerReq);
+          await closeWriter(err instanceof Error ? err.message : String(err ?? ''));
         } catch {
           // Best-effort: the connection may already be gone.
         }
@@ -382,12 +376,41 @@ export class LocalParticipant extends Participant {
       attributes?: Record<string, string>;
       destinationIdentities?: Array<string>;
       streamId?: string;
+      /**
+       * Whether the payload may be compressed on the wire. Defaults to true;
+       * compression is only applied when it actually reduces the payload size
+       * and every recipient supports it.
+       */
+      compress?: boolean;
     },
   ) {
-    const writer = await this.streamText(options);
-    await writer.write(text);
-    await writer.close();
-    return writer.info;
+    const req = new StreamSendTextRequest({
+      localParticipantHandle: this.ffi_handle.handle,
+      options: new StreamTextOptions({
+        topic: options?.topic ?? '',
+        attributes: options?.attributes,
+        destinationIdentities: options?.destinationIdentities,
+        id: options?.streamId,
+        senderIdentity: this.identity,
+        compress: options?.compress,
+      }),
+      text,
+    });
+
+    const res = FfiClient.instance.request<StreamSendTextResponse>({
+      message: { case: 'sendText', value: req },
+    });
+
+    const cb = await FfiClient.instance.waitFor<StreamSendTextCallback>(
+      (ev) => ev.message.case == 'sendText' && ev.message.value.asyncId == res.asyncId,
+      { signal: this.disconnectSignal },
+    );
+
+    if (cb.result.case !== 'info') {
+      throw new Error(cb.result.case === 'error' ? cb.result.value.description : 'unknown error');
+    }
+
+    return textStreamInfoFromProto(cb.result.value);
   }
 
   async streamBytes(options?: {
@@ -399,102 +422,72 @@ export class LocalParticipant extends Participant {
     mimeType?: string;
     totalSize?: number;
   }) {
-    const senderIdentity = this.identity;
-    const streamId = options?.streamId ?? crypto.randomUUID();
-    const destinationIdentities = options?.destinationIdentities;
-
-    const info: ByteStreamInfo = {
-      streamId: streamId,
-      mimeType: options?.mimeType ?? 'application/octet-stream',
-      topic: options?.topic ?? '',
-      timestamp: Date.now(),
-      attributes: options?.attributes,
-      totalSize: options?.totalSize,
-      name: options?.name ?? 'unknown',
-    };
-
-    const headerReq = new SendStreamHeaderRequest({
-      senderIdentity,
-      destinationIdentities,
+    const req = new ByteStreamOpenRequest({
       localParticipantHandle: this.ffi_handle.handle,
-      header: new DataStream_Header({
-        streamId,
-        mimeType: info.mimeType,
-        topic: info.topic,
-        timestamp: numberToBigInt(info.timestamp),
-        attributes: info.attributes,
-        totalLength: numberToBigInt(info.totalSize),
-        contentHeader: {
-          case: 'byteHeader',
-          value: new DataStream_ByteHeader({
-            name: info.name,
-          }),
-        },
+      options: new StreamByteOptions({
+        topic: options?.topic ?? '',
+        attributes: options?.attributes,
+        destinationIdentities: options?.destinationIdentities,
+        id: options?.streamId,
+        name: options?.name ?? 'unknown',
+        mimeType: options?.mimeType ?? 'application/octet-stream',
+        totalLength: numberToBigInt(options?.totalSize),
+        senderIdentity: this.identity,
       }),
     });
 
-    await this.sendStreamHeader(headerReq);
+    const res = FfiClient.instance.request<ByteStreamOpenResponse>({
+      message: { case: 'byteStreamOpen', value: req },
+    });
 
-    let chunkId = 0;
-    const localHandle = this.ffi_handle.handle;
-    const sendTrailer = this.sendStreamTrailer;
-    const sendChunk = this.sendStreamChunk;
-    const writeMutex = new Mutex();
+    const cb = await FfiClient.instance.waitFor<ByteStreamOpenCallback>(
+      (ev) => ev.message.case == 'byteStreamOpen' && ev.message.value.asyncId == res.asyncId,
+      { signal: this.disconnectSignal },
+    );
 
-    const writableStream = new WritableStream<Uint8Array>({
-      async write(chunk) {
-        const unlock = await writeMutex.lock();
+    if (cb.result.case !== 'writer') {
+      throw new Error(cb.result.case === 'error' ? cb.result.value.description : 'unknown error');
+    }
+
+    const writerHandle = cb.result.value.handle!.id!;
+    const info = byteStreamInfoFromProto(cb.result.value.info!);
+    this.openStreamWriters.add(writerHandle);
 
-        let byteOffset = 0;
+    // Sends the close request at most once: it consumes the writer handle on
+    // the native side, so a second one would fail and, worse, the handle must
+    // no longer be dropped by disconnect cleanup.
+    const closeWriter = async (reason?: string) => {
+      if (!this.openStreamWriters.delete(writerHandle)) {
+        return;
+      }
+      await this.byteStreamWriterClose(new ByteStreamWriterCloseRequest({ writerHandle, reason }));
+    };
+
+    const writableStream = new WritableStream<Uint8Array>({
+      write: async (chunk) => {
         try {
-          while (byteOffset < chunk.byteLength) {
-            const subChunk = chunk.slice(byteOffset, byteOffset + STREAM_CHUNK_SIZE);
-            const chunkRequest = new SendStreamChunkRequest({
-              senderIdentity,
-              localParticipantHandle: localHandle,
-              destinationIdentities,
-              chunk: new DataStream_Chunk({
-                content: subChunk,
-                streamId,
-                chunkIndex: numberToBigInt(chunkId),
-              }),
-            });
-
-            await sendChunk(chunkRequest);
-            chunkId += 1;
-            byteOffset += subChunk.byteLength;
-          }
-        } finally {
-          unlock();
+          await this.byteStreamWriterWrite(
+            new ByteStreamWriterWriteRequest({ writerHandle, bytes: chunk }),
+          );
+        } catch (err) {
+          // A rejected write leaves the writable stream errored, and an errored
+          // stream never runs the sink's close()/abort() — a later close() just
+          // rejects with this error. Close the native writer here so its handle
+          // isn't held for the lifetime of the process and peers get an
+          // end-of-stream instead of a stream that never terminates.
+          await closeWriter(err instanceof Error ? err.message : String(err ?? '')).catch(() => {
+            // Best-effort: the connection may already be gone.
+          });
+          throw err;
         }
       },
-      async close() {
-        const trailerReq = new SendStreamTrailerRequest({
-          senderIdentity,
-          localParticipantHandle: localHandle,
-          destinationIdentities,
-          trailer: new DataStream_Trailer({
-            streamId,
-            reason: '',
-          }),
-        });
-        await sendTrailer(trailerReq);
-      },
-      // Send a trailer with the error reason so the remote side's stream
+      close: () => closeWriter(),
+      // Close the stream with the error reason so the remote side's stream
       // controller is closed instead of waiting for data that won't arrive.
-      async abort(err) {
+      abort: async (err) => {
         log.error(err, 'Sink error');
         try {
-          const trailerReq = new SendStreamTrailerRequest({
-            senderIdentity,
-            localParticipantHandle: localHandle,
-            destinationIdentities,
-            trailer: new DataStream_Trailer({
-              streamId,
-              reason: err instanceof Error ? err.message : String(err ?? ''),
-            }),
-          });
-          await sendTrailer(trailerReq);
+          await closeWriter(err instanceof Error ? err.message : String(err ?? ''));
         } catch {
           // Best-effort: the connection may already be gone.
         }
@@ -508,80 +501,116 @@ export class LocalParticipant extends Participant {
 
   /** Sends a file provided as PathLike to specified recipients */
   async sendFile(path: PathLike, options?: ByteStreamOptions) {
-    const fileStats = await stat(path);
-    const file = await open(path);
-    try {
-      const stream: ReadableStream<Uint8Array> = file.readableWebStream();
-      const streamId = crypto.randomUUID();
-      const destinationIdentities = options?.destinationIdentities;
-
-      const writer = await this.streamBytes({
-        streamId: streamId,
-        name: options?.name,
-        totalSize: fileStats.size,
-        destinationIdentities,
-        topic: options?.topic,
-        mimeType: options?.mimeType,
+    const filePath = path instanceof URL ? fileURLToPath(path) : path.toString();
+
+    const req = new StreamSendFileRequest({
+      localParticipantHandle: this.ffi_handle.handle,
+      options: new StreamByteOptions({
+        topic: options?.topic ?? '',
         attributes: options?.attributes,
-      });
+        destinationIdentities: options?.destinationIdentities,
+        name: options?.name ?? 'unknown',
+        mimeType: options?.mimeType ?? 'application/octet-stream',
+        senderIdentity: this.identity,
+        compress: options?.compress,
+      }),
+      filePath,
+    });
 
-      for await (const chunk of stream) {
-        await writer.write(chunk);
-      }
-      await writer.close();
-    } finally {
-      await file.close();
+    const res = FfiClient.instance.request<StreamSendFileResponse>({
+      message: { case: 'sendFile', value: req },
+    });
+
+    const cb = await FfiClient.instance.waitFor<StreamSendFileCallback>(
+      (ev) => ev.message.case == 'sendFile' && ev.message.value.asyncId == res.asyncId,
+      { signal: this.disconnectSignal },
+    );
+
+    if (cb.result.case === 'error') {
+      throw new Error(cb.result.value.description);
     }
   }
 
-  private async sendStreamHeader(req: SendStreamHeaderRequest) {
-    const type = 'sendStreamHeader';
-    const res = FfiClient.instance.request<SendStreamHeaderResponse>({
-      message: { case: type, value: req },
+  private textStreamWriterWrite = async (req: TextStreamWriterWriteRequest) => {
+    const res = FfiClient.instance.request<TextStreamWriterWriteResponse>({
+      message: { case: 'textStreamWrite', value: req },
     });
 
-    const cb = await FfiClient.instance.waitFor<SendStreamHeaderCallback>(
-      (ev) => ev.message.case == type && ev.message.value.asyncId == res.asyncId,
+    const cb = await FfiClient.instance.waitFor<TextStreamWriterWriteCallback>(
+      (ev) => ev.message.case == 'textStreamWriterWrite' && ev.message.value.asyncId == res.asyncId,
       { signal: this.disconnectSignal },
     );
 
     if (cb.error) {
-      throw new Error(cb.error);
+      throw new Error(cb.error.description);
     }
-  }
+  };
 
-  private sendStreamChunk = async (req: SendStreamChunkRequest) => {
-    const type = 'sendStreamChunk';
-    const res = FfiClient.instance.request<SendStreamChunkResponse>({
-      message: { case: type, value: req },
+  private textStreamWriterClose = async (req: TextStreamWriterCloseRequest) => {
+    const res = FfiClient.instance.request<TextStreamWriterCloseResponse>({
+      message: { case: 'textStreamClose', value: req },
     });
 
-    const cb = await FfiClient.instance.waitFor<SendStreamChunkCallback>(
-      (ev) => ev.message.case == type && ev.message.value.asyncId == res.asyncId,
+    const cb = await FfiClient.instance.waitFor<TextStreamWriterCloseCallback>(
+      (ev) => ev.message.case == 'textStreamWriterClose' && ev.message.value.asyncId == res.asyncId,
       { signal: this.disconnectSignal },
     );
 
     if (cb.error) {
-      throw new Error(cb.error);
+      throw new Error(cb.error.description);
     }
   };
 
-  private sendStreamTrailer = async (req: SendStreamTrailerRequest) => {
-    const type = 'sendStreamTrailer';
-    const res = FfiClient.instance.request<SendStreamTrailerResponse>({
-      message: { case: type, value: req },
+  private byteStreamWriterWrite = async (req: ByteStreamWriterWriteRequest) => {
+    const res = FfiClient.instance.request<ByteStreamWriterWriteResponse>({
+      message: { case: 'byteStreamWrite', value: req },
     });
 
-    const cb = await FfiClient.instance.waitFor<SendStreamTrailerCallback>(
-      (ev) => ev.message.case == type && ev.message.value.asyncId == res.asyncId,
+    const cb = await FfiClient.instance.waitFor<ByteStreamWriterWriteCallback>(
+      (ev) => ev.message.case == 'byteStreamWriterWrite' && ev.message.value.asyncId == res.asyncId,
       { signal: this.disconnectSignal },
     );
 
     if (cb.error) {
-      throw new Error(cb.error);
+      throw new Error(cb.error.description);
+    }
+  };
+
+  private byteStreamWriterClose = async (req: ByteStreamWriterCloseRequest) => {
+    const res = FfiClient.instance.request<ByteStreamWriterCloseResponse>({
+      message: { case: 'byteStreamClose', value: req },
+    });
+
+    const cb = await FfiClient.instance.waitFor<ByteStreamWriterCloseCallback>(
+      (ev) => ev.message.case == 'byteStreamWriterClose' && ev.message.value.asyncId == res.asyncId,
+      { signal: this.disconnectSignal },
+    );
+
+    if (cb.error) {
+      throw new Error(cb.error.description);
     }
   };
 
+  /**
+   * Drops the native writers of any data streams that were opened but never
+   * closed — a writer the caller abandoned, or one whose write failed. Their
+   * handles would otherwise be held by the FFI server for the lifetime of the
+   * process. The room is already gone at this point, so the handles are dropped
+   * directly rather than closed: there is no end-of-stream left to deliver.
+   *
+   * @internal
+   */
+  disposeOpenStreamWriters() {
+    for (const writerHandle of this.openStreamWriters) {
+      try {
+        new FfiHandle(writerHandle).dispose();
+      } catch (err) {
+        log.warn('failed to dispose data stream writer handle: %s', err);
+      }
+    }
+    this.openStreamWriters.clear();
+  }
+
   /**
    * Sends a chat message to participants in the room
    *