livekit-client 2.15.4 → 2.15.6

package/src/room/data-stream/incoming/StreamReader.ts

@@ -0,0 +1,317 @@
+import type { DataStream_Chunk } from '@livekit/protocol';
+import { DataStreamError, DataStreamErrorReason } from '../../errors';
+import type { BaseStreamInfo, ByteStreamInfo, TextStreamInfo } from '../../types';
+import { Future, bigIntToNumber } from '../../utils';
+
+export type BaseStreamReaderReadAllOpts = {
+  /** An AbortSignal can be used to terminate reads early. */
+  signal?: AbortSignal;
+};
+
+abstract class BaseStreamReader<T extends BaseStreamInfo> {
+  protected reader: ReadableStream<DataStream_Chunk>;
+
+  protected totalByteSize?: number;
+
+  protected _info: T;
+
+  protected bytesReceived: number;
+
+  protected outOfBandFailureRejectingFuture?: Future<never>;
+
+  get info() {
+    return this._info;
+  }
+
+  /** @internal */
+  protected validateBytesReceived(doneReceiving: boolean = false) {
+    if (typeof this.totalByteSize !== 'number' || this.totalByteSize === 0) {
+      return;
+    }
+
+    if (doneReceiving && this.bytesReceived < this.totalByteSize) {
+      throw new DataStreamError(
+        `Not enough chunk(s) received - expected ${this.totalByteSize} bytes of data total, only received ${this.bytesReceived} bytes`,
+        DataStreamErrorReason.Incomplete,
+      );
+    } else if (this.bytesReceived > this.totalByteSize) {
+      throw new DataStreamError(
+        `Extra chunk(s) received - expected ${this.totalByteSize} bytes of data total, received ${this.bytesReceived} bytes`,
+        DataStreamErrorReason.LengthExceeded,
+      );
+    }
+  }
+
+  constructor(
+    info: T,
+    stream: ReadableStream<DataStream_Chunk>,
+    totalByteSize?: number,
+    outOfBandFailureRejectingFuture?: Future<never>,
+  ) {
+    this.reader = stream;
+    this.totalByteSize = totalByteSize;
+    this._info = info;
+    this.bytesReceived = 0;
+    this.outOfBandFailureRejectingFuture = outOfBandFailureRejectingFuture;
+  }
+
+  protected abstract handleChunkReceived(chunk: DataStream_Chunk): void;
+
+  onProgress?: (progress: number | undefined) => void;
+
+  abstract readAll(opts?: BaseStreamReaderReadAllOpts): Promise<string | Array<Uint8Array>>;
+}
+
+export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
+  protected handleChunkReceived(chunk: DataStream_Chunk) {
+    this.bytesReceived += chunk.content.byteLength;
+    this.validateBytesReceived();
+
+    const currentProgress = this.totalByteSize
+      ? this.bytesReceived / this.totalByteSize
+      : undefined;
+    this.onProgress?.(currentProgress);
+  }
+
+  onProgress?: (progress: number | undefined) => void;
+
+  signal?: AbortSignal;
+
+  [Symbol.asyncIterator]() {
+    const reader = this.reader.getReader();
+
+    let rejectingSignalFuture = new Future<never>();
+    let activeSignal: AbortSignal | null = null;
+    let onAbort: (() => void) | null = null;
+    if (this.signal) {
+      const signal = this.signal;
+      onAbort = () => {
+        rejectingSignalFuture.reject?.(signal.reason);
+      };
+      signal.addEventListener('abort', onAbort);
+      activeSignal = signal;
+    }
+
+    const cleanup = () => {
+      reader.releaseLock();
+
+      if (activeSignal && onAbort) {
+        activeSignal.removeEventListener('abort', onAbort);
+      }
+
+      this.signal = undefined;
+    };
+
+    return {
+      next: async (): Promise<IteratorResult<Uint8Array>> => {
+        try {
+          const { done, value } = await Promise.race([
+            reader.read(),
+            // Rejects if this.signal is aborted
+            rejectingSignalFuture.promise,
+            // Rejects if something external says it should, like a participant disconnecting, etc
+            this.outOfBandFailureRejectingFuture?.promise ??
+              new Promise<never>(() => {
+                /* never resolves */
+              }),
+          ]);
+          if (done) {
+            this.validateBytesReceived(true);
+            return { done: true, value: undefined as any };
+          } else {
+            this.handleChunkReceived(value);
+            return { done: false, value: value.content };
+          }
+        } catch (err) {
+          cleanup();
+          throw err;
+        }
+      },
+
+      // note: `return` runs only for premature exits, see:
+      // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#errors_during_iteration
+      async return(): Promise<IteratorResult<Uint8Array>> {
+        cleanup();
+        return { done: true, value: undefined };
+      },
+    };
+  }
+
+  /**
+   * Injects an AbortSignal, which if aborted, will terminate the currently active
+   * stream iteration operation.
+   *
+   * Note that when using AbortSignal.timeout(...), the timeout applies across
+   * the whole iteration operation, not just one individual chunk read.
+   */
+  withAbortSignal(signal: AbortSignal) {
+    this.signal = signal;
+    return this;
+  }
+
+  async readAll(opts: BaseStreamReaderReadAllOpts = {}): Promise<Array<Uint8Array>> {
+    let chunks: Set<Uint8Array> = new Set();
+    const iterator = opts.signal ? this.withAbortSignal(opts.signal) : this;
+    for await (const chunk of iterator) {
+      chunks.add(chunk);
+    }
+    return Array.from(chunks);
+  }
+}
+
+/**
+ * A class to read chunks from a ReadableStream and provide them in a structured format.
+ */
+export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
+  private receivedChunks: Map<number, DataStream_Chunk>;
+
+  signal?: AbortSignal;
+
+  /**
+   * A TextStreamReader instance can be used as an AsyncIterator that returns the entire string
+   * that has been received up to the current point in time.
+   */
+  constructor(
+    info: TextStreamInfo,
+    stream: ReadableStream<DataStream_Chunk>,
+    totalChunkCount?: number,
+    outOfBandFailureRejectingFuture?: Future<never>,
+  ) {
+    super(info, stream, totalChunkCount, outOfBandFailureRejectingFuture);
+    this.receivedChunks = new Map();
+  }
+
+  protected handleChunkReceived(chunk: DataStream_Chunk) {
+    const index = bigIntToNumber(chunk.chunkIndex);
+    const previousChunkAtIndex = this.receivedChunks.get(index);
+    if (previousChunkAtIndex && previousChunkAtIndex.version > chunk.version) {
+      // we have a newer version already, dropping the old one
+      return;
+    }
+    this.receivedChunks.set(index, chunk);
+
+    this.bytesReceived += chunk.content.byteLength;
+    this.validateBytesReceived();
+
+    const currentProgress = this.totalByteSize
+      ? this.bytesReceived / this.totalByteSize
+      : undefined;
+    this.onProgress?.(currentProgress);
+  }
+
+  /**
+   * @param progress - progress of the stream between 0 and 1. Undefined for streams of unknown size
+   */
+  onProgress?: (progress: number | undefined) => void;
+
+  /**
+   * Async iterator implementation to allow usage of `for await...of` syntax.
+   * Yields structured chunks from the stream.
+   *
+   */
+  [Symbol.asyncIterator]() {
+    const reader = this.reader.getReader();
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+
+    let rejectingSignalFuture = new Future<never>();
+    let activeSignal: AbortSignal | null = null;
+    let onAbort: (() => void) | null = null;
+    if (this.signal) {
+      const signal = this.signal;
+      onAbort = () => {
+        rejectingSignalFuture.reject?.(signal.reason);
+      };
+      signal.addEventListener('abort', onAbort);
+      activeSignal = signal;
+    }
+
+    const cleanup = () => {
+      reader.releaseLock();
+
+      if (activeSignal && onAbort) {
+        activeSignal.removeEventListener('abort', onAbort);
+      }
+
+      this.signal = undefined;
+    };
+
+    return {
+      next: async (): Promise<IteratorResult<string>> => {
+        try {
+          const { done, value } = await Promise.race([
+            reader.read(),
+            // Rejects if this.signal is aborted
+            rejectingSignalFuture.promise,
+            // Rejects if something external says it should, like a participant disconnecting, etc
+            this.outOfBandFailureRejectingFuture?.promise ??
+              new Promise<never>(() => {
+                /* never resolves */
+              }),
+          ]);
+          if (done) {
+            this.validateBytesReceived(true);
+            return { done: true, value: undefined };
+          } else {
+            this.handleChunkReceived(value);
+
+            let decodedResult;
+            try {
+              decodedResult = decoder.decode(value.content);
+            } catch (err) {
+              throw new DataStreamError(
+                `Cannot decode datastream chunk ${value.chunkIndex} as text: ${err}`,
+                DataStreamErrorReason.DecodeFailed,
+              );
+            }
+
+            return {
+              done: false,
+              value: decodedResult,
+            };
+          }
+        } catch (err) {
+          cleanup();
+          throw err;
+        }
+      },
+
+      // note: `return` runs only for premature exits, see:
+      // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#errors_during_iteration
+      async return(): Promise<IteratorResult<string>> {
+        cleanup();
+        return { done: true, value: undefined };
+      },
+    };
+  }
+
+  /**
+   * Injects an AbortSignal, which if aborted, will terminate the currently active
+   * stream iteration operation.
+   *
+   * Note that when using AbortSignal.timeout(...), the timeout applies across
+   * the whole iteration operation, not just one individual chunk read.
+   */
+  withAbortSignal(signal: AbortSignal) {
+    this.signal = signal;
+    return this;
+  }
+
+  async readAll(opts: BaseStreamReaderReadAllOpts = {}): Promise<string> {
+    let finalString: string = '';
+    const iterator = opts.signal ? this.withAbortSignal(opts.signal) : this;
+    for await (const chunk of iterator) {
+      finalString += chunk;
+    }
+    return finalString;
+  }
+}
+
+export type ByteStreamHandler = (
+  reader: ByteStreamReader,
+  participantInfo: { identity: string },
+) => void;
+
+export type TextStreamHandler = (
+  reader: TextStreamReader,
+  participantInfo: { identity: string },
+) => void;

