@stream-io/video-client 1.54.1-beta.0 → 1.55.1

package/src/StreamSfuClient.ts

@@ -164,13 +164,24 @@ export class StreamSfuClient {
    */
   isClosingClean = false;
 
+  /**
+   * One-shot latch guarding `onSignalClose`. The signal connection can be
+   * detected as dead by more than one source (the health watchdog and the
+   * WebSocket `close` event, which on a wedged socket can arrive seconds
+   * apart). This ensures revival is triggered at most once per client.
+   */
+  private signalClosed = false;
+
   private readonly rpc: SignalServerClient;
   private keepAliveInterval?: number;
-  private connectionCheckTimeout?: NodeJS.Timeout;
+  private connectionCheckInterval?: number;
   private migrateAwayTimeout?: NodeJS.Timeout;
   private readonly pingIntervalInMs = 5 * 1000;
-  private readonly unhealthyTimeoutInMs = 15 * 1000;
-  private lastMessageTimestamp?: Date;
+  private readonly unhealthyTimeoutInMs = this.pingIntervalInMs * 2 + 2 * 1000;
+  private readonly connectionCheckIntervalInMs = Math.round(
+    this.unhealthyTimeoutInMs / 3,
+  );
+  private lastMessageTimestamp?: number;
   private readonly tracer?: Tracer;
   private readonly unsubscribeIceTrickle: () => void;
   private readonly unsubscribeNetworkChanged: () => void;
@@ -209,7 +220,7 @@ export class StreamSfuClient {
   /**
    * The error code used when the SFU connection is unhealthy.
    * Usually, this means that no message has been received from the SFU for
-   * a certain amount of time (`connectionCheckTimeout`).
+   * a certain amount of time (`unhealthyTimeoutInMs`).
    */
   static ERROR_CONNECTION_UNHEALTHY = 4001;
   /**
@@ -311,7 +322,7 @@ export class StreamSfuClient {
       endpoint: `${this.credentials.server.ws_endpoint}?${new URLSearchParams(params).toString()}`,
       tracer: this.tracer,
       onMessage: (message) => {
-        this.lastMessageTimestamp = new Date();
+        this.lastMessageTimestamp = Date.now();
         this.scheduleConnectionCheck();
         const eventKind = message.eventPayload.oneofKind;
         if (eventsToTrace[eventKind]) {
@@ -336,7 +347,7 @@ export class StreamSfuClient {
           this.signalWs.addEventListener('open', onOpen);
 
           this.signalWs.addEventListener('close', (e) => {
-            this.handleWebSocketClose(e);
+            this.notifySignalClose(`${e.code} ${e.reason ?? ''}`);
             // Normally, this shouldn't have any effect, because WS should never emit 'close'
             // before emitting 'open'. However, stranger things have happened, and we don't
             // want to leave signalReady in a pending state.
@@ -371,11 +382,13 @@ export class StreamSfuClient {
     return this.joinResponseTask.promise;
   }
 
-  private handleWebSocketClose = (e: CloseEvent) => {
-    this.signalWs.removeEventListener('close', this.handleWebSocketClose);
-    getTimers().clearInterval(this.keepAliveInterval);
-    clearTimeout(this.connectionCheckTimeout);
-    this.onSignalClose?.(`${e.code} ${e.reason}`);
+  private notifySignalClose = (reason: string) => {
+    if (this.signalClosed) return;
+    this.signalClosed = true;
+    const timers = getTimers();
+    timers.clearInterval(this.keepAliveInterval);
+    timers.clearInterval(this.connectionCheckInterval);
+    this.onSignalClose?.(reason.trim());
   };
 
   close = (code: number = StreamSfuClient.NORMAL_CLOSURE, reason?: string) => {
@@ -392,7 +405,9 @@ export class StreamSfuClient {
     ) {
       this.logger.debug(`Closing SFU WS connection: ${code} - ${reason}`);
       ws.close(code, `js-client: ${reason}`);
-      ws.removeEventListener('close', this.handleWebSocketClose);
+    }
+    if (!this.isClosingClean) {
+      this.notifySignalClose(`${code} ${reason ?? ''}`);
     }
     this.dispose(reason);
   };
@@ -401,8 +416,9 @@ export class StreamSfuClient {
     this.logger.debug('Disposing SFU client');
     this.unsubscribeIceTrickle();
     this.unsubscribeNetworkChanged();
-    clearInterval(this.keepAliveInterval);
-    clearTimeout(this.connectionCheckTimeout);
+    const timers = getTimers();
+    timers.clearInterval(this.keepAliveInterval);
+    timers.clearInterval(this.connectionCheckInterval);
     clearTimeout(this.migrateAwayTimeout);
     this.abortController.abort();
     this.migrationTask?.resolve();
@@ -697,7 +713,7 @@ export class StreamSfuClient {
       return;
     }
     this.logger.debug(`Sending message to: ${this.edgeName}`, msgJson);
-    this.signalWs.send(SfuRequest.toBinary(message));
+    this.signalWs.send(SfuRequest.toBinary(message) as Uint8Array<ArrayBuffer>);
   };
 
   private keepAlive = () => {
@@ -711,12 +727,11 @@ export class StreamSfuClient {
   };
 
   private scheduleConnectionCheck = () => {
-    clearTimeout(this.connectionCheckTimeout);
-    this.connectionCheckTimeout = setTimeout(() => {
+    const timers = getTimers();
+    timers.clearInterval(this.connectionCheckInterval);
+    this.connectionCheckInterval = timers.setInterval(() => {
       if (this.lastMessageTimestamp) {
-        const timeSinceLastMessage =
-          new Date().getTime() - this.lastMessageTimestamp.getTime();
-
+        const timeSinceLastMessage = Date.now() - this.lastMessageTimestamp;
         if (timeSinceLastMessage > this.unhealthyTimeoutInMs) {
           this.close(
             StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
@@ -724,6 +739,6 @@ export class StreamSfuClient {
           );
         }
       }
-    }, this.unhealthyTimeoutInMs);
+    }, this.connectionCheckIntervalInMs);
   };
 }

package/src/__tests__/StreamSfuClient.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { StreamSfuClient } from '../StreamSfuClient';
 import { Dispatcher } from '../rtc';
 import { StreamClient } from '../coordinator/connection/client';
+import { getTimers } from '../timers';
 
 /**
  * Minimal `WebSocket` stub used to drive `StreamSfuClient.close()` while the
@@ -38,9 +39,13 @@ class CapturingWebSocket {
     this.closeArgs = { code, reason };
     this.readyState = CapturingWebSocket.CLOSED;
   }
+  /** Test helper: synchronously fire a registered event (e.g. `close`). */
+  emit(event: string, payload: unknown) {
+    this.listeners.get(event)?.forEach((listener) => listener(payload));
+  }
 }
 
-const buildSfuClient = () => {
+const buildSfuClient = (onSignalClose?: (reason: string) => void) => {
   const dispatcher = new Dispatcher();
   const streamClient = new StreamClient('test-key');
   return new StreamSfuClient({
@@ -59,9 +64,109 @@ const buildSfuClient = () => {
     },
     tag: 'test',
     enableTracing: false,
+    onSignalClose,
   });
 };
 
+describe('StreamSfuClient unhealthy watchdog timer source', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('arms the unhealthy watchdog on the worker timer, not the main-thread setInterval', () => {
+    const sfuClient = buildSfuClient();
+    const workerSetInterval = vi
+      .spyOn(getTimers(), 'setInterval')
+      .mockReturnValue(1 as unknown as number);
+    const mainSetInterval = vi.spyOn(globalThis, 'setInterval');
+
+    (
+      sfuClient as unknown as { scheduleConnectionCheck: () => void }
+    ).scheduleConnectionCheck();
+
+    expect(workerSetInterval).toHaveBeenCalledTimes(1);
+    expect(mainSetInterval).not.toHaveBeenCalled();
+
+    sfuClient.close(1000, 'test cleanup');
+  });
+});
+
+describe('StreamSfuClient unhealthy watchdog resilience', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('re-arms the unhealthy watchdog after a check passes (not single-shot)', () => {
+    vi.useFakeTimers();
+    const sfuClient = buildSfuClient();
+    const closeSpy = vi.spyOn(sfuClient, 'close').mockImplementation(() => {});
+    const c = sfuClient as unknown as {
+      lastMessageTimestamp?: number;
+      unhealthyTimeoutInMs: number;
+      scheduleConnectionCheck: () => void;
+    };
+    const window = c.unhealthyTimeoutInMs;
+
+    c.lastMessageTimestamp = Date.now();
+    c.scheduleConnectionCheck();
+
+    // At exactly the threshold the connection is still healthy (strict `>`),
+    // so no poll within the first window closes it. A single-shot watchdog
+    // armed for the threshold would now be dead.
+    vi.advanceTimersByTime(window);
+    expect(closeSpy).not.toHaveBeenCalled();
+
+    // No further messages arrive; the self-rescheduling watchdog keeps polling
+    // and detects the connection as unhealthy on a later tick.
+    vi.advanceTimersByTime(window);
+    expect(closeSpy).toHaveBeenCalledWith(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      expect.stringContaining('unhealthy'),
+    );
+  });
+
+  it('detects an unhealthy connection shortly after the threshold, not a full window later', () => {
+    vi.useFakeTimers();
+    const sfuClient = buildSfuClient();
+    const closeSpy = vi.spyOn(sfuClient, 'close').mockImplementation(() => {});
+    const c = sfuClient as unknown as {
+      lastMessageTimestamp?: number;
+      unhealthyTimeoutInMs: number;
+      scheduleConnectionCheck: () => void;
+    };
+    const window = c.unhealthyTimeoutInMs;
+
+    c.lastMessageTimestamp = Date.now();
+    c.scheduleConnectionCheck();
+
+    // healthy up to (and exactly at) the threshold
+    vi.advanceTimersByTime(window);
+    expect(closeSpy).not.toHaveBeenCalled();
+
+    // the watchdog polls finer than the window, so silence is caught well
+    // before a second full window elapses (the old period == window design
+    // could take up to 2x the window to notice).
+    vi.advanceTimersByTime(window / 2);
+    expect(closeSpy).toHaveBeenCalledWith(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      expect.stringContaining('unhealthy'),
+    );
+  });
+});
+
 describe('StreamSfuClient.close()', () => {
   beforeEach(() => {
     CapturingWebSocket.instances = [];
@@ -164,6 +269,59 @@ describe('StreamSfuClient.close()', () => {
   });
 });
 
+describe('StreamSfuClient signal-close revival', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it('drives revival immediately on an unhealthy close, without waiting for the onclose event', () => {
+    const onSignalClose = vi.fn();
+    const sfuClient = buildSfuClient(onSignalClose);
+
+    // A wedged socket may fire `onclose` only after the OS TCP timeout. The
+    // health watchdog closes with ERROR_CONNECTION_UNHEALTHY; revival must
+    // start now, not when (or if) the transport `close` event arrives.
+    sfuClient.close(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      'SFU connection unhealthy',
+    );
+
+    expect(onSignalClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifies revival only once when the late onclose event follows an unhealthy close', () => {
+    const onSignalClose = vi.fn();
+    const sfuClient = buildSfuClient(onSignalClose);
+    const ws = CapturingWebSocket.instances.at(-1)!;
+
+    // watchdog closes the dead socket (revival triggered proactively)...
+    sfuClient.close(
+      StreamSfuClient.ERROR_CONNECTION_UNHEALTHY,
+      'SFU connection unhealthy',
+    );
+    // ...then the OS finally surfaces the wedged socket's `close` event.
+    ws.emit('close', { code: 1006, reason: '' });
+
+    expect(onSignalClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifies revival when only the onclose event fires (server-initiated close)', () => {
+    const onSignalClose = vi.fn();
+    buildSfuClient(onSignalClose);
+    const ws = CapturingWebSocket.instances.at(-1)!;
+
+    ws.emit('close', { code: 1006, reason: '' });
+
+    expect(onSignalClose).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('StreamSfuClient.leaveAndClose()', () => {
   beforeEach(() => {
     CapturingWebSocket.instances = [];

package/src/__tests__/StreamVideoClient.api.test.ts

@@ -1,94 +1,122 @@
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from 'vitest';
 import { StreamVideoClient } from '../StreamVideoClient';
-import 'dotenv/config';
+import { Call } from '../Call';
+import { CallCreatedPayload } from './data';
 import { generateUUIDv4 } from '../coordinator/connection/utils';
-import { StreamClient } from '@stream-io/node-sdk';
-import { CreateDeviceRequest } from '../gen/coordinator';
+import type { StreamClient } from '../coordinator/connection/client';
+import type {
+  CreateDeviceRequest,
+  GetEdgesResponse,
+  ListDevicesResponse,
+  QueryCallsResponse,
+  QueryCallStatsResponse,
+} from '../gen/coordinator';
 
-const apiKey = process.env.STREAM_API_KEY!;
-const secret = process.env.STREAM_SECRET!;
-
-const serverClient = new StreamClient(apiKey, secret);
+const apiKey = 'mock-api-key';
 
 describe('StreamVideoClient - coordinator API', () => {
   let client: StreamVideoClient;
+  // the client only talks to the backend through streamClient.post/get/delete,
+  // so we spy on those and assert against them instead of a live backend.
+  let post: Mock<StreamClient['post']>;
+  let get: Mock<StreamClient['get']>;
+  let del: Mock<StreamClient['delete']>;
+
+  beforeEach(() => {
+    client = new StreamVideoClient(apiKey, { browser: true });
+    post = vi.spyOn(client.streamClient, 'post');
+    get = vi.spyOn(client.streamClient, 'get');
+    del = vi.spyOn(client.streamClient, 'delete');
+  });
 
-  beforeAll(() => {
-    const user = { id: 'sara' };
-    client = new StreamVideoClient(apiKey, {
-      // tests run in node, so we have to fake being in browser env
-      browser: true,
-      timeout: 15000,
-    });
-    client.connectUser(
-      user,
-      serverClient.generateUserToken({ user_id: user.id }),
-    );
+  afterEach(() => {
+    vi.restoreAllMocks();
   });
 
-  it('query calls', { retry: 3, timeout: 20000 }, async () => {
-    let response = await client.queryCalls();
+  it('query calls', async () => {
+    const response: QueryCallsResponse = {
+      duration: '1ms',
+      next: 'next-page-token',
+      calls: [
+        {
+          call: CallCreatedPayload.call,
+          members: CallCreatedPayload.members,
+          own_capabilities: [],
+        },
+      ],
+    };
+    post.mockResolvedValue(response);
 
-    let calls = response.calls;
-    expect(calls.length).toBeGreaterThanOrEqual(1);
+    await client.queryCalls();
+    expect(post).toHaveBeenCalledWith('/calls', {});
 
     const queryCallsReq = {
       sort: [{ field: 'starts_at', direction: -1 }],
       limit: 2,
     };
-    response = await client.queryCalls(queryCallsReq);
-
-    calls = response.calls;
-    expect(calls.length).toBe(2);
-
-    response = await client.queryCalls({
-      ...queryCallsReq,
-      next: response.next,
-    });
-
-    expect(response.calls.length).toBeLessThanOrEqual(2);
-
-    response = await client.queryCalls({
-      filter_conditions: { backstage: { $eq: false } },
-    });
-
-    expect(response.calls.length).toBeGreaterThanOrEqual(1);
+    const result = await client.queryCalls(queryCallsReq);
+    expect(post).toHaveBeenCalledWith('/calls', queryCallsReq);
+
+    // each response entry is wrapped into a Call instance
+    expect(result.next).toBe('next-page-token');
+    expect(result.calls).toHaveLength(1);
+    const [call] = result.calls;
+    expect(call).toBeInstanceOf(Call);
+    expect(call.cid).toBe(CallCreatedPayload.call.cid);
   });
 
   it('query calls - ongoing', async () => {
-    const response = await client.queryCalls({
-      filter_conditions: { ongoing: { $eq: true } },
-    });
+    post.mockResolvedValue({ duration: '1ms', calls: [] });
+
+    const queryCallsReq = { filter_conditions: { ongoing: { $eq: true } } };
+    await client.queryCalls(queryCallsReq);
 
-    // Dummy test
-    expect(response.calls).toBeDefined();
+    expect(post).toHaveBeenCalledWith('/calls', queryCallsReq);
   });
 
   it('query calls - upcoming', async () => {
+    post.mockResolvedValue({ duration: '1ms', calls: [] });
+
     const mins30 = 1000 * 60 * 60 * 30;
     const inNext30mins = new Date(Date.now() + mins30);
-    const response = await client.queryCalls({
-      filter_conditions: {
-        starts_at: { $gt: inNext30mins.toISOString() },
-      },
-    });
+    const queryCallsReq = {
+      filter_conditions: { starts_at: { $gt: inNext30mins.toISOString() } },
+    };
+    await client.queryCalls(queryCallsReq);
 
-    // Dummy test
-    expect(response.calls).toBeDefined();
+    expect(post).toHaveBeenCalledWith('/calls', queryCallsReq);
   });
 
   it('query call stats', async () => {
-    const response = await client.queryCallStats({
+    const response: QueryCallStatsResponse = { duration: '1ms', reports: [] };
+    post.mockResolvedValue(response);
+
+    const result = await client.queryCallStats({
       filter_conditions: { call_cid: 'default:test' },
     });
 
-    expect(response.reports).toBeDefined();
+    expect(post).toHaveBeenCalledWith('/call/stats', {
+      filter_conditions: { call_cid: 'default:test' },
+    });
+    expect(result).toBe(response);
   });
 
   it('edges', async () => {
-    const response = await client.edges();
+    const response: GetEdgesResponse = { duration: '1ms', edges: [] };
+    get.mockResolvedValue(response);
+
+    const result = await client.edges();
 
-    expect(response.edges).toBeDefined();
+    expect(get).toHaveBeenCalledWith('/edges');
+    expect(result).toBe(response);
   });
 
   describe('devices', () => {
@@ -99,57 +127,55 @@ describe('StreamVideoClient - coordinator API', () => {
     };
 
     it('add device', async () => {
-      expect(
-        async () =>
-          await client.addDevice(
-            device.id,
-            device.push_provider,
-            device.push_provider_name,
-          ),
-      ).not.toThrowError();
+      post.mockResolvedValue(undefined);
+
+      await client.addDevice(
+        device.id,
+        device.push_provider,
+        device.push_provider_name,
+      );
+
+      expect(post).toHaveBeenCalledWith('/devices', {
+        id: device.id,
+        push_provider: device.push_provider,
+        voip_token: undefined,
+        push_provider_name: device.push_provider_name,
+      });
     });
 
     it('add voip device', async () => {
-      expect(
-        async () =>
-          await client.addVoipDevice(
-            device.id + 'voip',
-            device.push_provider,
-            device.push_provider_name!,
-          ),
-      ).not.toThrowError();
+      post.mockResolvedValue(undefined);
+
+      await client.addVoipDevice(
+        device.id + 'voip',
+        device.push_provider,
+        device.push_provider_name!,
+      );
+
+      expect(post).toHaveBeenCalledWith('/devices', {
+        id: device.id + 'voip',
+        push_provider: device.push_provider,
+        voip_token: true,
+        push_provider_name: device.push_provider_name,
+      });
     });
 
-    it('get devices', { retry: 3, timeout: 15000 }, async () => {
-      // Wait a little bit, because if we query devices too soon backend will return 404
-      await new Promise<void>((resolve) => {
-        setTimeout(resolve, 5000);
-      });
+    it('get devices', async () => {
+      const response: ListDevicesResponse = { duration: '1ms', devices: [] };
+      get.mockResolvedValue(response);
 
-      const response = await client.getDevices();
+      const result = await client.getDevices();
 
-      expect(response.devices.find((d) => d.id === device.id)).toBeDefined();
-      expect(
-        response.devices.find((d) => d.id === device.id + 'voip'),
-      ).toBeDefined();
+      expect(get).toHaveBeenCalledWith('/devices', {});
+      expect(result).toBe(response);
     });
 
-    it('remove device', { retry: 3, timeout: 15000 }, async () => {
-      // Wait a little bit, because if we query devices too soon backend will return 404
-      await new Promise<void>((resolve) => {
-        setTimeout(resolve, 5000);
-      });
+    it('remove device', async () => {
+      del.mockResolvedValue(undefined);
 
-      expect(
-        async () => await client.removeDevice(device.id),
-      ).not.toThrowError();
-      expect(
-        async () => await client.removeDevice(device.id + 'void'),
-      ).not.toThrowError();
-    });
-  });
+      await client.removeDevice(device.id);
 
-  afterAll(() => {
-    client.disconnectUser();
+      expect(del).toHaveBeenCalledWith('/devices', { id: device.id });
+    });
   });
 });

package/src/coordinator/connection/__tests__/connection.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { StreamClient } from '../client';
 import { StableWSConnection } from '../connection';
 import type { WSConnectionError } from '../types';
+import { getTimers } from '../../../timers';
 
 class StuckWebSocket {
   static CONNECTING = 0;
@@ -108,6 +109,27 @@ const buildClient = () => {
   return client;
 };
 
+describe('StableWSConnection connection-check timer source', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('arms the connection-check watchdog on the worker timer, not the main-thread setTimeout', () => {
+    const client = buildClient();
+    const wsConnection = new StableWSConnection(client);
+    const workerSetTimeout = vi
+      .spyOn(getTimers(), 'setTimeout')
+      .mockReturnValue(1 as unknown as number);
+    const mainSetTimeout = vi.spyOn(globalThis, 'setTimeout');
+
+    wsConnection.scheduleConnectionCheck();
+
+    expect(workerSetTimeout).toHaveBeenCalledTimes(1);
+    expect(mainSetTimeout).not.toHaveBeenCalled();
+  });
+});
+
 describe('StableWSConnection - silent handshake hang', () => {
   beforeEach(() => {
     StuckWebSocket.instances = [];
@@ -193,6 +215,53 @@ describe('StableWSConnection - silent handshake hang', () => {
     expect(outcome.kind).toBe('rejected');
   });
 
+  it('preserves an initial WS close reason when reconnect cannot get healthy', async () => {
+    const client = new StreamClient('test-key', {
+      browser: false,
+      defaultWsTimeout: 5000,
+      WebSocketImpl: ManualWebSocket as unknown as typeof WebSocket,
+      timeout: 1000,
+    });
+    vi.spyOn(client.tokenManager, 'tokenReady').mockResolvedValue('fake-token');
+    vi.spyOn(client.tokenManager, 'loadToken').mockResolvedValue('fake-token');
+    vi.spyOn(client.tokenManager, 'getToken').mockReturnValue('fake-token');
+
+    client._setUser({ id: 'test-user' });
+    client.userID = 'test-user';
+    client.clientID = 'test-user--abcdef';
+    client._setupConnectionIdPromise();
+
+    const wsConnection = new StableWSConnection(client);
+    client.wsConnection = wsConnection;
+
+    const connectAttemptOutcome = wsConnection.connect(5000).then(
+      () => ({ kind: 'resolved' as const }),
+      (error: Error) => ({ kind: 'rejected' as const, error }),
+    );
+
+    await vi.advanceTimersByTimeAsync(0);
+    const ws = ManualWebSocket.instances.at(-1)!;
+    expect(ws).toBeDefined();
+
+    ws.onclose?.({
+      code: 1006,
+      reason: 'specific ws close reason',
+      wasClean: false,
+      target: ws,
+    });
+
+    await vi.advanceTimersByTimeAsync(20000);
+    const outcome = await connectAttemptOutcome;
+
+    expect(outcome.kind).toBe('rejected');
+    if (outcome.kind === 'rejected') {
+      expect(outcome.error.message).toContain('specific ws close reason');
+      expect(outcome.error.message).not.toContain(
+        'initial WS connection could not be established',
+      );
+    }
+  });
+
   it('does not schedule a reconnect (and leaves connectionIdPromise rejected) on a permanent, non-WS failure', async () => {
     const client = new StreamClient('test-key', {
       browser: false,