livekit-client 2.22.3 → 2.23.0

package/src/room/DefaultReconnectPolicy.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import DefaultReconnectPolicy from './DefaultReconnectPolicy';
+
+const delayFor = (policy: DefaultReconnectPolicy, retryCount: number, random: number) => {
+  vi.spyOn(Math, 'random').mockReturnValue(random);
+  return policy.nextRetryDelayInMs({ retryCount, elapsedMs: 0 });
+};
+
+describe('DefaultReconnectPolicy', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('spreads the first retry over a window instead of retrying immediately', () => {
+    const policy = new DefaultReconnectPolicy();
+    expect(delayFor(policy, 0, 0)).toBe(0);
+    expect(delayFor(policy, 0, 0.5)).toBe(250);
+    expect(delayFor(policy, 0, 0.999)).toBeGreaterThan(450);
+    expect(delayFor(policy, 0, 0.999)).toBeLessThan(500);
+  });
+
+  it('scales the jitter of later retries with the delay', () => {
+    const policy = new DefaultReconnectPolicy();
+    expect(delayFor(policy, 1, 0)).toBe(150);
+    expect(delayFor(policy, 1, 0.5)).toBe(300);
+    expect(delayFor(policy, 2, 0)).toBe(600);
+    expect(delayFor(policy, 2, 0.5)).toBe(1200);
+    expect(delayFor(policy, 9, 0)).toBe(3500);
+    expect(delayFor(policy, 9, 0.999)).toBeLessThan(10500);
+  });
+
+  it('returns a different delay for each client on every retry', () => {
+    const policy = new DefaultReconnectPolicy();
+    for (let retryCount = 0; retryCount < 10; retryCount++) {
+      expect(delayFor(policy, retryCount, 0.1)).not.toBe(delayFor(policy, retryCount, 0.9));
+    }
+  });
+
+  it('returns null once the retries are exhausted', () => {
+    const policy = new DefaultReconnectPolicy([0, 100]);
+    expect(policy.nextRetryDelayInMs({ retryCount: 2, elapsedMs: 0 })).toBeNull();
+    expect(
+      new DefaultReconnectPolicy().nextRetryDelayInMs({ retryCount: 10, elapsedMs: 0 }),
+    ).toBeNull();
+  });
+
+  it('applies jitter to custom delays', () => {
+    const policy = new DefaultReconnectPolicy([1000]);
+    expect(delayFor(policy, 0, 0.5)).toBe(1000);
+    expect(delayFor(policy, 0, 0)).toBe(500);
+  });
+
+  it('keeps a zero delay at a later index immediate', () => {
+    const policy = new DefaultReconnectPolicy([100, 0]);
+    expect(delayFor(policy, 1, 0.5)).toBe(0);
+    expect(delayFor(policy, 1, 0.999)).toBe(0);
+  });
+});

package/src/room/DefaultReconnectPolicy.ts

@@ -2,6 +2,12 @@ import type { ReconnectContext, ReconnectPolicy } from './ReconnectPolicy';
 
 const maxRetryDelay = 7000;
 
+/**
+ * Upper bound of the random delay added to the first retry, whose base delay is 0. It keeps a
+ * brief network blip recovering quickly while spreading out clients that disconnect together.
+ */
+const maxFirstRetryJitterInMs = 500;
+
 const DEFAULT_RETRY_DELAYS_IN_MS = [
   0,
   300,
@@ -26,9 +32,15 @@ class DefaultReconnectPolicy implements ReconnectPolicy {
     if (context.retryCount >= this._retryDelays.length) return null;
 
     const retryDelay = this._retryDelays[context.retryCount];
-    if (context.retryCount <= 1) return retryDelay;
 
-    return retryDelay + Math.random() * 1_000;
+    // The first retry has no base delay to scale, so it gets a fixed window instead. A zero at a
+    // later index is an explicit request for an immediate retry and passes through the formula as zero.
+    if (context.retryCount === 0 && retryDelay === 0) {
+      return Math.random() * maxFirstRetryJitterInMs;
+    }
+
+    // Jitter scales with the delay (+/-50%) so clients spread out further on later retries.
+    return Math.round(retryDelay * (0.5 + Math.random()));
   }
 }
 

package/src/room/PCTransport.test.ts

@@ -1,12 +1,16 @@
 import { type MediaDescription, parse } from 'sdp-transform';
