livekit-client 2.20.2 → 2.21.0

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

@@ -0,0 +1,216 @@
+import { Mutex } from '@livekit/mutex';
+import TypedPromise from '../../utils/TypedPromise';
+import { UnexpectedConnectionState } from '../errors';
+import type { DataChannelKind } from './types';
+
+export interface FlowControlledDataChannelOptions {
+  kind: DataChannelKind;
+  /** Buffer level (bytes) at which blocked senders resume; armed as `bufferedAmountLowThreshold`. */
+  lowWaterMark: number;
+  /** Buffer level (bytes) above which senders block until the buffer drains to the low mark. */
+  highWaterMark: number;
+  /** Whether the owning engine has been closed — a closed engine rejects waiters immediately. */
+  isEngineClosed: () => boolean;
+  /**
+   * Notified when the buffer crosses the low-water mark in either direction (debounced: fires only
+   * on an actual change). Drives the engine's public DCBufferStatusChanged event.
+   */
+  onBufferStatusChanged?: (isLow: boolean) => void;
+}
+
+/**
+ * Two-watermark flow control for one data channel kind.
+ *
+ * Owns the per-kind headroom gate: senders proceed freely while the buffer is at or below the
+ * high-water mark and otherwise block — serialized FIFO through a mutex — until the browser's
+ * `bufferedamountlow` event (armed at the low-water mark) signals the buffer has drained. The
+ * serialization prevents woken senders from all refilling at once and overflowing the SCTP send
+ * buffer (see livekit/client-sdk-js#1995).
+ *
+ * Waiters are parked on the channel object captured at wait entry. If that object stops being
+ * current — replaced or torn down — its events may never fire again, so the owner must call
+ * {@link invalidateWaiters}, which aborts parked waiters (releasing the gate); the next waiter
+ * gets a fresh controller.
+ */
+export class FlowControlledDataChannel {
+  readonly kind: DataChannelKind;
+
+  readonly lowWaterMark: number;
+
+  readonly highWaterMark: number;
+
+  protected isEngineClosed: () => boolean;
+
+  private onBufferStatusChanged?: (isLow: boolean) => void;
+
+  /** Last emitted low-water status; starts true (an empty buffer is below the mark). */
+  private bufferStatusLow = true;
+
+  private handle?: RTCDataChannel;
+
+  private headroomLock = new Mutex();
+
+  /** Cancels parked headroom waiters when the handle is replaced or torn down. */
+  private waiterAbortController = new AbortController();
+
+  constructor(opts: FlowControlledDataChannelOptions) {
+    this.kind = opts.kind;
+    this.lowWaterMark = opts.lowWaterMark;
+    this.highWaterMark = opts.highWaterMark;
+    this.isEngineClosed = opts.isEngineClosed;
+    this.onBufferStatusChanged = opts.onBufferStatusChanged;
+  }
+
+  /** The currently attached RTCDataChannel handle, if any. */
+  get channelHandle(): RTCDataChannel | undefined {
+    return this.handle;
+  }
+
+  /**
+   * Attaches the channel handle this wrapper controls. Replacing an existing handle rejects
+   * parked waiters — their events would never fire again on the abandoned object — and installs a
+   * fresh controller, so queued senders re-check against the new channel. Wrappers outlive their
+   * handles: this is the one place handle turnover happens, which is what makes stranding a
+   * waiter structurally impossible.
+   */
+  attach(dc: RTCDataChannel) {
+    if (this.handle && this.handle !== dc) {
+      this.invalidateWaiters('data channel replaced');
+    }
+    this.handle = dc;
+  }
+
+  /** Detaches the handle on teardown, rejecting parked waiters. */
+  detach(reason: string = 'data channel torn down') {
+    if (this.handle) {
+      this.invalidateWaiters(reason);
+    }
+    this.handle = undefined;
+  }
+
+  protected getChannel(): RTCDataChannel | undefined {
+    return this.handle;
+  }
+
+  /**
+   * Whether the send buffer has room to accept more data (the send gate). Senders proceed while
+   * this is true and block once it goes false. Callers resolve the handle (and decide what an
+   * absent one means) before asking.
+   */
+  isBelowHighWaterMark(dc: RTCDataChannel): boolean {
+    // RTCDataChannel has no built-in high-water mark, so we compare against our static mark.
+    return dc.bufferedAmount <= this.highWaterMark;
+  }
+
+  /**
+   * Whether the send buffer has drained to its low-water mark. Drives the engine's public
+   * DCBufferStatusChanged event.
+   */
+  isBelowLowWaterMark(dc: RTCDataChannel): boolean {
+    // Read the channel's own threshold: it is tuned dynamically for the lossy channel.
+    return dc.bufferedAmount <= dc.bufferedAmountLowThreshold;
+  }
+
+  /**
+   * Acquires the headroom lock, resolving with the unlock function. Batch senders (the resume
+   * replay) hold it across all of their sends so no other sender can interleave, calling
+   * {@link waitForHeadroomWithoutLock} per message to respect flow control within the batch.
+   */
+  lockHeadroom(): Promise<() => void> {
+    return this.headroomLock.lock();
+  }
+
+  /**
+   * Resolves once the caller may send on this channel: immediately while the send buffer is at or
+   * below its high-water mark, otherwise once the buffer has drained to the low-water mark (the
+   * `bufferedamountlow` event). Callers are serialized through the headroom lock so that, when
+   * the buffer drains, they refill it one at a time (up to the high-water mark) rather than all
+   * sending at once and overflowing the SCTP send buffer (see livekit/client-sdk-js#1995). The
+   * closed/buffer checks run inside the lock so queued callers proceed in FIFO order.
+   */
+  async waitForHeadroomWithLock() {
+    const unlock = await this.lockHeadroom();
+    try {
+      await this.waitForHeadroomWithoutLock();
+    } finally {
+      unlock();
+    }
+  }
+
+  /** Core wait of {@link waitForHeadroomWithLock}. The caller must hold the headroom lock. */
+  async waitForHeadroomWithoutLock() {
+    if (this.isEngineClosed()) {
+      throw new UnexpectedConnectionState('engine closed');
+    }
+    const dc = this.getChannel();
+    if (!dc) {
+      throw new UnexpectedConnectionState(`DataChannel not found, kind: ${this.kind}`);
+    }
+    if (this.isBelowHighWaterMark(dc)) {
+      return;
+    }
+    const abortSignal = this.waiterAbortController.signal;
+    await new TypedPromise<void, UnexpectedConnectionState>((resolve, reject) => {
+      const onBufferedAmountLow = () => {
+        cleanup();
+        resolve();
+      };
+      const onDCClose = () => {
+        cleanup();
+        reject(
+          new UnexpectedConnectionState(
+            `DataChannel ${this.kind} closed while draining the buffer`,
+          ),
+        );
+      };
+      const onAbort = () => {
+        cleanup();
+        reject(
+          new UnexpectedConnectionState(
+            `DataChannel ${this.kind} was replaced or torn down while waiting for headroom`,
+          ),
+        );
+      };
+      const cleanup = () => {
+        dc.removeEventListener('bufferedamountlow', onBufferedAmountLow);
+        dc.removeEventListener('close', onDCClose);
+        abortSignal.removeEventListener('abort', onAbort);
+      };
+      if (abortSignal.aborted) {
+        onAbort();
+        return;
+      }
+      dc.addEventListener('bufferedamountlow', onBufferedAmountLow);
+      // Proxy along any error caused by the data channel closing while we wait.
+      dc.addEventListener('close', onDCClose);
+      // The channel object we're parked on can be abandoned without ever firing another event
+      // (e.g. the engine recreating channels); the abort is our way out.
+      abortSignal.addEventListener('abort', onAbort);
+    });
+  }
+
+  /** Rejects all parked headroom waiters; the next waiter gets a fresh controller. */
+  invalidateWaiters(reason: string) {
+    this.waiterAbortController.abort(reason);
+    this.waiterAbortController = new AbortController();
+  }
+
+  /**
+   * Recomputes whether the buffer has drained to the low-water mark and, if that changed since the
+   * last check, notifies the status listener. Two independent triggers land here: a send (which
+   * raises the buffer) and the `bufferedamountlow` drain event (which lowers it) — the latter has
+   * no send to hang the work off, which is why this is a shared entry point rather than a tail of
+   * `send`.
+   */
+  refreshBufferStatus() {
+    const dc = this.getChannel();
+    if (!dc) {
+      return;
+    }
+    const isLow = this.isBelowLowWaterMark(dc);
+    if (isLow !== this.bufferStatusLow) {
+      this.bufferStatusLow = isLow;
+      this.onBufferStatusChanged?.(isLow);
+    }
+  }
+}

