ws: WebSocketServer({ server }) never upgrades — handshake answered by the HTTP handler with 200 OK

[proggeramlug]

Summary

new WebSocketServer({ server }) — ws attached to an existing http.Server for upgrade handling — never completes a handshake. The upgrade request is answered by the server's ordinary request handler with a normal HTTP response, so every client fails with:

WebSocket connect error: HTTP error: 200 OK

A standalone new WebSocketServer({ port }) works correctly, so this is specific to the attached form: the upgrade event never reaches ws, and the handshake is served as though it were a plain GET.

Perry 0.5.1520 (7b1907703), ws@8.21.3, Linux x86_64.

Reproduction

import { createServer } from "node:http";
import { WebSocketServer, WebSocket } from "ws";

const port = 45701;
const server = createServer((_req, res) => { res.end("http-ok"); });
const wss = new WebSocketServer({ server });          // attached, not standalone
await new Promise<void>((r) => server.listen(port, () => r()));

console.log("http:", await (await fetch(`http://127.0.0.1:${port}/`)).text());   // "http-ok" both runtimes

let opened = 0, errored = 0;
await Promise.all(Array.from({ length: 120 }, () => new Promise<void>((resolve) => {
  const c = new WebSocket(`ws://127.0.0.1:${port}/`);
  c.on("open",  () => { opened++;  resolve(); });
  c.on("error", () => { errored++; resolve(); });
  setTimeout(() => resolve(), 15000);
})));
console.log({ opened, errored, size: wss.clients.size });

	node 26.8.1	perry 0.5.1520
plain HTTP on the same server	http-ok	http-ok
clients opened	120	0
clients errored	0	120
wss.clients.size	120	0

The error text is the tell: the client receives 200 OK, which is the request handler's response. The upgrade never routed.

Replacing { server } with { port } and dropping the HTTP server makes all 120 clients connect under Perry, which isolates it to the attachment.

Two smaller findings alongside it

Both from the same investigation, both on a standalone WebSocketServer:

1. port: 0 never fires listening. With an ephemeral port the event does not arrive and the program hangs on the await. An explicit port works.
2. wss.address() returns undefined where Node returns { address, family, port }. This compounds the first: the usual way to learn an ephemeral port is unavailable too.

Happy to split those into their own issues if you would rather.

Impact

Attaching ws to an existing HTTP server is the normal deployment shape — one port, one process, HTTP and WebSocket side by side — and it is what every Node WebSocket guide shows. For us it is the live-auction fanout: bids broadcast to every connected dealer over a socket on the same server as the REST API. Under Perry that server accepts the TCP connection, answers 200, and no socket is ever established.

It also fails quietly from the server's perspective: the HTTP side is healthy, the process is fine, and only the client knows the handshake was refused.

Happy to test a patch; the repro runs in a couple of seconds.

[proggeramlug]

The noServer form fails too, and more quietly

I filed this against WebSocketServer({ server }). The other common shape — { noServer: true } with a manual server.on("upgrade") calling wss.handleUpgrade() — is also broken, and its failure is harder to notice.

const server = createServer((_req, res) => { res.end("http-ok"); });
const wss = new WebSocketServer({ noServer: true });

server.on("upgrade", (req, socket, head) => {
  if ((req.url ?? "").split("?")[0] !== "/v1/ws") return;
  wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
});
wss.on("connection", (ws) => { connections++; ws.send("hello"); });

60 clients:

	node 26.8.1	perry 0.5.1520
client open fired	60	60
client received a message	60	0
client error fired	0	0
server-side connection events	60	0

The client reports the socket as open, no error is ever raised, and the server never sees a connection. So unlike the { server } case — which at least fails loudly with HTTP error: 200 OK — this one leaves both ends believing something happened. A client sits waiting for data that will never arrive; the server has nothing to send it to.

Either server.on("upgrade") is not firing, or handleUpgrade's callback is not running. Plain HTTP on the same server is unaffected (http-ok in both runtimes), so the listener and the request path are fine.

Worth folding into this issue rather than a separate one, I think — same feature, and I would expect one fix to cover both. Say the word if you would rather have them split.

This is the shape most real applications use, because it is how you route upgrades by path and authenticate the handshake before accepting it. It is what ours does.

[proggeramlug]

Fixed by #9763, which landed on main via merge train #9798. The train was merged as its own branch, so the Fixes #9619 keyword in #9763 never fired — closing manually. Verified the fix is on main by patch-id (git cherry), not just by the PR being closed.