livekit-client 2.20.2 → 2.21.0

package/src/room/data-channel/ReliableDataChannel.ts

@@ -0,0 +1,153 @@
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
+import { DataPacketBuffer } from '../../utils/dataPacketBuffer';
+import {
+  FlowControlledDataChannel,
+  type FlowControlledDataChannelOptions,
+} from './FlowControlledDataChannel';
+
+export interface ReliableDataChannelOptions extends FlowControlledDataChannelOptions {
+  /**
+   * Whether sends should currently be deferred to the resume replay instead of hitting the wire
+   * (i.e. a reconnect attempt is underway). Read at send time so the reliable channel matches the
+   * engine's reconnect state without owning it.
+   */
+  isDeferringSends: () => boolean;
+}
+
+/**
+ * The reliable channel: flow control plus delivery-across-resume semantics.
+ *
+ * Every packet gets a monotonic sequence (stamped into the protobuf by the caller before
+ * serialization, via {@link nextSequence}) and is retained in a replay buffer until the channel's
+ * `bufferedAmount` confirms it has been handed to the transport. Sends that land in a reconnect
+ * window — or whose headroom wait is torn down transiently — are queued unsent and resolve;
+ * {@link replay} delivers them (plus any unacked packets) after a resume. Only an engine close
+ * rejects, because no replay is coming after that.
+ */
+export class ReliableDataChannel extends FlowControlledDataChannel {
+  private messageBuffer = new DataPacketBuffer();
+
+  private sequence = 1;
+
+  private isDeferringSends: () => boolean;
+
+  constructor(opts: ReliableDataChannelOptions) {
+    super(opts);
+    this.isDeferringSends = opts.isDeferringSends;
+  }
+
+  /**
+   * Claims the next packet sequence. The caller stamps it into the packet before serialization,
+   * then passes it back to {@link send} so the replay buffer stays keyed by wire sequence.
+   */
+  nextSequence(): number {
+    const sequence = this.sequence;
+    this.sequence += 1;
+    return sequence;
+  }
+
+  /**
+   * Sends prepared bytes with reliable semantics. Resolves once the packet has either been handed
+   * to the channel or queued for the resume replay; throws only when the engine is closed.
+   */
+  async send(msg: NonSharedUint8Array, sequence: number) {
+    if (this.isDeferringSends()) {
+      // A reconnect is already underway — queue for the resume replay instead of parking on a
+      // channel that is being torn down. The send resolves; delivery is deferred to the replay.
+      this.messageBuffer.push({ data: msg, sequence, sent: false });
+      return;
+    }
+
+    const dc = this.getChannel();
+    if (!dc) {
+      return;
+    }
+
+    try {
+      await this.waitForHeadroomWithLock();
+    } catch (error) {
+      if (this.isEngineClosed()) {
+        // No replay is coming after an engine close — surface the failure.
+        throw error;
+      }
+      // Transient teardown (the channel closed or was replaced while we waited): the reliable
+      // channel promises delivery across resume, so queue the packet for the replay instead of
+      // rejecting a send the app can't meaningfully retry.
+      this.messageBuffer.push({ data: msg, sequence, sent: false });
+      return;
+    }
+
+    if (this.isDeferringSends()) {
+      // A reconnect began while we waited for headroom — same deal as above.
+      this.messageBuffer.push({ data: msg, sequence, sent: false });
+      return;
+    }
+
+    this.messageBuffer.push({ data: msg, sequence, sent: true });
+    dc.send(msg);
+    this.refreshBufferStatus();
+  }
+
+  /**
+   * Replays the buffered backlog after a resume: drops everything the server acked
+   * (`lastMessageSeq`), then re-sends the rest in order. The headroom lock is held across the
+   * whole replay — releasing it between messages would let a concurrent send (whose newer
+   * sequence was already assigned before it queued on the lock) hit the wire mid-replay, and
+   * receivers would then discard the remaining lower-sequence resent messages as duplicates.
+   */
+  async replay(lastMessageSeq: number) {
+    const dc = this.getChannel();
+    if (!dc) {
+      return;
+    }
+    this.messageBuffer.popToSequence(lastMessageSeq);
+    const unlock = await this.lockHeadroom();
+    try {
+      // Everything left after the ack cutoff must be re-handed to the current channel.
+      this.messageBuffer.markAllUnsent();
+      // Drain in passes, re-scanning the live buffer each time: a send that arrives (deferred,
+      // sent:false) during our own awaits appends after this pass started, so we pick it up on
+      // the next one. Mark each packet only once we've actually handed it to the channel — a
+      // blanket "mark all sent" would flip such a late arrival to sent without transmitting it,
+      // and a later alignBufferedAmount would then drop it for good. If the loop throws
+      // mid-drain, unsent entries keep their flag and the next replay picks them up.
+      for (
+        let batch = this.messageBuffer.getUnsent();
+        batch.length > 0;
+        batch = this.messageBuffer.getUnsent()
+      ) {
+        for (const item of batch) {
+          // Respect flow control on resume too, so a large resend doesn't overflow the buffer.
+          await this.waitForHeadroomWithoutLock();
+          dc.send(item.data);
+          this.messageBuffer.markSent(item);
+        }
+      }
+    } finally {
+      unlock();
+    }
+    this.refreshBufferStatus();
+  }
+
+  /**
+   * Before recomputing status, trim packets the transport has now delivered — a send or a drain
+   * may have acked buffered packets, and the replay buffer is keyed off the channel's buffered
+   * bytes.
+   */
+  override refreshBufferStatus() {
+    const dc = this.channelHandle;
+    if (dc) {
+      this.messageBuffer.alignBufferedAmount(dc.bufferedAmount);
+    }
+    super.refreshBufferStatus();
+  }
+
+  /**
+   * Drops all replay state and restarts sequencing. Only valid on a full reconnect, where the
+   * session (and the receivers' sequence tracking) starts over.
+   */
+  reset() {
+    this.messageBuffer = new DataPacketBuffer();
+    this.sequence = 1;
+  }
+}

