livekit-client 2.20.2 → 2.22.0

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

@@ -0,0 +1,237 @@
+import type { PCTransportManager } from '../PCTransportManager';
+import { FlowControlledDataChannel } from './FlowControlledDataChannel';
+import { LossyDataChannel } from './LossyDataChannel';
+import { ReliableDataChannel } from './ReliableDataChannel';
+import { DataChannelKind, dataChannelHighWaterMark, dataChannelLowWaterMark } from './types';
+
+const lossyDataChannelLabel = '_lossy';
+const reliableDataChannelLabel = '_reliable';
+const dataTrackDataChannelLabel = '_data_track';
+
+export interface DataChannelManagerOptions {
+  /** Whether the owning engine has been closed — a closed engine rejects headroom waiters. */
+  isEngineClosed: () => boolean;
+  /**
+   * Whether a reconnect attempt is underway: reliable sends defer to the resume replay and lossy
+   * sends are skipped while this is true.
+   */
+  isReconnecting: () => boolean;
+  onDataMessage: (message: MessageEvent) => void;
+  onDataTrackMessage: (message: MessageEvent) => void;
+  onDataError: (event: Event) => void;
+  onChannelClose: (kind: DataChannelKind) => void;
+  /** A channel's buffer crossed its low-water mark (debounced). Drives DCBufferStatusChanged. */
+  onBufferStatusChanged: (kind: DataChannelKind, isLow: boolean) => void;
+}
+
+/**
+ * Owns the engine's data channels: the three flow-controlled publisher channel wrappers (which
+ * live for the engine's lifetime and have RTCDataChannel handles attached/detached as peer
+ * connections come and go) plus the subscriber-side receive handles adopted by label.
+ *
+ * Handle turnover goes through {@link FlowControlledDataChannel.attach}/`detach`, which reject
+ * parked headroom waiters as a built-in — there is no separate invalidation step to forget.
+ */
+export class DataChannelManager {
+  readonly reliable: ReliableDataChannel;
+
+  readonly lossy: LossyDataChannel;
+
+  readonly dataTrack: LossyDataChannel;
+
+  private reliableSub?: RTCDataChannel;
+
+  private lossySub?: RTCDataChannel;
+
+  private dataTrackSub?: RTCDataChannel;
+
+  private opts: DataChannelManagerOptions;
+
+  constructor(opts: DataChannelManagerOptions) {
+    this.opts = opts;
+    const flowControlOptions = (kind: DataChannelKind) => ({
+      kind,
+      lowWaterMark: dataChannelLowWaterMark(kind),
+      highWaterMark: dataChannelHighWaterMark(kind),
+      isEngineClosed: opts.isEngineClosed,
+      onBufferStatusChanged: (isLow: boolean) => opts.onBufferStatusChanged(kind, isLow),
+    });
+    this.reliable = new ReliableDataChannel({
+      ...flowControlOptions(DataChannelKind.RELIABLE),
+      isDeferringSends: opts.isReconnecting,
+    });
+    this.lossy = new LossyDataChannel({
+      ...flowControlOptions(DataChannelKind.LOSSY),
+      // Classic lossy user data: a stale packet is worthless, so drop instead of queueing.
+      bufferFullBehavior: 'drop',
+      shouldSkipSends: opts.isReconnecting,
+    });
+    this.dataTrack = new LossyDataChannel({
+      ...flowControlOptions(DataChannelKind.DATA_TRACK_LOSSY),
+      // Data tracks backpressure the producer instead — it decides what to skip at frame
+      // granularity rather than the engine dropping arbitrary chunks out of frames.
+      bufferFullBehavior: 'wait',
+      shouldSkipSends: opts.isReconnecting,
+    });
+  }
+
+  /** The flow-control wrapper for `kind`. */
+  channelFor(kind: DataChannelKind): FlowControlledDataChannel {
+    switch (kind) {
+      case DataChannelKind.RELIABLE:
+        return this.reliable;
+      case DataChannelKind.LOSSY:
+        return this.lossy;
+      case DataChannelKind.DATA_TRACK_LOSSY:
+        return this.dataTrack;
+    }
+  }
+
+  /** The raw RTCDataChannel handle for `kind`, publisher side by default. */
+  getHandle(kind: DataChannelKind, subscriber: boolean = false): RTCDataChannel | undefined {
+    if (!subscriber) {
+      return this.channelFor(kind).channelHandle;
+    }
+    switch (kind) {
+      case DataChannelKind.RELIABLE:
+        return this.reliableSub;
+      case DataChannelKind.LOSSY:
+        return this.lossySub;
+      case DataChannelKind.DATA_TRACK_LOSSY:
+        return this.dataTrackSub;
+    }
+  }
+
+  get hasPublisherChannels(): boolean {
+    return Boolean(
+      this.reliable.channelHandle || this.lossy.channelHandle || this.dataTrack.channelHandle,
+    );
+  }
+
+  /**
+   * Creates the three publisher data channels on the given transport, wires their handlers, and
+   * attaches them to the wrappers — attaching rejects any waiters still parked on replaced
+   * channel objects.
+   */
+  createPublisherChannels(pcManager: PCTransportManager) {
+    // clear old data channel callbacks if recreate
+    for (const channel of [this.lossy, this.reliable, this.dataTrack]) {
+      const old = channel.channelHandle;
+      if (old) {
+        old.onmessage = null;
+        old.onerror = null;
+        old.onclose = null;
+      }
+    }
+
+    const wire = (
+      channel: FlowControlledDataChannel,
+      dc: RTCDataChannel,
+      onMessage: (message: MessageEvent) => void,
+    ) => {
+      // also handle messages over the pub channel, for backwards compatibility
+      dc.onmessage = onMessage;
+      // handle datachannel errors
+      dc.onerror = this.opts.onDataError;
+      // detect unexpected publisher data channel closes
+      dc.onclose = () => this.opts.onChannelClose(channel.kind);
+      // set up dc buffer threshold - if this is not set, it will default to 0
+      dc.bufferedAmountLowThreshold = channel.lowWaterMark;
+      // handle buffer amount low events
+      dc.onbufferedamountlow = () => channel.refreshBufferStatus();
+      channel.attach(dc);
+    };
+
+    wire(
+      this.lossy,
+      pcManager.createPublisherDataChannel(lossyDataChannelLabel, {
+        ordered: false,
+        maxRetransmits: 0,
+      }),
+      this.opts.onDataMessage,
+    );
+    wire(
+      this.reliable,
+      pcManager.createPublisherDataChannel(reliableDataChannelLabel, {
+        ordered: true,
+      }),
+      this.opts.onDataMessage,
+    );
+    wire(
+      this.dataTrack,
+      pcManager.createPublisherDataChannel(dataTrackDataChannelLabel, {
+        ordered: false,
+        maxRetransmits: 0,
+      }),
+      this.opts.onDataTrackMessage,
+    );
+
+    this.lossy.startThresholdTuning();
+  }
+
+  /**
+   * Adopts a subscriber-side data channel by label, wiring the matching receive handler.
+   * Returns false for labels this manager doesn't own.
+   */
+  adoptSubscriberChannel(channel: RTCDataChannel): boolean {
+    let handler: (message: MessageEvent) => void;
+    if (channel.label === reliableDataChannelLabel) {
+      this.reliableSub = channel;
+      handler = this.opts.onDataMessage;
+    } else if (channel.label === lossyDataChannelLabel) {
+      this.lossySub = channel;
+      handler = this.opts.onDataMessage;
+    } else if (channel.label === dataTrackDataChannelLabel) {
+      this.dataTrackSub = channel;
+      handler = this.opts.onDataTrackMessage;
+    } else {
+      return false;
+    }
+    channel.onmessage = handler;
+    return true;
+  }
+
+  /**
+   * Tears down all channels for a peer-connection cleanup: rejects parked waiters (detach — the
+   * spec allows `pc.close()` to transition channels to 'closed' without firing events, so waiting
+   * for browser close events is not an option), strips handlers, closes the handles, and resets
+   * the reliable session state.
+   */
+  teardown() {
+    const dcCleanup = (dc: RTCDataChannel | undefined) => {
+      if (!dc) {
+        return;
+      }
+
+      // Detach the data channel handlers before closing anything. Closing a peer connection tears
+      // down the SCTP transport, which can dispatch `error`/`close` events on the still-open data
+      // channels; if our handlers are still attached at that point, handleDataError logs a spurious
+      // "Unknown DataChannel error" during an otherwise graceful disconnect. Removing the handlers
+      // before dc.close()/pcManager.close() makes this deterministic regardless of how/when the
+      // browser dispatches those teardown events. See livekit/client-sdk-js#1953.
+      dc.onbufferedamountlow = null;
+      dc.onclose = null;
+      dc.onclosing = null;
+      dc.onerror = null;
+      dc.onmessage = null;
+      dc.onopen = null;
+
+      dc.close();
+    };
+
+    for (const channel of [this.lossy, this.reliable, this.dataTrack]) {
+      const dc = channel.channelHandle;
+      channel.detach('peer connections cleaned up');
+      dcCleanup(dc);
+    }
+    dcCleanup(this.lossySub);
+    dcCleanup(this.reliableSub);
+    dcCleanup(this.dataTrackSub);
+    this.lossySub = undefined;
+    this.reliableSub = undefined;
+    this.dataTrackSub = undefined;
+
+    // Full teardown starts the session over: drop replay state and restart sequencing.
+    this.reliable.reset();
+  }
+}

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

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from 'vitest';
+import { UnexpectedConnectionState } from '../errors';
+import { FlowControlledDataChannel } from './FlowControlledDataChannel';
+import { DataChannelKind } from './types';
+
+class FakeDataChannel extends EventTarget {
+  bufferedAmount = 0;
+
+  bufferedAmountLowThreshold = 64;
+}
+
+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(),
+  engineClosed = false,
+}: { dc?: FakeDataChannel | null; engineClosed?: boolean } = {}) {
+  const state = { engineClosed };
+  const onBufferStatusChanged = vi.fn();
+  const channel = new FlowControlledDataChannel({
+    kind: DataChannelKind.RELIABLE,
+    lowWaterMark: 64,
+    highWaterMark: 1024,
+    isEngineClosed: () => state.engineClosed,
+    onBufferStatusChanged,
+  });
+  if (dc) {
+    channel.attach(dc as unknown as RTCDataChannel);
+  }
+  return { channel, dc: dc as FakeDataChannel, state, onBufferStatusChanged };
+}
+
+describe('FlowControlledDataChannel', () => {
+  describe('refreshBufferStatus', () => {
+    it('notifies only on a change and in both directions', () => {
+      const { channel, dc, onBufferStatusChanged } = makeChannel();
+
+      // Starts "low" (empty buffer); a refresh that stays low emits nothing.
+      channel.refreshBufferStatus();
+      expect(onBufferStatusChanged).not.toHaveBeenCalled();
+
+      // Cross above the low mark → one not-low notification.
+      dc.bufferedAmount = 512;
+      channel.refreshBufferStatus();
+      channel.refreshBufferStatus(); // debounced: no second fire
+      expect(onBufferStatusChanged.mock.calls).toEqual([[false]]);
+
+      // Drain back below → one low notification.
+      dc.bufferedAmount = 0;
+      channel.refreshBufferStatus();
+      expect(onBufferStatusChanged.mock.calls).toEqual([[false], [true]]);
+    });
+
+    it('is a no-op without a handle (no throw, no notification)', () => {
+      const { channel, onBufferStatusChanged } = makeChannel({ dc: null });
+      expect(() => channel.refreshBufferStatus()).not.toThrow();
+      expect(onBufferStatusChanged).not.toHaveBeenCalled();
+    });
+  });
+
+  it('reports watermark status against the given channel', () => {
+    const { channel, dc } = makeChannel();
+    const handle = dc as unknown as RTCDataChannel;
+    dc.bufferedAmount = 0;
+    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle)).toBe(true);
+
+    dc.bufferedAmount = 512; // between low (64) and high (1024)
+    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle)).toBe(false);
+
+    dc.bufferedAmount = 2048;
+    expect(channel.isBelowHighWaterMark(handle)).toBe(false);
+  });
+
+  it('waiting for headroom without a handle rejects with a connection error', async () => {
+    const { channel } = makeChannel({ dc: null });
+    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+      UnexpectedConnectionState,
+    );
+  });
+
+  it('resolves immediately while below the high-water mark', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 1024;
+    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+  });
+
+  it('parks above the high-water mark and resumes on bufferedamountlow', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const resolved = vi.fn();
+    const wait = channel.waitForHeadroomWithLock().then(resolved);
+    await tick();
+    expect(resolved).not.toHaveBeenCalled();
+
+    dc.bufferedAmount = 32;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await wait;
+    expect(resolved).toHaveBeenCalled();
+  });
+
+  it('rejects a parked waiter when the channel closes', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const wait = channel.waitForHeadroomWithLock();
+    wait.catch(() => {});
+    await tick();
+
+    dc.dispatchEvent(new Event('close'));
+    await expect(wait).rejects.toBeInstanceOf(UnexpectedConnectionState);
+  });
+
+  it('rejects a parked waiter on invalidateWaiters and recovers with a fresh controller', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const wait = channel.waitForHeadroomWithLock();
+    wait.catch(() => {});
+    await tick();
+
+    channel.invalidateWaiters('channel replaced');
+    await expect(wait).rejects.toBeInstanceOf(UnexpectedConnectionState);
+
+    // Fresh controller: the gate is usable again and the lock was released.
+    dc.bufferedAmount = 0;
+    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+  });
+
+  it('rejects immediately when the engine is closed', async () => {
+    const { channel, state } = makeChannel();
+    state.engineClosed = true;
+    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+      UnexpectedConnectionState,
+    );
+  });
+
+  it('serializes waiters FIFO through the headroom lock', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const order: number[] = [];
+    const first = channel.waitForHeadroomWithLock().then(() => order.push(1));
+    const second = channel.waitForHeadroomWithLock().then(() => order.push(2));
+    await tick();
+
+    // One drain event wakes the head waiter; the second re-checks under the lock and, with the
+    // buffer now low, proceeds right after — strictly in arrival order.
+    dc.bufferedAmount = 0;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await Promise.all([first, second]);
+    expect(order).toEqual([1, 2]);
+  });
+});

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);
+    }
+  }
+}