livekit-client 2.22.3 → 2.22.4

package/dist/ts4.2/version.d.ts

@@ -1,15 +1,15 @@
-export declare const version: string;
-export declare const protocolVersion = 17;
-/** Initial client protocol. */
-export declare const CLIENT_PROTOCOL_DEFAULT = 0;
-/** Replaces RPC v1 protocol with a v2 data streams based one to support unlimited request /
- * response payload length. */
-export declare const CLIENT_PROTOCOL_DATA_STREAM_RPC = 1;
-/** "Data streams v2": the client knows how to receive a single-packet data stream (a stream whose
- * entire payload is smuggled into the header packet, with no chunk/trailer packets). Senders only
- * use the single-packet optimization when the recipient advertises at least this protocol. */
-export declare const CLIENT_PROTOCOL_DATA_STREAM_V2 = 2;
-/** The client protocol version indicates what level of support that the client has for
- * client <-> client api interactions. */
-export declare const clientProtocol = 2;
-//# sourceMappingURL=version.d.ts.map
+export declare const version: string;
+export declare const protocolVersion = 17;
+/** Initial client protocol. */
+export declare const CLIENT_PROTOCOL_DEFAULT = 0;
+/** Replaces RPC v1 protocol with a v2 data streams based one to support unlimited request /
+ * response payload length. */
+export declare const CLIENT_PROTOCOL_DATA_STREAM_RPC = 1;
+/** "Data streams v2": the client knows how to receive a single-packet data stream (a stream whose
+ * entire payload is smuggled into the header packet, with no chunk/trailer packets). Senders only
+ * use the single-packet optimization when the recipient advertises at least this protocol. */
+export declare const CLIENT_PROTOCOL_DATA_STREAM_V2 = 2;
+/** The client protocol version indicates what level of support that the client has for
+ * client <-> client api interactions. */
+export declare const clientProtocol = 2;
+//# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.22.3",
+  "version": "2.22.4",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -50,7 +50,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@livekit/mutex": "1.1.1",
-    "@livekit/protocol": "1.50.4",
+    "@livekit/protocol": "1.52.1",
     "events": "^3.3.0",
     "jose": "^6.1.0",
     "loglevel": "^1.9.2",
@@ -85,9 +85,10 @@
     "@types/ua-parser-js": "0.7.39",
     "@typescript-eslint/eslint-plugin": "8.64.0",
     "@typescript-eslint/parser": "8.64.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
-    "downlevel-dts": "^0.11.0",
+    "@nbilyk/downlevel-dts": "^0.15.2",
     "eslint": "10.7.0",
     "eslint-config-airbnb-extended": "^2.3.2",
     "eslint-config-prettier": "10.1.8",
@@ -113,7 +114,7 @@
     "tsx": "^4.21.0",
     "typedoc": "0.28.20",
     "typedoc-plugin-no-inherit": "1.6.1",
-    "typescript": "5.9.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.47.0",
     "vite": "8.1.5",
     "vitest": "^4.1.10"

package/src/api/SignalClient.e2e.test.ts