package/src/room/data-channel/types.ts

@@ -0,0 +1,30 @@
+import { DataPacket_Kind } from '@livekit/protocol';
+
+export enum DataChannelKind {
+  RELIABLE = DataPacket_Kind.RELIABLE,
+  LOSSY = DataPacket_Kind.LOSSY,
+  DATA_TRACK_LOSSY = 2,
+}
+
+// Two-watermark flow control for the reliable and data-track channels. Senders fill the buffer
+// freely up to the high-water mark; once it's exceeded they block until the browser's
+// `bufferedamountlow` event (which we arm at the low-water mark) signals the buffer has drained.
+// The gap between the marks keeps the SCTP send buffer saturated while we refill, so throughput
+// isn't starved, while the high-water mark bounds the buffer well below the level that would abort
+// the channel (see livekit/client-sdk-js#1995).
+export const reliableDataChannelWaterMarkLow = 64 * 1024;
+export const reliableDataChannelWaterMarkHigh = 1024 * 1024;
+export const lossyDataChannelWaterMarkLow = 8 * 1024;
+export const lossyDataChannelWaterMarkHigh = 256 * 1024;
+
+export function dataChannelLowWaterMark(kind: DataChannelKind): number {
+  return kind === DataChannelKind.RELIABLE
+    ? reliableDataChannelWaterMarkLow
+    : lossyDataChannelWaterMarkLow;
+}
+
+export function dataChannelHighWaterMark(kind: DataChannelKind): number {
+  return kind === DataChannelKind.RELIABLE
+    ? reliableDataChannelWaterMarkHigh
+    : lossyDataChannelWaterMarkHigh;
+}

package/src/room/data-stream/compression.ts

