@kuralle-syrinx/ws 4.4.0 → 4.5.0

package/src/index.test.ts

@@ -0,0 +1,350 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, describe, expect, it } from "vitest";
+import { WebSocketServer, type WebSocket } from "ws";
+import type { RetryConfig } from "@kuralle-syrinx/core";
+
+import { WebSocketConnection, type ManagedSocket, type SocketFactory } from "./index.js";
+import { createNodeWsSocket } from "./node.js";
+
+let servers: WebSocketServer[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          for (const client of server.clients) client.terminate();
+          server.close(() => resolve());
+        }),
+    ),
+  );
+});
+
+async function createServer(onConnection: (socket: WebSocket) => void): Promise<{ url: string; port: number; server: WebSocketServer }> {
+  const server = await new Promise<WebSocketServer>((resolve) => {
+    let next: WebSocketServer;
+    next = new WebSocketServer({ port: 0 }, () => resolve(next));
+  });
+  servers.push(server);
+  server.on("connection", onConnection);
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+  return { url: `ws://127.0.0.1:${address.port}/`, port: address.port, server };
+}
+
+const FAST_RETRY: RetryConfig = { maxAttempts: 3, baseDelayMs: 10, maxDelayMs: 40 };
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error("Timed out waiting for condition");
+}
+
+describe("WebSocketConnection", () => {
+  it("delivers messages and holds the socket open with a KeepAlive", async () => {
+    const serverReceived: string[] = [];
+    const { url } = await createServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) serverReceived.push(data.toString());
+      });
+      socket.send("hello-from-server");
+    });
+
+    const messages: string[] = [];
+    const conn = new WebSocketConnection({
+      url: () => url,
+      socketFactory: createNodeWsSocket,
+      retry: FAST_RETRY,
+      keepAliveIntervalMs: 30,
+      keepAliveMessage: () => JSON.stringify({ type: "KeepAlive" }),
+      onMessage: (data, isBinary) => {
+        if (!isBinary) messages.push(data.toString());
+      },
+    });
+    await conn.connect();
+    await waitFor(() => messages.includes("hello-from-server"));
+    // Several keepalive intervals should have elapsed.
+    await waitFor(() => serverReceived.filter((m) => m.includes("KeepAlive")).length >= 2);
+
+    expect(messages).toContain("hello-from-server");
+    expect(serverReceived.filter((m) => m.includes("KeepAlive")).length).toBeGreaterThanOrEqual(2);
+
+    await conn.close();
+  });
+
+  it("reconnects with verification after the server drops the socket", async () => {
+    let connections = 0;
+    const { url } = await createServer((socket) => {
+      connections += 1;
+      // ws auto-replies to ping with pong, so verify() passes.
+      if (connections === 1) {
+        // Drop the first connection shortly after it opens.
+        setTimeout(() => socket.close(1011, "transient"), 20);
+      }
+    });
+
+    let reconnecting = 0;
+    let reconnected = 0;
+    const conn = new WebSocketConnection({
+      url: () => url,
+      socketFactory: createNodeWsSocket,
+      retry: FAST_RETRY,
+      minStableMs: 0, // don't treat the deliberate drop as a quick failure
+      onMessage: () => undefined,
+      onReconnecting: () => {
+        reconnecting += 1;
+      },
+      onReconnected: () => {
+        reconnected += 1;
+      },
+    });
+    await conn.connect();
+    await waitFor(() => reconnected >= 1);
+
+    expect(reconnecting).toBeGreaterThanOrEqual(1);
+    expect(reconnected).toBe(1);
+    expect(connections).toBeGreaterThanOrEqual(2);
+    // The reconnected socket is usable.
+    expect(conn.isReady).toBe(true);
+    conn.send("after-reconnect");
+
+    await conn.close();
+  });
+
+  it("gives up and reports unrecoverable when the server stays down", async () => {
+    const { url, server } = await createServer(() => undefined);
+    let unrecoverable: Error | null = null;
+    const conn = new WebSocketConnection({
+      url: () => url,
+      socketFactory: createNodeWsSocket,
+      retry: FAST_RETRY,
+      maxReconnectAttempts: 2,
+      minStableMs: 0,
+      onMessage: () => undefined,
+      onUnrecoverable: (err) => {
+        unrecoverable = err;
+      },
+    });
+    await conn.connect();
+    expect(conn.isReady).toBe(true);
+
+    // Kill the server: the live socket drops and every reconnect attempt fails.
+    await new Promise<void>((resolve) => {
+      for (const client of server.clients) client.terminate();
+      server.close(() => resolve());
+    });
+
+    await waitFor(() => unrecoverable !== null, 3000);
+    expect(unrecoverable).toBeInstanceOf(Error);
+    expect((unrecoverable! as Error).message).toContain("failed to reconnect");
+
+    await conn.close();
+  });
+
+  it("rejects connect when disposed before the socket opens", async () => {
+    const hangingSocket: ManagedSocket = {
+      get isOpen() {
+        return false;
+      },
+      send: () => undefined,
+      keepAlivePing: () => undefined,
+      verify: async () => false,
+      dispose: () => undefined,
+      onOpen: () => undefined,
+      onMessage: () => undefined,
+      onClose: () => undefined,
+      onError: () => undefined,
+    };
+    const socketFactory: SocketFactory = () => hangingSocket;
+    const conn = new WebSocketConnection({
+      url: () => "ws://127.0.0.1:1/",
+      socketFactory,
+      retry: FAST_RETRY,
+      onMessage: () => undefined,
+    });
+
+    const connectPromise = conn.connect();
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    await conn.close();
+
+    await expect(connectPromise).rejects.toThrow(/disposed/i);
+  });
+
+  it("stops reconnecting when the socket keeps dying right after connecting", async () => {
+    // Server accepts + answers ping (verify passes) but closes ~15ms after open,
+    // every time — backoff can't fix this, so the quick-failure guard must give up.
+    const { url } = await createServer((socket) => {
+      setTimeout(() => socket.close(1011, "flap"), 15);
+    });
+
+    let unrecoverable: Error | null = null;
+    let reconnects = 0;
+    const conn = new WebSocketConnection({
+      url: () => url,
+      socketFactory: createNodeWsSocket,
+      retry: FAST_RETRY,
+      minStableMs: 200,
+      maxQuickFailures: 2,
+      onMessage: () => undefined,
+      onReconnected: () => {
+        reconnects += 1;
+      },
+      onUnrecoverable: (err) => {
+        unrecoverable = err;
+      },
+    });
+    await conn.connect();
+    await waitFor(() => unrecoverable !== null, 3000);
+
+    expect((unrecoverable! as Error).message).toContain("check credentials or provider policy");
+    // It should bail out quickly, not loop forever.
+    expect(reconnects).toBeLessThanOrEqual(3);
+
+    await conn.close();
+  });
+
+  it("rejects openSocket when the socket factory never resolves", async () => {
+    const connectTimeoutMs = 50;
+    const hangingFactory: SocketFactory = () =>
+      new Promise<ManagedSocket>(() => {
+        /* never resolves */
+      });
+
+    const conn = new WebSocketConnection({
+      url: () => "ws://127.0.0.1:1/",
+      socketFactory: hangingFactory,
+      connectTimeoutMs,
+      retry: FAST_RETRY,
+      onMessage: () => undefined,
+    });
+
+    const startedAt = Date.now();
+    await expect(conn.connect()).rejects.toThrow(/connect timeout/i);
+    expect(Date.now() - startedAt).toBeLessThan(connectTimeoutMs + 100);
+    expect(Date.now() - startedAt).toBeGreaterThanOrEqual(connectTimeoutMs - 10);
+
+    await conn.close();
+  });
+
+  it("rejects openSocket when the socket fires no event after construction", async () => {
+    const connectTimeoutMs = 50;
+    const silentSocket: ManagedSocket = {
+      get isOpen() {
+        return false;
+      },
+      send: () => undefined,
+      keepAlivePing: () => undefined,
+      verify: async () => false,
+      dispose: () => undefined,
+      onOpen: () => undefined,
+      onMessage: () => undefined,
+      onClose: () => undefined,
+      onError: () => undefined,
+    };
+    const socketFactory: SocketFactory = () => silentSocket;
+
+    const conn = new WebSocketConnection({
+      url: () => "ws://127.0.0.1:1/",
+      socketFactory,
+      connectTimeoutMs,
+      retry: { maxAttempts: 2, baseDelayMs: 5, maxDelayMs: 10 },
+      maxReconnectAttempts: 1,
+      minStableMs: 0,
+      onMessage: () => undefined,
+    });
+
+    const startedAt = Date.now();
+    await expect(conn.connect()).rejects.toThrow(/connect timeout/i);
+    expect(Date.now() - startedAt).toBeLessThan(connectTimeoutMs + 100);
+
+    await conn.close();
+  });
+
+  it("reconnects after openSocket times out on a silent socket during tryReconnect", async () => {
+    const connectTimeoutMs = 40;
+    let factoryCalls = 0;
+    const { url, server } = await createServer((socket) => {
+      socket.on("message", () => undefined);
+    });
+
+    const silentSocket: ManagedSocket = {
+      get isOpen() {
+        return false;
+      },
+      send: () => undefined,
+      keepAlivePing: () => undefined,
+      verify: async () => false,
+      dispose: () => undefined,
+      onOpen: () => undefined,
+      onMessage: () => undefined,
+      onClose: () => undefined,
+      onError: () => undefined,
+    };
+
+    const socketFactory: SocketFactory = (targetUrl, headers) => {
+      factoryCalls += 1;
+      if (factoryCalls === 2) return silentSocket;
+      return createNodeWsSocket(targetUrl, headers);
+    };
+
+    let reconnected = 0;
+    const conn = new WebSocketConnection({
+      url: () => url,
+      socketFactory,
+      connectTimeoutMs,
+      retry: { maxAttempts: 3, baseDelayMs: 5, maxDelayMs: 10 },
+      minStableMs: 0,
+      onMessage: () => undefined,
+      onReconnected: () => {
+        reconnected += 1;
+      },
+    });
+
+    await conn.connect();
+    expect(factoryCalls).toBe(1);
+
+    for (const client of server.clients) client.terminate();
+    await waitFor(() => reconnected >= 1, 5000);
+    expect(factoryCalls).toBeGreaterThanOrEqual(3);
+
+    await conn.close();
+  });
+
+  it("gives up after maxReconnectDurationMs when the link keeps flapping", async () => {
+    const minStableMs = 30;
+    const maxReconnectDurationMs = 200;
+    const { url } = await createServer((socket) => {
+      setTimeout(() => socket.close(1011, "flap"), minStableMs + 1);
+    });
+
+    let unrecoverable: Error | null = null;
+    let reconnects = 0;
+    const conn = new WebSocketConnection({
+      url: () => url,
+      socketFactory: createNodeWsSocket,
+      retry: { maxAttempts: 50, baseDelayMs: 5, maxDelayMs: 10 },
+      minStableMs,
+      maxQuickFailures: 100,
+      maxReconnectDurationMs,
+      maxReconnectAttempts: 50,
+      onMessage: () => undefined,
+      onReconnected: () => {
+        reconnects += 1;
+      },
+      onUnrecoverable: (err) => {
+        unrecoverable = err;
+      },
+    });
+    await conn.connect();
+    await waitFor(() => unrecoverable !== null, 5000);
+
+    expect((unrecoverable! as Error).message).toContain(String(maxReconnectDurationMs));
+    expect(reconnects).toBeGreaterThanOrEqual(1);
+
+    await conn.close();
+  });
+});

