traforo 0.0.9 → 0.2.0

package/README

@@ -2,6 +2,7 @@
 
 HTTP tunnel via Cloudflare Durable Objects and WebSockets.
 Expose local servers to the internet with a simple CLI.
+Infinitely scalable with support for Cloudflare CDN caching and password protection.
 
 ## INSTALLATION
 
@@ -29,12 +30,66 @@ The tunnel URL will be:
 
 ## OPTIONS
 
-    -p, --port <port>       Local port to expose (required)
-    -t, --tunnel-id [id]    Custom tunnel ID (prefer random default)
-    -h, --host [host]       Local host (default: localhost)
-    -s, --server [url]      Custom tunnel server URL
-    --help                  Show help
-    --version               Show version
+    -p, --port <port>          Local port to expose (required)
+    -t, --tunnel-id [id]       Custom tunnel ID (prefer random default)
+    -c, --cache [key]          Enable edge caching (optional partition key)
+    --password <password>      Protect the tunnel with a password
+    -h, --host [host]          Local host (default: localhost)
+    -s, --server [url]         Custom tunnel server URL
+    --help                     Show help
+    --version                  Show version
+
+## EDGE CACHING
+
+Cache responses at Cloudflare's edge so repeat requests never hit your
+local machine:
+
+    traforo -p 3000 --cache
+
+What gets cached:
+
+- GET requests where the origin sends cacheable Cache-Control headers
+  (public, max-age, s-maxage)
+- Static asset extensions use Cloudflare-like default fallback TTLs when
+  cache headers are missing: 200/301=120m, 302/303=20m, 404/410=3m
+
+What never gets cached:
+
+- Non-GET requests
+- 206 Partial Content responses (Cache API put() limitation)
+- Responses with Set-Cookie, Cache-Control: no-store/no-cache/private
+- Streaming responses (SSE, ndjson)
+- WebSocket connections
+
+Requests with `Authorization`, `Cache-Control: no-cache/no-store/max-age=0`,
+or `Pragma: no-cache` bypass edge cache lookup.
+
+Cache partitioning lets you bust all cached content by changing the key:
+
+    traforo -p 3000 --cache v1     # first deployment
+    traforo -p 3000 --cache v2     # new deploy, fresh cache
+
+Each key creates a separate cache namespace. Old entries expire via TTL.
+
+The X-Traforo-Cache response header shows HIT, MISS, or BYPASS for debugging.
+When BYPASS/MISS comes from the local origin path, X-Traforo-Cache-Reason explains why.
+
+## PASSWORD PROTECTION
+
+Restrict tunnel access with a password:
+
+    traforo -p 3000 --password mysecret
+
+Visitors in a browser see a login page. After entering the correct password
+a `traforo-password` cookie is set and they can browse normally.
+
+Non-browser clients (curl, APIs) get a 401 Unauthorized response with
+instructions to pass the password as a cookie:
+
+    curl -b 'traforo-password=mysecret' https://{tunnel-id}-tunnel.traforo.dev
+
+WebSocket upgrade requests without the correct cookie are rejected with
+close code 4013.
 
 ## HOW IT WORKS
 
@@ -48,6 +103,7 @@ The tunnel URL will be:
 
     /traforo-status         Check if tunnel is online
     /traforo-upstream       WebSocket endpoint for local client
