The best way to control Claude Code, Codex and more from any computer or phone

main
ts 477 lines 15.6 KB
Raw
1 import * as NodeHttp from "node:http";
2 import type { AddressInfo } from "node:net";
3 import * as NodeNet from "node:net";
4 import { Readable } from "node:stream";
5 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
6 import { WebSocket, WebSocketServer } from "ws";
7 import { handleWebSocket } from "../websockets.ts";
8
9 const DEBUG = !!process.env.WS_PROXY_DEBUG;
10 const dbg = (...args: Array<unknown>) => {
11 if (DEBUG) {
12 console.error(`[ws-dbg ${Date.now() % 100000}]`, ...args);
13 }
14 };
15
16 interface UpstreamCall {
17 url: string;
18 method: string | undefined;
19 headers: NodeHttp.IncomingHttpHeaders;
20 }
21
22 interface Harness {
23 clientServer: NodeHttp.Server;
24 clientPort: number;
25 upstreamServer: NodeHttp.Server;
26 upstreamWss: WebSocketServer;
27 upstreamPort: number;
28 upstreamCalls: Array<UpstreamCall>;
29 upstreamConnections: Array<WebSocket>;
30 cleanup: () => void;
31 }
32
33 const listen = (server: NodeHttp.Server) =>
34 new Promise<number>((resolve) => {
35 server.listen(0, "127.0.0.1", () => {
36 resolve((server.address() as AddressInfo).port);
37 });
38 });
39
40 const close = (server: NodeHttp.Server) =>
41 new Promise<void>((resolve, reject) => {
42 server.close((err) => (err ? reject(err) : resolve()));
43 server.closeAllConnections();
44 });
45
46 const setup = async (): Promise<Harness> => {
47 const upstreamCalls: Array<UpstreamCall> = [];
48 const upstreamConnections: Array<WebSocket> = [];
49
50 const upstreamServer = NodeHttp.createServer((_req, res) => {
51 res.statusCode = 200;
52 res.end("upstream-http");
53 });
54 const upstreamWss = new WebSocketServer({ noServer: true });
55 upstreamServer.on("upgrade", (req, socket, head) => {
56 dbg("upstream received upgrade", req.method, req.url);
57 upstreamCalls.push({
58 url: req.url ?? "",
59 method: req.method,
60 headers: { ...req.headers },
61 });
62 upstreamWss.handleUpgrade(req, socket, head, (ws) => {
63 dbg("upstream handshake completed, emitting connection");
64 upstreamConnections.push(ws);
65 upstreamWss.emit("connection", ws, req);
66 });
67 });
68
69 const clientServer = NodeHttp.createServer((_req, res) => res.end("OK"));
70 const upstreamPort = await listen(upstreamServer);
71 const removeListener = handleWebSocket(
72 clientServer,
73 `http://127.0.0.1:${upstreamPort}`,
74 "websocket-secret",
75 );
76 const clientPort = await listen(clientServer);
77
78 return {
79 clientServer,
80 clientPort,
81 upstreamServer,
82 upstreamWss,
83 upstreamPort,
84 upstreamCalls,
85 upstreamConnections,
86 cleanup: () => {
87 removeListener();
88 for (const client of upstreamWss.clients) {
89 client.terminate();
90 }
91 upstreamWss.close();
92 },
93 };
94 };
95
96 const makeFakeRequest = (overrides: {
97 host: string;
98 url?: string;
99 protocol?: string;
100 }): NodeHttp.IncomingMessage => {
101 const readable = Readable.from([]);
102 return Object.assign(readable, {
103 url: overrides.url ?? "/",
104 method: "GET",
105 socket: {},
106 headers: {
107 host: overrides.host,
108 upgrade: "websocket",
109 connection: "Upgrade",
110 "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==",
111 "sec-websocket-version": "13",
112 ...(overrides.protocol ? { "sec-websocket-protocol": overrides.protocol } : {}),
113 },
114 }) as unknown as NodeHttp.IncomingMessage;
115 };
116
117 const teardown = async (harness: Harness) => {
118 harness.cleanup();
119 for (const ws of harness.upstreamConnections) {
120 ws.terminate();
121 }
122 harness.clientServer.closeAllConnections();
123 harness.upstreamServer.closeAllConnections();
124 await close(harness.clientServer);
125 await close(harness.upstreamServer);
126 };
127
128 describe("handleWebSocket", () => {
129 let harness: Harness;
130
131 beforeEach(async () => {
132 harness = await setup();
133 });
134
135 afterEach(async () => {
136 await teardown(harness);
137 });
138
139 test("proxies messages bidirectionally", async () => {
140 harness.upstreamWss.on("connection", (ws) => {
141 ws.on("message", (data) => {
142 ws.send(`echo:${data.toString()}`);
143 });
144 ws.send("hello");
145 });
146
147 const client = new WebSocket(`ws://127.0.0.1:${harness.clientPort}/path?x=1`);
148 const received: Array<string> = [];
149 client.on("upgrade", (res) => dbg("client received upgrade response", res.statusCode));
150 client.on("unexpected-response", (_req, res) =>
151 dbg("client unexpected-response", res.statusCode),
152 );
153 client.on("close", (code, reason) => dbg("client close", code, reason.toString()));
154 await new Promise<void>((resolve, reject) => {
155 client.on("open", () => {
156 dbg("client open, sending ping");
157 client.send("ping");
158 });
159 client.on("message", (data) => {
160 dbg("client message", data.toString());
161 received.push(data.toString());
162 if (received.length === 2) {
163 client.close();
164 resolve();
165 }
166 });
167 client.on("error", (err) => {
168 dbg("client error", err.message);
169 reject(err);
170 });
171 });
172
173 expect(received).toEqual(["hello", "echo:ping"]);
174 expect(harness.upstreamCalls).toHaveLength(1);
175 const call = harness.upstreamCalls[0]!;
176 expect(call.url).toBe("/path?x=1");
177 expect(call.method).toBe("GET");
178 expect(call.headers.host).toBe(`127.0.0.1:${harness.clientPort}`);
179 expect(call.headers.upgrade).toBe("websocket");
180 });
181
182 test("ignores vite HMR upgrades", async () => {
183 // Emit a synthetic upgrade event directly to avoid leaving an orphaned
184 // upgraded socket on the test HTTP server.
185 const fakeReq = makeFakeRequest({
186 host: `127.0.0.1:${harness.clientPort}`,
187 protocol: "vite-hmr",
188 });
189 const fakeSocket = new NodeNet.Socket();
190 const destroySpy = vi.spyOn(fakeSocket, "destroy");
191 const writeSpy = vi.spyOn(fakeSocket, "write");
192
193 harness.clientServer.emit("upgrade", fakeReq, fakeSocket, Buffer.alloc(0));
194
195 await new Promise((r) => setTimeout(r, 50));
196
197 expect(harness.upstreamCalls).toHaveLength(0);
198 expect(destroySpy).not.toHaveBeenCalled();
199 expect(writeSpy).not.toHaveBeenCalled();
200 });
201
202 test("forwards sandbox-preview-URL upgrades even with vite protocol", async () => {
203 harness.upstreamWss.on("connection", (ws) => {
204 ws.send("ack");
205 });
206
207 const sandboxHost = `4567-my-sandbox-sup3rs3cr3t.localhost:${harness.clientPort}`;
208 const client = new WebSocket(`ws://127.0.0.1:${harness.clientPort}/`, "vite-hmr", {
209 headers: { host: sandboxHost },
210 });
211 client.on("open", () => dbg("sandbox client open"));
212 client.on("upgrade", (res) => dbg("sandbox client received upgrade response", res.statusCode));
213 client.on("unexpected-response", (_req, res) =>
214 dbg("sandbox client unexpected-response", res.statusCode),
215 );
216 client.on("close", (code, reason) => dbg("sandbox client close", code, reason.toString()));
217 const message = await new Promise<string>((resolve, reject) => {
218 client.on("message", (data) => {
219 dbg("sandbox client message", data.toString());
220 resolve(data.toString());
221 client.close();
222 });
223 client.on("error", (err) => {
224 dbg("sandbox client error", err.message);
225 reject(err);
226 });
227 });
228
229 expect(message).toBe("ack");
230 expect(harness.upstreamCalls).toHaveLength(1);
231 expect(harness.upstreamCalls[0]!.headers.host).toBe(sandboxHost);
232 expect(harness.upstreamCalls[0]!.headers["sec-websocket-protocol"]).toBe("vite-hmr");
233 });
234
235 test("prefers X-Forwarded-Host over Host when set by a tunnel", async () => {
236 harness.upstreamWss.on("connection", (ws) => {
237 ws.send("ack");
238 });
239
240 const client = new WebSocket(`ws://127.0.0.1:${harness.clientPort}/`, {
241 headers: { "x-forwarded-host": "example.ngrok.app" },
242 });
243 const message = await new Promise<string>((resolve, reject) => {
244 client.on("message", (data) => {
245 resolve(data.toString());
246 client.close();
247 });
248 client.on("error", reject);
249 });
250
251 expect(message).toBe("ack");
252 expect(harness.upstreamCalls).toHaveLength(1);
253 expect(harness.upstreamCalls[0]!.headers.host).toBe("example.ngrok.app");
254 });
255
256 // https://github.com/cloudflare/workers-sdk/issues/12047
257 test("survives client disconnect during upgrade", async () => {
258 // Upstream upgrade handler that never responds — the proxy is stuck waiting
259 // when the client resets the connection.
260 harness.upstreamServer.removeAllListeners("upgrade");
261 harness.upstreamServer.on("upgrade", () => {});
262
263 const fakeReq = makeFakeRequest({ host: "localhost" });
264 const fakeSocket = new NodeNet.Socket();
265 harness.clientServer.emit("upgrade", fakeReq, fakeSocket, Buffer.alloc(0));
266
267 fakeSocket.destroy(new Error("ECONNRESET"));
268
269 // The proxy and Vite server should still be responsive.
270 const response = await fetch(`http://127.0.0.1:${harness.clientPort}/`);
271 expect(response.ok).toBe(true);
272 });
273
274 test("relays the worker's response and closes when it refuses the upgrade", async () => {
275 // The worker rejects the handshake with a plain HTTP response instead of
276 // upgrading — the client must see that response, not a connection reset,
277 // and the socket closes once it is relayed (the promise resolves on close).
278 harness.upstreamServer.removeAllListeners("upgrade");
279 harness.upstreamServer.on("upgrade", (_request, socket) => {
280 socket.end(
281 [
282 "HTTP/1.1 403 Forbidden",
283 "content-type: text/plain",
284 "content-length: 9",
285 "connection: close",
286 "",
287 "Forbidden",
288 ].join("\r\n"),
289 );
290 });
291
292 const received = await new Promise<string>((resolve, reject) => {
293 const socket = NodeNet.connect(harness.clientPort, "127.0.0.1", () => {
294 socket.write(
295 [
296 "GET /ws HTTP/1.1",
297 `Host: 127.0.0.1:${harness.clientPort}`,
298 "Connection: Upgrade",
299 "Upgrade: websocket",
300 "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==",
301 "Sec-WebSocket-Version: 13",
302 "",
303 "",
304 ].join("\r\n"),
305 );
306 });
307 let buffer = "";
308 socket.setEncoding("utf8");
309 socket.on("data", (chunk) => {
310 buffer += chunk;
311 });
312 socket.on("close", () => resolve(buffer));
313 socket.on("error", reject);
314 });
315
316 expect(received).toContain("HTTP/1.1 403 Forbidden");
317 expect(received).toContain("content-type: text/plain");
318 expect(received.endsWith("Forbidden")).toBe(true);
319 });
320
321 test("forwards an upgrade an async listener declines", async () => {
322 harness.upstreamWss.on("connection", (ws) => ws.send("ack"));
323 // Like Vite's `server.proxy`, which awaits a `bypass` before it decides.
324 harness.clientServer.on("upgrade", async () => {
325 await new Promise((resolve) => setTimeout(resolve, 200));
326 });
327
328 const client = new WebSocket(`ws://127.0.0.1:${harness.clientPort}/ws`);
329 const message = await new Promise<string>((resolve, reject) => {
330 client.on("message", (data) => {
331 resolve(data.toString());
332 client.close();
333 });
334 client.on("error", reject);
335 });
336 expect(message).toBe("ack");
337 });
338
339 test("forwards an upgrade another listener only guards with a no-op error handler", async () => {
340 harness.upstreamWss.on("connection", (ws) => ws.send("ack"));
341 // Vite 8.3.5's HMR listener does this for every upgrade it doesn't handle.
342 harness.clientServer.on("upgrade", (_request, socket) => {
343 socket.on("error", function noop() {});
344 socket.on("error", () => {});
345 });
346
347 const client = new WebSocket(`ws://127.0.0.1:${harness.clientPort}/ws`);
348 const message = await new Promise<string>((resolve, reject) => {
349 client.on("message", (data) => {
350 resolve(data.toString());
351 client.close();
352 });
353 client.on("error", reject);
354 });
355 expect(message).toBe("ack");
356 });
357
358 // https://github.com/alchemy-run/alchemy/issues/2191
359 describe("leaves an upgrade another plugin accepts to that plugin", () => {
360 const refuseUpgrades = () => {
361 // workerd answers an upgrade on a path the Worker doesn't route with
362 // plain HTTP.
363 harness.upstreamServer.removeAllListeners("upgrade");
364 harness.upstreamServer.on("upgrade", (_request, socket) => {
365 socket.end(
366 [
367 "HTTP/1.1 404 Not Found",
368 "content-length: 9",
369 "connection: close",
370 "",
371 "Not Found",
372 ].join("\r\n"),
373 );
374 });
375 };
376
377 // A plugin's own dev WebSocket, like `@foldkit/vite-plugin`'s relay.
378 const echoPlugin = (
379 server: NodeHttp.Server,
380 options: { verifyDelay?: number; listenerDelay?: number } = {},
381 ) => {
382 const wss = new WebSocketServer({
383 noServer: true,
384 ...(options.verifyDelay !== undefined
385 ? {
386 verifyClient: (_info: unknown, done: (result: boolean) => void) =>
387 setTimeout(() => done(true), options.verifyDelay),
388 }
389 : {}),
390 });
391 server.on("upgrade", async (request, socket, head) => {
392 if (request.url !== "/__echo") return;
393 if (options.listenerDelay !== undefined) {
394 await new Promise((resolve) => setTimeout(resolve, options.listenerDelay));
395 }
396 wss.handleUpgrade(request, socket, head, (ws) => {
397 ws.on("message", (data) => ws.send(`echo ${data}`));
398 });
399 });
400 return wss;
401 };
402
403 const echo = (port: number) =>
404 new Promise<Array<string>>((resolve, reject) => {
405 const client = new WebSocket(`ws://127.0.0.1:${port}/__echo`);
406 const events: Array<string> = [];
407 client.on("open", () => {
408 events.push("open");
409 client.send("hi");
410 });
411 client.on("message", (data) => {
412 events.push(data.toString());
413 // Stay open long enough for a late close to show up.
414 setTimeout(() => {
415 resolve([...events]);
416 client.close();
417 }, 200);
418 });
419 client.on("close", (code) => {
420 events.push(`close ${code}`);
421 resolve(events);
422 });
423 client.on("error", reject);
424 });
425
426 test("a plugin registered after the proxy", async () => {
427 refuseUpgrades();
428 const wss = echoPlugin(harness.clientServer);
429 expect(await echo(harness.clientPort)).toEqual(["open", "echo hi"]);
430 wss.close();
431 });
432
433 test("a plugin registered before the proxy", async () => {
434 refuseUpgrades();
435 const server = NodeHttp.createServer();
436 const wss = echoPlugin(server);
437 const remove = handleWebSocket(
438 server,
439 `http://127.0.0.1:${harness.upstreamPort}`,
440 "websocket-secret",
441 );
442 const port = await listen(server);
443 expect(await echo(port)).toEqual(["open", "echo hi"]);
444 remove();
445 wss.close();
446 await close(server);
447 });
448
449 test("a plugin that accepts after the Worker has answered", async () => {
450 refuseUpgrades();
451 const wss = echoPlugin(harness.clientServer, { verifyDelay: 200 });
452 expect(await echo(harness.clientPort)).toEqual(["open", "echo hi"]);
453 wss.close();
454 });
455
456 test("a plugin that awaits before it touches the socket", async () => {
457 refuseUpgrades();
458 const wss = echoPlugin(harness.clientServer, { listenerDelay: 200 });
459 expect(await echo(harness.clientPort)).toEqual(["open", "echo hi"]);
460 wss.close();
461 });
462 });
463
464 test("returns a cleanup function that removes the upgrade listener", async () => {
465 const server = NodeHttp.createServer();
466 await listen(server);
467 const remove = handleWebSocket(
468 server,
469 `http://127.0.0.1:${harness.upstreamPort}`,
470 "websocket-secret",
471 );
472 expect(server.listenerCount("upgrade")).toBe(1);
473 remove();
474 expect(server.listenerCount("upgrade")).toBe(0);
475 await close(server);
476 });
477 });