Module websocket 

WebSocket proxying: detect a client upgrade, open the matching upstream WebSocket handshake, and relay the two upgraded connections byte-for-byte.

This is the one place raw hyper connection-upgrade machinery lives. The node-graph still runs for a WebSocket request (so access-phase plugins — auth, cors, rate-limit, path rewrite — apply); the upstream node resolves the target and signals intent with 101 + __ws_upstream_* context keys, and the listener calls proxy_upgrade to finish the handshake and start the relay.

The relay is a transparent byte pump ([tokio::io::copy_bidirectional]) — no frame parsing. The upstream leg is always an HTTP/1.1 WebSocket handshake — ws:// by default, or wss:// when the upstream node sets tls (see proxy_upgrade).

Two client transports are supported: HTTP/1.1 (Connection: Upgrade → 101, key/accept forwarded transparently) and HTTP/2 (RFC 8441 extended CONNECT → 200; the h2 client sends no Sec-WebSocket-Key, so the gateway synthesizes one for the upstream handshake). Client-facing wss:// works for either, because TLS is terminated before this runs.

Enums

WsError

Failure establishing the upstream side of a WebSocket proxy. All variants map to a 502 Bad Gateway at the listener — the client was never sent the 101, so it sees a failed handshake.

Constants

ECHO_HEADERS 🔒

The upstream 101-response headers to echo back to the client.

FORWARD_HEADERS 🔒

The WebSocket handshake headers to forward verbatim from the client request to the upstream. Host is set separately to the upstream target.

Functions

bad_gateway_502

A 502 Bad Gateway JSON response, returned when the upstream WebSocket handshake could not be completed.

is_h2_websocket_connect

Returns true when this is an HTTP/2 RFC 8441 extended-CONNECT WebSocket request: :method == CONNECT and a :protocol extension of websocket.

is_websocket_upgrade

Returns true when the request headers ask for a WebSocket upgrade: Connection carries an upgrade token (comma-separated, case-insensitive) and Upgrade: websocket.

proxy_upgrade

Opens the (always HTTP/1.1) upstream WebSocket handshake to host:port at path, and — on a successful upstream 101 — returns the client-facing response and spawns a task that relays bytes between the client and upstream once the client connection upgrades.

synthesize_ws_key 🔒

Generates a fresh Sec-WebSocket-Key (16 random bytes, base64) for the upstream HTTP/1.1 handshake when the client came in over HTTP/2 and thus never sent one.