+    /traforo-login          POST endpoint for password login
     /*                      All other paths proxied to local server
 
 ## LIBRARY USAGE
@@ -58,6 +114,8 @@ The tunnel URL will be:
     const client = new TunnelClient({
       localPort: 3000,
       tunnelId: 'my-app',
+      cacheKey: 'v1',       // optional: enable edge caching
+      password: 'mysecret', // optional: password protection
     })
 
     await client.connect()

package/dist/cli.js

@@ -9,10 +9,15 @@ cli
     .option('-t, --tunnel-id [id]', 'Custom tunnel ID (only for services safe to expose publicly; prefer random default)')
     .option('-h, --host [host]', 'Local host (default: localhost)')
     .option('-s, --server [url]', 'Tunnel server URL')
+    .option('-c, --cache [key]', 'Enable edge caching for static assets (optional key for cache partitioning, default: "default")')
+    .option('--password <password>', 'Protect the tunnel with a password (visitors must enter it to access)')
+    .option('-k, --kill', 'Kill any existing process on the port before starting')
     .example(`${CLI_NAME} -p 3000`)
     .example(`${CLI_NAME} -p 3000 -- next start`)
     .example(`${CLI_NAME} -p 3000 -- pnpm dev`)
     .example(`${CLI_NAME} -p 5173 -t my-app -- vite`)
+    .example(`${CLI_NAME} -p 3000 --cache`)
+    .example(`${CLI_NAME} -p 3000 --cache v2`)
     .action(async (options) => {
     if (!options.port) {
         console.error('Error: --port is required');
@@ -24,12 +29,21 @@ cli
         console.error(`Error: Invalid port number: ${options.port}`);
         process.exit(1);
     }
+    // --cache with no value comes as boolean true, --cache v2 comes as string "v2"
+    const cacheKey = options.cache
+        ? typeof options.cache === 'string'
+            ? options.cache
+            : 'default'
+        : undefined;
     await runTunnel({
         port,
         tunnelId: options.tunnelId,
         localHost: options.host,
         serverUrl: options.server,
         command: command.length > 0 ? command : undefined,
+        cacheKey,
+        password: options.password,
+        kill: options.kill,
     });
 });
 cli.help();

package/dist/client.d.ts

@@ -18,16 +18,23 @@ type TunnelClientOptions = {
     autoReconnect?: boolean;
     /** Reconnect delay in ms */
     reconnectDelay?: number;