package/src/room/data-channel/LossyDataChannel.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { LossyDataChannel } from './LossyDataChannel';
+import { DataChannelKind } from './types';
+
+class FakeDataChannel extends EventTarget {
+  bufferedAmount = 0;
+
+  bufferedAmountLowThreshold = 64;
+
+  send = vi.fn();
+}
+
+// Pass `dc: null` for a handle-less channel; omit it to get a fresh one. `null` (not `undefined`)
+// is deliberate — a destructuring default fills in on `undefined`, so only `null` passes through.
+function makeChannel(
+  bufferFullBehavior: 'drop' | 'wait',
+  { dc = new FakeDataChannel() }: { dc?: FakeDataChannel | null } = {},
+) {
+  const state = { engineClosed: false, skipSends: false };
+  const channel = new LossyDataChannel({
+    kind: DataChannelKind.LOSSY,
+    lowWaterMark: 64,
+    highWaterMark: 1024,
+    isEngineClosed: () => state.engineClosed,
+    bufferFullBehavior,
+    shouldSkipSends: () => state.skipSends,
+  });
+  if (dc) {
+    channel.attach(dc as unknown as RTCDataChannel);
+  }
+  const stats = channel as unknown as { statCurrentBytes: number; dropCount: number };
+  return { channel, dc, state, stats };
+}
+
+describe('LossyDataChannel', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('drop policy: sends below the threshold and counts bytes', async () => {
+    const { channel, dc, stats } = makeChannel('drop');
+    const msg = new Uint8Array(10);
+
+    await channel.send(msg);
+
+    expect(dc.send).toHaveBeenCalledWith(msg);
+    expect(stats.statCurrentBytes).toBe(10);
+  });
+
+  it('drop policy: discards while the buffer is above the dc threshold', async () => {
+    const { channel, dc, stats } = makeChannel('drop');
+    dc.bufferedAmount = 128; // above the 64-byte dc threshold
+
+    await channel.send(new Uint8Array(10));
+
+    expect(dc.send).not.toHaveBeenCalled();
+    expect(stats.dropCount).toBe(1);
+    expect(stats.statCurrentBytes).toBe(0);
+  });
+
+  it('wait policy: parks above the high-water mark instead of dropping', async () => {
+    const { channel, dc } = makeChannel('wait');
+    dc.bufferedAmount = 2048;
+    const resolved = vi.fn();
+    const send = channel.send(new Uint8Array(10)).then(resolved);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(resolved).not.toHaveBeenCalled();
+
+    dc.bufferedAmount = 0;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await send;
+    expect(dc.send).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips sends while a reconnect is underway', async () => {
+    const { channel, dc, state } = makeChannel('drop');
+    state.skipSends = true;
+
+    await channel.send(new Uint8Array(10));
+
+    expect(dc.send).not.toHaveBeenCalled();
+  });
+
+  it('tunes the dc threshold to ~100ms of observed byterate, clamped to the watermarks', async () => {
+    const { channel, dc } = makeChannel('drop');
+    channel.startThresholdTuning();
+
+    // 10_000 bytes/second → threshold byterate/10 = 1000, clamped to the 1024 high mark? No —
+    // 1000 is within [64, 1024], so it applies as-is.
+    await channel.send(new Uint8Array(10_000));
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(dc.bufferedAmountLowThreshold).toBe(1000);
+
+    // Idle second → byterate 0 → clamps up to the low-water mark.
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(dc.bufferedAmountLowThreshold).toBe(64);
+
+    channel.stopThresholdTuning();
+  });
+
+  it('stopThresholdTuning halts adjustments and resets stats', async () => {
+    const { channel, dc, stats } = makeChannel('drop');
+    channel.startThresholdTuning();
+    await channel.send(new Uint8Array(500));
+
+    channel.stopThresholdTuning();
+    expect(stats.statCurrentBytes).toBe(0);
+    expect(stats.dropCount).toBe(0);
+
+    const before = dc.bufferedAmountLowThreshold;
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(dc.bufferedAmountLowThreshold).toBe(before);
+  });
+});

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