package/src/room/data-stream/outgoing/OutgoingDataStreamManager.ts

@@ -0,0 +1,316 @@
+import { Mutex } from '@livekit/mutex';
+import {
+  DataPacket,
+  DataPacket_Kind,
+  DataStream_ByteHeader,
+  DataStream_Chunk,
+  DataStream_Header,
+  DataStream_OperationType,
+  DataStream_TextHeader,
+  DataStream_Trailer,
+} from '@livekit/protocol';
+import { type StructuredLogger } from '../../../logger';
+import type RTCEngine from '../../RTCEngine';
+import { EngineEvent } from '../../events';
+import type {
+  ByteStreamInfo,
+  SendFileOptions,
+  SendTextOptions,
+  StreamBytesOptions,
+  StreamTextOptions,
+  TextStreamInfo,
+} from '../../types';
+import { numberToBigInt, splitUtf8 } from '../../utils';
+import { ByteStreamWriter, TextStreamWriter } from './StreamWriter';
+
+const STREAM_CHUNK_SIZE = 15_000;
+
+/**
+ * Manages sending custom user data via data channels.
+ * @internal
+ */
+export default class OutgoingDataStreamManager {
+  protected engine: RTCEngine;
+
+  protected log: StructuredLogger;
+
+  constructor(engine: RTCEngine, log: StructuredLogger) {
+    this.engine = engine;
+    this.log = log;
+  }
+
+  setupEngine(engine: RTCEngine) {
+    this.engine = engine;
+  }
+
+  /** {@inheritDoc LocalParticipant.sendText} */
+  async sendText(text: string, options?: SendTextOptions): Promise<TextStreamInfo> {
+    const streamId = crypto.randomUUID();
+    const textInBytes = new TextEncoder().encode(text);
+    const totalTextLength = textInBytes.byteLength;
+
+    const fileIds = options?.attachments?.map(() => crypto.randomUUID());
+
+    const progresses = new Array<number>(fileIds ? fileIds.length + 1 : 1).fill(0);
+
+    const handleProgress = (progress: number, idx: number) => {
+      progresses[idx] = progress;
+      const totalProgress = progresses.reduce((acc, val) => acc + val, 0);
+      options?.onProgress?.(totalProgress);
+    };
+
+    const writer = await this.streamText({
+      streamId,
+      totalSize: totalTextLength,
+      destinationIdentities: options?.destinationIdentities,
+      topic: options?.topic,
+      attachedStreamIds: fileIds,
+      attributes: options?.attributes,
+    });
+
+    await writer.write(text);
+    // set text part of progress to 1
+    handleProgress(1, 0);
+
+    await writer.close();
+
+    if (options?.attachments && fileIds) {
+      await Promise.all(
+        options.attachments.map(async (file, idx) =>
+          this._sendFile(fileIds[idx], file, {
+            topic: options.topic,
+            mimeType: file.type,
+            onProgress: (progress) => {
+              handleProgress(progress, idx + 1);
+            },
+          }),
+        ),
+      );
+    }
+    return writer.info;
+  }
+
+  /**
+   * @internal
+   * @experimental CAUTION, might get removed in a minor release
+   */
+  async streamText(options?: StreamTextOptions): Promise<TextStreamWriter> {
+    const streamId = options?.streamId ?? crypto.randomUUID();
+
+    const info: TextStreamInfo = {
+      id: streamId,
+      mimeType: 'text/plain',
+      timestamp: Date.now(),
+      topic: options?.topic ?? '',
+      size: options?.totalSize,
+      attributes: options?.attributes,
+    };
+    const header = new DataStream_Header({
+      streamId,
+      mimeType: info.mimeType,
+      topic: info.topic,
+      timestamp: numberToBigInt(info.timestamp),
+      totalLength: numberToBigInt(options?.totalSize),
+      attributes: info.attributes,
+      contentHeader: {
+        case: 'textHeader',
+        value: new DataStream_TextHeader({
+          version: options?.version,
+          attachedStreamIds: options?.attachedStreamIds,
+          replyToStreamId: options?.replyToStreamId,
+          operationType:
+            options?.type === 'update'
+              ? DataStream_OperationType.UPDATE
+              : DataStream_OperationType.CREATE,
+        }),
+      },
+    });
+    const destinationIdentities = options?.destinationIdentities;
+    const packet = new DataPacket({
+      destinationIdentities,
+      value: {
+        case: 'streamHeader',
+        value: header,
+      },
+    });
+    await this.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+
+    let chunkId = 0;
+    const engine = this.engine;
+
+    const writableStream = new WritableStream<string>({
+      // Implement the sink
+      async write(text) {
+        for (const textByteChunk of splitUtf8(text, STREAM_CHUNK_SIZE)) {
+          await engine.waitForBufferStatusLow(DataPacket_Kind.RELIABLE);
+          const chunk = new DataStream_Chunk({
+            content: textByteChunk,
+            streamId,
+            chunkIndex: numberToBigInt(chunkId),
+          });
+          const chunkPacket = new DataPacket({
+            destinationIdentities,
+            value: {
+              case: 'streamChunk',
+              value: chunk,
+            },
+          });
+          await engine.sendDataPacket(chunkPacket, DataPacket_Kind.RELIABLE);
+
+          chunkId += 1;
+        }
+      },
+      async close() {
+        const trailer = new DataStream_Trailer({
+          streamId,
+        });
+        const trailerPacket = new DataPacket({
+          destinationIdentities,
+          value: {
+            case: 'streamTrailer',
+            value: trailer,
+          },
+        });
+        await engine.sendDataPacket(trailerPacket, DataPacket_Kind.RELIABLE);
+      },
+      abort(err) {
+        console.log('Sink error:', err);
+        // TODO handle aborts to signal something to receiver side
+      },
+    });
+
+    let onEngineClose = async () => {
+      await writer.close();
+    };
+
+    engine.once(EngineEvent.Closing, onEngineClose);
+
+    const writer = new TextStreamWriter(writableStream, info, () =>
+      this.engine.off(EngineEvent.Closing, onEngineClose),
+    );
+
+    return writer;
+  }
+
+  async sendFile(file: File, options?: SendFileOptions): Promise<{ id: string }> {
+    const streamId = crypto.randomUUID();
+    await this._sendFile(streamId, file, options);
+    return { id: streamId };
+  }
+
+  private async _sendFile(streamId: string, file: File, options?: SendFileOptions) {
+    const writer = await this.streamBytes({
+      streamId,
+      totalSize: file.size,
+      name: file.name,
+      mimeType: options?.mimeType ?? file.type,
+      topic: options?.topic,
+      destinationIdentities: options?.destinationIdentities,
+    });
+    const reader = file.stream().getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      await writer.write(value);
+    }
+    await writer.close();
+    return writer.info;
+  }
+
+  async streamBytes(options?: StreamBytesOptions) {
+    const streamId = options?.streamId ?? crypto.randomUUID();
+    const destinationIdentities = options?.destinationIdentities;
+
+    const info: ByteStreamInfo = {
+      id: streamId,
+      mimeType: options?.mimeType ?? 'application/octet-stream',
+      topic: options?.topic ?? '',
+      timestamp: Date.now(),
+      attributes: options?.attributes,
+      size: options?.totalSize,
+      name: options?.name ?? 'unknown',
+    };
+
+    const header = new DataStream_Header({
+      totalLength: numberToBigInt(info.size ?? 0),
+      mimeType: info.mimeType,
+      streamId,
+      topic: info.topic,
+      timestamp: numberToBigInt(Date.now()),
+      attributes: info.attributes,
+      contentHeader: {
+        case: 'byteHeader',
+        value: new DataStream_ByteHeader({
+          name: info.name,
+        }),
+      },
+    });
+
+    const packet = new DataPacket({
+      destinationIdentities,
+      value: {
+        case: 'streamHeader',
+        value: header,
+      },
+    });
+
+    await this.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+
+    let chunkId = 0;
+    const writeMutex = new Mutex();
+    const engine = this.engine;
+    const logLocal = this.log;
+
+    const writableStream = new WritableStream<Uint8Array>({
+      async write(chunk) {
+        const unlock = await writeMutex.lock();
+
+        let byteOffset = 0;
+        try {
+          while (byteOffset < chunk.byteLength) {
+            const subChunk = chunk.slice(byteOffset, byteOffset + STREAM_CHUNK_SIZE);
+            await engine.waitForBufferStatusLow(DataPacket_Kind.RELIABLE);
+            const chunkPacket = new DataPacket({
+              destinationIdentities,
+              value: {
+                case: 'streamChunk',
+                value: new DataStream_Chunk({
+                  content: subChunk,
+                  streamId,
+                  chunkIndex: numberToBigInt(chunkId),
+                }),
+              },
+            });
+            await engine.sendDataPacket(chunkPacket, DataPacket_Kind.RELIABLE);
+            chunkId += 1;
+            byteOffset += subChunk.byteLength;
+          }
+        } finally {
+          unlock();
+        }
+      },
+      async close() {
+        const trailer = new DataStream_Trailer({
+          streamId,
+        });
+        const trailerPacket = new DataPacket({
+          destinationIdentities,
+          value: {
+            case: 'streamTrailer',
+            value: trailer,
+          },
+        });
+        await engine.sendDataPacket(trailerPacket, DataPacket_Kind.RELIABLE);
+      },
+      abort(err) {
+        logLocal.error('Sink error:', err);
+      },
+    });
+
+    const byteWriter = new ByteStreamWriter(writableStream, info);
+
+    return byteWriter;
+  }
+}