+    /** Enable edge caching with this partition key */
+    cacheKey?: string;
+    /** Password to protect the tunnel */
+    password?: string;
 };
 export declare class TunnelClient {
     private options;
     private ws;
     private localWsConnections;
     private closed;
+    private pingInterval;
     constructor(options: TunnelClientOptions);
     get url(): string;
     connect(): Promise<void>;
     close(): void;
+    private startPingInterval;
+    private stopPingInterval;
     private handleMessage;
     private handleHttpRequest;
     private handleWsOpen;

package/dist/client.js

@@ -2,11 +2,19 @@
  * Local tunnel client - runs on user's machine to expose a local server.
  */
 import WebSocket from 'ws';
+/**
+ * Interval (ms) between keepalive pings sent to the DO.
+ * Cloudflare's CDN has a ~100s inactivity timeout on WebSockets.
+ * The DO's setWebSocketAutoResponse handles these at the edge without
+ * waking the DO from hibernation, so this is zero-cost.
+ */
+const PING_INTERVAL_MS = 30_000;
 export class TunnelClient {
     options;
     ws = null;
     localWsConnections = new Map();
     closed = false;
+    pingInterval = null;
     constructor(options) {
         const baseDomain = options.baseDomain || 'traforo.dev';
         this.options = {
@@ -16,6 +24,7 @@ export class TunnelClient {
             localHttps: false,
             autoReconnect: true,
             reconnectDelay: 3000,
+            cacheKey: undefined,
             ...options,
         };
     }
@@ -26,12 +35,19 @@ export class TunnelClient {
         if (this.closed) {
             throw new Error('Client is closed');
         }
-        const wsUrl = `${this.options.serverUrl}/traforo-upstream?_tunnelId=${this.options.tunnelId}`;
+        let wsUrl = `${this.options.serverUrl}/traforo-upstream?_tunnelId=${this.options.tunnelId}`;
+        if (this.options.cacheKey) {
+            wsUrl += `&_cacheKey=${encodeURIComponent(this.options.cacheKey)}`;
+        }
+        if (this.options.password) {
+            wsUrl += `&_password=${encodeURIComponent(this.options.password)}`;
+        }
         // console.log(`Connecting to ${wsUrl}...`)
         return new Promise((resolve, reject) => {
             this.ws = new WebSocket(wsUrl);
             this.ws.on('open', () => {
                 console.log(`Connected with Traforo! Tunnel URL: ${this.url}`);
+                this.startPingInterval();
                 resolve();
             });
             this.ws.on('error', (err) => {
@@ -40,6 +56,7 @@ export class TunnelClient {
             });
             this.ws.on('close', (code, reason) => {
                 console.log(`Disconnected: ${code} ${reason.toString()}`);
+                this.stopPingInterval();
                 this.ws = null;
                 // Close all local WS connections
                 for (const [, localWs] of this.localWsConnections) {
@@ -64,6 +81,7 @@ export class TunnelClient {
     }
     close() {
         this.closed = true;
+        this.stopPingInterval();
         if (this.ws) {
             this.ws.close();
             this.ws = null;
@@ -76,6 +94,27 @@ export class TunnelClient {
         }
         this.localWsConnections.clear();
     }
+    startPingInterval() {
+        this.stopPingInterval();
+        this.pingInterval = setInterval(() => {
+            const ws = this.ws;
+            if (!ws || ws.readyState !== WebSocket.OPEN) {
+                return;
+            }
+            try {
+                ws.send('{"type":"ping"}');
+            }
+            catch {
+                // readyState can flip between check and send(); safe to ignore
+            }
+        }, PING_INTERVAL_MS);
+    }
+    stopPingInterval() {
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+    }
     handleMessage(rawMessage) {
         let msg;
         try {

package/dist/run-tunnel.d.ts

@@ -6,6 +6,12 @@ export type RunTunnelOptions = {
     baseDomain?: string;
     serverUrl?: string;
     command?: string[];
+    /** Enable edge caching with optional partition key */
+    cacheKey?: string;
+    /** Password to protect the tunnel */
+    password?: string;
+    /** Kill any existing process on the port before starting */
+    kill?: boolean;
 };
 /**
  * Parse argv to extract command after `--` separator.

package/dist/run-tunnel.js

@@ -1,6 +1,8 @@
-import { spawn } from 'node:child_process';
+import { exec, spawn } from 'node:child_process';
 import net from 'node:net';
+import { promisify } from 'node:util';
 import { TunnelClient } from './client.js';
+const execPromise = promisify(exec);
 export const CLI_NAME = 'traforo';
 const DEFAULT_TUNNEL_ID_LENGTH = 16;
 /**
@@ -30,6 +32,113 @@ async function waitForPort(port, host = 'localhost', timeoutMs = 60_000) {
         check();
     });
 }
+/**
+ * Check if a port is currently in use (something is listening).
+ */
+async function isPortInUse(port, host = 'localhost') {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.once('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once('error', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, host);
+    });
+}
+/**
+ * Kill any process listening on the given port.
+ * Cross-platform: uses lsof on macOS/Linux, netstat+taskkill on Windows.
+ * Never throws — silently succeeds if no process is found or kill fails.
+ */
+async function killProcessOnPort(port) {
+    try {
+        const inUse = await isPortInUse(port);
+        if (!inUse) {
+            return;
+        }
+        console.log(`Killing process on port ${port}...`);
+        if (process.platform === 'win32') {
+            // Windows: parse netstat output to find PIDs listening on the port
+            const { stdout } = await execPromise(`netstat -ano | findstr :${port} | findstr LISTENING`);
+            const pids = new Set();
+            for (const line of stdout.trim().split('\n')) {
+                const parts = line.trim().split(/\s+/);
+                const pid = parseInt(parts[parts.length - 1], 10);
+                if (!isNaN(pid) && pid > 0) {
+                    pids.add(pid);
+                }
+            }
+            for (const pid of pids) {
+                try {
+                    await execPromise(`taskkill /PID ${pid} /F`);
+                }
+                catch { }
+            }
+        }
+        else {
+            // macOS / Linux: lsof returns PIDs listening on tcp port
+            const { stdout } = await execPromise(`lsof -ti tcp:${port}`);
+            const pids = stdout
+                .trim()
+                .split('\n')
+                .map((s) => {
+                return parseInt(s, 10);
+            })
+                .filter((n) => {
+                return !isNaN(n) && n > 0;
+            });
+            for (const pid of pids) {
+                try {
+                    process.kill(pid, 'SIGTERM');
+                }
+                catch { }
+            }
+        }
+        // Brief wait for the port to actually free up
+        const maxWait = 3_000;
+        const start = Date.now();
+        while (Date.now() - start < maxWait) {
+            const stillInUse = await isPortInUse(port);
+            if (!stillInUse) {
+                console.log(`Port ${port} is now free`);
+                return;
+            }
+            await new Promise((r) => {
+                return setTimeout(r, 200);
+            });
+        }
+        // If SIGTERM didn't work on POSIX, try SIGKILL as last resort
+        if (process.platform !== 'win32') {
+            try {
+                const { stdout } = await execPromise(`lsof -ti tcp:${port}`);
+                const pids = stdout
+                    .trim()
+                    .split('\n')
+                    .map((s) => {
+                    return parseInt(s, 10);
+                })
+                    .filter((n) => {
+                    return !isNaN(n) && n > 0;
+                });
+                for (const pid of pids) {
+                    try {
+                        process.kill(pid, 'SIGKILL');
+                    }
+                    catch { }
+                }
+            }
+            catch { }
+        }
+    }
+    catch {
+        // Never crash — if anything fails, just continue and let the
+        // child process or port-wait logic surface the actual error
+    }
+}
 /**
  * Parse argv to extract command after `--` separator.
  * Returns the command array and remaining argv without the command.
@@ -49,9 +158,14 @@ export function parseCommandFromArgv(argv) {
  */
 export async function runTunnel(options) {
     const tunnelId = options.tunnelId ||
-        crypto.randomUUID().replaceAll('-', '').slice(0, DEFAULT_TUNNEL_ID_LENGTH);
+        crypto.randomUUID().replaceAll('-', '').slice(0, DEFAULT_TUNNEL_ID_LENGTH) +
+            options.port;
     const localHost = options.localHost || 'localhost';
     const port = options.port;
+    // Kill existing process on port if requested
+    if (options.kill) {
+        await killProcessOnPort(port);
+    }
     let child = null;
     // If command provided, spawn child process with PORT env
     if (options.command && options.command.length > 0) {
@@ -97,7 +211,15 @@ export async function runTunnel(options) {
         localHost,
         ...(options.baseDomain && { baseDomain: options.baseDomain }),
         ...(options.serverUrl && { serverUrl: options.serverUrl }),
+        ...(options.cacheKey && { cacheKey: options.cacheKey }),
+        ...(options.password && { password: options.password }),
     });
+    if (options.cacheKey) {
+        console.log(`Edge caching enabled (key: ${options.cacheKey})`);
+    }
+    if (options.password) {
+        console.log(`Password protection enabled`);
+    }
     // Handle shutdown
     const cleanup = () => {
         console.log('\nShutting down...');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "traforo",
-  "version": "0.0.9",
-  "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets",
+  "version": "0.2.0",
+  "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",
   "repository": "https://github.com/remorses/traforo",
@@ -30,16 +30,19 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250712.0",
+    "@types/http-cache-semantics": "^4.2.0",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
     "tsx": "^4.20.5",
     "typescript": "^5.7.0",
+    "undici-types": "~6.21.0",
     "vite": "^7.1.4",
     "vitest": "^3.2.4",
     "wrangler": "^4.24.3"
   },
   "dependencies": {
-    "goke": "^6.1.2",
+    "goke": "^6.3.0",
+    "http-cache-semantics": "^4.2.0",
     "string-dedent": "^3.0.2",
     "ws": "^8.19.0"
   },