@kuralle-syrinx/ws 4.0.0 → 4.2.0

package/package.json

@@ -1,9 +1,27 @@
 {
   "name": "@kuralle-syrinx/ws",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "private": false,
-  "type": "module",
+  "description": "Reconnecting WebSocket connection manager for Syrinx provider sockets — verify-before-trust reconnects, ordered replay, keepalive; Node and Workers",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "websocket",
+    "reconnect"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/ws"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -15,7 +33,7 @@
   },
   "dependencies": {
     "ws": "^8.18.0",
-    "@kuralle-syrinx/core": "4.0.0"
+    "@kuralle-syrinx/core": "4.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.0",

package/src/index.ts

@@ -106,6 +106,10 @@ let connectionSequence = 0;
 export class WebSocketConnection {
   private socket: ManagedSocket | null = null;
   private ready = false;
+  /** True only once the connection is verified and onReadyBeforeReplay has been
+   * given the chance to run — send() must not reach an open-but-unconfigured
+   * socket, or caller frames beat the provider config frame on reconnect. */
+  private established = false;
   private closed = false;
   private reconnecting = false;
   private connResolver: (() => void) | null = null;
@@ -135,6 +139,7 @@ export class WebSocketConnection {
   async connect(): Promise<void> {
     this.closed = false;
     await this.openSocket();
+    this.established = true;
     this.opts.onReadyBeforeReplay?.();
     this.flushReplay();
   }
@@ -149,7 +154,7 @@ export class WebSocketConnection {
    * throws and the caller decides how to retry/report.
    */
   send(payload: SocketData): void {
-    if (!this.socket || !this.socket.isOpen) {
+    if (!this.socket || !this.socket.isOpen || !this.established) {
       if (this.replayBufferSize > 0 && !this.closed) {
         this.bufferForReplay(payload);
         return;
@@ -208,6 +213,7 @@ export class WebSocketConnection {
     this.connResolver = null;
     this.connRejecter = null;
     this.ready = false;
+    this.established = false;
     this.socket?.dispose();
     this.socket = null;
   }
@@ -223,6 +229,7 @@ export class WebSocketConnection {
     this.socket?.dispose();
     this.socket = null;
     this.ready = false;
+    this.established = false;
     this.stopKeepAlive();
     void this.tryReconnect();
   }
@@ -235,6 +242,7 @@ export class WebSocketConnection {
     this.abortPendingOpen(new Error("WebSocket connection replaced"));
     this.socket?.dispose();
     this.ready = false;
+    this.established = false;
 
     let socket: ManagedSocket | null = null;
     let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
@@ -312,6 +320,7 @@ export class WebSocketConnection {
               settle(() => reject(err));
               if (!bindSocket(created)) return;
               this.ready = false;
+              this.established = false;
               this.connRejecter?.(err);
               this.connResolver = null;
               this.connRejecter = null;
@@ -322,6 +331,7 @@ export class WebSocketConnection {
               settle(() => reject(closeErr));
               if (!bindSocket(created)) return;
               this.ready = false;
+              this.established = false;
               this.stopKeepAlive();
               this.connRejecter?.(closeErr);
               this.connResolver = null;
@@ -416,6 +426,7 @@ export class WebSocketConnection {
           await this.openSocket();
           if (this.socket && (await this.verifyConnection(VERIFY_TIMEOUT_MS))) {
             this.scheduleReconnectBurstReset();
+            this.established = true;
             this.opts.onReadyBeforeReplay?.();
             this.flushReplay();
             this.opts.onReconnected?.();

package/src/replay.test.ts

@@ -7,7 +7,7 @@
 import { describe, expect, it } from "vitest";
 import type { RetryConfig } from "@kuralle-syrinx/core";
 
-import { WebSocketConnection, type SocketData } from "./index.js";
+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 };
@@ -83,6 +83,69 @@ describe("WebSocketConnection reconnect replay (VE-06.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[] = [];