package/src/node.test.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+//
+// Regression: disposing a Node `ws` socket that is still CONNECTING must not crash
+// the process. `ws.close()` on a connecting socket emits an asynchronous 'error'
+// event ("WebSocket was closed before the connection was established"); dispose()
+// removeAllListeners()'d the error sink, so without re-attaching one the event
+// becomes an uncaught exception. This happens whenever a caller hangs up during a
+// slow provider connect (surfaced live via the Cartesia TTS plugin teardown).
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { WebSocketServer, type WebSocket } from "ws";
+import { createNodeWsSocket } from "./node.js";
+
+describe("createNodeWsSocket dispose while connecting", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not raise an unhandled 'error' when disposed mid-handshake", async () => {
+    // A socket to a non-routable address stays in CONNECTING. If dispose() leaked an
+    // unhandled 'error', the vitest process would record an uncaughtException and fail
+    // this file — reaching the assertion is the proof.
+    const uncaught: unknown[] = [];
+    const onUncaught = (err: unknown): void => {
+      uncaught.push(err);
+    };
+    process.on("uncaughtException", onUncaught);
+    try {
+      // createNodeWsSocket is synchronous; await narrows the SocketFactory union.
+      const socket = await createNodeWsSocket("ws://10.255.255.1:9999", {});
+      socket.dispose(); // synchronous, while readyState === CONNECTING
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    } finally {
+      process.off("uncaughtException", onUncaught);
+    }
+    expect(uncaught).toEqual([]);
+  });
+
+  it("clears the verify timeout when disposed during verify", async () => {
+    vi.useFakeTimers();
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let next: WebSocketServer;
+      next = new WebSocketServer({ port: 0 }, () => resolve(next));
+    });
+    server.on("connection", (ws) => {
+      ws.on("ping", () => undefined);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+
+    const socket = await createNodeWsSocket(`ws://127.0.0.1:${String(address.port)}/`, {});
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("Timed out waiting for websocket open")), 2000);
+      socket.onOpen(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+
+    const verifyPromise = socket.verify(5000);
+    socket.dispose();
+    await vi.advanceTimersByTimeAsync(6000);
+    await expect(verifyPromise).resolves.toBe(false);
+
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    vi.useRealTimers();
+  });
+});