@@ -0,0 +1,117 @@
+/**
+ * Compression helpers for data streams. The buffered deflate-raw variant ({@link deflateRawCompress})
+ * is for the inline (single-packet) case where the payload is small and bounded;
+ * {@link deflateRawTransform} / {@link inflateRawTransform} serve the chunked (multi-packet)
+ * `sendText`/`sendBytes`/`sendFile` paths, streaming the bytes through without buffering the whole
+ * payload.
+ *
+ * These operate on bytes (not strings) so a single set of helpers serves both text and byte streams;
+ * the `TextEncoder`/`TextDecoder` boundary lives at the manager/reader edges.
+ *
+ * Both streaming variants are exposed as `ReadableWritablePair`s so they drop straight into a
+ * `pipeThrough` chain. Each needs one localized cast to bridge a DOM lib-type mismatch: the platform
+ * `CompressionStream`/`DecompressionStream` type their `writable` as `WritableStream<BufferSource>`
+ * (a wider element type than `Uint8Array`), and `WritableStream<W>` is covariant in `W`, so neither
+ * is structurally a `ReadableWritablePair<Uint8Array, Uint8Array>` without help.
+ *
+ * @internal
+ */
+import { type NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
+import { DataStreamError, DataStreamErrorReason } from '../errors';
+
+/**
+ * A `deflate-raw` compression transform (inverse of {@link inflateRawTransform}): pipe a byte stream
+ * through it to get the compressed bytes without buffering the whole payload. Used for the chunked
+ * `sendText`/`sendBytes`/`sendFile` paths, where the full payload is known up front but is streamed
+ * (e.g. from `file.stream()`) rather than held in memory.
+ */
+export function deflateRawTransform(): ReadableWritablePair<
+  NonSharedUint8Array,
+  NonSharedUint8Array
+> {
+  return new CompressionStream('deflate-raw') as unknown as ReadableWritablePair<
+    NonSharedUint8Array,
+    NonSharedUint8Array
+  >;
+}
+
+/**
+ * A `deflate-raw` decompression transform (inverse of {@link deflateRawTransform}): pipe a
+ * stream of compressed bytes through it to get the decompressed bytes. Inflate emits output greedily,
+ * so as long as the sender flushed at write boundaries each write's content is produced as soon as
+ * its compressed bytes arrive.
+ */
+export function inflateRawTransform(): ReadableWritablePair<
+  NonSharedUint8Array,
+  NonSharedUint8Array
+> {
+  return new DecompressionStream('deflate-raw') as unknown as ReadableWritablePair<
+    NonSharedUint8Array,
+    NonSharedUint8Array
+  >;
+}
+
+/** deflate-raw compresses a byte array in full. Use for inline payloads; prefer the streaming
+ * path for the chunked case. */
+export async function deflateRawCompress(data: NonSharedUint8Array): Promise<NonSharedUint8Array> {
+  const cs = new CompressionStream('deflate-raw');
+  const writer = cs.writable.getWriter();
+  writer.write(data as NonSharedUint8Array);
+  writer.close();
+  return collect(cs.readable);
+}
+
+/**
+ * Decompresses a raw-deflate byte array in full (inverse of {@link deflateRawCompress}).
+ * `maxByteLength` bounds the decompressed output (decompression-bomb guard); exceeding it rejects
+ * with a `PayloadTooLarge` error.
+ */
+export async function deflateRawDecompress(
+  data: NonSharedUint8Array,
+  maxByteLength?: number,
+): Promise<NonSharedUint8Array> {
+  const ds = new DecompressionStream('deflate-raw');
+  const writer = ds.writable.getWriter();
+  // The writer promises are intentionally not awaited (output is consumed via `collect`), but
+  // they reject when the byte cap cancels the readable mid-stream — swallow that so an enforced
+  // cap doesn't surface as an unhandled rejection.
+  writer.write(data as NonSharedUint8Array).catch(() => {});
+  writer.close().catch(() => {});
+  return collect(ds.readable, maxByteLength);
+}
+
+/**
+ * Drains a byte stream, concatenating all of its chunks into a single array. When
+ * `maxByteLength` is given, drops the stream and throws `PayloadTooLarge` as soon as the
+ * accumulated output exceeds it.
+ */
+export async function collect(
+  stream: ReadableStream<NonSharedUint8Array>,
+  maxByteLength?: number,
+): Promise<NonSharedUint8Array> {
+  const reader = stream.getReader();
+  const chunks: Array<NonSharedUint8Array> = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    chunks.push(value);
+    total += value.byteLength;
+    if (typeof maxByteLength === 'number' && total > maxByteLength) {
+      await reader.cancel();
+      throw new DataStreamError(
+        `Decompressed payload exceeds the maximum payload size of ${maxByteLength} bytes`,
+        DataStreamErrorReason.PayloadTooLarge,
+      );
+    }
+  }
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}

package/src/room/data-stream/constants.ts

@@ -0,0 +1,18 @@
+/**
+ * Maximum size of a single data-stream chunk in bytes, and the budget used to decide whether a
+ * payload can be sent inline as a single header packet. Kept below the ~16k data-channel MTU to
+ * leave headroom for protocol framing and E2EE overhead.
+ *
+ * @internal
+ */
+export const STREAM_CHUNK_SIZE_BYTES = 15_000;
+
+/**
+ * Default cap on the number of decompressed bytes a single incoming compressed data stream may
+ * produce (5 GB). A tiny compressed payload can inflate to an arbitrarily large output
+ * (decompression bomb), so the decompressor's output is bounded rather than trusting the wire
+ * size; streams exceeding the cap error with `PayloadTooLarge`.
+ *
+ * @internal
+ */
+export const DEFAULT_MAX_PAYLOAD_BYTE_LENGTH = 5_000_000_000;