traforo 0.1.0 → 0.2.1

package/dist/cli.js

@@ -11,6 +11,7 @@ cli
     .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`)
@@ -42,6 +43,7 @@ cli
         command: command.length > 0 ? command : undefined,
         cacheKey,
         password: options.password,
+        kill: options.kill,
     });
 });
 cli.help();

package/dist/client.d.ts

@@ -28,10 +28,13 @@ export declare class TunnelClient {
     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 = {
@@ -38,7 +46,8 @@ export class TunnelClient {
         return new Promise((resolve, reject) => {
             this.ws = new WebSocket(wsUrl);
             this.ws.on('open', () => {
-                console.log(`Connected with Traforo! Tunnel URL: ${this.url}`);
+                console.log(`Connected with Traforo!\n${this.url}`);
+                this.startPingInterval();
                 resolve();
             });
             this.ws.on('error', (err) => {
@@ -47,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) {
@@ -71,6 +81,7 @@ export class TunnelClient {
     }
     close() {
         this.closed = true;
+        this.stopPingInterval();
         if (this.ws) {
             this.ws.close();
             this.ws = null;
@@ -83,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

@@ -1,4 +1,7 @@
 export declare const CLI_NAME = "traforo";
+export declare function createRandomTunnelId({ port }: {
+    port: number;
+}): string;
 export type RunTunnelOptions = {
     port: number;
     tunnelId?: string;
@@ -10,6 +13,8 @@ export type RunTunnelOptions = {
     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,8 +1,14 @@
-import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+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;
+const DEFAULT_TUNNEL_ID_BYTES = 16;
+export function createRandomTunnelId({ port }) {
+    return `${crypto.randomBytes(DEFAULT_TUNNEL_ID_BYTES).toString('hex')}-${port}`;
+}
 /**
  * Wait for a port to be available (accepting connections).
  * Used when spawning a child process to wait for the server to start.
@@ -30,6 +36,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.
@@ -48,10 +161,13 @@ export function parseCommandFromArgv(argv) {
  * Run the tunnel, optionally spawning a child process first.
  */
 export async function runTunnel(options) {
-    const tunnelId = options.tunnelId ||
-        crypto.randomUUID().replaceAll('-', '').slice(0, DEFAULT_TUNNEL_ID_LENGTH);
     const localHost = options.localHost || 'localhost';
     const port = options.port;
+    const tunnelId = options.tunnelId || createRandomTunnelId({ 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traforo",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,18 @@
       "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",
+    "deploy:preview": "wrangler deploy --env preview",
+    "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",
@@ -35,6 +47,7 @@
     "@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"
@@ -44,16 +57,5 @@
     "http-cache-semantics": "^4.2.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",
-    "deploy:preview": "wrangler deploy --env preview",
-    "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.