-import { describe, expect, it } from 'vitest';
-import {
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import PCTransport, {
   applyVideoStartBitrate,
+  computeConnectionStartBitrate,
+  computeTrackStartBitrate,
   conformBundledCodecFmtp,
   ensureAudioNackAndStereo,
   ensureVideoDDExtension,
   extractStereoAndNackAudioFromOffer,
+  findTrackCodecPayload,
   fmtpConfigHasParam,
+  isDuplicateAnswer,
   placeholderMidsFromTransceivers,
 } from './PCTransport';
 import { ddExtensionURI } from './utils';
@@ -61,9 +65,7 @@ a=recvonly
 a=rtpmap:49 H265/90000
 a=fmtp:49 level-id=180;profile-id=1;tier-flag=0;tx-mode=SRST`;
 
-describe('video start bitrate', () => {
-  it('applies the bitrate only to the section whose msid track ID matches the cid', () => {
-    const { media } = parse(`v=0
+const TWO_VIDEO_SECTIONS = `v=0
 o=- 0 0 IN IP4 127.0.0.1
 s=-
 t=0 0
@@ -79,15 +81,301 @@ c=IN IP4 0.0.0.0
 a=mid:1
 a=sendonly
 a=msid:PA_remote|camera camera-cid
-a=rtpmap:96 VP8/90000`);
+a=rtpmap:96 VP8/90000`;
+
+// The same bundle after the screen share is unpublished: `unpublishTrack` sets the
+// transceiver to `inactive`, but the section keeps its `a=msid`, so it still matches the
+// append-only trackBitrates entry. Only the camera is still sending.
+const UNPUBLISHED_SCREEN_SHARE = `v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+a=group:BUNDLE 0 1
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:0
+a=inactive
+a=msid:PA_remote|camera other-track
+a=rtpmap:96 VP8/90000
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:1
+a=sendonly
+a=msid:PA_remote|camera camera-cid
+a=rtpmap:96 VP8/90000`;
+
+// The legacy `addTrack` fallback (no `addTransceiver` support) reuses a transceiver instead
+// of creating a sendonly one, so the published camera lands on a `sendrecv` section. Mid 1
+// omits the direction attribute entirely, which SDP also defaults to sendrecv. Both send.
+const LEGACY_ADD_TRACK_SECTIONS = `v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+a=group:BUNDLE 0 1
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:0
+a=sendrecv
+a=msid:PA_remote|camera camera-cid
+a=rtpmap:96 VP8/90000
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:1
+a=msid:PA_remote|camera other-track
+a=rtpmap:96 VP8/90000`;
+
+describe('video start bitrate', () => {
+  it('matches only the section whose msid track ID matches the cid', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    expect(findTrackCodecPayload(media[0], 'camera-cid', 'VP8')).toBeUndefined();
+    expect(findTrackCodecPayload(media[1], 'camera-cid', 'VP8')).toBe(96);
+    // Section belongs to the track but does not offer the codec.
+    expect(findTrackCodecPayload(media[1], 'camera-cid', 'AV1')).toBe(0);
+  });
+
+  it('applies the bitrate only to the section it is given', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
 
-    for (const section of media) {
-      applyVideoStartBitrate(section, 'camera-cid', 'VP8', 1_000);
-    }
+    applyVideoStartBitrate(media[1], 96, 900);
 
     expect(fmtpOf(media, '0', 96)).toBeUndefined();
     expect(paramSet(fmtpOf(media, '1', 96)!)).toContain('x-google-start-bitrate=900');
   });
+
+  it('caps camera at 1 Mbps but leaves screen share uncapped', () => {
+    const camera = { cid: 'c', codec: 'VP8', maxbr: 3_000 };
+    const screenShare = { ...camera, isScreenShare: true };
+
+    expect(computeTrackStartBitrate(camera)).toBe(1_000);
+    expect(computeTrackStartBitrate(screenShare)).toBe(2_700);
+  });
+
+  it('gives no hint below the 300 kbps target floor', () => {
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 299 })).toBeUndefined();
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 300 })).toBe(270);
+  });
+
+  it('ramps the cap down with connection setup time', () => {
+    // A 3 Mbps camera target, so only the cap moves.
+    const camera = (ms: number) =>
+      computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, ms);
+
+    expect(camera(0)).toBe(1_000);
+    expect(camera(471)).toBe(1_000); // unshaped baseline
+    expect(camera(1_273)).toBe(1_000); // 1 Mbps link median
+    expect(camera(1_500)).toBe(1_000); // the fast anchor
+    expect(camera(1_724)).toBe(922); // 1 Mbps link slow attempt
+    expect(camera(2_334)).toBe(708); // 500 kbps link median
+    expect(camera(2_500)).toBe(650); // midpoint of the ramp
+    expect(camera(3_093)).toBe(442); // 300 kbps link fastest attempt
+    expect(camera(3_500)).toBe(300); // the slow anchor
+    expect(camera(18_131)).toBe(300); // anything slower stays at the floor
+  });
+
+  it('keeps the 1 Mbps ceiling without a setup time', () => {
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, undefined)).toBe(
+      1_000,
+    );
+  });
+
+  it('still applies 90% of the target under the ramp, and hints at the floor', () => {
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 500 }, 2_500)).toBe(450);
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 300 }, 3_500)).toBe(270);
+  });
+
+  it('leaves screen share uncapped however slow the setup', () => {
+    const screenShare = (ms: number) =>
+      computeTrackStartBitrate({ cid: 's', codec: 'VP8', maxbr: 3_000, isScreenShare: true }, ms);
+
+    expect(screenShare(1_273)).toBe(2_700);
+    expect(screenShare(2_500)).toBe(2_700);
+    expect(screenShare(4_061)).toBe(2_700);
+  });
+
+  it('applies the setup time to the connection-level value', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+    const camera = { cid: 'camera-cid', codec: 'VP8', maxbr: 3_000 };
+    const screenShare = { cid: 'other-track', codec: 'VP8', maxbr: 3_000, isScreenShare: true };
+
+    expect(computeConnectionStartBitrate(media, [camera], 1_000)).toBe(1_000);
+    expect(computeConnectionStartBitrate(media, [camera], 2_500)).toBe(650);
+    // The uncapped screen share still wins the connection-level max on a slow setup.
+    expect(computeConnectionStartBitrate(media, [camera, screenShare], 2_500)).toBe(2_700);
+  });
+
+  describe('browser effective connection type', () => {
+    const withEffectiveType = (effectiveType: string | undefined) =>
+      vi.stubGlobal('navigator', { connection: effectiveType ? { effectiveType } : undefined });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    // A 3 Mbps camera target, so only the cap moves.
+    const camera = (setupTimeMs?: number) =>
+      computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, setupTimeMs);
+
+    it('caps 2g and slow-2g at 300 kbps and 3g at 500 kbps', () => {
+      withEffectiveType('slow-2g');
+      expect(camera(500)).toBe(300);
+      withEffectiveType('2g');
+      expect(camera(500)).toBe(300);
+      withEffectiveType('3g');
+      expect(camera(500)).toBe(500);
+    });
+
+    it('gives no cap for 4g or without the API', () => {
+      withEffectiveType('4g');
+      expect(camera(500)).toBe(1_000);
+      withEffectiveType(undefined);
+      expect(camera(500)).toBe(1_000);
+      vi.stubGlobal('navigator', undefined);
+      expect(camera(500)).toBe(1_000);
+    });
+
+    it('takes the lower of the setup time cap and the effective type cap', () => {
+      withEffectiveType('3g');
+      expect(camera(2_500)).toBe(500); // setup time alone allows 650
+      expect(camera(3_093)).toBe(442); // setup time is lower
+      expect(camera()).toBe(500);
+    });
+
+    it('still applies 90% of a target below the cap', () => {
+      withEffectiveType('3g');
+      expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 450 }, 500)).toBe(405);
+    });
+
+    it('leaves screen share uncapped', () => {
+      withEffectiveType('slow-2g');
+      expect(
+        computeTrackStartBitrate(
+          { cid: 's', codec: 'VP8', maxbr: 3_000, isScreenShare: true },
+          500,
+        ),
+      ).toBe(2_700);
+    });
+  });
+
+  describe('connection setup time while still connecting', () => {
+    beforeEach(() => {
+      // The constructor creates its peer connection eagerly; only its event handlers are set.
+      vi.stubGlobal('RTCPeerConnection', class {});
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+      vi.unstubAllGlobals();
+    });
+
+    const estimate = (transport: PCTransport) =>
+      (
+        transport as unknown as { connectionSetupTimeEstimateMs(): number | undefined }
+      ).connectionSetupTimeEstimateMs();
+
+    it('uses the time elapsed since the join started before the setup time is measured', () => {
+      const transport = new PCTransport();
+      vi.spyOn(performance, 'now').mockReturnValue(10_000);
+      transport.setConnectionStartedAt(7_500);
+
+      expect(estimate(transport)).toBe(2_500);
+      expect(
+        computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, estimate(transport)),
+      ).toBe(650);
+    });
+
+    it('prefers the measured setup time once known', () => {
+      const transport = new PCTransport();
+      vi.spyOn(performance, 'now').mockReturnValue(10_000);
+      transport.setConnectionStartedAt(7_500);
+      transport.setConnectionSetupTime(3_600);
+
+      expect(estimate(transport)).toBe(3_600);
+    });
+
+    it('has no estimate without any timing', () => {
+      expect(estimate(new PCTransport())).toBeUndefined();
+    });
+  });
+
+  it('uses one connection-level value: the largest hint across video sections', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    const startBitrate = computeConnectionStartBitrate(media, [
+      { cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 },
+      { cid: 'other-track', codec: 'VP8', maxbr: 3_000, isScreenShare: true },
+    ]);
+
+    expect(startBitrate).toBe(2_700);
+  });
+
+  it('ignores registered tracks with no section in the current SDP', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    const startBitrate = computeConnectionStartBitrate(media, [
+      { cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 },
+      // Stale entry: trackBitrates is append-only and outlives an unpublish.
+      { cid: 'unpublished-cid', codec: 'VP8', maxbr: 8_000, isScreenShare: true },
+    ]);
+
+    expect(startBitrate).toBe(900);
+  });
+
+  it('ignores a section that stopped sending but kept its msid', () => {
+    const trackBitrates = [
+      { cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 },
+      { cid: 'other-track', codec: 'VP8', maxbr: 8_000, isScreenShare: true },
+    ];
+
+    // While both send, the uncapped screen share wins the connection-level max.
+    expect(computeConnectionStartBitrate(parse(TWO_VIDEO_SECTIONS).media, trackBitrates)).toBe(
+      7_200,
+    );
+    // Once it is unpublished its entry is stale, so only the capped camera counts. Both
+    // directions a removed sender can land on are excluded: `inactive` from a sendonly
+    // transceiver, `recvonly` from the sendrecv one the addTrack fallback reuses.
+    expect(
+      computeConnectionStartBitrate(parse(UNPUBLISHED_SCREEN_SHARE).media, trackBitrates),
+    ).toBe(900);
+    expect(
+      computeConnectionStartBitrate(
+        parse(UNPUBLISHED_SCREEN_SHARE.replace('a=inactive', 'a=recvonly')).media,
+        trackBitrates,
+      ),
+    ).toBe(900);
+  });
+
+  it('gives no connection value when no section maps to a published track', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+
+    expect(computeConnectionStartBitrate(media, [])).toBeUndefined();
+  });
+
+  it('counts sendrecv and direction-less sections, which still send local media', () => {
+    // The legacy addTrack fallback never produces `sendonly`, so a strict match on it would
+    // leave those clients with no hint at all.
+    const { media } = parse(LEGACY_ADD_TRACK_SECTIONS);
+
+    expect(
+      computeConnectionStartBitrate(media, [{ cid: 'camera-cid', codec: 'VP8', maxbr: 1_000 }]),
+    ).toBe(900);
+    expect(
+      computeConnectionStartBitrate(media, [
+        { cid: 'other-track', codec: 'VP8', maxbr: 2_000, isScreenShare: true },
+      ]),
+    ).toBe(1_800);
+  });
+
+  it('leaves the hint unset when only non-sending sections match', () => {
+    // Nothing is published, so the one-shot hint must not be consumed on a dead section.
+    const { media } = parse(UNPUBLISHED_SCREEN_SHARE);
+
+    expect(
+      computeConnectionStartBitrate(media, [
+        { cid: 'other-track', codec: 'VP8', maxbr: 8_000, isScreenShare: true },
+      ]),
+    ).toBeUndefined();
+  });
 });
 
 describe('placeholderMidsFromTransceivers', () => {
@@ -390,3 +678,33 @@ a=extmap:3 ${ddExtensionURI}`);
     expect(ddOf(sdp.media, '1')).toBe(12);
   });
 });
