@ekodb/ekodb-client 0.19.0 → 0.21.0

package/dist/websocket.test.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
 const ws_1 = require("ws");
+const msgpack_1 = require("@msgpack/msgpack");
 const client_1 = require("./client");
 // ============================================================================
 // Test Helpers
@@ -14,11 +15,48 @@ const client_1 = require("./client");
 let wss;
 let port;
 let serverConnections = [];
+// Format the mock server Welcomes during the handshake. Default "json" keeps
+// the existing tests on the text transport they assert against; the binary
+// negotiation test sets "msgpack" before connecting.
+let welcomeFormat = "json";
+const recvState = new Map();
 function startServer() {
     return new Promise((resolve) => {
         wss = new ws_1.WebSocketServer({ port: 0 });
         wss.on("connection", (ws) => {
             serverConnections.push(ws);
+            const state = {
+                queue: [],
+                waiters: [],
+                handshakeDone: false,
+                lastBinary: false,
+            };
+            recvState.set(ws, state);
+            ws.on("message", (data, isBinary) => {
+                let msg;
+                try {
+                    msg = isBinary ? (0, msgpack_1.decode)(data) : JSON.parse(data.toString());
+                }
+                catch {
+                    return;
+                }
+                // Answer the additive Hello handshake exactly like the real server, and
+                // never surface it to the test. The Hello is always text.
+                if (!state.handshakeDone && msg?.type === "Hello") {
+                    state.handshakeDone = true;
+                    ws.send(JSON.stringify({
+                        type: "Welcome",
+                        payload: { format: welcomeFormat },
+                    }));
+                    return;
+                }
+                state.lastBinary = isBinary;
+                const waiter = state.waiters.shift();
+                if (waiter)
+                    waiter(msg);
+                else
+                    state.queue.push(msg);
+            });
         });
         wss.on("listening", () => {
             const addr = wss.address();
@@ -29,12 +67,15 @@ function startServer() {
 function getLastConnection() {
     return serverConnections[serverConnections.length - 1];
 }
+// Resolve with the next real (post-handshake) frame, draining any already
+// buffered. Decoded per the negotiated frame type, so it works for both JSON
+// and msgpack connections without the caller caring which.
 function waitForMessage(ws) {
-    return new Promise((resolve) => {
-        ws.once("message", (data) => {
-            resolve(JSON.parse(data.toString()));
-        });
-    });
+    const state = recvState.get(ws);
+    const queued = state.queue.shift();
+    if (queued !== undefined)
+        return Promise.resolve(queued);
+    return new Promise((resolve) => state.waiters.push(resolve));
 }
 // ============================================================================
 // Tests
@@ -42,6 +83,8 @@ function waitForMessage(ws) {
 (0, vitest_1.describe)("WebSocketClient", () => {
     (0, vitest_1.beforeEach)(async () => {
         serverConnections = [];
+        recvState.clear();
+        welcomeFormat = "json";
         port = await startServer();
     });
     (0, vitest_1.afterEach)(() => {
@@ -91,6 +134,31 @@ function waitForMessage(ws) {
         });
     });
     // --------------------------------------------------------------------------
+    // URL normalization
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("URL normalization", () => {
+        function captureRequestPath() {
+            return new Promise((resolve) => {
+                wss.once("connection", (_ws, req) => resolve(req.url ?? ""));
+            });
+        }
+        (0, vitest_1.it)("appends /api/ws without a double slash when the base URL has a trailing slash", async () => {
+            const pathPromise = captureRequestPath();
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/`, "test-token");
+            // Trigger a connect; we only assert the path the server receives.
+            client.findAll("users").catch(() => { });
+            (0, vitest_1.expect)(await pathPromise).toBe("/api/ws");
+            client.close();
+        });
+        (0, vitest_1.it)("does not duplicate /api/ws when the URL already ends with it plus a trailing slash", async () => {
+            const pathPromise = captureRequestPath();
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws/`, "test-token");
+            client.findAll("users").catch(() => { });
+            (0, vitest_1.expect)(await pathPromise).toBe("/api/ws");
+            client.close();
+        });
+    });
+    // --------------------------------------------------------------------------
     // subscribe
     // --------------------------------------------------------------------------
     (0, vitest_1.describe)("subscribe", () => {
@@ -292,6 +360,70 @@ function waitForMessage(ws) {
         });
     });
     // --------------------------------------------------------------------------
+    // unsubscribe
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("unsubscribe", () => {
+        (0, vitest_1.it)("sends an Unsubscribe frame to the server", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.subscribe("orders");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const subMsg = await waitForMessage(ws);
+            (0, vitest_1.expect)(subMsg.type).toBe("Subscribe");
+            ws.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: subMsg.messageId, status: "subscribed" },
+            }));
+            await streamPromise;
+            const unsubMsg = waitForMessage(ws);
+            client.unsubscribe("orders");
+            const sent = await unsubMsg;
+            (0, vitest_1.expect)(sent.type).toBe("Unsubscribe");
+            (0, vitest_1.expect)(sent.payload.collection).toBe("orders");
+            client.close();
+        });
+    });
+    // cancelChat
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("cancelChat", () => {
+        (0, vitest_1.it)("sends CancelChat frame", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            // Open the connection via a chat stream first.
+            const streamPromise = client.chatSend("chat-1", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws); // ChatSend
+            await streamPromise;
+            const cancelMsg = waitForMessage(ws);
+            await client.cancelChat("chat-1");
+            const sent = await cancelMsg;
+            (0, vitest_1.expect)(sent.type).toBe("CancelChat");
+            (0, vitest_1.expect)(sent.payload.chat_id).toBe("chat-1");
+            // A correlation id must be attached so a Success ack can't be misrouted by
+            // the dispatcher's single-pending fallback.
+            (0, vitest_1.expect)(typeof sent.messageId).toBe("string");
+            (0, vitest_1.expect)(sent.messageId.length).toBeGreaterThan(0);
+            client.close();
+        });
+        (0, vitest_1.it)("attaches a unique messageId on each CancelChat frame", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.chatSend("chat-1", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws); // ChatSend
+            await streamPromise;
+            const first = waitForMessage(ws);
+            await client.cancelChat("chat-1");
+            const firstSent = await first;
+            const second = waitForMessage(ws);
+            await client.cancelChat("chat-1");
+            const secondSent = await second;
+            (0, vitest_1.expect)(firstSent.messageId).toBeTruthy();
+            (0, vitest_1.expect)(secondSent.messageId).toBeTruthy();
+            (0, vitest_1.expect)(firstSent.messageId).not.toBe(secondSent.messageId);
+            client.close();
+        });
+    });
     // sendToolResult
     // --------------------------------------------------------------------------
     (0, vitest_1.describe)("sendToolResult", () => {
@@ -493,4 +625,206 @@ function waitForMessage(ws) {
             client.close();
         });
     });
