import { afterAll, beforeAll, describe, expect, test, vi } from "vitest"; import { createServer, Server } from "node:http"; import { existsSync, unlinkSync } from "node:fs"; import { connect as netConnect } from "node:net"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { getRandomPort, waitForPort } from "get-port-please"; import { WebSocket as WsWebSocket } from "ws"; import nodeAdapter from "../src/adapters/node.ts"; import { createWebSocketProxy, defineHooks } from "../src/index.ts"; import type { WebSocketProxyCloseDetails, WebSocketProxyOptions } from "../src/index.ts"; import { _normalizeOutgoingCode, _remapIncomingCode, _resolveProtocols } from "../src/proxy.ts"; import { wsConnect } from "./_utils.ts"; describe("createWebSocketProxy", () => { let upstreamServer: Server; let proxyServer: Server; let dynamicProxyServer: Server; let limitedProxyServer: Server; let badProxyServer: Server; let timeoutProxyServer: Server; let idleProxyServer: Server; let upstreamURL: string; let proxyURL: string; let dynamicProxyURL: string; let limitedProxyURL: string; let badProxyURL: string; let timeoutProxyURL: string; let idleProxyURL: string; beforeAll(async () => { // Upstream echo server (crossws node adapter) const upstream = nodeAdapter({ hooks: defineHooks({ open(peer) { peer.send("welcome"); }, async upgrade(req) { const { pathname } = new URL(req.url); if (pathname === "/slow") { await new Promise((r) => setTimeout(r, 100)); } if (req.headers.get("sec-websocket-protocol") === "chat") { return { headers: { "sec-websocket-protocol": "chat" } }; } }, message(peer, message) { const text = message.text(); if (text === "getbinary") { peer.send(new TextEncoder().encode("binary-pong")); return; } if (text === "type") { const kind = typeof message.rawData === "string" ? "text" : "binary"; peer.send(`type:${kind}`); return; } if (text.startsWith("close:")) { const [, codeStr, reason] = text.split(":"); peer.close(Number(codeStr), reason); return; } peer.send(`echo:${text}`); }, }), }); upstreamServer = createServer((_req, res) => res.end("ok")); upstreamServer.on("upgrade", upstream.handleUpgrade); const upstreamPort = await getRandomPort("localhost"); upstreamURL = `ws://localhost:${upstreamPort}/`; await new Promise((resolve) => upstreamServer.listen(upstreamPort, resolve)); await waitForPort(upstreamPort); // Proxy server using createWebSocketProxy hooks const proxy = nodeAdapter({ hooks: createWebSocketProxy(upstreamURL), }); proxyServer = createServer((_req, res) => res.end("ok")); proxyServer.on("upgrade", proxy.handleUpgrade); const proxyPort = await getRandomPort("localhost"); proxyURL = `ws://localhost:${proxyPort}/`; await new Promise((resolve) => proxyServer.listen(proxyPort, resolve)); await waitForPort(proxyPort); // Proxy server using dynamic target function const dynamicProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: () => upstreamURL }), }); dynamicProxyServer = createServer((_req, res) => res.end("ok")); dynamicProxyServer.on("upgrade", dynamicProxy.handleUpgrade); const dynamicProxyPort = await getRandomPort("localhost"); dynamicProxyURL = `ws://localhost:${dynamicProxyPort}/`; await new Promise((resolve) => dynamicProxyServer.listen(dynamicProxyPort, resolve)); await waitForPort(dynamicProxyPort); // Proxy with a small buffer limit pointing at a slow-upgrade path const limitedProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: `${upstreamURL}slow`, maxBufferSize: 5, }), }); limitedProxyServer = createServer((_req, res) => res.end("ok")); limitedProxyServer.on("upgrade", limitedProxy.handleUpgrade); const limitedProxyPort = await getRandomPort("localhost"); limitedProxyURL = `ws://localhost:${limitedProxyPort}/`; await new Promise((resolve) => limitedProxyServer.listen(limitedProxyPort, resolve)); await waitForPort(limitedProxyPort); // Proxy pointing at a port with nothing listening const deadPort = await getRandomPort("localhost"); const badProxy = nodeAdapter({ hooks: createWebSocketProxy(`ws://localhost:${deadPort}/`), }); badProxyServer = createServer((_req, res) => res.end("ok")); badProxyServer.on("upgrade", badProxy.handleUpgrade); const badProxyPort = await getRandomPort("localhost"); badProxyURL = `ws://localhost:${badProxyPort}/`; await new Promise((resolve) => badProxyServer.listen(badProxyPort, resolve)); await waitForPort(badProxyPort); // Proxy with a small connect timeout pointing at the slow-upgrade path const timeoutProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: `${upstreamURL}slow`, connectTimeout: 25, }), }); timeoutProxyServer = createServer((_req, res) => res.end("ok")); timeoutProxyServer.on("upgrade", timeoutProxy.handleUpgrade); const timeoutProxyPort = await getRandomPort("localhost"); timeoutProxyURL = `ws://localhost:${timeoutProxyPort}/`; await new Promise((resolve) => timeoutProxyServer.listen(timeoutProxyPort, resolve)); await waitForPort(timeoutProxyPort); // Proxy with a short client-inactivity timeout const idleProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: upstreamURL, clientIdleTimeout: 80, }), }); idleProxyServer = createServer((_req, res) => res.end("ok")); idleProxyServer.on("upgrade", idleProxy.handleUpgrade); const idleProxyPort = await getRandomPort("localhost"); idleProxyURL = `ws://localhost:${idleProxyPort}/`; await new Promise((resolve) => idleProxyServer.listen(idleProxyPort, resolve)); await waitForPort(idleProxyPort); }); afterAll(() => { for (const server of [ proxyServer, dynamicProxyServer, limitedProxyServer, badProxyServer, timeoutProxyServer, idleProxyServer, upstreamServer, ]) { server.closeAllConnections?.(); server.close(); } }); test("forwards welcome message from upstream", async () => { const ws = await wsConnect(proxyURL); expect(await ws.next()).toBe("welcome"); }); test("forwards text messages bidirectionally", async () => { const ws = await wsConnect(proxyURL, { skip: 1 }); await ws.send("hello"); expect(await ws.next()).toBe("echo:hello"); await ws.send("world"); expect(await ws.next()).toBe("echo:world"); }); test("forwards text frames as text (not binary)", async () => { // Regression: on Node's `ws` lib, text frames arrive as Buffer. // The Node adapter must decode them so downstream hooks see a string. const ws = await wsConnect(proxyURL, { skip: 1 }); await ws.send("type"); expect(await ws.next()).toBe("type:text"); }); test("forwards binary messages", async () => { const ws = await wsConnect(proxyURL, { skip: 1 }); await ws.send("getbinary"); // wsConnect decodes incoming binary frames as UTF-8 text expect(await ws.next()).toBe("binary-pong"); }); test("forwards subprotocol negotiation", async () => { const ws = await wsConnect(proxyURL, { headers: { "sec-websocket-protocol": "chat" }, }); expect(ws.inspector.headers).toMatchObject({ "sec-websocket-protocol": "chat", }); }); test("buffers messages sent before upstream is open", async () => { // The client "open" event fires once the proxy handshake completes, // but the upstream WebSocket is still connecting inside the `open` hook, // so early messages must be buffered by the proxy. const ws = await wsConnect(proxyURL, { skip: 1 }); await ws.send("early"); expect(await ws.next()).toBe("echo:early"); }); test("accepts dynamic target function", async () => { const ws = await wsConnect(dynamicProxyURL, { skip: 1 }); await ws.send("dyn"); expect(await ws.next()).toBe("echo:dyn"); }); test("accepts an async (promise-returning) target resolver", async () => { // The upstream address may not be known when the client connects (e.g. a // worker that's still booting). An async resolver lets the proxy wait. const asyncProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: async () => { await new Promise((r) => setTimeout(r, 50)); return upstreamURL; }, }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", asyncProxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { // Frames sent before the async target resolves must be buffered and // flushed once the upstream opens. const ws = await wsConnect(`ws://localhost:${port}/`, { skip: 1 }); await ws.send("early"); expect(await ws.next()).toBe("echo:early"); } finally { server.closeAllConnections?.(); server.close(); } }); test("accepts a non-native thenable target resolver", async () => { // Resolvers backed by non-native promises (Bluebird, cross-realm, custom // thenables from RPC clients) must be awaited like any other promise — not // stringified into `new URL()`. const thenableProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: () => ({ // oxlint-disable-next-line unicorn/no-thenable -- intentionally a non-native thenable then(onFulfilled: (value: string) => void) { setTimeout(() => onFulfilled(upstreamURL), 50); }, }) as unknown as Promise, }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", thenableProxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { const ws = await wsConnect(`ws://localhost:${port}/`, { skip: 1 }); await ws.send("early"); expect(await ws.next()).toBe("echo:early"); } finally { server.closeAllConnections?.(); server.close(); } }); test("closes peer with 1011 when an async target resolver rejects", async () => { const rejectProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: async () => { throw new Error("worker never came up"); }, }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", rejectProxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { const ws = await wsConnect(`ws://localhost:${port}/`); const event = await new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); expect(event.code).toBe(1011); } finally { server.closeAllConnections?.(); server.close(); } }); test("proxies to a unix-socket upstream out of the box (no custom WebSocket)", async () => { // A `ws+unix://:` target works without any custom // `WebSocket` constructor: the proxy picks the right per-runtime dialing // strategy internally. On this Node test runner that means a lazy // `import("ws")` (Node's global undici WebSocket rejects the scheme). const socketPath = join(tmpdir(), `crossws-proxy-unix-${process.pid}.sock`); if (existsSync(socketPath)) unlinkSync(socketPath); // Upstream echo server bound to the unix socket instead of a TCP port. const unixUpstream = nodeAdapter({ hooks: defineHooks({ message(peer, message) { peer.send(`echo:${message.text()}`); }, }), }); const unixUpstreamServer = createServer((_req, res) => res.end("ok")); unixUpstreamServer.on("upgrade", unixUpstream.handleUpgrade); await new Promise((resolve) => unixUpstreamServer.listen(socketPath, resolve)); // No `WebSocket` option — the proxy resolves the dialer per runtime. const unixProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: `ws+unix://${socketPath}:/chat`, }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", unixProxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { const ws = await wsConnect(`ws://localhost:${port}/`); await ws.send("unix"); expect(await ws.next()).toBe("echo:unix"); } finally { server.closeAllConnections?.(); server.close(); unixUpstreamServer.closeAllConnections?.(); unixUpstreamServer.close(); if (existsSync(socketPath)) unlinkSync(socketPath); } }); test("proxies to a unix-socket upstream with an explicit ws WebSocket", async () => { // An explicit `WebSocket` constructor is honored verbatim (bypassing the // per-runtime strategy) — the `ws` client dials `ws+unix:` directly. const socketPath = join(tmpdir(), `crossws-proxy-unix-explicit-${process.pid}.sock`); if (existsSync(socketPath)) unlinkSync(socketPath); const unixUpstream = nodeAdapter({ hooks: defineHooks({ message(peer, message) { peer.send(`echo:${message.text()}`); }, }), }); const unixUpstreamServer = createServer((_req, res) => res.end("ok")); unixUpstreamServer.on("upgrade", unixUpstream.handleUpgrade); await new Promise((resolve) => unixUpstreamServer.listen(socketPath, resolve)); const unixProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: `ws+unix://${socketPath}:/`, WebSocket: WsWebSocket as unknown as typeof WebSocket, }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", unixProxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { const ws = await wsConnect(`ws://localhost:${port}/`); await ws.send("unix"); expect(await ws.next()).toBe("echo:unix"); } finally { server.closeAllConnections?.(); server.close(); unixUpstreamServer.closeAllConnections?.(); unixUpstreamServer.close(); if (existsSync(socketPath)) unlinkSync(socketPath); } }); test("dials a unix socket via a webSocketOptions transport override", async () => { // Some runtimes (Deno) reject the `ws+unix:` scheme and can only reach a // unix socket by redirecting the transport through a constructor option // (Deno's `client`). `webSocketOptions` is the escape hatch for that: here // we keep a plain `ws://` target and inject `ws`'s `createConnection` to // dial the socket — the same shape a Deno consumer would use for `client`. const socketPath = join(tmpdir(), `crossws-proxy-wsopts-${process.pid}.sock`); if (existsSync(socketPath)) unlinkSync(socketPath); const unixUpstream = nodeAdapter({ hooks: defineHooks({ message(peer, message) { peer.send(`echo:${message.text()}`); }, }), }); const unixUpstreamServer = createServer((_req, res) => res.end("ok")); unixUpstreamServer.on("upgrade", unixUpstream.handleUpgrade); await new Promise((resolve) => unixUpstreamServer.listen(socketPath, resolve)); const optsProxy = nodeAdapter({ hooks: createWebSocketProxy({ target: "ws://localhost/", WebSocket: WsWebSocket as unknown as typeof WebSocket, webSocketOptions: () => ({ createConnection: () => netConnect({ path: socketPath }), }), }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", optsProxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { const ws = await wsConnect(`ws://localhost:${port}/`); await ws.send("via-opts"); expect(await ws.next()).toBe("echo:via-opts"); } finally { server.closeAllConnections?.(); server.close(); unixUpstreamServer.closeAllConnections?.(); unixUpstreamServer.close(); if (existsSync(socketPath)) unlinkSync(socketPath); } }); test("propagates upstream close code", async () => { const ws = await wsConnect(proxyURL, { skip: 1 }); const closed = new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); await ws.send("close:4321:bye"); const event = await closed; expect(event.code).toBe(4321); }); test("closes peer with 1011 when upstream cannot connect", async () => { const ws = await wsConnect(badProxyURL); const event = await new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); expect(event.code).toBe(1011); }); test("closes peer with 1011 when upstream handshake times out", async () => { // Upstream has a 100ms upgrade delay, proxy's connectTimeout is 25ms. const ws = await wsConnect(timeoutProxyURL); const event = await new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); expect(event.code).toBe(1011); }); test("enforces maxBufferSize limit", async () => { const ws = await wsConnect(limitedProxyURL); const closed = new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); // Upstream has a 100ms upgrade delay, so these messages queue in the // proxy's buffer before the upstream connection opens. The proxy // accounts strings at their UTF-8 worst case (3 bytes per code unit) // so any non-empty frame exceeds the 5-byte limit configured above. await ws.send("aaaaa"); const event = await closed; expect(event.code).toBe(1009); }); test("closes an idle client with 1001 after clientIdleTimeout", async () => { // The client stays silent after connecting. Upstream→client traffic (the // "welcome" frame) must NOT keep it alive — only client→proxy frames do — // so the inactivity watchdog fires and closes with 1001. const ws = await wsConnect(idleProxyURL, { skip: 1 }); const event = await new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); expect(event.code).toBe(1001); }); test("client traffic resets the inactivity timer", async () => { const ws = await wsConnect(idleProxyURL, { skip: 1 }); let closed = false; ws.ws.addEventListener("close", () => { closed = true; }); // Each gap is under the 80ms idle window, but the total span is well past // it — the connection must stay open because every send resets the timer. for (let i = 0; i < 4; i++) { await new Promise((r) => setTimeout(r, 40)); await ws.send(`ping${i}`); expect(await ws.next()).toBe(`echo:ping${i}`); } expect(closed).toBe(false); }); }); describe("createWebSocketProxy unit hooks", () => { test("returns perMessageDeflate from the upgrade hook", () => { const perMessageDeflate = { threshold: 1024 }; const hooks = createWebSocketProxy({ target: "ws://localhost/", perMessageDeflate }); expect(hooks.upgrade?.(new Request("http://localhost/"))).toEqual({ perMessageDeflate }); const withProtocol = new Request("http://localhost/", { headers: { "sec-websocket-protocol": "chat" }, }); expect(hooks.upgrade?.(withProtocol)).toEqual({ headers: { "sec-websocket-protocol": "chat" }, perMessageDeflate, }); }); test("echoes valid subprotocol tokens in upgrade response", () => { const hooks = createWebSocketProxy("ws://localhost/"); const req = new Request("http://localhost/", { headers: { "sec-websocket-protocol": "chat" }, }); const result = hooks.upgrade?.(req); expect(result).toMatchObject({ headers: { "sec-websocket-protocol": "chat" }, }); }); test("drops subprotocol values that are not RFC 7230 tokens", () => { // Defense-in-depth: even if a buggy runtime lets a client smuggle a // non-token character into the header, the proxy must not echo it // into the upgrade response. const hooks = createWebSocketProxy("ws://localhost/"); for (const bad of ["a/b", "has space", "semi;colon", "ctl\u0001"]) { const req = new Request("http://localhost/", { headers: { "sec-websocket-protocol": bad }, }); expect(hooks.upgrade?.(req)).toBeUndefined(); } }); test("passes headers option through to custom WebSocket constructor", () => { const calls: Array<{ url: unknown; protocols: unknown; options: unknown; }> = []; class StubWS extends EventTarget { binaryType = "arraybuffer"; readyState = 0; constructor(url: unknown, protocols: unknown, options?: unknown) { super(); calls.push({ url, protocols, options }); } send(): void {} close(): void {} } const hooks = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, headers: (peer) => ({ cookie: peer.request?.headers.get("cookie") ?? "", "x-trace": "t1", }), }); const peer = { id: "p-headers", request: new Request("http://localhost/", { headers: { cookie: "sid=abc" }, }), close() {}, send() {}, }; hooks.open?.(peer as never); expect(calls).toHaveLength(1); expect(calls[0]!.options).toEqual({ headers: { cookie: "sid=abc", "x-trace": "t1" }, }); }); test("merges webSocketOptions into the constructor's third argument", () => { const calls: Array<{ options: unknown }> = []; class StubWS extends EventTarget { binaryType = "arraybuffer"; readyState = 0; constructor(_url: unknown, _protocols: unknown, options?: unknown) { super(); calls.push({ options }); } send(): void {} close(): void {} } const peer = { id: "p-opts", request: new Request("http://localhost/", { headers: { cookie: "sid=abc" } }), close() {}, send() {}, }; // A per-peer resolver's keys land in the third argument, and the dedicated // `headers` option is applied on top of any `headers` key it returns. const marker = { transport: "unix" }; const withResolver = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, webSocketOptions: (p) => ({ client: marker, headers: { "x-ignored": p.id } }), headers: (p) => ({ cookie: p.request?.headers.get("cookie") ?? "" }), }); withResolver.open?.(peer as never); expect(calls).toHaveLength(1); expect(calls[0]!.options).toEqual({ client: marker, headers: { cookie: "sid=abc" }, }); // A static object works too, and passes through with no headers option. calls.length = 0; const withStatic = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, webSocketOptions: { agent: false }, }); withStatic.open?.({ ...peer, id: "p-opts-static" } as never); expect(calls[0]!.options).toEqual({ agent: false }); }); test("omits the third argument when neither headers nor webSocketOptions is set", () => { const calls: Array<{ argc: number }> = []; class StubWS extends EventTarget { binaryType = "arraybuffer"; readyState = 0; constructor(..._args: unknown[]) { super(); calls.push({ argc: _args.length }); } send(): void {} close(): void {} } const hooks = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, }); hooks.open?.({ id: "p-noopts", request: new Request("http://localhost/"), close() {}, send() {}, } as never); // Only (url, protocols) — no third options object fabricated. expect(calls).toEqual([{ argc: 2 }]); }); test("closes peer with 1011 when WebSocket constructor rejects the target", async () => { // The WHATWG `WebSocket` constructor throws `SyntaxError` for any // scheme other than `ws:`/`wss:`. The open hook must catch that // and close the peer instead of letting the exception escape. const badAdapter = nodeAdapter({ hooks: createWebSocketProxy({ target: () => new URL("http://localhost:1/"), }), }); const server = createServer((_req, res) => res.end("ok")); server.on("upgrade", badAdapter.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); try { const ws = await wsConnect(`ws://localhost:${port}/`); const event = await new Promise((resolve) => { ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); expect(event.code).toBe(1011); } finally { server.closeAllConnections?.(); server.close(); } }); test("passes ws+unix targets through to a custom WebSocket client", () => { // No built-in scheme validation: anything the custom constructor // accepts (e.g. the `ws+unix:` syntax supported by `ws`) works. const calls: unknown[] = []; class StubWS extends EventTarget { binaryType = "arraybuffer"; readyState = 0; constructor(url: unknown) { super(); calls.push(url); } send(): void {} close(): void {} } const hooks = createWebSocketProxy({ target: "ws+unix:/tmp/sock:/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, }); const peer = { id: "p-unix", request: new Request("http://localhost/"), close() {}, send() {}, }; hooks.open?.(peer as never); expect(calls).toHaveLength(1); expect(String(calls[0])).toContain("ws+unix:"); }); }); describe("createWebSocketProxy internals", () => { test("_normalizeOutgoingCode allows 1000 and 3000-4999 range", () => { // state.ws is a client-side WebSocket; WHATWG forbids anything else. expect(_normalizeOutgoingCode(undefined)).toBeUndefined(); expect(_normalizeOutgoingCode(1000)).toBe(1000); expect(_normalizeOutgoingCode(3000)).toBe(3000); expect(_normalizeOutgoingCode(4999)).toBe(4999); }); test("_normalizeOutgoingCode rewrites reserved and disallowed codes to 1000", () => { // Regression: state.ws.close(1005) would throw InvalidAccessError, // leaking the upstream socket. 1001/1008 are valid server-side codes // but still forbidden for client-side close(), so they also normalize. for (const code of [1001, 1005, 1006, 1008, 1011, 1015, 2999, 5000]) { expect(_normalizeOutgoingCode(code)).toBe(1000); } }); test("_remapIncomingCode rewrites reserved pseudo-codes before peer close", () => { expect(_remapIncomingCode(undefined)).toBeUndefined(); expect(_remapIncomingCode(1000)).toBe(1000); expect(_remapIncomingCode(1005)).toBe(1000); expect(_remapIncomingCode(1006)).toBe(1011); expect(_remapIncomingCode(1015)).toBe(1011); expect(_remapIncomingCode(4321)).toBe(4321); }); test("_resolveProtocols resolves boolean and function forms", () => { const peerWith = (protocol?: string) => ({ request: new Request( "http://localhost/", protocol ? { headers: { "sec-websocket-protocol": protocol } } : undefined, ), }) as never; // boolean: undefined/true forwards the client header verbatim expect(_resolveProtocols(peerWith("a, b"), undefined)).toEqual(["a", "b"]); expect(_resolveProtocols(peerWith("a, b"), true)).toEqual(["a", "b"]); expect(_resolveProtocols(peerWith(), true)).toBeUndefined(); // boolean false: offer nothing expect(_resolveProtocols(peerWith("a, b"), false)).toBeUndefined(); // function: string, array, undefined expect(_resolveProtocols(peerWith("a"), () => "x")).toEqual(["x"]); expect(_resolveProtocols(peerWith("a"), () => ["x", " y "])).toEqual(["x", "y"]); expect(_resolveProtocols(peerWith("a"), () => undefined)).toBeUndefined(); expect(_resolveProtocols(peerWith("a"), () => [])).toBeUndefined(); expect(_resolveProtocols(peerWith("a"), () => ["", " "])).toBeUndefined(); // function: re-label client token for the upstream const stripPrefix = (peer: { request: Request }) => (peer.request.headers.get("sec-websocket-protocol") ?? "") .split(",") .map((p) => p.trim()) .filter(Boolean) .map((p) => (p.startsWith("x-test-") ? p.slice("x-test-".length) : p)); expect(_resolveProtocols(peerWith("x-test-vite-hmr"), stripPrefix as never)).toEqual([ "vite-hmr", ]); // static string / string[]: offer a fixed value regardless of the client expect(_resolveProtocols(peerWith("x-test-vite-hmr"), "vite-hmr")).toEqual(["vite-hmr"]); expect(_resolveProtocols(peerWith(), "vite-hmr")).toEqual(["vite-hmr"]); expect(_resolveProtocols(peerWith("a"), [" v1 ", "v2", ""])).toEqual(["v1", "v2"]); expect(_resolveProtocols(peerWith("a"), " ")).toBeUndefined(); // rewrite map: swap mapped tokens, pass the rest through verbatim expect( _resolveProtocols(peerWith("pspace-proxied-vite-hmr, chat"), { "pspace-proxied-vite-hmr": "vite-hmr", }), ).toEqual(["vite-hmr", "chat"]); // map with no matching client tokens forwards them unchanged expect(_resolveProtocols(peerWith("chat"), { other: "x" })).toEqual(["chat"]); // map ignores inherited keys (no client header → nothing to offer) expect(_resolveProtocols(peerWith(), { a: "b" })).toBeUndefined(); expect(_resolveProtocols(peerWith("toString"), {})).toEqual(["toString"]); // de-dupe: a rewrite map collapsing several tokens onto one value, or a // client offering duplicates, must not produce repeats (the WHATWG // WebSocket constructor rejects a protocols list with duplicates). expect(_resolveProtocols(peerWith("proxied-hmr, hmr"), { "proxied-hmr": "hmr" })).toEqual([ "hmr", ]); expect(_resolveProtocols(peerWith("a, a, b"), true)).toEqual(["a", "b"]); expect(_resolveProtocols(peerWith("a"), () => ["x", "x"])).toEqual(["x"]); // nullish entries inside a returned/mapped list are dropped, not coerced // to the literal strings "null"/"undefined". expect(_resolveProtocols(peerWith("a"), () => ["vite-hmr", null as never])).toEqual([ "vite-hmr", ]); expect(_resolveProtocols(peerWith("a, b"), { a: undefined as never })).toEqual(["b"]); }); test("forwardProtocol resolver feeds the upstream constructor's protocols argument", () => { const calls: Array<{ protocols: unknown }> = []; class StubWS extends EventTarget { binaryType = "arraybuffer"; readyState = 0; constructor(_url: unknown, protocols?: unknown) { super(); calls.push({ protocols }); } send(): void {} close(): void {} } const hooks = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, forwardProtocol: (peer) => (peer.request?.headers.get("sec-websocket-protocol") ?? "") .split(",") .map((p) => p.trim()) .filter(Boolean) .map((p) => (p.startsWith("x-test-") ? p.slice("x-test-".length) : p)), }); const peer = { id: "p-proto", request: new Request("http://localhost/", { headers: { "sec-websocket-protocol": "x-test-vite-hmr" }, }), close() {}, send() {}, }; hooks.open?.(peer as never); expect(calls).toHaveLength(1); expect(calls[0]!.protocols).toEqual(["vite-hmr"]); // The client-facing echo stays the client-offered token, not the resolved one. expect(hooks.upgrade?.(peer.request)).toMatchObject({ headers: { "sec-websocket-protocol": "x-test-vite-hmr" }, }); }); }); // The proxy terminates the WebSocket, so `permessage-deflate` is negotiated per // leg: `perMessageDeflate` enables it towards the client only. describe("createWebSocketProxy (perMessageDeflate)", () => { const big = "x".repeat(64 * 1024); let upstreamServer: Server; let proxyServer: Server; let proxyURL: string; let adapters: { close: () => Promise }[]; let upstreamOffer: string | null | undefined; beforeAll(async () => { const upstream = nodeAdapter({ hooks: defineHooks({ upgrade(req) { upstreamOffer = req.headers.get("sec-websocket-extensions"); }, message(peer, message) { peer.send(message.text() === "big" ? big : `echo:${message.text()}`); }, }), }); upstreamServer = createServer((_req, res) => res.end("ok")); upstreamServer.on("upgrade", upstream.handleUpgrade); const upstreamPort = await getRandomPort("localhost"); await new Promise((resolve) => upstreamServer.listen(upstreamPort, resolve)); const proxy = nodeAdapter({ hooks: createWebSocketProxy({ target: `ws://localhost:${upstreamPort}/`, perMessageDeflate: { zlibDeflateOptions: { level: 3 } }, webSocketOptions: { perMessageDeflate: false }, }), }); adapters = [upstream, proxy]; proxyServer = createServer((_req, res) => res.end("ok")); proxyServer.on("upgrade", proxy.handleUpgrade); const proxyPort = await getRandomPort("localhost"); proxyURL = `ws://localhost:${proxyPort}/`; await new Promise((resolve) => proxyServer.listen(proxyPort, resolve)); await waitForPort(proxyPort); }); afterAll(async () => { await Promise.all(adapters.map((adapter) => adapter.close())); upstreamServer.close(); proxyServer.close(); }); test("compresses the client leg only", async () => { const client = new WsWebSocket(proxyURL); await new Promise((resolve) => client.on("open", resolve)); expect(client.extensions).toContain("permessage-deflate"); const echo = new Promise((resolve) => client.once("message", (d) => resolve(`${d}`))); client.send("hi"); expect(await echo).toBe("echo:hi"); // The upstream leg is dialed without offering the extension. expect(upstreamOffer).toBeNull(); const socket = (client as unknown as { _socket: { bytesRead: number } })._socket; const before = socket.bytesRead; const reply = new Promise((resolve) => client.once("message", (d) => resolve(`${d}`))); client.send("big"); expect(await reply).toBe(big); expect(socket.bytesRead - before).toBeLessThan(1024); client.close(); }); }); describe("createWebSocketProxy (lifecycle callbacks)", () => { type Event = | { type: "connect" | "open"; url: string } | ({ type: "close"; url: string } & Omit); let upstreamServer: Server; let upstreamURL: string; const servers: Server[] = []; beforeAll(async () => { const upstream = nodeAdapter({ hooks: defineHooks({ async upgrade(req) { if (new URL(req.url).pathname === "/slow") { await new Promise((r) => setTimeout(r, 100)); } }, message(peer, message) { const text = message.text(); if (text.startsWith("close:")) { const [, code, reason] = text.split(":"); peer.close(Number(code), reason); return; } peer.send(`echo:${text}`); }, }), }); upstreamServer = createServer((_req, res) => res.end("ok")); upstreamServer.on("upgrade", upstream.handleUpgrade); const port = await getRandomPort("localhost"); upstreamURL = `ws://localhost:${port}/`; await new Promise((resolve) => upstreamServer.listen(port, resolve)); await waitForPort(port); }); afterAll(() => { for (const server of [...servers, upstreamServer]) { server.closeAllConnections?.(); server.close(); } }); // Start a proxy that records every lifecycle callback. `closed` resolves a // beat after the first `onUpstreamClose`, so asserting the full event list // also proves no duplicate report follows. async function startProxy(options: Omit) { const events: Event[] = []; let onClosed: () => void; const closed = new Promise((resolve) => (onClosed = resolve)); const proxy = nodeAdapter({ hooks: createWebSocketProxy({ ...options, onUpstreamConnect: (_peer, { url }) => events.push({ type: "connect", url: url.href }), onUpstreamOpen: (_peer, { url }) => events.push({ type: "open", url: url.href }), onUpstreamClose: (_peer, { url, ...details }) => { events.push({ type: "close", url: url.href, ...details }); onClosed(); }, }), }); const server = createServer((_req, res) => res.end("ok")); servers.push(server); server.on("upgrade", proxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); return { url: `ws://localhost:${port}/`, events, closed: closed.then(settle) }; } const settle = () => new Promise((r) => setTimeout(r, 50)); function waitClientClose(ws: WebSocket) { return new Promise((resolve) => { ws.addEventListener("close", (e) => resolve(e as CloseEvent)); }); } test("reports connect, open and a client-initiated close", async () => { const proxy = await startProxy({ target: async () => upstreamURL }); const ws = await wsConnect(proxy.url); await ws.send("hi"); expect(await ws.next()).toBe("echo:hi"); ws.ws.close(4000, "bye"); await proxy.closed; expect(proxy.events).toEqual([ { type: "connect", url: upstreamURL }, { type: "open", url: upstreamURL }, { type: "close", url: upstreamURL, source: "client", code: 4000, reason: "bye" }, ]); }); test("reports an upstream-initiated close", async () => { const proxy = await startProxy({ target: upstreamURL }); const ws = await wsConnect(proxy.url); const clientClose = waitClientClose(ws.ws); await ws.send("close:4001:done"); await proxy.closed; expect((await clientClose).code).toBe(4001); expect(proxy.events).toEqual([ { type: "connect", url: upstreamURL }, { type: "open", url: upstreamURL }, { type: "close", url: upstreamURL, source: "upstream", code: 4001, reason: "done" }, ]); }); test("settles a connect timeout without an open", async () => { const proxy = await startProxy({ target: `${upstreamURL}slow`, connectTimeout: 25 }); const ws = await wsConnect(proxy.url); expect((await waitClientClose(ws.ws)).code).toBe(1011); await proxy.closed; expect(proxy.events).toEqual([ { type: "connect", url: `${upstreamURL}slow` }, { type: "close", url: `${upstreamURL}slow`, source: "proxy", code: 1011, reason: "Upstream connect timeout", }, ]); }); test("settles an upstream that cannot be reached", async () => { const deadURL = `ws://localhost:${await getRandomPort("localhost")}/`; const proxy = await startProxy({ target: deadURL }); const ws = await wsConnect(proxy.url); expect((await waitClientClose(ws.ws)).code).toBe(1011); await proxy.closed; expect(proxy.events).toHaveLength(2); expect(proxy.events[1]).toMatchObject({ type: "close", url: deadURL, source: "upstream" }); // The underlying error, not the `error` event, and no made-up close code. expect(proxy.events[1]).toHaveProperty("error", expect.any(Error)); expect(proxy.events[1]).not.toHaveProperty("code"); }); test("settles with the error when onUpstreamConnect throws", async () => { const thrown = new Error("rejected by accounting"); const closes: WebSocketProxyCloseDetails[] = []; const proxy = nodeAdapter({ hooks: createWebSocketProxy({ target: upstreamURL, onUpstreamConnect: () => { throw thrown; }, onUpstreamClose: (_peer, details) => closes.push(details), }), }); const server = createServer((_req, res) => res.end("ok")); servers.push(server); server.on("upgrade", proxy.handleUpgrade); const port = await getRandomPort("localhost"); await new Promise((resolve) => server.listen(port, resolve)); await waitForPort(port); const ws = await wsConnect(`ws://localhost:${port}/`); expect((await waitClientClose(ws.ws)).code).toBe(1011); expect(closes).toEqual([ { url: new URL(upstreamURL), source: "proxy", code: 1011, reason: "Upstream setup failed", error: thrown, }, ]); }); test("skips peers whose target never resolved", async () => { let resolveTarget!: (url: string) => void; const target = new Promise((resolve) => (resolveTarget = resolve)); const proxy = await startProxy({ target: () => target }); const ws = await wsConnect(proxy.url); const clientClose = waitClientClose(ws.ws); ws.ws.close(1000); await clientClose; // Let the proxy's `close` hook run: resolving after the peer is gone must // not dial (or report) anything. await settle(); resolveTarget(upstreamURL); await settle(); const rejecting = await startProxy({ target: async () => { throw new Error("no worker"); }, }); const ws2 = await wsConnect(rejecting.url); expect((await waitClientClose(ws2.ws)).code).toBe(1011); // Connect timeout while the resolver is still pending. const pending = await startProxy({ target: () => new Promise(() => {}), connectTimeout: 25 }); const ws3 = await wsConnect(pending.url); expect((await waitClientClose(ws3.ws)).code).toBe(1011); await settle(); expect(proxy.events).toEqual([]); expect(rejecting.events).toEqual([]); expect(pending.events).toEqual([]); }); test("settles a client idle timeout", async () => { const proxy = await startProxy({ target: upstreamURL, clientIdleTimeout: 50 }); const ws = await wsConnect(proxy.url); expect((await waitClientClose(ws.ws)).code).toBe(1001); await proxy.closed; expect(proxy.events).toEqual([ { type: "connect", url: upstreamURL }, { type: "open", url: upstreamURL }, { type: "close", url: upstreamURL, source: "proxy", code: 1001, reason: "Client idle timeout", }, ]); }); test("settles a buffer limit overflow", async () => { const proxy = await startProxy({ target: `${upstreamURL}slow`, maxBufferSize: 5 }); const ws = await wsConnect(proxy.url); const clientClose = waitClientClose(ws.ws); await ws.send("this is more than five bytes"); expect((await clientClose).code).toBe(1009); await proxy.closed; expect(proxy.events).toEqual([ { type: "connect", url: `${upstreamURL}slow` }, { type: "close", url: `${upstreamURL}slow`, source: "proxy", code: 1009, reason: "Proxy buffer limit exceeded", }, ]); }); }); describe("createWebSocketProxy (lifecycle callbacks, unit)", () => { const instances: StubWS[] = []; class StubWS extends EventTarget { binaryType = "arraybuffer"; readyState = 0; constructor(public url: URL) { super(); instances.push(this); } send(): void {} close(): void {} } function stubPeer(id: string, onClose?: () => void) { return { id, request: new Request("http://localhost/"), close: onClose ?? (() => {}), send() {}, }; } test("doesn't dial when onUpstreamConnect closes the peer", () => { instances.length = 0; const closes: WebSocketProxyCloseDetails[] = []; // Adapters such as uWS run the `close` hook synchronously from `peer.close()`. const peer = stubPeer("p-reenter", () => hooks.close?.(peer as never, { code: 1013, reason: "busy" }), ); const hooks = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, onUpstreamConnect: (p) => p.close(1013, "busy"), onUpstreamClose: (_p, details) => closes.push(details), }); hooks.open?.(peer as never); expect(instances).toHaveLength(0); expect(closes).toEqual([ { url: new URL("ws://upstream.invalid/"), source: "client", code: 1013, reason: "busy" }, ]); }); test("doesn't dial when onUpstreamConnect closes the peer (async close hook)", () => { instances.length = 0; const closes: WebSocketProxyCloseDetails[] = []; // Most adapters only mark the socket CLOSING and run the `close` hook later. const websocket = { readyState: 1 }; const peer = { ...stubPeer("p-closing", () => (websocket.readyState = 2)), websocket }; const hooks = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, onUpstreamConnect: (p) => p.close(1013, "busy"), onUpstreamClose: (_p, details) => closes.push(details), }); hooks.open?.(peer as never); expect(instances).toHaveLength(0); expect(closes).toEqual([]); // The adapter's deferred `close` hook still settles the peer exactly once. hooks.close?.(peer as never, { code: 1013, reason: "busy" }); hooks.close?.(peer as never, { code: 1013, reason: "busy" }); expect(closes).toEqual([ { url: new URL("ws://upstream.invalid/"), source: "client", code: 1013, reason: "busy" }, ]); }); test("logs errors thrown by onUpstreamOpen and onUpstreamClose", () => { instances.length = 0; const logged = vi.spyOn(console, "error").mockImplementation(() => {}); try { const hooks = createWebSocketProxy({ target: "ws://upstream.invalid/", WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, onUpstreamOpen: () => { throw new Error("open failed"); }, onUpstreamClose: () => { throw new Error("close failed"); }, }); hooks.open?.(stubPeer("p-throws") as never); instances[0]!.dispatchEvent(new Event("open")); instances[0]!.dispatchEvent(Object.assign(new Event("close"), { code: 1000, reason: "" })); expect(logged.mock.calls.map((args) => (args[1] as Error).message)).toEqual([ "open failed", "close failed", ]); } finally { logged.mockRestore(); } }); test("gives each peer its own copy of a static URL target", () => { instances.length = 0; const target = new URL("ws://upstream.invalid/"); const seen: URL[] = []; const hooks = createWebSocketProxy({ target, WebSocket: StubWS as unknown as typeof WebSocket, connectTimeout: 0, onUpstreamConnect: (_p, { url }) => { seen.push(url); url.searchParams.set("mutated", "1"); }, }); hooks.open?.(stubPeer("p-url-1") as never); hooks.open?.(stubPeer("p-url-2") as never); expect(seen[0]).not.toBe(seen[1]); expect(target.href).toBe("ws://upstream.invalid/"); expect(instances[1]!.url.href).toBe("ws://upstream.invalid/?mutated=1"); }); });