fix: stop putting the subscriber into restartingIce on a reconnect (#2054)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: xianshijing-lk

.changeset/bound-subscriber-ice-restart-window.md

@@ -0,0 +1,13 @@
+---
+'livekit-client': patch
+---
+
+Fix the subscriber silently buffering remote ICE candidates after a reconnect
+
+`triggerIceRestart` put the subscriber into `restartingIce` on every reconnect, but only
+`setRemoteDescription` clears that — and the server re-offers the subscriber only when the
+reconnect moved the participant to a different node. After an ordinary signal-only resume no
+offer arrives, so the flag stayed set for the lifetime of the transport and every subsequent
+remote candidate was queued instead of applied, leaving the subscriber unable to adopt any new
+network path the server proposed. The subscriber no longer enters that state: the server does
+not send candidates ahead of the offer that introduces them, so queueing them gains nothing.

src/room/PCTransportManager.test.ts

@@ -279,3 +279,38 @@ describe('PCTransportManager.negotiate', () => {
     await expect(p).resolves.toBeUndefined();
   });
 });
+
+describe('PCTransportManager.triggerIceRestart', () => {
+  let originalRTCPeerConnection: unknown;
+
+  beforeEach(() => {
+    originalRTCPeerConnection = (globalThis as unknown as { RTCPeerConnection?: unknown })
+      .RTCPeerConnection;
+    (globalThis as unknown as { RTCPeerConnection: unknown }).RTCPeerConnection = StubPC;
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { RTCPeerConnection: unknown }).RTCPeerConnection =
+      originalRTCPeerConnection;
+  });
+
+  /**
+   * The subscriber must keep applying remote candidates across a reconnect.
+   *
+   * Putting it into `restartingIce` would queue them until a new remote description arrives —
+   * but the server only re-offers the subscriber when the reconnect moved us to another node,
+   * so on an ordinary signal-only resume nothing would ever flush that queue, and the
+   * transport would stop adopting new network paths for the rest of the session. The server
+   * also never sends candidates ahead of the offer that introduces them, so queueing buys
+   * nothing in exchange.
+   */
+  it('does not stop the subscriber applying remote candidates', async () => {
+    const manager = new PCTransportManager('subscriber-primary', {});
+    const publisher = new FakePublisher();
+    (manager as unknown as { publisher: FakePublisher }).publisher = publisher;
+
+    await manager.triggerIceRestart();
+
+    expect(manager.subscriber?.restartingIce).toBe(false);
+  });
+});

src/room/PCTransportManager.ts

@@ -162,12 +162,20 @@ export class PCTransportManager {
     this.updateState();
   }
 
+  /**
+   * Restarts ICE on the transports that need it. Only the publisher: the server restarts the
+   * subscriber's ICE itself and follows with a fresh offer.
+   *
+   * The subscriber deliberately does NOT enter `restartingIce` here. Queueing its remote
+   * candidates would guard against candidates for a new generation arriving before the offer
+   * that introduces it, but the server does not send them in that order -- on a same-node
+   * resume it buffers them until the offer has gone out, and on a reconnect that lands on
+   * another node it withholds subscriber candidates until immediately before creating the
+   * offer. Setting the flag only risks withholding candidates during the window that decides
+   * whether the reconnect succeeded.
+   */
   async triggerIceRestart() {
     this.iceLog.warn('triggering ICE restart');
-    if (this.subscriber) {
-      this.subscriber.restartingIce = true;
-    }
-    // only restart publisher if it's needed
     if (this.needsPublisher) {
       await this.createAndSendPublisherOffer({ iceRestart: true });
     }