traforo 0.3.0 → 0.5.0

package/README

@@ -111,6 +111,29 @@ instructions to pass the password as a cookie:
 WebSocket upgrade requests without the correct cookie are rejected with
 close code 4013.
 
+## TRAFORO_URL ENVIRONMENT VARIABLE
+
+When you run a command after `--`, traforo injects `TRAFORO_URL` into the
+child process environment with the full public tunnel URL:
+
+    TRAFORO_URL=https://{tunnel-id}-tunnel.traforo.dev
+
+Your app can read it directly:
+
+    const baseUrl = process.env.TRAFORO_URL
+
+To remap it to a custom env var your app already uses, prefix the command:
+
+    traforo -p 3000 -- sh -c 'APP_URL=$TRAFORO_URL exec node server.js'
+    traforo -p 3000 -- sh -c 'NEXT_PUBLIC_URL=$TRAFORO_URL exec next dev'
+    traforo -p 3000 -- sh -c 'VITE_BASE_URL=$TRAFORO_URL exec vite'
+
+Or set it in your .env / startup script and let traforo override only
+`TRAFORO_URL`, reading it where needed:
+
+    // next.config.js
+    const baseUrl = process.env.APP_URL || process.env.TRAFORO_URL || 'http://localhost:3000'
+
 ## HOW IT WORKS
 
 1. Local client connects to Cloudflare Durable Object via WebSocket

package/dist/client.d.ts

@@ -1,6 +1,8 @@
 /**
  * Local tunnel client - runs on user's machine to expose a local server.
  */
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { SocksProxyAgent } from 'socks-proxy-agent';
 type TunnelClientOptions = {
     /** Local port to proxy to */
     localPort: number;
@@ -23,6 +25,9 @@ type TunnelClientOptions = {
     /** Password to protect the tunnel */
     password?: string;
 };
+export declare function createWebSocketAgentFromEnv({ wsUrl, }: {
+    wsUrl: string;
+}): HttpsProxyAgent<string> | SocksProxyAgent | undefined;
 export declare class TunnelClient {
     private options;
     private ws;

package/dist/client.js

@@ -1,6 +1,10 @@
 /**
  * Local tunnel client - runs on user's machine to expose a local server.
  */
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { getProxyForUrl } from 'proxy-from-env';
+import { SocksProxyAgent } from 'socks-proxy-agent';
+import { isAgent } from 'std-env';
 import WebSocket from 'ws';
 /**
  * Interval (ms) between keepalive pings sent to the DO.
@@ -9,6 +13,26 @@ import WebSocket from 'ws';
  * waking the DO from hibernation, so this is zero-cost.
  */
 const PING_INTERVAL_MS = 30_000;
+export function createWebSocketAgentFromEnv({ wsUrl, }) {
+    const httpLikeUrl = (() => {
+        const parsedUrl = new URL(wsUrl);
+        if (parsedUrl.protocol === 'ws:') {
+            parsedUrl.protocol = 'http:';
+        }
+        if (parsedUrl.protocol === 'wss:') {
+            parsedUrl.protocol = 'https:';
+        }
+        return parsedUrl.toString();
+    })();
+    const proxyUrl = getProxyForUrl(wsUrl) || getProxyForUrl(httpLikeUrl);
+    if (!proxyUrl) {
+        return undefined;
+    }
+    if (proxyUrl.startsWith('socks')) {
+        return new SocksProxyAgent(proxyUrl);
+    }
+    return new HttpsProxyAgent(proxyUrl);
+}
 export class TunnelClient {
     options;
     ws = null;
@@ -44,9 +68,18 @@ export class TunnelClient {
         }
         // console.log(`Connecting to ${wsUrl}...`)
         return new Promise((resolve, reject) => {
-            this.ws = new WebSocket(wsUrl);
+            this.ws = new WebSocket(wsUrl, {
+                agent: createWebSocketAgentFromEnv({ wsUrl }),
+            });
             this.ws.on('open', () => {
-                console.log(`Connected with Traforo!\n${this.url}`);
+                const { localHost, localPort, localHttps } = this.options;
+                const localProtocol = localHttps ? 'https' : 'http';
+                const localUrl = `${localProtocol}://${localHost}:${localPort}`;
+                let message = `Connected with Traforo!\n${this.url}`;
+                if (isAgent) {
+                    message += `\n\nUse ${localUrl} directly for lower latency. The tunnel URL is for remote access. Show both URLs to the user.`;
+                }
+                console.log(message);
                 this.startPingInterval();
                 resolve();
             });

package/dist/run-tunnel.js

@@ -330,6 +330,9 @@ export async function runTunnel(options) {
         }
     }
     let child = null;
+    // Compute tunnel URL early so it can be injected into the child env
+    const baseDomain = options.baseDomain || 'traforo.dev';
+    const tunnelUrl = `https://${tunnelId}-tunnel.${baseDomain}`;
     // If command provided, spawn child process with PORT env
     if (options.command && options.command.length > 0) {
         const cmd = options.command[0];
@@ -347,6 +350,7 @@ export async function runTunnel(options) {
             env: {
                 ...process.env,
                 ...(port ? { PORT: String(port) } : {}),
+                TRAFORO_URL: tunnelUrl,
                 // Disable clear/animations for common tools without lying about CI
                 FORCE_COLOR: '1',
                 VITE_CLS: 'false',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traforo",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",
@@ -28,10 +28,23 @@
       "import": "./dist/run-tunnel.js"
     }
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.client.json && chmod +x dist/cli.js",
+    "prepublishOnly": "pnpm build",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy --env preview",
+    "deploy:prod": "wrangler deploy # only run if user asks specifically!",
+    "typecheck": "tsc --noEmit",
+    "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "cli": "tsx src/cli.ts",
+    "test": "vitest --run"
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250712.0",
     "@types/http-cache-semantics": "^4.2.0",
     "@types/node": "^22.0.0",
+    "@types/proxy-from-env": "^1.0.4",
     "@types/ws": "^8.18.1",
     "tsx": "^4.20.5",
     "typescript": "^5.7.0",
@@ -43,18 +56,11 @@
   "dependencies": {
     "goke": "^6.8.0",
     "http-cache-semantics": "^4.2.0",
+    "https-proxy-agent": "^7.0.6",
+    "proxy-from-env": "^2.1.0",
+    "socks-proxy-agent": "^8.0.5",
+    "std-env": "^4.1.0",
     "string-dedent": "^3.0.2",
     "ws": "^8.19.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.client.json && chmod +x dist/cli.js",
-    "dev": "wrangler dev",
-    "deploy": "wrangler deploy --env preview",
-    "deploy:prod": "wrangler deploy # only run if user asks specifically!",
-    "typecheck": "tsc --noEmit",
-    "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
-    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
-    "cli": "tsx src/cli.ts",
-    "test": "vitest --run"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Kimaki
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.