feat(tunnel): bridge public WebSockets over the tunnel

[slvnperron]

Summary

The tunnel protocol was strictly request/response, so a visitor upgrading a WebSocket against a tunneled path (e.g. the VDK edge webchat behind tunnel.botpress.cloud/<tunnelId>/edge) got its 101 from the server's WSS and then hung forever — there was no way to relay frames to the tail. This adds WebSocket bridging, multiplexed over the tunnel's existing connection.

• Protocol (types.ts): new frames keyed by a per-socket connection id — ws_open / ws_accept / ws_reject for the handshake, ws_frame (utf-8 text, base64 when binary) and ws_close for the lifetime. Existing request/response/hello schemas untouched.
• Capability negotiation: tails advertise capabilities: ['ws'] in hello (now sent automatically on open). The head only bridges to tails that advertised it, and refuses other visitors with a new close code 4006 WS_UNSUPPORTED — a pre-websocket tail never receives frames it can't parse (which would make it close the whole tunnel), and old servers strip the unknown hello field harmlessly.
• Server (tunnel-server.ts): upgrades on /:tunnelId/:path — previously closed as invalid tail registrations — now bridge to the tail: 10s accept timeout, frames the visitor sends before the tail accepts are buffered, closes propagate in both directions, and all visitor sockets close when their tunnel disconnects.
• Client (tunnel-client.ts): TunnelTail.acceptWebSocket/rejectWebSocket + shared sendWebSocketFrame/closeWebSocket; TunnelHead.openWebSocket + supportsWebSockets. Also upstreams the patch VDK carried against the published dist: under Bun the bundled ws client rejects the 101, so the tail prefers Bun's native WebSocket there.

Once this publishes and the tunnel service redeploys with it, no service-side code changes should be needed if its WSS is a TunnelServer attached to its HTTP server — the bridging is entirely in the library. Consumer-side, vdk dev gains a ws_open → local workerd socket relay (separate PR in the vdk repo).

Test plan

• pnpm exec tsc --noEmit clean.
• New e2e: websocket-bridge (visitor → server → tail echo, path/query fidelity, pre-accept buffering, close propagation to the tail) and websocket-unsupported (clean 4006 refusal when the tail didn't advertise the capability). Existing nodejs-success / nodejs-invalid-request still pass.
• Verified live against a real workerd edge socket: simulated browser → local TunnelServer → TunnelTail (wired like vdk's dev-runtime) → VDK runtime worker's conversation WebSocket returned the edge protocol's ready frame through the bridge.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR extends the tunnel protocol and client/server implementations to multiplex public WebSocket connections over an existing tunnel.

• Adds capability negotiation and ws_open, ws_accept, ws_reject, ws_frame, and ws_close protocol messages.
• Adds visitor upgrade routing, frame buffering and forwarding, close propagation, and selected visitor-header forwarding.
• Adds tail/head WebSocket APIs, Bun-native client selection, and end-to-end bridge coverage.

Confidence Score: 4/5

The PR should not merge until public pre-accept buffering is bounded and subprotocol negotiation is made consistent across both WebSocket endpoints.

Public clients can accumulate uncapped frame data during the acceptance window, and the bridge discards the local endpoint's selected subprotocol after the visitor has already completed its handshake.

Files Needing Attention: tunnel/src/tunnel-server.ts, tunnel/src/tunnel-client.ts

Security Review

The public bridge buffers attacker-controlled frames without a byte, frame-count, or connection-wide limit while waiting up to ten seconds for tail acceptance. How this was verified: Public message data is appended to an uncapped pendingFrames array, and no application-level payload, connection, or rate limit surrounds that path.

Important Files Changed

Filename	Overview
tunnel/src/tunnel-server.ts	Implements public WebSocket lifecycle management, but pre-accept buffering is unbounded and the tail-selected subprotocol is discarded.
tunnel/src/tunnel-client.ts	Adds capability advertisement and multiplexed WebSocket APIs, including a subprotocol parameter whose server-side result is not honored.
tunnel/src/types.ts	Defines the capability and directional WebSocket protocol schemas with connection IDs and frame metadata.
tunnel/src/rooting.ts	Adds parsing for tunnel-prefixed public paths and query strings.
tunnel/e2e/websocket.ts	Covers basic bridging, path/query fidelity, pre-accept buffering, close propagation, and unsupported tails, but not subprotocol negotiation or resource limits.

Sequence Diagram

sequenceDiagram
    participant V as Public visitor
    participant H as Tunnel server/head
    participant T as Tunnel tail
    participant L as Local WebSocket
    V->>H: WebSocket upgrade + frames
    H->>T: ws_open(id, path, headers)
    Note over H: Buffer pre-accept frames
    T->>L: Open local socket
    L-->>T: Accept + subprotocol
    T->>H: ws_accept(id, subprotocol)
    H->>T: ws_frame(id, data)
    T->>L: WebSocket frame
    L-->>T: WebSocket frame
    T-->>H: ws_frame(id, data)
    H-->>V: WebSocket frame
    V->>H: close
    H->>T: ws_close(id)

Loading

_{Reviews (1): Last reviewed commit: "feat(tunnel): bridge public WebSockets o..." | Re-trigger Greptile}