@volter/tunnel 1.0.0 → 1.1.0

package/README.md

@@ -79,6 +79,23 @@ npm install && node server.mjs
 
 Client and relay must share the same `TUNNEL_SECRET`.
 
+## Server — scalable relay (Cloudflare Workers + Durable Objects)
+
+`server/` (the Fly relay) is a single stateful process and does not scale
+horizontally. For large/global scale there is a drop-in alternative in
+`server-cf/`: a Cloudflare **Worker** that routes by subdomain to **one Durable
+Object per tunnelId**, which holds the client's control socket (hibernatable, so
+idle tunnels are ~free). Same wire protocol and client — the only client-visible
+change is that `createTunnel` appends `?id=<tunnelId>` to the control URL so the
+Worker can pick the right DO (the Fly relay tolerates and ignores it).
+
+```bash
+cd server-cf
+npm run dev      # wrangler dev --local (real workerd)
+npm test         # vitest: real Worker+DO + createTunnel, no mocks
+npm run deploy   # wrangler deploy (needs a CF zone for the wildcard host)
+```
+
 ## Layout
 
 ```

package/client/tunnel-client.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env bun
 /**
  * WebSocket-based HTTP tunnel client.
  *
@@ -13,7 +14,11 @@ import https from 'node:https';
 import net from 'node:net';
 import WebSocket from 'ws';
 
-/** Force HTTP/1.1 for WebSocket connections — HTTP/2 breaks the Upgrade handshake. */
+/**
+ * Force HTTP/1.1 for the (TLS) control WebSocket — HTTP/2 breaks the Upgrade
+ * handshake. Only applies to wss:// (an https.Agent rejects a plain ws:// URL),
+ * so it's used conditionally; plain ws:// (e.g. a local relay) needs no agent.
+ */
 const http1Agent = new https.Agent({ ALPNProtocols: ['http/1.1'] });
 
 /** Minimal logger interface for tunnel client — compatible with pino, console, etc. */
@@ -265,7 +270,14 @@ export function createTunnel({
   logger,
 }: TunnelOptions): Promise<TunnelHandle> {
   const log = logger ?? defaultLogger;
-  const wsUrl = `${host.replace(/^http/, 'ws')}/ws`;
+  // Include the tunnelId in the control URL so a routing relay (e.g. the
+  // Cloudflare Workers + Durable Objects relay) can pick the right backend at
+  // upgrade time, before the `register` message is sent. The Fly relay ignores
+  // the query param and reads tunnelId from `register`, so one client works
+  // against both servers.
+  const wsUrl =
+    `${host.replace(/^http/, 'ws')}/ws` +
+    (tunnelId ? `?id=${encodeURIComponent(tunnelId)}` : '');
 
   // Resolved loopback address for this port (set before first connection)
   let localHost = '127.0.0.1';
@@ -284,7 +296,7 @@ export function createTunnel({
   ): void {
     if (closed) return;
 
-    const ws = new WebSocket(wsUrl, { agent: http1Agent });
+    const ws = new WebSocket(wsUrl, wsUrl.startsWith('wss:') ? { agent: http1Agent } : {});
     let registered = false;
     // Hoisted so every teardown path (a reconnect via the 'close' handler, or an
     // explicit handle.close()) can clear it. It used to be declared inside the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/tunnel",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Volter tunnel — WebSocket-based HTTP/WS reverse tunnel: a relay server plus a client connector library and CLI.",
   "type": "module",
   "license": "UNLICENSED",
@@ -21,6 +21,8 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test": "bun test ./test",
+    "test:cf": "cd server-cf && vitest run",
     "tunnel": "bun run client/tunnel-client.ts",
     "server": "node server/server.mjs"
   },
@@ -36,8 +38,10 @@
     }
   },
   "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.0",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.14",
+    "jsonwebtoken": "^9.0.2",
     "typescript": "^5.0.0"
   }
 }

package/server/server.mjs

@@ -422,8 +422,10 @@ server.on('upgrade', (req, socket, head) => {
 
   const tunnelId = getTunnelIdFromHost(req.headers.host);
 
-  // No subdomain + /ws path → control channel for tunnel clients
-  if (!tunnelId && req.url === '/ws') {
+  // No subdomain + /ws path → control channel for tunnel clients.
+  // Tolerate a query string (the client appends ?id=<tunnelId> so a routing
+  // relay can pick its backend; this server reads tunnelId from `register`).
+  if (!tunnelId && req.url && req.url.split('?')[0] === '/ws') {
     wss.handleUpgrade(req, socket, head, (ws) => {
       wss.emit('connection', ws, req);
     });