Tunnel WebSockets end to end

[jonastemplestein]

Captun tunnels now forward WebSockets end to end. The headline use case: a tunnel target is just a fetch function, and that fetch function can serve a Cap'n Web RPC capability over a WebSocket — so any process, anywhere, can expose a live object the whole internet can call:

import { newWebSocketRpcSession, newWorkersWebSocketRpcResponse, RpcTarget } from "capnweb";
import { createCaptunTunnel } from "captun";

class Calculator extends RpcTarget {
  add(a: number, b: number) {
    return a + b;
  }
}

using tunnel = await createCaptunTunnel({
  fetch: (request) => newWorkersWebSocketRpcResponse(request, new Calculator()),
});

// ...anywhere else on the internet:
const rpc = newWebSocketRpcSession<Calculator>(tunnel.url.replace(/^http/, "ws"));
await rpc.add(2, 3); // 5

No WebSocket plumbing in sight: a fetch handler that returns a Workers-style response carrying a webSocket is bridged automatically. This exact flow is the first e2e test.

API

CLI — captun 3000 now forwards WebSockets to the local server like it forwards HTTP, including handshake headers (Cookie, Authorization, Origin), subprotocol negotiation, binary frames, and close codes. Verified against socket.io, ws, Bun.serve, Deno, and crossws servers (see below).

Workers-style on any runtime — Node has no WebSocketPair and its Response rejects status 101, so the library exports the two missing primitives; the same handler code runs on workerd, Node, or Bun:

import { createCaptunTunnel, createWebSocketResponse, isWebSocketUpgradeRequest, WebSocketPair } from "captun";

using tunnel = await createCaptunTunnel({
  fetch(request) {
    if (!isWebSocketUpgradeRequest(request)) return new Response("hello");
    const pair = new WebSocketPair();
    pair[1].accept();
    pair[1].addEventListener("message", (event) => pair[1].send(`echo:${event.data}`));
    return createWebSocketResponse(pair[0]);
  },
});

Low-level hook — connectWebSocket(request, remote) for dial-out proxying to a separate local WebSocket server (what the CLI uses internally). Cap'n Web stub lifetime (dup()/dispose) is handled inside pipeWebSocketToHandle, so implementors never see it.

How it works

There is no WebSocket wire format in this PR. The tunnel already runs on Cap'n Web, which passes capabilities both directions, delivers calls in order, and serializes Uint8Array natively — so a tunneled WebSocket is a pair of handles (send/close), and every message is one ordered RPC call:

public client ⇄ gateway DO (WebSocketPair) ⇄ Cap'n Web RPC ⇄ tunnel client ⇄ local WebSocket server

Decisions worth knowing:

• The 101 must come from DO fetch, not the forward RPC — an upgrade response with an attached webSocket does not survive a Durable Object RPC method return (verified empirically), so WebSocket requests route through shard.fetch().
• Tunnel death closes its public sockets with 1001 (going away), so browser reconnect logic fires instead of hanging on a zombie socket.
• Messages are capped at 16MiB (close 4009 on just that socket): benchmarking showed a ~24MiB message overflows the Cap'n Web leg's ~32MiB frame limit (base64 inflates 4/3) and would otherwise kill every connection on the tunnel.
• Message-level relay: ping/pong and permessage-deflate are per-hop; close codes outside 1000/3000–4999 degrade to a bare close (the close() API refuses them).
• An earlier draft shipped a hand-rolled frame codec (newline JSON + base64 in streamed HTTP bodies); replacing it with capability passing deleted ~200 lines and structurally removed reordering/drop/crash races.

Tested and proven

E2e suite (17 tests): Cap'n Web RPC through a tunneled WebSocket, CLI forwarding (text, binary, subprotocols, close codes, handshake headers), Workers-style handler in plain Node, hosted-gateway forwarding, concurrent sockets without cross-talk, fast failure when the local server rejects the upgrade, disconnect cleanup, the oversized-message guard, and Captun through Captun (an inner gateway tunneled through an outer tunnel — traffic crosses two gateways and two tunnel clients).

Robustness campaign against a real deployed gateway (Cloudflare, gateway secret):

• Server matrix, all passing the full check set (connect, push, text, byte-verified binary, close codes both directions, concurrent clients): socket.io (own framing + acks, unmodified), Node ws, Bun.serve, Deno, crossws, in-process WebSocketPair, and a Cloudflare Durable Object running createCaptunTunnel against its own fetch (tunnel survived 67+ minutes inside the DO).
• Benchmarks: p50 RTT 51ms through the real edge vs 0.32ms local (captun's own stack adds <1ms); ~1,900 msgs/s; byte-exact payloads to ~24MiB (hence the 16MiB guard); 50 concurrent connections, 100-cycle churn, 90s soak, 200 pipelined mixed text/binary — zero losses, reorders, or cross-talk.

What was difficult

• Cap'n Web disposes stubs received as call arguments when the call returns — handles kept for the socket's lifetime must be dup()ed (verified with a standalone repro, encapsulated in the pipe).
• Runtimes disagree about binary: Node delivers Blob (async to read), workerd ArrayBuffer/Blob, ws gives Buffer — sometimes cross-realm where instanceof lies. Conversions are duck-typed and chained through a promise queue so a slow Blob read can never reorder frames or race the close event.
• miniflare landmines (test infra only): getWorker().fetch() corrupts binary frames to "[object Blob]", and workerd stringifies send(Blob) — noted in the tests where they bite; binary coverage runs over real sockets.

Validation

• pnpm run check, pnpm test (core suite, 134 passed — example tests moved to pnpm test:examples, which CI runs with its pinned Bun/Deno versions)
• Full server/client matrix + benchmarks against a deployed gateway (results above)

🤖 Generated with Claude Code

---

Note

High Risk
Changes core gateway routing, Durable Object lifecycle, and tunnel RPC surface; bugs could break upgrades, leak cookies on non-101 paths, or affect all connections on a tunnel if limits fail.

Overview
Adds end-to-end WebSocket forwarding through Captun tunnels, not just HTTP.

The gateway routes upgrades through the Durable Object’s fetch path (not forward RPC) so 101 + webSocket survives workerd. Public sockets are bridged to the tunnel client via Cap’n Web connectWebSocket and pipeWebSocketToHandle, with a 16MiB per-message cap, ordered relay, and 1001 cleanup when the tunnel client drops.

Library: new WebSocketFetcher / WebSocketHandle, optional connectWebSocket on createCaptunTunnel, runtime helpers (WebSocketPair, createWebSocketResponse, isWebSocketUpgradeRequest), and automatic bridging when fetch returns a Workers-style upgrade response.

CLI: dials wss: to the local target, forwards handshake headers, and logs 101 upgrades.

Tests/docs: large e2e coverage (RPC, CLI, hosted gateway, nested tunnels), pnpm test scoped to test/, pnpm test:examples in CI, engines.node >=22.4, and README WebSocket section.

^{Reviewed by Cursor Bugbot for commit 89d2dd5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/captun@27

commit: 89d2dd5

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 665c18d. Configure here.}