traforo 0.0.9 → 0.1.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,14 @@ 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)')
     .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);

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

@@ -97,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.9",
-  "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"
   },