A closed client is forgotten, a bad frame is refused with a code, and a wrong message is answered (#1313) #1314

Merged
jaylouisw merged 1 commit from fix/websocket-surface into main 2026-11-10 01:44:24 +00:00
Owner

A closed client is forgotten, a bad frame is refused with a code, and a wrong message is answered.

Fixes #1313.

The only thing any test asserted about server/ws.js was that a broadcast carries verdicts (#1306). Nobody had
ever sent it a frame it did not expect. Four things came out — and the first is why the obvious fix would not have
worked.

1. clients only ever grew — and close is never the moment

Every browser tab that had ever connected stayed in the set: broadcast() wrote to dead sockets for the life of the
process and count never came down.

The trap: deleting on socket.on('close') does not fix it. An upgraded socket has allowHalfOpen = true, so
when the peer goes away it emits end and stops there — close never fires. Measured:

server socket: allowHalfOpen = true
destroying client; count = 1
  server socket event: end
after destroy: count = 1

2. An unmasked client frame was accepted

RFC 6455 §5.1 makes masking mandatory client→server; a browser always masks, so refusing costs nothing and a plain
TCP writer can no longer speak the protocol.

3. No frame-size ceiling

parseFrame() waits for the declared length and Buffer.concat() grows until it arrives — one connection could ask
the process to hold what it liked (8 MiB was accepted in full). The 64-bit length form also read only
readUInt32BE(6), so a length over 4 GiB became a small frame and the parser waited for bytes that were never
coming.

4. A wrong message was a silence

subscribe{topologyId:"nope"} and {type:"nonsense"} both vanished — indistinguishable from an empty board. Same
rule the HTTP surface got in #1309.

Fixes

forget() on end/error/close; unmasked or absurd 64-bit length → close 1002, over 1 MiB → close
1009 (the code names the broken rule); every message answered — E_NO_TOPOLOGY naming the id asked for,
E_UNKNOWN_TYPE naming the one that exists, E_BAD_MESSAGE — and none of those closes the connection; a throwing
onMessage is caught, since it ran inside a socket data listener where a throw is an uncaught exception that
takes every other client with it; the connect frame is only sent when the board exists.

Evidence

test/websocket-surface.test.js — 21 checks: half a unit test of WebSocketServer over a real socket pair
(count comes down when a client leaves, a close frame empties the set, a broadcast after a departure throws nothing
and still arrives), half against the running server (a new tab is given the board with its verdicts; five kinds of
message each get their answer and the connection survives; unmasked → 1002; over the ceiling → 1009; absurd 64-bit
length → 1002; ping → pong; and the server is still answering HTTP afterwards).

With server/ws.js and server/index.js reverted, 9 of the 21 fail — count stuck at 2 after a client leaves,
silence for an unknown board and an unknown type, and no close code for any of the three bad frames.

docs/ARCHITECTURE.md: "The live-sync socket" — the answer table, the close codes, and why end is the moment.

Suite: 172 suites, 6,918 assertions, 0 failed.

A closed client is forgotten, a bad frame is refused with a code, and a wrong message is answered. Fixes #1313. The only thing any test asserted about `server/ws.js` was that a broadcast carries `verdicts` (#1306). Nobody had ever sent it a frame it did not expect. Four things came out — and the first is why the obvious fix would not have worked. ## 1. `clients` only ever grew — and `close` is never the moment Every browser tab that had ever connected stayed in the set: `broadcast()` wrote to dead sockets for the life of the process and `count` never came down. The trap: deleting on `socket.on('close')` **does not fix it**. An upgraded socket has `allowHalfOpen = true`, so when the peer goes away it emits `end` and stops there — `close` never fires. Measured: ``` server socket: allowHalfOpen = true destroying client; count = 1 server socket event: end after destroy: count = 1 ``` ## 2. An unmasked client frame was accepted RFC 6455 §5.1 makes masking mandatory client→server; a browser always masks, so refusing costs nothing and a plain TCP writer can no longer speak the protocol. ## 3. No frame-size ceiling `parseFrame()` waits for the declared length and `Buffer.concat()` grows until it arrives — one connection could ask the process to hold what it liked (8 MiB was accepted in full). The 64-bit length form also read only `readUInt32BE(6)`, so a length over 4 GiB became a small frame and the parser waited for bytes that were never coming. ## 4. A wrong message was a silence `subscribe{topologyId:"nope"}` and `{type:"nonsense"}` both vanished — indistinguishable from an empty board. Same rule the HTTP surface got in #1309. ## Fixes `forget()` on `end`/`error`/`close`; unmasked or absurd 64-bit length → close **1002**, over **1 MiB** → close **1009** (the code names the broken rule); every message answered — `E_NO_TOPOLOGY` naming the id asked for, `E_UNKNOWN_TYPE` naming the one that exists, `E_BAD_MESSAGE` — and none of those closes the connection; a throwing `onMessage` is caught, since it ran inside a socket `data` listener where a throw is an uncaught exception that takes every other client with it; the connect frame is only sent when the board exists. ## Evidence `test/websocket-surface.test.js` — **21 checks**: half a unit test of `WebSocketServer` over a real socket pair (count comes down when a client leaves, a close frame empties the set, a broadcast after a departure throws nothing and still arrives), half against the running server (a new tab is given the board with its verdicts; five kinds of message each get their answer and the connection survives; unmasked → 1002; over the ceiling → 1009; absurd 64-bit length → 1002; ping → pong; and the server is still answering HTTP afterwards). With `server/ws.js` and `server/index.js` reverted, **9 of the 21 fail** — count stuck at 2 after a client leaves, silence for an unknown board and an unknown type, and no close code for any of the three bad frames. `docs/ARCHITECTURE.md`: "The live-sync socket" — the answer table, the close codes, and why `end` is the moment. Suite: 172 suites, 6,918 assertions, 0 failed.
A closed client is forgotten, a bad frame is refused with a code, and a wrong message is answered (#1313)
Some checks failed
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 17s
CI / Test (Node 20) (pull_request) Successful in 2m28s
CI / Test (Node 18) (pull_request) Failing after 2m36s
CI / Server smoke test (pull_request) Successful in 35s
CI / Docker build (pull_request) Successful in 49s
CI / Test (Node 22) (pull_request) Successful in 2m15s
a6079f66b3
The only thing any test asserted about server/ws.js was that a broadcast carries verdicts (#1306). Nobody had sent it
a frame it did not expect. Four things came out - and the first is why the obvious fix would not have worked.

1. `clients` only ever grew - and `close` is never the moment

client.onClose was never wired and nothing removed a client from the set: every browser tab that had ever connected
stayed in it, so broadcast() wrote to dead sockets for the life of the process and count never came down.

The trap: deleting on socket.on('close') does not fix it. An upgraded socket has allowHalfOpen = true, so when the
peer goes away it emits 'end' and stops there - 'close' never fires. Measured:

  server socket: allowHalfOpen = true
  destroying client; count = 1
    server socket event: end
  after destroy: count = 1

end and error count as gone too, or the fix is decorative.

2. An unmasked client frame was accepted. RFC 6455 5.1 makes masking mandatory client-to-server; a browser always
masks, so refusing costs nothing and a plain TCP writer can no longer speak the protocol.

3. There was no frame-size ceiling: parseFrame() waits for the declared length and Buffer.concat() grows until it
arrives, so one connection could ask the process to hold what it liked (8 MiB was accepted in full). The 64-bit
length form also read only readUInt32BE(6), so a length over 4 GiB became a small frame and the parser waited for
bytes that were never coming.

4. A wrong message was a silence: subscribe{topologyId:"nope"} and {type:"nonsense"} both vanished, which a client
cannot tell from an empty board. Same rule the HTTP surface got in #1309 - every message gets an answer.

Fixes: forget() on end/error/close; unmasked or absurd 64-bit length -> close 1002, over 1 MiB -> close 1009 (the
code names the broken rule); every message answered - E_NO_TOPOLOGY naming the id asked for, E_UNKNOWN_TYPE naming
the one that exists, E_BAD_MESSAGE - and none of those closes the connection; a throwing onMessage is caught, since
it ran inside a socket 'data' listener where a throw is an uncaught exception that takes every other client with it;
the connect frame is only sent when the board exists.

test/websocket-surface.test.js: 21 checks, half of them a unit test of WebSocketServer over a real socket pair and
half over the running server - a new tab is given the board with its verdicts; five kinds of message each get their
answer and the connection survives; unmasked -> 1002; over the ceiling -> 1009; absurd 64-bit length -> 1002; ping
-> pong; and the server is still answering HTTP afterwards. With server/ws.js and server/index.js reverted, 9 of the
21 fail - count stuck at 2 after a client leaves, silence for an unknown board and type, and no close code for any
of the three bad frames.

docs/ARCHITECTURE.md: "The live-sync socket" - the answer table, the close codes, and why 'end' is the moment.

Suite: 172 suites, 6,918 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 01:44:20 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1314
No description provided.