livekit-client 2.20.2 → 2.22.0

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

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