@@ -174,9 +174,7 @@ describe.skipIf(!!unavailable)('SignalClient e2e', () => {
 
     it('rejects a reconnect when a leave arrives as the first message', async () => {
       // Reconnecting into a room that sends leave-first exercises the client's
-      // first-message validation while in RECONNECTING (path-independent: it
-      // doesn't rely on the mock detecting reconnect, which v1 hides inside the
-      // gzipped join_request the mock ignores).
+      // first-message validation while in RECONNECTING.
       await join('happy');
       const token = await createToken({ signal: 'leave_first_message' });
       const err = await client.reconnect(serverUrl, token, 'RM_session').then(

package/src/api/SignalClient.test.ts

@@ -206,6 +206,152 @@ describe('SignalClient.connect', () => {
         ClientInfo_Capability.CAP_PACKET_TRAILER,
       ]);
     });
+
+    it('does not request full ICE by default', async () => {
+      const joinResponse = createJoinResponse();
+      const signalResponse = createSignalResponse('join', joinResponse);
+      const mockReadable = createMockReadableStream([signalResponse]);
+      const mockConnection = createMockConnection(mockReadable);
+      let capturedUrl = '';
+
+      mockWebSocketStream({
+        connection: mockConnection,
+        onUrl: (url) => {
+          capturedUrl = url;
+        },
+      });
+
+      await signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions);
+
+      const joinRequest = await decodeJoinRequestFromUrl(capturedUrl);
+      expect(joinRequest.connectionSettings?.disableIceLite).toBe(false);
+    });
+
+    it('requests full ICE in the join request when disableIceLite is set', async () => {
+      const joinResponse = createJoinResponse();
+      const signalResponse = createSignalResponse('join', joinResponse);
+      const mockReadable = createMockReadableStream([signalResponse]);
+      const mockConnection = createMockConnection(mockReadable);
+      let capturedUrl = '';
+
+      mockWebSocketStream({
+        connection: mockConnection,
+        onUrl: (url) => {
+          capturedUrl = url;
+        },
+      });
+
+      await signalClient.join('wss://test.livekit.io', 'test-token', {
+        ...defaultOptions,
+        disableIceLite: true,
+      });
+
+      const joinRequest = await decodeJoinRequestFromUrl(capturedUrl);
+      expect(joinRequest.connectionSettings?.disableIceLite).toBe(true);
+    });
+
+    it('requests full ICE on the v0 path when disableIceLite is set', async () => {
+      const joinResponse = createJoinResponse();
+      const signalResponse = createSignalResponse('join', joinResponse);
+      const mockReadable = createMockReadableStream([signalResponse]);
+      const mockConnection = createMockConnection(mockReadable);
+      let capturedUrl = '';
+
+      mockWebSocketStream({
+        connection: mockConnection,
+        onUrl: (url) => {
+          capturedUrl = url;
+        },
+      });
+
+      await signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        { ...defaultOptions, disableIceLite: true },
+        undefined,
+        true,
+      );
+
+      expect(new URL(capturedUrl).searchParams.get('disable_ice_lite')).toBe('1');
+    });
+
+    it('leaves subscriberAllowPause unset by default so the server default applies', async () => {
+      const joinResponse = createJoinResponse();
+      const signalResponse = createSignalResponse('join', joinResponse);
+      const mockReadable = createMockReadableStream([signalResponse]);
+      const mockConnection = createMockConnection(mockReadable);
+      let capturedUrl = '';
+
+      mockWebSocketStream({
+        connection: mockConnection,
+        onUrl: (url) => {
+          capturedUrl = url;
+        },
+      });
+
+      await signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions);
+
+      const joinRequest = await decodeJoinRequestFromUrl(capturedUrl);
+      expect(joinRequest.connectionSettings?.subscriberAllowPause).toBeUndefined();
+    });
+
+    it.each([true, false])(
+      'sets subscriberAllowPause=%s in the join request',
+      async (subscriberAllowPause) => {
+        const joinResponse = createJoinResponse();
+        const signalResponse = createSignalResponse('join', joinResponse);
+        const mockReadable = createMockReadableStream([signalResponse]);
+        const mockConnection = createMockConnection(mockReadable);
+        let capturedUrl = '';
+
+        mockWebSocketStream({
+          connection: mockConnection,
+          onUrl: (url) => {
+            capturedUrl = url;
+          },
+        });
+
+        await signalClient.join('wss://test.livekit.io', 'test-token', {
+          ...defaultOptions,
+          subscriberAllowPause,
+        });
+
+        const joinRequest = await decodeJoinRequestFromUrl(capturedUrl);
+        expect(joinRequest.connectionSettings?.subscriberAllowPause).toBe(subscriberAllowPause);
+      },
+    );
+
+    it.each([
+      [undefined, null],
+      [true, '1'],
+      [false, '0'],
+    ])(
+      'sets subscriber_allow_pause on the v0 path when subscriberAllowPause=%s',
+      async (subscriberAllowPause, expected) => {
+        const joinResponse = createJoinResponse();
+        const signalResponse = createSignalResponse('join', joinResponse);
+        const mockReadable = createMockReadableStream([signalResponse]);
+        const mockConnection = createMockConnection(mockReadable);
+        let capturedUrl = '';
+
+        mockWebSocketStream({
+          connection: mockConnection,
+          onUrl: (url) => {
+            capturedUrl = url;
+          },
+        });
+
+        await signalClient.join(
+          'wss://test.livekit.io',
+          'test-token',
+          { ...defaultOptions, subscriberAllowPause },
+          undefined,
+          true,
+        );
+
+        expect(new URL(capturedUrl).searchParams.get('subscriber_allow_pause')).toBe(expected);
+      },
+    );
   });
 
   describe('Happy Path - Reconnect', () => {
@@ -236,7 +382,7 @@ describe('SignalClient.connect', () => {
       expect(signalClient.currentState).toBe(SignalConnectionState.CONNECTED);
     });
 
-    it('should handle reconnect with non-reconnect message (edge case)', async () => {
+    it('drops stray messages during reconnect and waits for the reconnect response', async () => {
       // First, initial connection
       const joinResponse = createJoinResponse();
       const joinSignalResponse = createSignalResponse('join', joinResponse);
@@ -247,19 +393,24 @@ describe('SignalClient.connect', () => {
 
       await signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions);
 
-      // Setup reconnect with non-reconnect message (e.g., participant update)
+      // Server sends a stray update first, then the actual reconnect response.
+      // The stray should be dropped with a warning; the reconnect response should resolve.
       const updateSignalResponse = createSignalResponse('update', { participants: [] });
-      const reconnectMockReadable = createMockReadableStream([updateSignalResponse]);
+      const reconnectResponse = new ReconnectResponse({ iceServers: [] });
+      const reconnectSignalResponse = createSignalResponse('reconnect', reconnectResponse);
+      const reconnectMockReadable = createMockReadableStream([
+        updateSignalResponse,
+        reconnectSignalResponse,
+      ]);
       const reconnectMockConnection = createMockConnection(reconnectMockReadable);
 
       mockWebSocketStream({ connection: reconnectMockConnection });
 
       const result = await signalClient.reconnect('wss://test.livekit.io', 'test-token', 'sid-123');
 
-      // This is an edge case: reconnect resolves with undefined when non-reconnect message is received
-      expect(result).toBeUndefined();
+      expect(result).toEqual(reconnectResponse);
       expect(signalClient.currentState).toBe(SignalConnectionState.CONNECTED);
-    }, 1000);
+    });
   });
 
   describe('Failure Case - Timeout', () => {
@@ -1026,7 +1177,7 @@ describe('SignalClient.validateFirstMessage', () => {
     }
   });
 
-  it('should accept non-reconnect message during reconnecting state', async () => {
+  it('should reject non-reconnect message during reconnecting state', async () => {
     // First establish a connection
     const joinResponse = createJoinResponse();
     const joinSignalResponse = createSignalResponse('join', joinResponse);
@@ -1044,9 +1195,8 @@ describe('SignalClient.validateFirstMessage', () => {
     const validateMethod = (signalClient as any).validateFirstMessage;
     if (validateMethod) {
       const result = validateMethod.call(signalClient, updateSignalResponse, true);
-      expect(result.isValid).toBe(true);
-      expect(result.response).toBeUndefined();
-      expect(result.shouldProcessFirstMessage).toBe(true);
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(ConnectionError);
     }
   });
 

package/src/api/SignalClient.ts

@@ -92,6 +92,8 @@ interface ConnectOpts extends SignalOptions {
 export interface SignalOptions {
   autoSubscribe: boolean;
   adaptiveStream?: boolean;
+  disableIceLite?: boolean;
+  subscriberAllowPause?: boolean;
   clientInfoCapabilities?: ClientInfo_Capability[];
   maxRetries: number;
   e2eeEnabled: boolean;
@@ -581,38 +583,61 @@ export class SignalClient {
           this.streamWriter = connection.writable.getWriter();
 
           // wsTimeout only guarded the upgrade; guard the first-message read with
-          // its own timeout so a silent server can't hang join() forever.
-          let firstMessage: ReadableStreamReadResult<string | ArrayBuffer>;
-          let firstMessageTimeout: ReturnType<typeof setTimeout> | undefined;
+          // its own deadline so a silent server can't hang join() forever.
+          // During reconnect, drop any stray messages that arrive before the
+          // ReconnectResponse so we do not declare the channel reconnected on the
+          // wrong signal.
+          let firstSignalResponse: SignalResponse;
           try {
-            firstMessage = await Promise.race([
-              signalReader.read(),
-              new Promise<never>((_, rejectRead) => {
-                firstMessageTimeout = setTimeout(() => {
-                  rejectRead(
-                    ConnectionError.timeout(
-                      'signal connection timed out while waiting for the first message',
-                    ),
-                  );
-                }, JOIN_RESPONSE_TIMEOUT);
-              }),
-            ]);
+            const deadline = Date.now() + JOIN_RESPONSE_TIMEOUT;
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+              const remaining = deadline - Date.now();
+              if (remaining <= 0) {
+                throw ConnectionError.timeout(
+                  'signal connection timed out while waiting for the first message',
+                );
+              }
+              let readTimeout: ReturnType<typeof setTimeout> | undefined;
+              const readResult = await Promise.race([
+                signalReader.read(),
+                new Promise<never>((_, rejectRead) => {
+                  readTimeout = setTimeout(() => {
+                    rejectRead(
+                      ConnectionError.timeout(
+                        'signal connection timed out while waiting for the first message',
+                      ),
+                    );
+                  }, remaining);
+                }),
+              ]);
+              clearTimeout(readTimeout);
+              if (!readResult.value) {
+                throw ConnectionError.internal('no message received as first message');
+              }
+              const parsed = parseSignalResponse(readResult.value);
+              if (
+                this.lifecycleState === 'reconnecting' &&
+                parsed.message?.case !== 'reconnect' &&
+                parsed.message?.case !== 'leave'
+              ) {
+                this.log.warn('dropping signal message while awaiting reconnect response', {
+                  messageCase: parsed.message?.case,
+                });
+                continue;
+              }
+              firstSignalResponse = parsed;
+              break;
+            }
           } catch (e) {
-            // No first message in time: release the reader and tear down the ws
+            // No usable first message in time: release the reader and tear down the ws
             // so we surface the timeout instead of leaking an open connection.
             signalReader.releaseLock();
             reject(e);
             this.close();
             return;
-          } finally {
-            clearTimeout(firstMessageTimeout);
           }
           signalReader.releaseLock();
-          if (!firstMessage.value) {
-            throw ConnectionError.internal('no message received as first message');
-          }
-
-          const firstSignalResponse = parseSignalResponse(firstMessage.value);
 
           // Validate the first message
           const validation = this.validateFirstMessage(
@@ -643,11 +668,7 @@ export class SignalClient {
             }
           }
 
-          // Handle successful connection
-          const firstMessageToProcess = validation.shouldProcessFirstMessage
-            ? firstSignalResponse
-            : undefined;
-          this.handleSignalConnected(connection, wsTimeout, attemptId, firstMessageToProcess);
+          this.handleSignalConnected(connection, wsTimeout, attemptId);
           resolve(validation.response);
         } catch (e) {
           reject(e);
@@ -660,13 +681,7 @@ export class SignalClient {
     });
   }
 
-  async startReadingLoop(
-    signalReader: ReadableStreamDefaultReader<string | ArrayBuffer>,
-    firstMessage?: SignalResponse,
-  ) {
-    if (firstMessage) {
-      this.handleSignalResponse(firstMessage);
-    }
+  async startReadingLoop(signalReader: ReadableStreamDefaultReader<string | ArrayBuffer>) {
     const attemptId = this.attemptId;
     while (true) {
       if (this.signalLatency) {
@@ -1099,7 +1114,11 @@ export class SignalClient {
    * Handles a transport we lost without asking to. The client goes to `offline` rather than
    * `closed`: whether this session gets resumed, restarted or given up on is the engine's call.
    */
-  private async handleOnClose(reason: string, attemptId: number = this.attemptId) {
+  private async handleOnClose(
+    reason: string,
+    attemptId: number = this.attemptId,
+    simulateReconnectDelay?: number,
+  ) {
     const onCloseCallback = this.onClose;
     if (!this.sendLifecycleInput({ type: 'transportFailed', attemptId, reason })) {
       // a close we caused ourselves, or one from a transport that has since been replaced: logged
@@ -1114,6 +1133,10 @@ export class SignalClient {
     }
     await this.teardownTransport(reason);
     this.log.info(`websocket connection closed: ${reason}`, { reason });
+    if (simulateReconnectDelay) {
+      this.log.info(`waiting for ${simulateReconnectDelay}ms until reconnecting signal`);
+      await sleep(simulateReconnectDelay);
+    }
     if (onCloseCallback) {
       onCloseCallback(reason);
     }
@@ -1184,7 +1207,6 @@ export class SignalClient {
     connection: WebSocketConnection,
     timeoutHandle: ReturnType<typeof setTimeout>,
     attemptId: number,
-    firstMessage?: SignalResponse,
   ) {
     clearTimeout(timeoutHandle);
     const established = this.sendLifecycleInput(
@@ -1205,7 +1227,7 @@ export class SignalClient {
     }
     this.log.info('signal connected');
     this.startPingInterval();
-    this.startReadingLoop(connection.readable.getReader(), firstMessage);
+    this.startReadingLoop(connection.readable.getReader());
   }
 
   /**
@@ -1222,7 +1244,6 @@ export class SignalClient {
     isValid: boolean;
     response?: JoinResponse | ReconnectResponse;
     error?: ConnectionError;
-    shouldProcessFirstMessage?: boolean;
   } {
     if (firstSignalResponse.message?.case === 'join') {
       return {
@@ -1231,22 +1252,12 @@ export class SignalClient {
       };
     } else if (
       this.lifecycleState === 'reconnecting' &&
-      firstSignalResponse.message?.case !== 'leave'
+      firstSignalResponse.message?.case === 'reconnect'
     ) {
-      if (firstSignalResponse.message?.case === 'reconnect') {
-        return {
-          isValid: true,
-          response: firstSignalResponse.message.value,
-        };
-      } else {
-        // in reconnecting, any message received means signal reconnected and we still need to process it
-        this.log.debug('declaring signal reconnected without reconnect response received');
-        return {
-          isValid: true,
-          response: undefined,
-          shouldProcessFirstMessage: true,
-        };
-      }
+      return {
+        isValid: true,
+        response: firstSignalResponse.message.value,
+      };
     } else if (this.isEstablishingConnection && firstSignalResponse.message?.case === 'leave') {
       return {
         isValid: false,
@@ -1394,6 +1405,14 @@ function createConnectionParams(
     params.set('adaptive_stream', '1');
   }
 
+  if (opts.disableIceLite) {
+    params.set('disable_ice_lite', '1');
+  }
+
+  if (typeof opts.subscriberAllowPause !== 'undefined') {
+    params.set('subscriber_allow_pause', opts.subscriberAllowPause ? '1' : '0');
+  }
+
   if (opts.reconnectReason) {
     params.set('reconnect_reason', opts.reconnectReason.toString());
   }
@@ -1421,6 +1440,8 @@ async function createJoinRequestConnectionParams(
     connectionSettings: new ConnectionSettings({
       autoSubscribe: !!opts.autoSubscribe,
       adaptiveStream: !!opts.adaptiveStream,
+      disableIceLite: !!opts.disableIceLite,
+      subscriberAllowPause: opts.subscriberAllowPause,
     }),
     reconnect: !!opts.reconnect,
     participantSid: opts.sid ? opts.sid : undefined,

package/src/options.ts

@@ -166,6 +166,22 @@ export interface InternalRoomConnectOptions {
    */
   rtcConfig?: RTCConfiguration;
 
+  /**
+   * when the server runs ICE lite, asks it to use a full ICE agent for this participant.
+   * this is a server-side setting that the server may ignore, defaults to false
+   */
+  disableIceLite: boolean;
+
+  /**
+   * whether the SFU may pause subscribed video tracks when this participant's downstream
+   * connection is congested, so that other tracks can continue to stream smoothly.
+   * paused tracks resume automatically when conditions allow, and `RoomEvent.TrackStreamStateChanged`
+   * fires on each transition.
+   * when left undefined, the server's default applies (the project setting on LiveKit Cloud,
+   * or `rtc.congestion_control.allow_pause` when self-hosting)
+   */
+  subscriberAllowPause?: boolean;
+
   /** specifies how often an initial join connection is allowed to retry (only applicable if server is not reachable) */
   maxRetries: number;