@@ -0,0 +1,125 @@
+import log from '../../logger';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
+import CriticalTimers from '../timers';
+import {
+  FlowControlledDataChannel,
+  type FlowControlledDataChannelOptions,
+} from './FlowControlledDataChannel';
+
+export interface LossyDataChannelOptions extends FlowControlledDataChannelOptions {
+  /**
+   * What to do with a send while the buffer is full: `drop` discards it to keep latency bounded
+   * (the classic lossy channel), `wait` backpressures the producer until there is headroom (the
+   * data-track channel, whose producer decides what to skip at frame granularity).
+   */
+  bufferFullBehavior: 'drop' | 'wait';
+  /** Sends are silently discarded while this is true (a reconnect attempt is underway). */
+  shouldSkipSends: () => boolean;
+}
+
+/**
+ * A lossy channel: flow control plus a per-instance full-buffer policy.
+ *
+ * Each instance owns its own byterate stat, drop counter, and (when tuning is started) the
+ * dynamic `bufferedAmountLowThreshold` adjustment that keeps the drop gate at roughly 100ms of
+ * buffered latency. Keeping these per instance is what prevents one channel's traffic from
+ * steering another channel's policy.
+ */
+export class LossyDataChannel extends FlowControlledDataChannel {
+  private bufferFullBehavior: 'drop' | 'wait';
+
+  private shouldSkipSends: () => boolean;
+
+  private statCurrentBytes = 0;
+
+  private statByterate = 0;
+
+  private statInterval: ReturnType<typeof setInterval> | undefined;
+
+  private dropCount = 0;
+
+  constructor(opts: LossyDataChannelOptions) {
+    super(opts);
+    this.bufferFullBehavior = opts.bufferFullBehavior;
+    this.shouldSkipSends = opts.shouldSkipSends;
+  }
+
+  /** Sends prepared bytes with this channel's full-buffer policy (drop or wait). */
+  async send(msg: NonSharedUint8Array) {
+    const dc = this.getChannel();
+    if (!dc) {
+      return;
+    }
+    // Depending on the channel's policy, either drop or wait for the buffer to drain below the
+    // high-water mark before continuing.
+    switch (this.bufferFullBehavior) {
+      case 'wait':
+        if (!this.isBelowHighWaterMark(dc)) {
+          await this.waitForHeadroomWithLock();
+        }
+        break;
+      case 'drop':
+        // We check against the actual threshold on the DC here, as it is tuned dynamically.
+        if (!this.isBelowLowWaterMark(dc)) {
+          // Drop messages to reduce latency
+          this.dropCount += 1;
+          if (this.dropCount % 100 === 0) {
+            log.warn(`dropping lossy data channel messages, total dropped: ${this.dropCount}`);
+          }
+          return;
+        }
+    }
+    this.statCurrentBytes += msg.byteLength;
+
+    if (this.shouldSkipSends()) {
+      return;
+    }
+
+    try {
+      dc.send(msg);
+      this.refreshBufferStatus();
+    } catch (error: unknown) {
+      // Preserve prior surface behaviour: a send that fails because the channel is closing is
+      // logged, not thrown, so lossy/data-track sends don't reject during teardown windows.
+      if (error instanceof TypeError) {
+        log.error(error);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Starts the once-per-second adjustment of the channel's `bufferedAmountLowThreshold` to the
+   * observed byterate, keeping the drop gate at roughly 100ms of buffered latency (clamped to
+   * the watermarks). Restarts cleanly if already running.
+   */
+  startThresholdTuning() {
+    this.stopThresholdTuning();
+    this.statInterval = CriticalTimers.setInterval(() => {
+      this.statByterate = this.statCurrentBytes;
+      this.statCurrentBytes = 0;
+
+      const dc = this.getChannel();
+      if (dc) {
+        // control buffered latency to ~100ms
+        const threshold = this.statByterate / 10;
+        dc.bufferedAmountLowThreshold = Math.min(
+          Math.max(threshold, this.lowWaterMark),
+          this.highWaterMark,
+        );
+      }
+    }, 1000);
+  }
+
+  /** Stops the threshold tuning and resets the stats and drop counter. */
+  stopThresholdTuning() {
+    this.statByterate = 0;
+    this.statCurrentBytes = 0;
+    if (this.statInterval) {
+      CriticalTimers.clearInterval(this.statInterval);
+      this.statInterval = undefined;
+    }
+    this.dropCount = 0;
+  }
+}

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

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from 'vitest';
+import { UnexpectedConnectionState } from '../errors';
+import { ReliableDataChannel } from './ReliableDataChannel';
+import { DataChannelKind } from './types';
+
+class FakeDataChannel extends EventTarget {
+  bufferedAmount = 0;
+
+  bufferedAmountLowThreshold = 64;
+
+  send = vi.fn();
+}
+
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+// Pass `dc: null` for a handle-less channel; omit it to get a fresh one. `null` (not `undefined`)
+// is deliberate — a destructuring default fills in on `undefined`, so only `null` passes through.
+function makeChannel({ dc = new FakeDataChannel() }: { dc?: FakeDataChannel | null } = {}) {
+  const state = { engineClosed: false, deferring: false };
+  const channel = new ReliableDataChannel({
+    kind: DataChannelKind.RELIABLE,
+    lowWaterMark: 64,
+    highWaterMark: 1024,
+    isEngineClosed: () => state.engineClosed,
+    isDeferringSends: () => state.deferring,
+  });
+  if (dc) {
+    channel.attach(dc as unknown as RTCDataChannel);
+  }
+  const buffer = (channel as unknown as { messageBuffer: { getAll(): unknown[]; length: number } })
+    .messageBuffer as unknown as {
+    getAll(): Array<{ data: Uint8Array; sequence: number; sent: boolean }>;
+    length: number;
+  };
+  return { channel, dc, state, buffer };
+}
+
+describe('ReliableDataChannel', () => {
+  it('hands out monotonic sequences and resets them with the session', () => {
+    const { channel } = makeChannel();
+    expect(channel.nextSequence()).toBe(1);
+    expect(channel.nextSequence()).toBe(2);
+    channel.reset();
+    expect(channel.nextSequence()).toBe(1);
+  });
+
+  it('sends below the high-water mark and retains the packet for replay as sent', async () => {
+    const { channel, dc, buffer } = makeChannel();
+    const msg = new Uint8Array([1]);
+
+    await channel.send(msg, channel.nextSequence());
+
+    expect(dc.send).toHaveBeenCalledWith(msg);
+    expect(buffer.getAll()).toEqual([{ data: msg, sequence: 1, sent: true }]);
+  });
+
+  it('queues unsent while sends are deferred (reconnect window)', async () => {
+    const { channel, dc, state, buffer } = makeChannel();
+    state.deferring = true;
+
+    await channel.send(new Uint8Array([1]), channel.nextSequence());
+
+    expect(dc.send).not.toHaveBeenCalled();
+    expect(buffer.getAll()[0].sent).toBe(false);
+  });
+
+  it('queues unsent and resolves when the headroom wait is torn down transiently', async () => {
+    const { channel, dc, buffer } = makeChannel();
+    dc.bufferedAmount = 2048; // above high mark → send parks
+    const send = channel.send(new Uint8Array([1]), channel.nextSequence());
+    await tick();
+
+    channel.invalidateWaiters('channel replaced');
+
+    await expect(send).resolves.toBeUndefined();
+    expect(dc.send).not.toHaveBeenCalled();
+    expect(buffer.getAll()[0].sent).toBe(false);
+  });
+
+  it('rejects when the engine is closed while waiting', async () => {
+    const { channel, dc, state } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const send = channel.send(new Uint8Array([1]), channel.nextSequence());
+    send.catch(() => {});
+    await tick();
+
+    state.engineClosed = true;
+    channel.invalidateWaiters('engine closed');
+
+    await expect(send).rejects.toBeInstanceOf(UnexpectedConnectionState);
+  });
+
+  it('replay drops acked packets, resends the rest in order, and marks them sent', async () => {
+    const { channel, dc, buffer } = makeChannel();
+    const acked = new Uint8Array([1]);
+    const unacked = new Uint8Array([2]);
+    await channel.send(acked, channel.nextSequence());
+    await channel.send(unacked, channel.nextSequence());
+    // A packet queued unsent during the reconnect window joins the replay.
+    const queued = new Uint8Array([3]);
+    (channel as unknown as { isDeferringSends: () => boolean }).isDeferringSends = () => true;
+    await channel.send(queued, 3);
+    dc.send.mockClear();
+
+    await channel.replay(1); // server acked sequence 1
+
+    expect(dc.send.mock.calls.map(([data]) => data)).toEqual([unacked, queued]);
+    expect(buffer.getAll().every((item) => item.sent)).toBe(true);
+  });
+
+  it('transmits a packet deferred mid-replay instead of marking it sent without sending', async () => {
+    const { channel, dc, state, buffer } = makeChannel();
+    // A packet sent before the disconnect, still buffered (unacked) at resume.
+    await channel.send(new Uint8Array([1]), channel.nextSequence());
+    dc.send.mockClear();
+
+    // Replay parks on a full buffer, giving an await window mid-drain.
+    dc.bufferedAmount = 2048;
+    const replay = channel.replay(0);
+    await tick();
+
+    // A send arrives while replay is parked; the reconnect is still active, so it defers into the
+    // buffer as sent:false — after replay's first drain pass already started.
+    state.deferring = true;
+    await channel.send(new Uint8Array([2]), channel.nextSequence());
+    state.deferring = false;
+
+    dc.bufferedAmount = 0;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await replay;
+
+    // The drain loop must transmit both; a blanket mark-all-sent would flip the late arrival to
+    // sent without sending it, and a later align would then strand it.
+    expect(dc.send.mock.calls.map(([d]) => d[0])).toEqual([1, 2]);
+    expect(buffer.getAll().filter((i) => !i.sent)).toHaveLength(0);
+  });
+
+  it('holds the headroom lock across the whole replay so new sends cannot interleave', async () => {
+    const { channel, dc } = makeChannel();
+    (channel as unknown as { isDeferringSends: () => boolean }).isDeferringSends = () => true;
+    await channel.send(new Uint8Array([1]), 1);
+    await channel.send(new Uint8Array([2]), 2);
+    (channel as unknown as { isDeferringSends: () => boolean }).isDeferringSends = () => false;
+
+    // Replay parks on a full buffer while a concurrent send races it.
+    dc.bufferedAmount = 2048;
+    const replay = channel.replay(0);
+    await tick();
+    const concurrent = channel.send(new Uint8Array([9]), channel.nextSequence());
+    await tick();
+
+    dc.bufferedAmount = 0;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await Promise.all([replay, concurrent]);
+
+    expect(dc.send.mock.calls.map(([data]) => data[0])).toEqual([1, 2, 9]);
+  });
+});