+    // --------------------------------------------------------------------------
+    // Per-request timeout
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("per-request timeout", () => {
+        (0, vitest_1.it)("rejects a pending request when no response arrives", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token", { requestTimeoutMs: 50, autoReconnect: false });
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws); // receive FindAll but never respond
+            await (0, vitest_1.expect)(resultPromise).rejects.toThrow(/timed out after 50ms/);
+            client.close();
+        });
+        (0, vitest_1.it)("does not time out when a response arrives in time", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token", { requestTimeoutMs: 500, autoReconnect: false });
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const msg = await waitForMessage(ws);
+            ws.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: msg.messageId, data: [{ id: "1" }] },
+            }));
+            await (0, vitest_1.expect)(resultPromise).resolves.toEqual([{ id: "1" }]);
+            client.close();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Reject pending requests on disconnect
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("disconnect handling", () => {
+        (0, vitest_1.it)("rejects in-flight requests when the socket drops", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token", { autoReconnect: false });
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws); // FindAll received, never answered
+            // Server drops the connection.
+            ws.close();
+            await (0, vitest_1.expect)(resultPromise).rejects.toThrow(/connection closed/i);
+            client.close();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Backoff helper
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("computeBackoff", () => {
+        (0, vitest_1.it)("grows exponentially, stays within jittered bounds, and caps", () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token", { reconnectInitialDelayMs: 200, reconnectMaxDelayMs: 5000 });
+            // attempt 0 -> base 200, +/-25% => [150, 250]
+            for (let i = 0; i < 20; i++) {
+                const d0 = client.computeBackoff(0);
+                (0, vitest_1.expect)(d0).toBeGreaterThanOrEqual(150);
+                (0, vitest_1.expect)(d0).toBeLessThanOrEqual(250);
+            }
+            // attempt 3 -> base 1600, +/-25% => [1200, 2000]
+            const d3 = client.computeBackoff(3);
+            (0, vitest_1.expect)(d3).toBeGreaterThanOrEqual(1200);
+            (0, vitest_1.expect)(d3).toBeLessThanOrEqual(2000);
+            // attempt 20 -> capped at 5000, +/-25% => [3750, 6250]
+            const dBig = client.computeBackoff(20);
+            (0, vitest_1.expect)(dBig).toBeGreaterThanOrEqual(3750);
+            (0, vitest_1.expect)(dBig).toBeLessThanOrEqual(6250);
+            client.close();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Auto-reconnect + re-subscribe + fresh token
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("auto-reconnect", () => {
+        (0, vitest_1.it)("re-subscribes after a socket drop and re-evaluates the token", async () => {
+            // Token provider returns a new token each call so we can assert the
+            // reconnect used a freshly-obtained token (not a stale snapshot).
+            let tokenCalls = 0;
+            const tokenProvider = () => `token-${++tokenCalls}`;
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, tokenProvider, {
+                autoReconnect: true,
+                reconnectInitialDelayMs: 10,
+                reconnectMaxDelayMs: 30,
+            });
+            // Establish the subscription on the first connection.
+            const streamPromise = client.subscribe("orders");
+            await new Promise((r) => wss.once("connection", r));
+            const ws1 = getLastConnection();
+            const sub1 = await waitForMessage(ws1);
+            (0, vitest_1.expect)(sub1.type).toBe("Subscribe");
+            (0, vitest_1.expect)(sub1.payload.collection).toBe("orders");
+            ws1.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: sub1.messageId, status: "subscribed" },
+            }));
+            const stream = await streamPromise;
+            (0, vitest_1.expect)(tokenCalls).toBe(1);
+            // Arm the next-connection handler BEFORE dropping so we don't miss it.
+            const nextConn = new Promise((resolve) => {
+                wss.once("connection", (ws) => resolve(ws));
+            });
+            // Simulate a transient drop: server closes the socket.
+            ws1.close();
+            // The client should auto-reconnect (new connection) and re-send Subscribe.
+            const ws2 = await nextConn;
+            const sub2 = await waitForMessage(ws2);
+            (0, vitest_1.expect)(sub2.type).toBe("Subscribe");
+            (0, vitest_1.expect)(sub2.payload.collection).toBe("orders");
+            // Reconnect re-evaluated the token provider.
+            (0, vitest_1.expect)(tokenCalls).toBeGreaterThanOrEqual(2);
+            // Ack the re-subscribe.
+            ws2.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: sub2.messageId, status: "subscribed" },
+            }));
+            // The SAME stream still delivers mutations over the new socket.
+            const mutationPromise = new Promise((resolve) => {
+                stream.on("mutation", resolve);
+            });
+            ws2.send(JSON.stringify({
+                type: "MutationNotification",
+                payload: {
+                    collection: "orders",
+                    event: "insert",
+                    record_ids: ["order-9"],
+                    timestamp: "2026-06-02T00:00:00Z",
+                },
+            }));
+            const mutation = await mutationPromise;
+            (0, vitest_1.expect)(mutation.recordIds).toEqual(["order-9"]);
+            (0, vitest_1.expect)(stream.closed).toBe(false);
+            client.close();
+        });
+        (0, vitest_1.it)("does not reconnect after an intentional close()", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token", { autoReconnect: true, reconnectInitialDelayMs: 10 });
+            const streamPromise = client.subscribe("widgets");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const sub = await waitForMessage(ws);
+            ws.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: sub.messageId, status: "subscribed" },
+            }));
+            await streamPromise;
+            const connectionsBefore = serverConnections.length;
+            // Intentional close: must NOT reconnect.
+            client.close();
+            // Give any erroneous reconnect time to land.
+            await new Promise((r) => setTimeout(r, 80));
+            (0, vitest_1.expect)(serverConnections.length).toBe(connectionsBefore);
+        });
+    });
+    (0, vitest_1.describe)("auth token validation", () => {
+        (0, vitest_1.it)("rejects connect when the token provider returns null (no Bearer null)", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, () => null);
+            await (0, vitest_1.expect)(client.findAll("users")).rejects.toThrow(/token is unavailable/i);
+            client.close();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Binary (msgpack) negotiation
+    // --------------------------------------------------------------------------
+    (0, vitest_1.describe)("msgpack negotiation", () => {
+        (0, vitest_1.it)("negotiates msgpack and round-trips a binary request/response", async () => {
+            welcomeFormat = "msgpack";
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const msg = await waitForMessage(ws);
+            // The request arrived as a binary msgpack frame, decoded to the same
+            // object shape as JSON would produce.
+            (0, vitest_1.expect)(recvState.get(ws).lastBinary).toBe(true);
+            (0, vitest_1.expect)(msg.type).toBe("FindAll");
+            (0, vitest_1.expect)(msg.payload.collection).toBe("users");
+            // Respond with a binary msgpack frame; the client must decode it
+            // transparently.
+            ws.send((0, msgpack_1.encode)({
+                type: "Success",
+                payload: {
+                    message_id: msg.messageId,
+                    data: [{ id: "1", name: "Alice" }],
+                },
+            }));
+            const result = await resultPromise;
+            (0, vitest_1.expect)(result).toEqual([{ id: "1", name: "Alice" }]);
+            client.close();
+        });
+        (0, vitest_1.it)("stays on JSON text when the server welcomes only json", async () => {
+            welcomeFormat = "json";
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const resultPromise = client.findAll("users");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            const msg = await waitForMessage(ws);
+            // The request is a JSON text frame, not binary.
+            (0, vitest_1.expect)(recvState.get(ws).lastBinary).toBe(false);
+            (0, vitest_1.expect)(msg.type).toBe("FindAll");
+            ws.send(JSON.stringify({
+                type: "Success",
+                payload: { message_id: msg.messageId, data: [] },
+            }));
+            await resultPromise;
+            client.close();
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",