When you send a Response that has a webSocket property -- the Cloudflare Workers extension, as produced by a fetch() that performs a WebSocket upgrade -- the receiving side now gets a Response with a working WebSocket attached. The socket's messages are tunneled over the RPC session.

On Workers, the receiver gets a real WebSocket (one end of a WebSocketPair, pumped to/from the tunnel) on a status-101 Response, so the Response can even be returned from a fetch handler to complete a real HTTP upgrade. On other platforms, which have no native upgrade socket type, the receiver gets a WebSocket-like object supporting send(), close(), accept(), readyState, and message/close/error events -- enough, in particular, to pass to newWebSocketRpcSession() and run a nested Cap'n Web session through the tunnel.

Bare WebSockets remain non-serializable, intentionally. A live socket isn't really a value, and scoping support to upgrade Responses matches how sockets actually enter a program through the fetch API.

Under the hood, the socket is represented as a pair of streams, reusing the existing ReadableStream/WritableStream serialization rather than inventing a parallel mechanism: the sender wraps its socket in a readable (messages arriving on the socket) and a writable (messages to send on it). Because the readable half is piped exactly like any ReadableStream value, the sender begins streaming the socket's messages the moment the Response is serialized -- before the receiver even knows they're coming -- and they wait in the receiver's stream buffer until the app attaches a listener. No round trip before messages flow, and both directions inherit the streams' BDP flow control. Messages are string/Uint8Array chunks; closure travels in-band as a final {"close": {"code", "reason"}} chunk, since the streams themselves can only signal an undifferentiated end.

On the wire, the pair rides in init.webSocket -- the slot protocol.md already reserved for this ("not supported and must not be sent, though that may change if WebSocket gains support for serialization"), evaluated like init.body is for ["request", ...], and matching the Workers ResponseInit shape, where webSocket is a property of the Response constructor's init. A pre-upgrade receiver that encounters it fails with the precise existing error ("Can't deserialize a Response containing a webSocket.") rather than a generic parse error. A real captured trace, in which the backend sends "welcome" before the client has attached any listener:

server -> client  ["pipe"]
server -> client  ["resolve", 1, ["response", null, {"webSocket": {"readable": ["readable", 1], "writable": ["writable", -1]}}]]
server -> client  ["stream", ["pipeline", 1, ["write"], ["welcome"]]]    <- streamed before the client is listening
client -> server  ["stream", ["pipeline", -1, ["write"], ["hello"]]]     <- socket.send("hello")
server -> client  ["stream", ["pipeline", 1, ["write"], ["hello"]]]      <- the echo
client -> server  ["stream", ["pipeline", -1, ["write"], [{"close": {"code": 1000, "reason": "done"}}]]]
client -> server  ["stream", ["pipeline", -1, ["close"], []]]

An upgrade response never carries status/statusText -- the upgrade itself implies 101. (Standard Response constructors refuse 1xx statuses anyway, so non-Workers receivers keep the default 200 and signal the upgrade purely via the webSocket property.) The full spec is in protocol.md.

Ownership follows the rules established for streams -- literally, since the socket now is a pair of streams. The receiver's socket only takes its own references on the app's first interaction -- accept(), attaching a listener, send(), or close() -- by locking the readable and duplicating the writable's hook. An upgrade Response whose socket nobody touches therefore releases both streams when its payload is disposed (e.g. when the call it arrived in returns), letting the sender close the underlying connection rather than hold it for a receiver that will never use it: the same reasoning as canceling an unread ReadableStream unless the app locks it. The WebSocket analog of locking is accept(), conveniently mirroring Workers semantics. On the sending side, a Response that is disposed without ever being serialized closes its socket rather than leaving the connection dangling, and a received Response can be re-returned onward, chaining tunnels, which is how proxying works (though, as with stream-bearing Responses, the proxy must await the Response rather than forward the unresolved promise). If the session breaks, the facade fires error and close like a failed WebSocket.

For testing, beyond focused cases (text/binary echo, close propagation in both directions, upgrade Responses in params, ignored-socket cleanup, accept-keeps-alive, two-hop tunnel proxying, bare-socket rejection, the native path on workerd), I pulled the direct-WebSocket test cases out of index.test.ts into a shared battery -- calls, errors, capabilities in both directions, pipelining, Blobs -- which now runs twice: over a direct WebSocket connection on every runtime, and over a WebSocket obtained by calling a fetch handler across another Cap'n Web session. Same cases, both transports, so a session over a tunneled socket demonstrably behaves like a session over a direct one.

Known limitations, which are documented in the README:

• Inbound flow control ends at the sender's socket: the WebSocket API offers no way to slow down a peer, so a flooding peer buffers on the sending side. (Everything from the sender's socket onward is windowed by the streams' flow control.)
• Binary frames ride as base64 inside the JSON messages for now. (The separate-binary-frame idea discussed in custom (de)serializer support cloudflare/capnweb#32 would help here too.)
• Ping/pong control frames aren't forwarded -- standard WebSocket APIs don't expose them.
• The sender's socket must support the standard addEventListener() API (browser WebSockets, ws, Workers WebSockets). Callback-based server sockets like Bun's ServerWebSocket would need an adapter.
• Cap'n Web first touches the socket when the Response is serialized. Workers sockets buffer incoming messages until accept(), so nothing is lost there; on platforms whose sockets don't buffer (Node ws), messages arriving before that point are dropped.

(Disclosure: the initial implementation was AI-written; it was then reviewed and substantially reworked -- also with AI assistance -- fixing among other things a listener leak when the same Response is serialized twice, a tripped rpcTargets assertion under deep-copy, and close codes that can't legally be re-sent. The full vitest matrix passes: node, workerd, chromium/firefox/webkit, 856 tests, plus bun, build, and type tests.)

🤖 Generated with Claude Code