// Client transport tests against a fake WebSocket: id matching, serialization, // error replies, timeouts and the not-connected guard. No server required. import { test } from "node:test"; import assert from "node:assert/strict"; import { PipelinesClient, ProtocolError, NotConnectedError } from "../src/client.js"; import { validateServerUrl } from "../src/serverUrl.js"; const VALID = validateServerUrl("ws://host:8080/connect"); class FakeWebSocket { static instances = []; constructor(url) { this.url = url; this.sent = []; this.closed = null; this.onopen = null; this.onmessage = null; this.onclose = null; this.onerror = null; /** @type {((frame: any) => any | undefined) | null} */ this.reply = null; FakeWebSocket.instances.push(this); } send(data) { const frame = JSON.parse(data); this.sent.push(frame); const response = this.reply?.(frame); if (response !== undefined) { this.onmessage?.({ data: JSON.stringify(response) }); } } close(code, reason) { this.closed = { code, reason }; this.onclose?.({ code, reason }); } // test hooks open() { this.onopen?.({}); } push(obj) { this.onmessage?.({ data: JSON.stringify(obj) }); } drop(code = 1006) { this.onclose?.({ code, reason: "test" }); } } /** Let the client's serialized call chain run to the point where it has sent. */ const flush = () => new Promise((resolve) => setImmediate(resolve)); function freshClient(options = {}) { FakeWebSocket.instances = []; return new PipelinesClient({ WebSocketImpl: FakeWebSocket, ...options }); } function connectedClient(options = {}) { const client = freshClient(options); client.connect(VALID); const ws = FakeWebSocket.instances.at(-1); ws.open(); return { client, ws }; } test("a call before connect is rejected as not connected", async () => { const client = freshClient(); await assert.rejects(() => client.call({ type: "ping" }), NotConnectedError); }); test("a call sends a JSON frame with a generated id and resolves the matching reply", async () => { const { client, ws } = connectedClient(); ws.reply = (frame) => ({ id: frame.id, type: "pong" }); const reply = await client.call({ type: "ping" }); assert.equal(reply.type, "pong"); assert.equal(ws.sent.length, 1); assert.equal(ws.sent[0].type, "ping"); assert.match(ws.sent[0].id, /^web-\d+$/); }); test("an error reply surfaces the server text as a ProtocolError", async () => { const { client, ws } = connectedClient(); ws.reply = (frame) => ({ id: frame.id, type: "error", error: "nope" }); await assert.rejects(() => client.call({ type: "get_run" }), ProtocolError); }); test("an unsolicited envelope is surfaced as a frame event and not misattributed", async () => { const { client, ws } = connectedClient(); ws.reply = undefined; const frames = []; client.addEventListener("frame", (event) => frames.push(event.detail)); const pending = client.call({ type: "ping" }); let settled = false; pending.then(() => (settled = true), () => (settled = true)); await flush(); ws.push({ type: "pipelines", pipelines: [] }); // no id await flush(); assert.equal(settled, false); assert.deepEqual(frames, [{ type: "pipelines", pipelines: [] }]); const frame = ws.sent.at(-1); ws.push({ id: frame.id, type: "pong" }); assert.equal((await pending).type, "pong"); // A matched reply is not also broadcast as an unsolicited frame. assert.equal(frames.length, 1); }); test("a server-pushed chat_event frame reaches a frame listener", async () => { const { client, ws } = connectedClient(); const frames = []; client.addEventListener("frame", (event) => frames.push(event.detail)); ws.push({ type: "chat_event", chat_event: { session_id: "ses_1", message_id: "a1", kind: "text", delta: "hi" }, }); await flush(); assert.equal(frames.length, 1); assert.equal(frames[0].type, "chat_event"); assert.equal(frames[0].chat_event.session_id, "ses_1"); }); test("sendOnly sends a frame, returns its id and never waits for a reply", () => { const { client, ws } = connectedClient(); const frames = []; client.addEventListener("frame", (event) => frames.push(event.detail)); // No reply is scripted: a send-only frame must not hang the caller. const id = client.sendOnly({ type: "subscribe", workspace: "" }); assert.match(id, /^web-\d+$/); assert.deepEqual(ws.sent, [{ type: "subscribe", workspace: "", id }]); // A server that does ack (or refuse) still reaches the app as an unsolicited // frame carrying that id, not as a resolved request. ws.push({ id, type: "subscribe" }); assert.equal(frames.length, 1); assert.equal(frames[0].type, "subscribe"); }); test("sendOnly before connect is rejected as not connected", () => { const client = freshClient(); assert.throws(() => client.sendOnly({ type: "subscribe" }), NotConnectedError); }); test("back-to-back sendOnly frames keep their order on the wire", () => { const { client, ws } = connectedClient(); client.sendOnly({ type: "unsubscribe" }); client.sendOnly({ type: "subscribe", workspace: "" }); assert.deepEqual( ws.sent.map((frame) => frame.type), ["unsubscribe", "subscribe"], ); }); test("a server-pushed run_event frame reaches a frame listener", async () => { const { client, ws } = connectedClient(); const frames = []; client.addEventListener("frame", (event) => frames.push(event.detail)); ws.push({ type: "run_event", run_event: { run_id: 7, status: "running" } }); await flush(); assert.equal(frames.length, 1); assert.equal(frames[0].type, "run_event"); assert.equal(frames[0].run_event.run_id, 7); }); test("a malformed frame is ignored and does not reject a pending call", async () => { const { client, ws } = connectedClient(); const pending = client.call({ type: "ping" }); await flush(); ws.onmessage?.({ data: "{not json" }); const frame = ws.sent.at(-1); ws.push({ id: frame.id, type: "pong" }); assert.equal((await pending).type, "pong"); }); test("a missing reply times out with a clear error", async () => { const { client } = connectedClient({ requestTimeoutMs: 20 }); await assert.rejects(() => client.call({ type: "ping" }), /timed out after 20ms/); }); test("concurrent calls are serialized in submission order", async () => { const { client, ws } = connectedClient(); const order = []; ws.reply = (frame) => { order.push(frame.type); return { id: frame.id, type: "ok" }; }; await Promise.all([client.call({ type: "a" }), client.call({ type: "b" })]); assert.deepEqual(order, ["a", "b"]); }); test("the state flow reports connecting then connected", async () => { const seen = []; const client = freshClient(); client.addEventListener("state", (e) => seen.push(e.detail.kind)); client.connect(VALID); FakeWebSocket.instances.at(-1).open(); assert.deepEqual(seen, ["connecting", "connected"]); }); test("an unexpected close fails pending calls and schedules a reconnect", async () => { const { client, ws } = connectedClient({ backoffBaseMs: 1, backoffMaxMs: 5 }); const pending = client.call({ type: "ping" }); // never answered await flush(); // let the call reach the socket before it is dropped ws.drop(1006); await assert.rejects(() => pending, /Connection closed/); assert.equal(client.state.kind, "disconnected"); assert.equal(client.state.retrying, true); client.disconnect(); // stop the reconnect timer before the test ends }); test("disconnect goes idle and does not schedule a reconnect", () => { const { client, ws } = connectedClient(); client.disconnect(); assert.equal(client.state.kind, "idle"); assert.equal(client.state.retrying, false); assert.deepEqual(ws.closed, { code: 1000, reason: "client closing" }); }); test("connecting again replaces the socket and ignores the superseded one", async () => { // The Settings `Connect` action is connect-only and must be safe to press while // connected: it re-opens the endpoint (Android's connectLocked replaces the // socket) instead of leaving two live sockets or letting the old one's late // close mark the new connection disconnected. const { client, ws } = connectedClient(); const pending = client.call({ type: "ping" }); // sent on the old socket await flush(); client.connect(VALID); const replacement = FakeWebSocket.instances.at(-1); assert.notEqual(replacement, ws); assert.equal(client.state.kind, "connecting"); await assert.rejects(() => pending, /Connection replaced/); assert.deepEqual(ws.closed, { code: 1000, reason: "superseded" }); replacement.open(); assert.equal(client.state.kind, "connected"); // The superseded socket's late failure must not touch the live connection. ws.drop(1006); assert.equal(client.state.kind, "connected"); assert.equal(client.state.retrying, false); });