traforo 0.0.8 → 0.1.0

package/README

@@ -1,24 +1,20 @@
-TRAFORO
-=======
+# TRAFORO
 
 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
-------------
+## INSTALLATION
 
     npm install -g traforo
 
-
-USAGE
------
+## USAGE
 
 Expose a local server:
 
     traforo -p 3000
 
-With a custom tunnel ID:
+With a custom tunnel ID (only for services safe to expose publicly):
 
     traforo -p 3000 -t my-app
 
@@ -32,20 +28,70 @@ The tunnel URL will be:
 
     https://{tunnel-id}-tunnel.traforo.dev
 
+## OPTIONS
+
+    -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.
 
-OPTIONS
--------
+Cache partitioning lets you bust all cached content by changing the key:
 
-    -p, --port <port>       Local port to expose (required)
-    -t, --tunnel-id [id]    Tunnel ID (random if omitted)
-    -h, --host [host]       Local host (default: localhost)
-    -s, --server [url]      Custom tunnel server URL
-    --help                  Show help
-    --version               Show version
+    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.
 
-HOW IT WORKS
-------------
+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
 
 1. Local client connects to Cloudflare Durable Object via WebSocket
 2. HTTP requests to tunnel URL are forwarded to the DO
@@ -53,17 +99,14 @@ HOW IT WORKS
 4. Local client makes request to localhost and returns response
 5. WebSocket connections from users are also proxied through
 
-
-API ENDPOINTS
--------------
+## API ENDPOINTS
 
     /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
--------------
+## LIBRARY USAGE
 
     import { TunnelClient } from 'traforo/client'
     import { runTunnel } from 'traforo/run-tunnel'
@@ -71,12 +114,12 @@ LIBRARY USAGE
     const client = new TunnelClient({
       localPort: 3000,
       tunnelId: 'my-app',
+      cacheKey: 'v1',       // optional: enable edge caching
+      password: 'mysecret', // optional: password protection
     })
 
     await client.connect()
 
-
-LICENSE
--------
+## LICENSE
 
 MIT

package/dist/cli.js

@@ -6,13 +6,17 @@ const cli = goke(CLI_NAME);
 cli
     .command('', 'Expose a local port via tunnel')
     .option('-p, --port <port>', 'Local port to expose (required)')
-    .option('-t, --tunnel-id [id]', 'Tunnel ID (random if omitted)')
+    .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)')
     .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 +28,20 @@ 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,
     });
 });
 cli.help();

package/dist/client.d.ts

@@ -18,6 +18,10 @@ 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;

package/dist/client.js

@@ -16,6 +16,7 @@ export class TunnelClient {
             localHttps: false,
             autoReconnect: true,
             reconnectDelay: 3000,
+            cacheKey: undefined,
             ...options,
         };
     }
@@ -26,7 +27,13 @@ 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);
@@ -240,22 +247,15 @@ export class TunnelClient {
                 this.localWsConnections.delete(msg.connId);
             });
             localWs.on('message', (data, isBinary) => {
-                let frameData;
-                let binary = false;
-                if (isBinary || data instanceof Buffer) {
-                    frameData = Buffer.isBuffer(data)
-                        ? data.toString('base64')
-                        : Buffer.from(data).toString('base64');
-                    binary = true;
-                }
-                else {
-                    frameData = data.toString();
-                }
+                const dataBuffer = rawDataToBuffer(data);
+                const frameData = isBinary
+                    ? dataBuffer.toString('base64')
+                    : dataBuffer.toString('utf8');
                 const frame = {
                     type: 'ws_frame',
                     connId: msg.connId,
                     data: frameData,
-                    binary,
+                    binary: isBinary,
                 };
                 this.send(frame);
             });
@@ -309,3 +309,12 @@ export class TunnelClient {
         this.ws.send(JSON.stringify(msg));
     }
 }
+function rawDataToBuffer(data) {
+    if (Buffer.isBuffer(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return Buffer.concat(data.map((chunk) => rawDataToBuffer(chunk)));
+    }
+    return Buffer.from(data);
+}

package/dist/run-tunnel.d.ts

@@ -6,6 +6,10 @@ 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;
 };
 /**
  * Parse argv to extract command after `--` separator.

package/dist/run-tunnel.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import net from 'node:net';
 import { TunnelClient } from './client.js';
 export const CLI_NAME = 'traforo';
+const DEFAULT_TUNNEL_ID_LENGTH = 16;
 /**
  * Wait for a port to be available (accepting connections).
  * Used when spawning a child process to wait for the server to start.
@@ -47,7 +48,8 @@ export function parseCommandFromArgv(argv) {
  * Run the tunnel, optionally spawning a child process first.
  */
 export async function runTunnel(options) {
-    const tunnelId = options.tunnelId || crypto.randomUUID().slice(0, 8);
+    const tunnelId = options.tunnelId ||
+        crypto.randomUUID().replaceAll('-', '').slice(0, DEFAULT_TUNNEL_ID_LENGTH);
     const localHost = options.localHost || 'localhost';
     const port = options.port;
     let child = null;
@@ -95,7 +97,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.8",
-  "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets",
+  "version": "0.1.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,6 +30,7 @@
   },
   "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",
@@ -39,7 +40,8 @@
     "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"
   },