traforo 0.1.0 → 0.2.0

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 = {
@@ -39,6 +47,7 @@ export class TunnelClient {
             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) => {
@@ -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

@@ -10,6 +10,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,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traforo",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,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"