+
+describe('isDuplicateAnswer', () => {
+  it('drops an answer while the same offer is still being answered', () => {
+    expect(isDuplicateAnswer(3, 3, 0, 'have-local-offer', false)).toBe(true);
+  });
+
+  it('drops a repeat of an unnumbered answer while the first is still applying', () => {
+    expect(isDuplicateAnswer(0, 0, 0, 'have-local-offer', false)).toBe(true);
+  });
+
+  it('drops an answer for an offer whose answer was already applied', () => {
+    expect(isDuplicateAnswer(3, undefined, 3, 'stable', false)).toBe(true);
+  });
+
+  it('accepts a retry after a failed apply: nothing in flight, nothing applied', () => {
+    expect(isDuplicateAnswer(3, undefined, 2, 'have-local-offer', false)).toBe(false);
+  });
+
+  it('accepts the answer for a new offer', () => {
+    expect(isDuplicateAnswer(4, undefined, 3, 'have-local-offer', false)).toBe(false);
+  });
+
+  it('without an offerId, drops an answer in stable', () => {
+    expect(isDuplicateAnswer(0, undefined, 0, 'stable', false)).toBe(true);
+  });
+
+  it('without an offerId, accepts the answer to a deferred initial offer', () => {
+    expect(isDuplicateAnswer(0, undefined, 0, 'stable', true)).toBe(false);
+  });
+});