package/src/replay.test.ts

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: MIT
+//
+// VE-06.2: reconnect replay. A frame whose send() fails because the socket is not open
+// (provably never reached the wire) is buffered and re-sent in order on reconnect; frames
+// sent on an open socket are never buffered, so received frames are never duplicated.
+
+import { describe, expect, it } from "vitest";
+import type { RetryConfig } from "@kuralle-syrinx/core";
+
+import { WebSocketConnection, type ManagedSocket, type SocketData } from "./index.js";
+import { wrapWebSocket, type WebSocketEventLike, type WebSocketLike } from "./web-socket.js";
+
+const FAST_RETRY: RetryConfig = { maxAttempts: 5, baseDelayMs: 5, maxDelayMs: 20 };
+
+class FakeWebSocket implements WebSocketLike {
+  readyState = 0;
+  binaryType = "blob";
+  readonly sent: SocketData[] = [];
+  private readonly listeners = new Map<string, Array<(event: WebSocketEventLike) => void>>();
+  send(data: string | ArrayBufferView | ArrayBuffer): void {
+    this.sent.push(typeof data === "string" ? data : new Uint8Array(data as ArrayBuffer));
+  }
+  close(): void { this.readyState = 3; this.emit("close", { code: 1006, reason: "drop" }); }
+  addEventListener(type: string, l: (e: WebSocketEventLike) => void): void {
+    const list = this.listeners.get(type) ?? []; list.push(l); this.listeners.set(type, list);
+  }
+  private emit(type: string, event: WebSocketEventLike): void { for (const l of this.listeners.get(type) ?? []) l(event); }
+  fireOpen(): void { this.readyState = 1; this.emit("open", {}); }
+}
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("WebSocketConnection reconnect replay (VE-06.2)", () => {
+  it("send() to a closed socket throws when replay is disabled (default)", async () => {
+    const fake = new FakeWebSocket();
+    const conn = new WebSocketConnection({
+      url: () => "wss://x", socketFactory: () => wrapWebSocket(fake), retry: FAST_RETRY,
+      onMessage: () => undefined,
+    });
+    const connected = conn.connect(); fake.fireOpen(); await connected;
+    fake.readyState = 3; // simulate closed
+    expect(() => conn.send("frame")).toThrow(/not open/);
+    await conn.close();
+  });
+
+  it("buffers gap frames and replays them in order on reconnect; on-wire frames are not replayed", async () => {
+    const fakes: FakeWebSocket[] = [];
+    const replayEvents: Array<{ event: string; count: number }> = [];
+    const conn = new WebSocketConnection({
+      url: () => "wss://x",
+      socketFactory: () => { const f = new FakeWebSocket(); fakes.push(f); return wrapWebSocket(f); },
+      retry: FAST_RETRY,
+      replayBufferSize: 10,
+      onReplay: (event, count) => replayEvents.push({ event, count }),
+      onMessage: () => undefined,
+    });
+
+    const connected = conn.connect();
+    fakes[0]!.fireOpen();
+    await connected;
+
+    conn.send("on-wire-1"); // sent on the open socket — must NOT be replayed
+    expect(fakes[0]!.sent).toEqual(["on-wire-1"]);
+
+    // Connection drops → reconnect begins.
+    fakes[0]!.close();
+    // During the gap (socket not open) the caller keeps sending — these buffer for replay.
+    conn.send("gap-1");
+    conn.send("gap-2");
+
+    // Wait for the reconnect to create a new socket, then open it.
+    await wait(40);
+    expect(fakes.length).toBeGreaterThanOrEqual(2);
+    fakes[fakes.length - 1]!.fireOpen();
+    await wait(10);
+
+    const reconnected = fakes[fakes.length - 1]!;
+    // The two gap frames are replayed in order on the new socket; the on-wire frame is NOT.
+    expect(reconnected.sent).toEqual(["gap-1", "gap-2"]);
+    expect(replayEvents.filter((e) => e.event === "replayed")).toHaveLength(1);
+    expect(replayEvents.find((e) => e.event === "replayed")?.count).toBe(2);
+
+    await conn.close();
+  });
+
+  it("buffers frames sent during the reconnect verify window until after onReadyBeforeReplay", async () => {
+    // The provider-facing contract: on a fresh connection, the config frame
+    // (sent by onReadyBeforeReplay) reaches the wire before any caller frame.
+    // A send() landing between socket-open and verify completion must buffer,
+    // not pass through — otherwise config-first providers see audio first.
+    class HeldVerifySocket implements ManagedSocket {
+      isOpen = false;
+      readonly sent: SocketData[] = [];
+      readonly supportsFramePing = true;
+      resolveVerify: ((ok: boolean) => void) | null = null;
+      private openHandler: (() => void) | null = null;
+      private closeHandler: ((code: number, reason: string) => void) | null = null;
+      send(data: SocketData): void { this.sent.push(data); }
+      keepAlivePing(): void {}
+      verify(): Promise<boolean> {
+        return new Promise((resolve) => { this.resolveVerify = resolve; });
+      }
+      dispose(): void {}
+      onOpen(h: () => void): void { this.openHandler = h; }
+      onMessage(): void {}
+      onClose(h: (code: number, reason: string) => void): void { this.closeHandler = h; }
+      onError(): void {}
+      fireOpen(): void { this.isOpen = true; this.openHandler?.(); }
+      fireClose(): void { this.isOpen = false; this.closeHandler?.(1006, "drop"); }
+    }
+
+    const sockets: HeldVerifySocket[] = [];
+    const conn = new WebSocketConnection({
+      url: () => "wss://x",
+      socketFactory: () => {
+        const s = new HeldVerifySocket();
+        sockets.push(s);
+        setTimeout(() => s.fireOpen(), 0);
+        return s;
+      },
+      retry: FAST_RETRY,
+      replayBufferSize: 10,
+      onReadyBeforeReplay: () => conn.send("config"),
+      onMessage: () => undefined,
+    });
+
+    await conn.connect();
+    expect(sockets[0]!.sent).toEqual(["config"]);
+
+    // Drop the link → reconnect opens socket 2, then awaits verify (held open).
+    sockets[0]!.fireClose();
+    await wait(40);
+    expect(sockets.length).toBeGreaterThanOrEqual(2);
+    const second = sockets[sockets.length - 1]!;
+    expect(second.isOpen).toBe(true);
+    expect(second.resolveVerify).not.toBeNull();
+
+    // Caller sends while the link is open but NOT yet verified/configured.
+    conn.send("audio-during-verify");
+    expect(second.sent).toEqual([]); // must buffer, not hit the wire
+
+    second.resolveVerify!(true);
+    await wait(10);
+    expect(second.sent).toEqual(["config", "audio-during-verify"]);
+
+    await conn.close();
+  });
+
+  it("bounds the replay buffer, dropping oldest with an overflow signal", async () => {
+    const fake = new FakeWebSocket();
+    const events: string[] = [];
+    const conn = new WebSocketConnection({
+      url: () => "wss://x", socketFactory: () => wrapWebSocket(fake), retry: FAST_RETRY,
+      replayBufferSize: 2, onReplay: (e) => events.push(e), onMessage: () => undefined,
+    });
+    const connected = conn.connect(); fake.fireOpen(); await connected;
+    fake.readyState = 3; // closed
+    conn.send("a"); conn.send("b"); conn.send("c"); // buffer holds last 2 → "a" overflows
+    expect(events.filter((e) => e === "overflow")).toHaveLength(1);
+    await conn.close();
+  });
+});