livekit-client 2.22.3 → 2.23.0

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.23.0",
   "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

@@ -11,8 +11,10 @@ import {
   WrappedJoinRequest_Compression,
 } from '@livekit/protocol';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Mutex } from '@livekit/mutex';
 import { ConnectionError, ConnectionErrorReason } from '../room/errors';
 import CriticalTimers from '../room/timers';
+import { Future } from '../room/utils';
 import { SignalClient, SignalConnectionState } from './SignalClient';
 import type { WebSocketCloseInfo, WebSocketConnection } from './WebSocketStream';
 import { WebSocketStream } from './WebSocketStream';
@@ -147,6 +149,167 @@ describe('SignalClient.connect', () => {
     return JoinRequest.fromBinary(bytes);
   }
 
+  describe('Cancelled connection attempts', () => {
+    it.each(['before join', 'while waiting for the connection lock'])(
+      'does not open a transport when aborted %s',
+      async (when) => {
+        const abortController = new AbortController();
+        const internals = signalClient as unknown as { connectionLock: Mutex };
+        const unlock = await internals.connectionLock.lock();
+        mockWebSocketStream({
+          connection: createMockConnection(
+            createMockReadableStream([createSignalResponse('join', createJoinResponse())]),
+          ),
+        });
+        if (when === 'before join') abortController.abort();
+        const joining = signalClient.join(
+          'wss://test.livekit.io',
+          'test-token',
+          defaultOptions,
+          abortController.signal,
+        );
+        abortController.abort();
+        unlock();
+
+        try {
+          await expect(joining).rejects.toMatchObject({ reason: ConnectionErrorReason.Cancelled });
+          expect(WebSocketStream).not.toHaveBeenCalled();
+        } finally {
+          await signalClient.close();
+          vi.mocked(WebSocketStream).mockReset();
+        }
+      },
+    );
+
+    it('does not replace a transport when aborted during its teardown', async () => {
+      const abortController = new AbortController();
+      const internals = signalClient as unknown as {
+        connectionLock: Mutex;
+        teardownTransport: (reason: string) => Promise<void>;
+      };
+      const teardownStarted = new Future<void, Error>();
+      const finishTeardown = new Future<void, Error>();
+      vi.spyOn(internals, 'teardownTransport').mockImplementationOnce(async () => {
+        teardownStarted.resolve?.();
+        await finishTeardown.promise;
+      });
+      signalClient.ws = {
+        close: () => {},
+        closed: Promise.resolve({ closeCode: 1000, reason: '' }),
+      } as WebSocketStream;
+      mockWebSocketStream({
+        connection: createMockConnection(
+          createMockReadableStream([createSignalResponse('join', createJoinResponse())]),
+        ),
+      });
+
+      const joining = signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        defaultOptions,
+        abortController.signal,
+      );
+      const cancelled = expect(joining).rejects.toMatchObject({
+        reason: ConnectionErrorReason.Cancelled,
+      });
+      await teardownStarted.promise;
+      abortController.abort();
+      finishTeardown.resolve?.();
+      await cancelled;
+      // The rejection can settle before the transport replacement resumes.
+      const unlock = await internals.connectionLock.lock();
+      unlock();
+
+      try {
+        expect(WebSocketStream).not.toHaveBeenCalled();
+      } finally {
+        await signalClient.close();
+        vi.mocked(WebSocketStream).mockReset();
+      }
+    });
+    it('does not validate the url when aborted while the websocket is opening', async () => {
+      const abortController = new AbortController();
+      const internals = signalClient as unknown as { connectionLock: Mutex };
+      const opened = new Future<WebSocketConnection, Error>();
+      opened.promise.catch(() => {});
+      mockWebSocketStream({ opened: opened.promise, readyState: 0 });
+      vi.mocked(global.fetch).mockClear();
+
+      const joining = signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        defaultOptions,
+        abortController.signal,
+      );
+      const cancelled = expect(joining).rejects.toMatchObject({
+        reason: ConnectionErrorReason.Cancelled,
+      });
+      await vi.waitFor(() => expect(WebSocketStream).toHaveBeenCalled());
+      abortController.abort();
+      opened.reject?.(new Error('closed by abort'));
+      await cancelled;
+      // let the attempt's continuation run to completion
+      const unlock = await internals.connectionLock.lock();
+      unlock();
+
+      try {
+        expect(global.fetch).not.toHaveBeenCalled();
+      } finally {
+        await signalClient.close();
+        vi.mocked(WebSocketStream).mockReset();
+      }
+    });
+
+    it('does not report a join that arrives after the attempt was aborted', async () => {
+      const abortController = new AbortController();
+      const internals = signalClient as unknown as { connectionLock: Mutex };
+      let enqueue: ((chunk: ArrayBuffer) => void) | undefined;
+      const readable = new ReadableStream<ArrayBuffer>({
+        start(controller) {
+          enqueue = (chunk) => controller.enqueue(chunk);
+        },
+      });
+      const writerReady = new Future<void, Error>();
+      const writable = new WritableStream();
+      const getWriter = writable.getWriter.bind(writable);
+      writable.getWriter = () => {
+        const writer = getWriter();
+        writerReady.resolve?.();
+        return writer;
+      };
+      mockWebSocketStream({
+        connection: { readable, writable, protocol: '', extensions: '' },
+      });
+      const onJoined = vi.fn();
+      signalClient.onJoined = onJoined;
+
+      const joining = signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        defaultOptions,
+        abortController.signal,
+      );
+      const cancelled = expect(joining).rejects.toMatchObject({
+        reason: ConnectionErrorReason.Cancelled,
+      });
+      await writerReady.promise;
+      abortController.abort();
+      enqueue?.(
+        createSignalResponse('join', createJoinResponse()).toBinary().buffer as ArrayBuffer,
+      );
+      await cancelled;
+      const unlock = await internals.connectionLock.lock();
+      unlock();
+
+      try {
+        expect(onJoined).not.toHaveBeenCalled();
+      } finally {
+        await signalClient.close();
+        vi.mocked(WebSocketStream).mockReset();
+      }
+    });
+  });
+
   describe('Happy Path - Initial Join', () => {
     it('should successfully connect and receive join response', async () => {
       const joinResponse = createJoinResponse();
@@ -162,6 +325,17 @@ describe('SignalClient.connect', () => {
       expect(signalClient.currentState).toBe(SignalConnectionState.CONNECTED);
     });
 
+    it('releases the connection lock when the url is malformed', async () => {
+      await expect(signalClient.join('not a url', 'test-token', defaultOptions)).rejects.toThrow();
+
+      const joinResponse = createJoinResponse();
+      const mockReadable = createMockReadableStream([createSignalResponse('join', joinResponse)]);
+      mockWebSocketStream({ connection: createMockConnection(mockReadable) });
+
+      const result = await signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions);
+      expect(result).toEqual(joinResponse);
+    });
+
     it('does not advertise packet trailer capability by default', async () => {
       const joinResponse = createJoinResponse();
       const signalResponse = createSignalResponse('join', joinResponse);
@@ -206,6 +380,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 +556,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 +567,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', () => {
@@ -742,6 +1067,66 @@ describe('SignalClient.connect', () => {
     });
   });
 
+  describe('Failure Case - Validate Request Hangs', () => {
+    // A socket that never opens on its own (a lossy network) and whose `opened` rejects once the
+    // client closes it, like a real WebSocketStream aborted during the handshake.
+    function mockHangingWebSocket() {
+      vi.mocked(WebSocketStream).mockImplementationOnce(function () {
+        let rejectOpened!: (e: unknown) => void;
+        let resolveClosed!: (info: WebSocketCloseInfo) => void;
+        return {
+          url: 'wss://test.livekit.io',
+          opened: new Promise((_, reject) => (rejectOpened = reject)),
+          closed: new Promise((resolve) => (resolveClosed = resolve)),
+          close: vi.fn(() => {
+            rejectOpened(new Error('aborted during handshake'));
+            resolveClosed({ closeCode: 1006, reason: '' });
+          }),
+          readyState: 0,
+        } as any;
+      });
+    }
+
+    it('does not let a timed-out attempt block the next one', async () => {
+      // A validate request on a dead pooled connection only settles once its abort signal fires.
+      // Without a deadline it held the connection lock, so the next attempt never started. A
+      // timed-out attempt now skips validation entirely, since its caller has already been rejected.
+      vi.useFakeTimers();
+      try {
+        const hangingFetch = (_url: unknown, init?: RequestInit) =>
+          new Promise<Response>((_, reject) => {
+            init?.signal?.addEventListener('abort', () => reject(init.signal!.reason));
+          });
+        vi.mocked(fetch).mockImplementationOnce(hangingFetch).mockImplementationOnce(hangingFetch);
+        mockHangingWebSocket();
+        mockHangingWebSocket();
+
+        // building the join request finishes on real I/O, so wait for each socket before advancing
+        const first = expect(
+          signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions),
+        ).rejects.toMatchObject({ reason: ConnectionErrorReason.Timeout });
+        await vi.waitFor(() => expect(WebSocketStream).toHaveBeenCalledTimes(1));
+        await vi.advanceTimersByTimeAsync(defaultOptions.websocketTimeout);
+        await first;
+
+        const second = expect(
+          signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions),
+        ).rejects.toMatchObject({ reason: ConnectionErrorReason.Timeout });
+        // past the validate deadline, which is what releases the lock the first attempt holds
+        await vi.advanceTimersByTimeAsync(10_000);
+        await vi.waitFor(() => expect(WebSocketStream).toHaveBeenCalledTimes(2));
+        await vi.advanceTimersByTimeAsync(defaultOptions.websocketTimeout);
+        await second;
+
+        expect(fetch).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+        // drop the unused hanging fetches so they don't leak into later tests
+        vi.mocked(fetch).mockReset();
+      }
+    });
+  });
+
   describe('Establishing over an existing session', () => {
     async function joinSuccessfully() {
       mockWebSocketStream({
@@ -1026,7 +1411,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 +1429,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);
     }
   });