livekit-client 2.22.4 → 2.23.0

package/src/room/PCTransport.ts

@@ -28,6 +28,9 @@ interface TrackBitrateInfo {
  * Why same for all codecs: Target bitrate already accounts for codec efficiency
  * (e.g., users set lower targets for VP9/AV1 knowing they're more efficient).
  * Why cap at 1 Mbps: Prevents BWE from starting too aggressively on high bitrate tracks.
+ * The cap is lowered further for connections that were slow to set up, see
+ * `computeStartBitrateCap`, or that the browser reports as slow, see
+ * `connectionEffectiveTypeStartBitrateCap`.
  */
 const startBitrateMultiplier = 0.9;
 
@@ -35,11 +38,35 @@ const startBitrateMultiplier = 0.9;
 const maxStartBitrateKbps = 1000;
 
 /**
- * Minimum target bitrate in kbps for the start bitrate hint. Below this, seeding above the
- * real capacity costs more than the ramp it saves, so libwebrtc's default is left in place.
+ * Minimum x-google-start-bitrate in kbps: libwebrtc's own default starting estimate. A target
+ * below this gets no hint, since seeding above the real capacity costs more than the ramp it
+ * saves, and a slow connection is seeded no higher than this.
  */
 const minTargetBitrateKbps = 300;
 
+/**
+ * Connection setup times (ms) bounding the ramp in `computeStartBitrateCap`: at or below the
+ * first the hint is capped at `maxStartBitrateKbps`, at or above the second at
+ * `minTargetBitrateKbps`. Measured on shaped links (CLT-3380): healthy links set up in under
+ * 860 ms, a 1 Mbps link with 150 ms RTT took 1.1–1.7 s, a 500 kbps link ~2.3 s at the median,
+ * and a 300 kbps link never under 3 s. The first sits above the 1 Mbps link, which a lower seed
+ * only slows down, and the second above the 500 kbps link's median, so only links that cannot
+ * carry more land at the floor.
+ */
+const setupTimeForMaxStartBitrateMs = 1500;
+const setupTimeForMinStartBitrateMs = 3500;
+
+/** Cap on the start bitrate hint, in kbps, when the browser reports a `3g` connection. */
+const effectiveType3gStartBitrateKbps = 500;
+
+/**
+ * The part of the Network Information API (`navigator.connection`) read here. It is Chromium
+ * only, so TypeScript's DOM typings do not declare it.
+ */
+interface NetworkInformation {
+  readonly effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+}
+
 const debounceInterval = 20;
 
 /**
@@ -71,17 +98,84 @@ export function findTrackCodecPayload(
  * high-bitrate track; screen share is exempt, because its content needs the bitrate
  * immediately to stay legible.
  *
- * TODO: adjust dynamically from network conditions (e.g. a previous BWE estimate) rather
- * than a fixed cap.
+ * The cap is lowered for a connection that was slow to set up (`computeStartBitrateCap`), and
+ * for one the browser reports as slow (`connectionEffectiveTypeStartBitrateCap`), whichever is
+ * lower. Screen share is exempt from both, however slow the connection.
  *
  * @internal
  */
-export function computeTrackStartBitrate(trackbr: TrackBitrateInfo): number | undefined {
+export function computeTrackStartBitrate(
+  trackbr: TrackBitrateInfo,
+  connectionSetupTimeMs?: number,
+): number | undefined {
   if (trackbr.maxbr < minTargetBitrateKbps) {
     return undefined;
   }
-  const calculated = Math.round(trackbr.maxbr * startBitrateMultiplier);
-  return trackbr.isScreenShare ? calculated : Math.min(calculated, maxStartBitrateKbps);
+  const calculated = Math.min(Math.round(trackbr.maxbr * startBitrateMultiplier), trackbr.maxbr);
+  if (trackbr.isScreenShare) {
+    return calculated;
+  }
+  const cap = Math.min(
+    computeStartBitrateCap(connectionSetupTimeMs),
+    connectionEffectiveTypeStartBitrateCap(),
+  );
+  return Math.min(calculated, cap);
+}
+
+/**
+ * Cap on the start bitrate hint, in kbps, from the browser's effective connection type
+ * (`navigator.connection.effectiveType`, Chromium only): `slow-2g` and `2g` cap at
+ * `minTargetBitrateKbps`, `3g` at `effectiveType3gStartBitrateKbps`.
+ *
+ * It catches links that have low bandwidth but low latency, which set up quickly and so slip
+ * past the setup time ramp. `4g`, and browsers without the API, give no guidance and stay at the
+ * `maxStartBitrateKbps` ceiling, as `computeStartBitrateCap` does without a setup time. The
+ * connection RTT the API also reports is not used: it lags behind network changes, and the setup
+ * time already reflects latency.
+ */
+function connectionEffectiveTypeStartBitrateCap(): number {
+  // A `typeof` guard, since `globalThis` is missing from some supported browsers (Chrome < 71,
+  // Firefox < 65, Safari < 12.1) and the build does not polyfill it.
+  const connection =
+    typeof navigator !== 'undefined'
+      ? (navigator as Navigator & { connection?: NetworkInformation }).connection
+      : undefined;
+  switch (connection?.effectiveType) {
+    case 'slow-2g':
+    case '2g':
+      return minTargetBitrateKbps;
+    case '3g':
+      return effectiveType3gStartBitrateKbps;
+    default:
+      return maxStartBitrateKbps;
+  }
+}
+
+/**
+ * Cap on the start bitrate hint, in kbps, from how long the connection took to set up.
+ *
+ * Connection setup time (signaling join plus ICE/DTLS) is the network signal every platform has
+ * before the first video offer, since libwebrtc cannot probe the path until a video sender
+ * exists. It grows with round-trip time and loss, which also mark the links where a 1 Mbps
+ * seed overshoots, so the cap ramps linearly from `maxStartBitrateKbps` at
+ * `setupTimeForMaxStartBitrateMs` down to `minTargetBitrateKbps` at
+ * `setupTimeForMinStartBitrateMs`. A video offer built while the connection is still being set
+ * up (publishing during connect) passes the time elapsed so far, a lower bound on the setup time.
+ * Without any timing the cap stays at the 1 Mbps ceiling.
+ */
+function computeStartBitrateCap(connectionSetupTimeMs?: number): number {
+  if (connectionSetupTimeMs === undefined) {
+    return maxStartBitrateKbps;
+  }
+  const ramp = Math.min(
+    Math.max(
+      (connectionSetupTimeMs - setupTimeForMaxStartBitrateMs) /
+        (setupTimeForMinStartBitrateMs - setupTimeForMaxStartBitrateMs),
+      0,
+    ),
+    1,
+  );
+  return Math.round(maxStartBitrateKbps - ramp * (maxStartBitrateKbps - minTargetBitrateKbps));
 }
 
 /**
@@ -114,6 +208,7 @@ export function computeTrackStartBitrate(trackbr: TrackBitrateInfo): number | un
 export function computeConnectionStartBitrate(
   media: MediaDescription[],
   trackBitrates: TrackBitrateInfo[],
+  connectionSetupTimeMs?: number,
 ): number | undefined {
   let connectionStartBitrate: number | undefined;
   for (const m of media) {
@@ -128,7 +223,8 @@ export function computeConnectionStartBitrate(
       if (codecPayload === undefined) {
         continue;
       }
-      const startBitrate = codecPayload > 0 ? computeTrackStartBitrate(trackbr) : undefined;
+      const startBitrate =
+        codecPayload > 0 ? computeTrackStartBitrate(trackbr, connectionSetupTimeMs) : undefined;
       if (
         startBitrate !== undefined &&
         (connectionStartBitrate === undefined || startBitrate > connectionStartBitrate)
@@ -234,6 +330,20 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
    */
   private hasAppliedVideoStartBitrate = false;
 
+  /**
+   * How long this peer connection took to set up, in ms, recorded once the initial connect
+   * succeeds. Lowers the start bitrate hint for a slow connection; see `computeStartBitrateCap`.
+   */
+  private connectionSetupTimeMs?: number;
+
+  /**
+   * When the connection attempt that built this peer connection began (`performance.now()`).
+   * Until `connectionSetupTimeMs` is known, the time elapsed since then is used as a lower bound
+   * on the setup time, so a video published during connect is still seeded from it rather than
+   * waiting for the connection, which would delay the offer.
+   */
+  private connectionStartedAt?: number;
+
   remoteStereoMids: string[] = [];
 
   remoteNackMids: string[] = [];
@@ -584,7 +694,11 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       // published (data channel or audio only) find no target and leave the latch unset.
       const connectionStartBitrate = this.hasAppliedVideoStartBitrate
         ? undefined
-        : computeConnectionStartBitrate(sdpParsed.media, this.trackBitrates);
+        : computeConnectionStartBitrate(
+            sdpParsed.media,
+            this.trackBitrates,
+            this.connectionSetupTimeEstimateMs(),
+          );
       let appliedVideoStartBitrate = false;
       sdpParsed.media.forEach((media) => {
         ensureIPAddrMatchVersion(media);
@@ -641,6 +755,10 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       // one-shot hint once the SDP carrying it has been accepted locally.
       if (appliedVideoStartBitrate && offer.sdp === mungedSdp) {
         this.hasAppliedVideoStartBitrate = true;
+        this.log.info('applied x-google-start-bitrate', {
+          startBitrateKbps: connectionStartBitrate,
+          connectionSetupTimeMs: this.connectionSetupTimeEstimateMs(),
+        });
       }
       this.onOffer(offer, this.latestOfferId);
     } finally {
@@ -695,6 +813,30 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     this.trackBitrates.push(info);
   }
 
+  /**
+   * Record how long this peer connection took to set up. Called once, when the initial connect
+   * succeeds; resumes and ICE restarts keep the estimator they have and never call this.
+   */
+  setConnectionSetupTime(ms: number) {
+    this.connectionSetupTimeMs = ms;
+  }
+
+  /** Record when the connection attempt that built this peer connection began. */
+  setConnectionStartedAt(startedAt: number) {
+    this.connectionStartedAt = startedAt;
+  }
+
+  /** The measured setup time, or while still connecting, the time elapsed so far. */
+  private connectionSetupTimeEstimateMs(): number | undefined {
+    if (this.connectionSetupTimeMs !== undefined) {
+      return this.connectionSetupTimeMs;
+    }
+    if (this.connectionStartedAt === undefined) {
+      return undefined;
+    }
+    return Math.round(performance.now() - this.connectionStartedAt);
+  }
+
   setConfiguration(rtcConfig: RTCConfiguration) {
     if (!this._pc) {
       throw new UnexpectedConnectionState('PC closed, cannot configure');

package/src/room/RTCEngine.test.ts

@@ -1,16 +1,22 @@
 import {
   DataPacket,
   DataPacket_Kind,
+  JoinResponse,
   ConnectionQuality as ProtoConnectionQuality,
   UserPacket,
 } from '@livekit/protocol';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SignalConnectionState, type SignalOptions } from '../api/SignalClient';
 import type { DataPacketBuffer } from '../utils/dataPacketBuffer';
+import DefaultReconnectPolicy from './DefaultReconnectPolicy';
 import { PCTransportState } from './PCTransportManager';
 import RTCEngine, { DataChannelKind } from './RTCEngine';
+import type { ReconnectContext, ReconnectPolicy } from './ReconnectPolicy';
 import { roomOptionDefaults } from './defaults';
-import { PublishDataError, UnexpectedConnectionState } from './errors';
+import { ConnectionError, PublishDataError, UnexpectedConnectionState } from './errors';
 import { EngineEvent } from './events';
+import CriticalTimers from './timers';
+import { Future } from './utils';
 
 describe('RTCEngine', () => {
   const originalRTCRtpSender = window.RTCRtpSender;
@@ -310,7 +316,13 @@ describe('RTCEngine', () => {
 
     bufferedAmountLowThreshold = 64 * 1024;
 
+    readyState: RTCDataChannelState = 'open';
+
     send = vi.fn();
+
+    close = vi.fn(() => {
+      this.readyState = 'closing';
+    });
   }
 
   const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
@@ -537,6 +549,37 @@ describe('RTCEngine', () => {
     });
   });
 
+  describe('createDataChannels', () => {
+    it('makes the next sender wait for replacement channels to open', () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const pcManager = {
+        createPublisherDataChannel: vi.fn((label: string) =>
+          Object.assign(new FakeDataChannel(), { label }),
+        ),
+      };
+      const connected = Promise.resolve();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        pcManager,
+        publisherConnectionPromise: connected,
+      });
+      const internals = engine as unknown as {
+        createDataChannels: () => void;
+        publisherConnectionPromise?: Promise<void>;
+        dataChannels: { lossy: { stopThresholdTuning: () => void } };
+      };
+
+      // First creation (nothing to replace) keeps the memoized readiness check.
+      internals.createDataChannels();
+      expect(internals.publisherConnectionPromise).toBe(connected);
+
+      // Recreation (the Safari null-id resume path) swaps in channels that start out connecting.
+      internals.createDataChannels();
+      expect(internals.publisherConnectionPromise).toBeUndefined();
+
+      internals.dataChannels.lossy.stopThresholdTuning();
+    });
+  });
+
   describe('handleDataChannelClose', () => {
     function stubCloseEnv(
       engine: RTCEngine,
@@ -701,6 +744,123 @@ describe('RTCEngine', () => {
     });
   });
 
+  describe('closing during a full reconnect', () => {
+    interface ReconnectInternals {
+      _isClosed: boolean;
+      url: string;
+      token: string;
+      signalOpts: SignalOptions;
+      attemptReconnect: () => Promise<void>;
+      configure: () => Promise<void>;
+      waitForPCReconnected: () => Promise<void>;
+      reconnectAbortController?: AbortController;
+    }
+
+    function primeEngine() {
+      const engine = new RTCEngine({ ...roomOptionDefaults, singlePeerConnection: false });
+      const internals = engine as unknown as ReconnectInternals;
+      internals._isClosed = false;
+      internals.url = 'wss://test.livekit.io';
+      internals.token = 'test-token';
+      internals.signalOpts = { autoSubscribe: true, maxRetries: 1, websocketTimeout: 15_000 };
+      engine.fullReconnectOnNext = true;
+      const configure = vi.spyOn(internals, 'configure').mockResolvedValue();
+      vi.spyOn(internals, 'waitForPCReconnected').mockResolvedValue();
+      const join = vi
+        .spyOn(engine.client, 'join')
+        .mockResolvedValue(new JoinResponse({ subscriberPrimary: true }));
+      return { engine, internals, configure, join };
+    }
+
+    it('does not join after close completes while reconnect cleanup is pending', async () => {
+      const { engine, internals, join } = primeEngine();
+      const cleanupStarted = new Future<void, Error>();
+      const finishCleanup = new Future<void, Error>();
+      vi.spyOn(engine, 'cleanupPeerConnections').mockImplementationOnce(async () => {
+        cleanupStarted.resolve?.();
+        await finishCleanup.promise;
+      });
+
+      const reconnect = internals.attemptReconnect();
+      await cleanupStarted.promise;
+      const controller = internals.reconnectAbortController;
+      expect(controller).toBeDefined();
+      await engine.close();
+      expect(controller?.signal.aborted).toBe(true);
+      expect(internals.reconnectAbortController).toBeUndefined();
+      finishCleanup.resolve?.();
+      await reconnect;
+
+      expect(internals.reconnectAbortController).toBeUndefined();
+      expect(join).not.toHaveBeenCalled();
+      expect(engine.isClosed).toBe(true);
+    });
+
+    it('does not join another region after close completes during region selection', async () => {
+      const { engine, internals, join } = primeEngine();
+      join.mockRejectedValue(ConnectionError.internal('signal connection failed'));
+      const selectingRegion = new Future<void, Error>();
+      const nextRegion = new Future<string | null, Error>();
+      const getNextUrl = vi.fn(async () => {
+        selectingRegion.resolve?.();
+        return nextRegion.promise;
+      });
+      engine.setRegionStrategy({ getNextUrl, resetAttempts: () => {} });
+
+      const reconnect = internals.attemptReconnect();
+      await selectingRegion.promise;
+      await engine.close();
+      nextRegion.resolve?.('wss://another-region.livekit.io');
+      // A second selection must terminate even on the unfixed implementation.
+      getNextUrl.mockResolvedValue(null);
+      await reconnect;
+
+      expect(join).toHaveBeenCalledTimes(1);
+      expect(getNextUrl).toHaveBeenCalledTimes(1);
+      expect(engine.isClosed).toBe(true);
+    });
+
+    it('does not reopen the engine when a signal join resolves after close', async () => {
+      const { engine, internals, configure, join } = primeEngine();
+      const joining = new Future<void, Error>();
+      const joinResponse = new Future<JoinResponse, Error>();
+      join.mockImplementationOnce(async () => {
+        joining.resolve?.();
+        return joinResponse.promise;
+      });
+
+      const reconnect = internals.attemptReconnect();
+      await joining.promise;
+      await engine.close();
+      joinResponse.resolve?.(new JoinResponse({ subscriberPrimary: true }));
+      await reconnect;
+
+      expect(engine.isClosed).toBe(true);
+      expect(configure).not.toHaveBeenCalled();
+      expect(join.mock.calls[0][3]?.aborted).toBe(true);
+    });
+
+    it('still completes a full reconnect while the engine is active', async () => {
+      const { engine, internals, join } = primeEngine();
+      vi.spyOn(engine.client, 'sendLeave').mockResolvedValue();
+      vi.spyOn(engine.client, 'currentState', 'get').mockReturnValue(
+        SignalConnectionState.CONNECTED,
+      );
+      const restarted = vi.fn();
+      engine.on(EngineEvent.Restarted, restarted);
+
+      try {
+        await internals.attemptReconnect();
+
+        expect(join).toHaveBeenCalledTimes(1);
+        expect(restarted).toHaveBeenCalledTimes(1);
+        expect(engine.isClosed).toBe(false);
+      } finally {
+        await engine.close();
+      }
+    });
+  });
+
   describe('reconnect requested mid-attempt', () => {
     // A full reconnect requested while a resume is already in flight (e.g. a server
     // RECONNECT leave racing the resume) sets `fullReconnectOnNext` mid-attempt. A
@@ -711,7 +871,7 @@ describe('RTCEngine', () => {
       clientConfiguration: unknown;
       pcManager: unknown;
       resumeConnection: (reason?: number) => Promise<void>;
-      restartConnection: (regionUrl?: string) => Promise<void>;
+      restartConnection: (abortSignal: AbortSignal, regionUrl?: string) => Promise<void>;
       clearPendingReconnect: () => void;
       handleDisconnect: (connection: string, reason?: number) => void;
       attemptReconnect: (reason?: number) => Promise<void>;
@@ -1003,4 +1163,76 @@ describe('RTCEngine', () => {
       expect(pendingAborts(engine).size).toBe(0);
     });
   });
+
+  describe('server-requested reconnect delay', () => {
+    // A RECONNECT or RESUME leave from the server skips any remaining backoff. It must still go
+    // through the reconnect policy, so that clients told to reconnect together spread out.
+    interface DisconnectInternals {
+      _isClosed: boolean;
+      reconnectAttempts: number;
+      handleDisconnect: (connection: string, reason?: number) => void;
+    }
+
+    function scheduledDelay(
+      nextRetryDelayInMs: ReconnectPolicy['nextRetryDelayInMs'],
+      attempts = 0,
+    ) {
+      const engine = new RTCEngine({
+        ...roomOptionDefaults,
+        reconnectPolicy: { nextRetryDelayInMs },
+      });
+      const internals = engine as unknown as DisconnectInternals;
+      internals._isClosed = false;
+      internals.reconnectAttempts = attempts;
+      const setTimeoutSpy = vi
+        .spyOn(CriticalTimers, 'setTimeout')
+        .mockReturnValue(0 as unknown as ReturnType<typeof setTimeout>);
+      internals.handleDisconnect('leave-reconnect');
+      expect(setTimeoutSpy).toHaveBeenCalledTimes(1);
+      return setTimeoutSpy.mock.calls[0][1];
+    }
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('uses the first retry delay of the policy instead of reconnecting immediately', () => {
+      const nextRetryDelayInMs = vi.fn((context: ReconnectContext) =>
+        context.retryCount === 0 ? 321 : 5000,
+      );
+      expect(scheduledDelay(nextRetryDelayInMs)).toBe(321);
+    });
+
+    it('skips the remaining backoff when the request arrives during a later retry', () => {
+      const nextRetryDelayInMs = vi.fn((context: ReconnectContext) =>
+        context.retryCount === 0 ? 321 : 5000,
+      );
+      expect(scheduledDelay(nextRetryDelayInMs, 3)).toBe(321);
+    });
+
+    it('gives up when the policy stops on the first retry delay', () => {
+      const engine = new RTCEngine({
+        ...roomOptionDefaults,
+        reconnectPolicy: {
+          nextRetryDelayInMs: (context: ReconnectContext) =>
+            context.retryCount === 0 ? null : 5000,
+        },
+      });
+      const internals = engine as unknown as DisconnectInternals;
+      internals._isClosed = false;
+      internals.reconnectAttempts = 3;
+      const setTimeoutSpy = vi.spyOn(CriticalTimers, 'setTimeout');
+      const disconnected = vi.fn();
+      engine.on(EngineEvent.Disconnected, disconnected);
+      internals.handleDisconnect('leave-reconnect');
+      expect(setTimeoutSpy).not.toHaveBeenCalled();
+      expect(disconnected).toHaveBeenCalledTimes(1);
+    });
+
+    it('spreads out clients that use the default policy', () => {
+      const defaultPolicy = new DefaultReconnectPolicy();
+      vi.spyOn(Math, 'random').mockReturnValue(0.5);
+      expect(scheduledDelay((context) => defaultPolicy.nextRetryDelayInMs(context))).toBe(250);
+    });
+  });
 });