livekit-client 2.17.2 → 2.18.0

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

@@ -1,7 +1,7 @@
 import type { DataStream_Chunk } from '@livekit/protocol';
 import { DataStreamError, DataStreamErrorReason } from '../../errors';
 import type { BaseStreamInfo, ByteStreamInfo, TextStreamInfo } from '../../types';
-import { Future, bigIntToNumber } from '../../utils';
+import { bigIntToNumber } from '../../utils';
 
 export type BaseStreamReaderReadAllOpts = {
   /** An AbortSignal can be used to terminate reads early. */
@@ -17,8 +17,6 @@ abstract class BaseStreamReader<T extends BaseStreamInfo> {
 
   protected bytesReceived: number;
 
-  protected outOfBandFailureRejectingFuture?: Future<never, Error>;
-
   get info() {
     return this._info;
   }
@@ -42,17 +40,11 @@ abstract class BaseStreamReader<T extends BaseStreamInfo> {
     }
   }
 
-  constructor(
-    info: T,
-    stream: ReadableStream<DataStream_Chunk>,
-    totalByteSize?: number,
-    outOfBandFailureRejectingFuture?: Future<never, Error>,
-  ) {
+  constructor(info: T, stream: ReadableStream<DataStream_Chunk>, totalByteSize?: number) {
     this.reader = stream;
     this.totalByteSize = totalByteSize;
     this._info = info;
     this.bytesReceived = 0;
-    this.outOfBandFailureRejectingFuture = outOfBandFailureRejectingFuture;
   }
 
   protected abstract handleChunkReceived(chunk: DataStream_Chunk): void;
@@ -79,48 +71,44 @@ export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
 
   [Symbol.asyncIterator]() {
     const reader = this.reader.getReader();
-
-    let rejectingSignalFuture = new Future<never, Error>();
-    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;
-    }
+    // Suppress unhandled rejection on reader.closed — errors are
+    // already propagated through reader.read() to the consumer.
+    reader.closed.catch(() => {});
 
     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) {
+          const signal = this.signal;
+          if (signal?.aborted) {
+            throw signal.reason;
+          }
+          const result = await new Promise<ReadableStreamReadResult<DataStream_Chunk>>(
+            (resolve, reject) => {
+              if (signal) {
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener('abort', onAbort, { once: true });
+                reader
+                  .read()
+                  .then(resolve, reject)
+                  .finally(() => {
+                    signal.removeEventListener('abort', onAbort);
+                  });
+              } else {
+                reader.read().then(resolve, reject);
+              }
+            },
+          );
+          if (result.done) {
             this.validateBytesReceived(true);
             return { done: true, value: undefined as any };
           } else {
-            this.handleChunkReceived(value);
-            return { done: false, value: value.content };
+            this.handleChunkReceived(result.value);
+            return { done: false, value: result.value.content };
           }
         } catch (err) {
           cleanup();
@@ -175,9 +163,8 @@ export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
     info: TextStreamInfo,
     stream: ReadableStream<DataStream_Chunk>,
     totalChunkCount?: number,
-    outOfBandFailureRejectingFuture?: Future<never, Error>,
   ) {
-    super(info, stream, totalChunkCount, outOfBandFailureRejectingFuture);
+    super(info, stream, totalChunkCount);
     this.receivedChunks = new Map();
   }
 
@@ -211,55 +198,51 @@ export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
    */
   [Symbol.asyncIterator]() {
     const reader = this.reader.getReader();
+    // Suppress unhandled rejection on reader.closed — errors are
+    // already propagated through reader.read() to the consumer.
+    reader.closed.catch(() => {});
     const decoder = new TextDecoder('utf-8', { fatal: true });
-
-    let rejectingSignalFuture = new Future<never, Error>();
-    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 signal = this.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) {
+          if (signal?.aborted) {
+            throw signal.reason;
+          }
+          const result = await new Promise<ReadableStreamReadResult<DataStream_Chunk>>(
+            (resolve, reject) => {
+              if (signal) {
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener('abort', onAbort, { once: true });
+                reader
+                  .read()
+                  .then(resolve, reject)
+                  .finally(() => {
+                    signal.removeEventListener('abort', onAbort);
+                  });
+              } else {
+                reader.read().then(resolve, reject);
+              }
+            },
+          );
+          if (result.done) {
             this.validateBytesReceived(true);
             return { done: true, value: undefined };
           } else {
-            this.handleChunkReceived(value);
+            this.handleChunkReceived(result.value);
 
             let decodedResult;
             try {
-              decodedResult = decoder.decode(value.content);
+              decodedResult = decoder.decode(result.value.content);
             } catch (err) {
               throw new DataStreamError(
-                `Cannot decode datastream chunk ${value.chunkIndex} as text: ${err}`,
+                `Cannot decode datastream chunk ${result.value.chunkIndex} as text: ${err}`,
                 DataStreamErrorReason.DecodeFailed,
               );
             }

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

@@ -114,7 +114,7 @@ export default class OutgoingDataStreamManager {
       mimeType: info.mimeType,
       topic: info.topic,
       timestamp: numberToBigInt(info.timestamp),
-      totalLength: numberToBigInt(options?.totalSize),
+      totalLength: numberToBigInt(info.size),
       attributes: info.attributes,
       contentHeader: {
         case: 'textHeader',
@@ -240,7 +240,7 @@ export default class OutgoingDataStreamManager {
     };
 
     const header = new DataStream_Header({
-      totalLength: numberToBigInt(info.size ?? 0),
+      totalLength: numberToBigInt(info.size),
       mimeType: info.mimeType,
       streamId,
       topic: info.topic,

package/src/room/data-track/LocalDataTrack.ts

@@ -0,0 +1,53 @@
+import type { DataTrackFrame } from './frame';
+import type OutgoingDataTrackManager from './outgoing/OutgoingDataTrackManager';
+import {
+  DataTrackSymbol,
+  type IDataTrack,
+  type ILocalTrack,
+  TrackSymbol,
+} from './track-interfaces';
+import type { DataTrackInfo } from './types';
+
+export default class LocalDataTrack implements ILocalTrack, IDataTrack {
+  readonly trackSymbol = TrackSymbol;
+
+  readonly isLocal = true;
+
+  readonly typeSymbol = DataTrackSymbol;
+
+  info: DataTrackInfo;
+
+  protected manager: OutgoingDataTrackManager;
+
+  /** @internal */
+  constructor(info: DataTrackInfo, manager: OutgoingDataTrackManager) {
+    this.info = info;
+    this.manager = manager;
+  }
+
+  /** The raw descriptor from the manager containing the internal state for this local track. */
+  protected get descriptor() {
+    return this.manager.getDescriptor(this.info.pubHandle);
+  }
+
+  isPublished() {
+    return this.descriptor?.type === 'active';
+  }
+
+  /** Try pushing a frame to subscribers of the track.
+   *
+   * Pushing a frame can fail for several reasons:
+   *
+   * - The track has been unpublished by the local participant or SFU
+   * - The room is no longer connected
+   */
+  tryPush(payload: DataTrackFrame['payload']) {
+    try {
+      return this.manager.tryProcessAndSend(this.info.pubHandle, payload);
+    } catch (err) {
+      // NOTE: wrapping in the bare try/catch like this means that the Throws<...> type doesn't
+      // propegate upwards into the public interface.
+      throw err;
+    }
+  }
+}

package/src/room/data-track/RemoteDataTrack.ts

@@ -0,0 +1,82 @@
+import type Participant from '../participant/Participant';
+import type { DataTrackFrame } from './frame';
+import type IncomingDataTrackManager from './incoming/IncomingDataTrackManager';
+import {
+  DataTrackSymbol,
+  type IDataTrack,
+  type IRemoteTrack,
+  TrackSymbol,
+} from './track-interfaces';
+import { type DataTrackInfo } from './types';
+
+type RemoteDataTrackOptions = {
+  publisherIdentity: Participant['identity'];
+};
+
+export type RemoteDataTrackSubscribeOptions = {
+  signal?: AbortSignal;
+
+  /** The number of {@link DataTrackFrame}s to hold in the ReadableStream before disgarding extra
+   * frames. Defaults to 4, but this may not be good enough for especially high frequency data. */
+  highWaterMark?: number;
+};
+
+export default class RemoteDataTrack implements IRemoteTrack, IDataTrack {
+  readonly trackSymbol = TrackSymbol;
+
+  readonly isLocal = false;
+
+  readonly typeSymbol = DataTrackSymbol;
+
+  info: DataTrackInfo;
+
+  publisherIdentity: Participant['identity'];
+
+  protected manager: IncomingDataTrackManager;
+
+  /** @internal */
+  constructor(
+    info: DataTrackInfo,
+    manager: IncomingDataTrackManager,
+    options: RemoteDataTrackOptions,
+  ) {
+    this.info = info;
+    this.manager = manager;
+    this.publisherIdentity = options.publisherIdentity;
+  }
+
+  /** Subscribes to the data track to receive frames.
+   *
+   * # Returns
+   *
+   * A stream that yields {@link DataTrackFrame}s as they arrive.
+   *
+   * # Multiple Subscriptions
+   *
+   * An application may call `subscribe` more than once to process frames in
+   * multiple places. For example, one async task might plot values on a graph
+   * while another writes them to a file.
+   *
+   * Internally, only the first call to `subscribe` communicates with the SFU and
+   * allocates the resources required to receive frames. Additional subscriptions
+   * reuse the same underlying pipeline and do not trigger additional signaling.
+   *
+   * Note that newly created subscriptions only receive frames published after
+   * the initial subscription is established.
+   */
+  async subscribe(
+    options?: RemoteDataTrackSubscribeOptions,
+  ): Promise<ReadableStream<DataTrackFrame>> {
+    try {
+      const stream = await this.manager.subscribeRequest(
+        this.info.sid,
+        options?.signal,
+        options?.highWaterMark,
+      );
+      return stream;
+    } catch (err) {
+      // NOTE: Rethrow errors to break Throws<...> type boundary
+      throw err;
+    }
+  }
+}

package/src/room/data-track/depacketizer.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { DataTrackDepacketizer } from './depacketizer';
+import DataTrackDepacketizer from './depacketizer';
 import { DataTrackHandle } from './handle';
 import { DataTrackPacket, DataTrackPacketHeader, FrameMarker } from './packet';
 import { DataTrackTimestamp, WrapAroundUnsignedInt } from './utils';

package/src/room/data-track/depacketizer.ts

@@ -1,5 +1,5 @@
+import { type Throws } from '@livekit/throws-transformer/throws';
 import { LoggerNames, getLogger } from '../../logger';
-import { type Throws } from '../../utils/throws';
 import { LivekitReasonedError } from '../errors';
 import { type DataTrackFrame } from './frame';
 import { DataTrackPacket, FrameMarker } from './packet';
@@ -21,7 +21,7 @@ type PartialFrame = {
 
 /** An error indicating a frame was dropped. */
 export class DataTrackDepacketizerDropError<
-  Reason extends DataTrackDepacketizerDropReason,
+  Reason extends DataTrackDepacketizerDropReason = DataTrackDepacketizerDropReason,
 > extends LivekitReasonedError<Reason> {
   readonly name = 'DataTrackDepacketizerDropError';
 
@@ -85,7 +85,7 @@ type PushOptions = {
   errorOnPartialFrames: boolean;
 };
 
-export class DataTrackDepacketizer {
+export default class DataTrackDepacketizer {
   /** Maximum number of packets to buffer per frame before dropping. */
   static MAX_BUFFER_PACKETS = 128;
 
@@ -99,13 +99,7 @@ export class DataTrackDepacketizer {
   push(
     packet: DataTrackPacket,
     options?: PushOptions,
-  ): Throws<
-    DataTrackFrame | null,
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Interrupted>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.BufferFull>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.UnknownFrame>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Incomplete>
-  > {
+  ): Throws<DataTrackFrame | null, DataTrackDepacketizerDropError> {
     switch (packet.header.marker) {
       case FrameMarker.Single:
         return this.frameFromSingle(packet, options);
@@ -191,13 +185,7 @@ export class DataTrackDepacketizer {
   /** Push to the existing partial frame. */
   private pushToPartial(
     packet: DataTrackPacket,
-  ): Throws<
-    DataTrackFrame | null,
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Interrupted>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.UnknownFrame>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.BufferFull>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Incomplete>
-  > {
+  ): Throws<DataTrackFrame | null, DataTrackDepacketizerDropError> {
     if (packet.header.marker !== FrameMarker.Inter && packet.header.marker !== FrameMarker.Final) {
       // @throws-transformer ignore - this should be treated as a "panic" and not be caught
       throw new Error(

package/src/room/data-track/e2ee.ts

@@ -0,0 +1,15 @@
+export type EncryptedPayload = {
+  payload: Uint8Array;
+  iv: Uint8Array; // NOTE: should be 12 bytes long
+  keyIndex: number;
+};
+
+export type EncryptionProvider = {
+  // FIXME: add in explicit `Throws<..., EncryptionError>`?
+  encrypt(payload: Uint8Array): EncryptedPayload;
+};
+
+export type DecryptionProvider = {
+  // FIXME: add in explicit `Throws<..., DecryptionError>`?
+  decrypt(payload: EncryptedPayload, senderIdentity: string): Uint8Array;
+};

package/src/room/data-track/frame.ts

@@ -1,5 +1,5 @@
 import { DataTrackExtensions } from './packet/extensions';
-import { DataTrackPacketizer } from './packetizer';
+import DataTrackPacketizer from './packetizer';
 
 /** A pair of payload bytes and packet extensions which can be fed into a {@link DataTrackPacketizer}. */
 export type DataTrackFrame = {

package/src/room/data-track/handle.test.ts

@@ -4,7 +4,7 @@ import { DataTrackHandle } from './handle';
 
 describe('DataTrackHandle', () => {
   it('should parse handle raw inputs', () => {
-    expect(DataTrackHandle.fromNumber(3).value).toEqual(3);
+    expect(DataTrackHandle.fromNumber(3)).toEqual(3);
     expect(() => DataTrackHandle.fromNumber(0)).toThrow('0x0 is a reserved value');
     expect(() => DataTrackHandle.fromNumber(9999999)).toThrow(
       'Value too large to be a valid track handle',

package/src/room/data-track/handle.ts

@@ -1,4 +1,4 @@
-import { type Throws } from '../../utils/throws';
+import { type Throws } from '@livekit/throws-transformer/throws';
 import { LivekitReasonedError } from '../errors';
 import { U16_MAX_SIZE } from './utils';
 
@@ -41,40 +41,29 @@ export class DataTrackHandleError<
   }
 }
 
-export class DataTrackHandle {
-  public value: number;
-
-  static fromNumber(
-    raw: number,
-  ): Throws<
-    DataTrackHandle,
-    | DataTrackHandleError<DataTrackHandleErrorReason.TooLarge>
-    | DataTrackHandleError<DataTrackHandleErrorReason.Reserved>
-  > {
+export type DataTrackHandle = number;
+export const DataTrackHandle = {
+  fromNumber(raw: number): Throws<DataTrackHandle, DataTrackHandleError> {
     if (raw === 0) {
       throw DataTrackHandleError.reserved(raw);
     }
     if (raw > U16_MAX_SIZE) {
       throw DataTrackHandleError.tooLarge();
     }
-    return new DataTrackHandle(raw);
-  }
-
-  constructor(raw: number) {
-    this.value = raw;
-  }
-}
+    return raw;
+  },
+};
 
 /** Manage allocating new handles which don't conflict over the lifetime of the client. */
 export class DataTrackHandleAllocator {
-  static value = 0;
+  value = 0;
 
   /** Returns a unique track handle for the next publication, if one can be obtained. */
-  static get(): DataTrackHandle | null {
+  get(): DataTrackHandle | null {
     this.value += 1;
     if (this.value > U16_MAX_SIZE) {
       return null;
     }
-    return new DataTrackHandle(this.value);
+    return this.value;
   }
 }