package/src/room/{StreamWriter.ts → data-stream/outgoing/StreamWriter.ts}

@@ -1,4 +1,4 @@
-import type { BaseStreamInfo, ByteStreamInfo, TextStreamInfo } from './types';
+import type { BaseStreamInfo, ByteStreamInfo, TextStreamInfo } from '../../types';
 
 class BaseStreamWriter<T, InfoType extends BaseStreamInfo> {
   protected writableStream: WritableStream<T>;

package/src/room/errors.ts

@@ -111,6 +111,40 @@ export class SignalRequestError extends LivekitError {
   }
 }
 
+// NOTE: matches with https://github.com/livekit/client-sdk-swift/blob/f37bbd260d61e165084962db822c79f995f1a113/Sources/LiveKit/DataStream/StreamError.swift#L17
+export enum DataStreamErrorReason {
+  // Unable to open a stream with the same ID more than once.
+  AlreadyOpened = 0,
+
+  // Stream closed abnormally by remote participant.
+  AbnormalEnd = 1,
+
+  // Incoming chunk data could not be decoded.
+  DecodeFailed = 2,
+
+  // Read length exceeded total length specified in stream header.
+  LengthExceeded = 3,
+
+  // Read length less than total length specified in stream header.
+  Incomplete = 4,
+
+  // Unable to register a stream handler more than once.
+  HandlerAlreadyRegistered = 7,
+}
+
+export class DataStreamError extends LivekitError {
+  reason: DataStreamErrorReason;
+
+  reasonName: string;
+
+  constructor(message: string, reason: DataStreamErrorReason) {
+    super(16, message);
+    this.name = 'DataStreamError';
+    this.reason = reason;
+    this.reasonName = DataStreamErrorReason[reason];
+  }
+}
+
 export enum MediaDeviceFailure {
   // user rejected permissions
   PermissionDenied = 'PermissionDenied',