traforo 0.0.1 → 0.0.4

package/README

@@ -0,0 +1,82 @@
+TRAFORO
+=======
+
+HTTP tunnel via Cloudflare Durable Objects and WebSockets.
+Expose local servers to the internet with a simple CLI.
+
+
+INSTALLATION
+------------
+
+    npm install -g traforo
+
+
+USAGE
+-----
+
+Expose a local server:
+
+    traforo -p 3000
+
+With a custom tunnel ID:
+
+    traforo -p 3000 -t my-app
+
+Run a command and tunnel it:
+
+    traforo -p 3000 -- next start
+    traforo -p 3000 -- pnpm dev
+    traforo -p 5173 -- vite
+
+The tunnel URL will be:
+
+    https://{tunnel-id}-tunnel.kimaki.xyz
+
+
+OPTIONS
+-------
+
+    -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
+
+
+HOW IT WORKS
+------------
+
+1. Local client connects to Cloudflare Durable Object via WebSocket
+2. HTTP requests to tunnel URL are forwarded to the DO
+3. DO sends requests over WebSocket to local client
+4. Local client makes request to localhost and returns response
+5. WebSocket connections from users are also proxied through
+
+
+API ENDPOINTS
+-------------
+
+    /traforo-status         Check if tunnel is online
+    /traforo-upstream       WebSocket endpoint for local client
+    /*                      All other paths proxied to local server
+
+
+LIBRARY USAGE
+-------------
+
+    import { TunnelClient } from 'traforo/client'
+    import { runTunnel } from 'traforo/run-tunnel'
+
+    const client = new TunnelClient({
+      localPort: 3000,
+      tunnelId: 'my-app',
+    })
+
+    await client.connect()
+
+
+LICENSE
+-------
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { cac } from '@xmorse/cac';
+import { CLI_NAME, runTunnel, parseCommandFromArgv } from './run-tunnel.js';
+const { command, argv } = parseCommandFromArgv(process.argv);
+const cli = cac(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('-h, --host [host]', 'Local host (default: localhost)')
+    .option('-s, --server [url]', 'Tunnel server URL')
+    .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`)
+    .action(async (options) => {
+    if (!options.port) {
+        console.error('Error: --port is required');
+        console.error(`\nUsage: ${CLI_NAME} -p <port> [-- command]`);
+        process.exit(1);
+    }
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        console.error(`Error: Invalid port number: ${options.port}`);
+        process.exit(1);
+    }
+    await runTunnel({
+        port,
+        tunnelId: options.tunnelId,
+        localHost: options.host,
+        serverUrl: options.server,
+        command: command.length > 0 ? command : undefined,
+    });
+});
+cli.help();
+cli.version('0.0.1');
+// Parse the modified argv (without the command after --)
+cli.parse(argv);

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Local tunnel client - runs on user's machine to expose a local server.
+ */
+type TunnelClientOptions = {
+    /** Local port to proxy to */
+    localPort: number;
+    /** Local host (default: localhost) */
+    localHost?: string;
+    /** Tunnel server URL (default: wss://{tunnelId}-tunnel.kimaki.xyz) */
+    serverUrl?: string;
+    /** Tunnel ID */
+    tunnelId: string;
+    /** Use HTTPS for local connections */
+    localHttps?: boolean;
+    /** Reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms */
+    reconnectDelay?: number;
+};
+export declare class TunnelClient {
+    private options;
+    private ws;
+    private localWsConnections;
+    private closed;
+    constructor(options: TunnelClientOptions);
+    get url(): string;
+    connect(): Promise<void>;
+    close(): void;
+    private handleMessage;
+    private handleHttpRequest;
+    private handleWsOpen;
+    private handleWsFrame;
+    private handleWsClose;
+    private send;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,297 @@
+/**
+ * Local tunnel client - runs on user's machine to expose a local server.
+ */
+import WebSocket from 'ws';
+export class TunnelClient {
+    options;
+    ws = null;
+    localWsConnections = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = {
+            localHost: 'localhost',
+            serverUrl: `wss://${options.tunnelId}-tunnel.kimaki.xyz`,
+            localHttps: false,
+            autoReconnect: true,
+            reconnectDelay: 3000,
+            ...options,
+        };
+    }
+    get url() {
+        return `https://${this.options.tunnelId}-tunnel.kimaki.xyz`;
+    }
+    async connect() {
+        if (this.closed) {
+            throw new Error('Client is closed');
+        }
+        const wsUrl = `${this.options.serverUrl}/traforo-upstream?_tunnelId=${this.options.tunnelId}`;
+        // console.log(`Connecting to ${wsUrl}...`)
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(wsUrl);
+            this.ws.on('open', () => {
+                console.log(`Connected with Traforo! Tunnel URL: ${this.url}`);
+                resolve();
+            });
+            this.ws.on('error', (err) => {
+                console.error('WebSocket error:', err.message);
+                reject(new Error('WebSocket connection failed'));
+            });
+            this.ws.on('close', (code, reason) => {
+                console.log(`Disconnected: ${code} ${reason.toString()}`);
+                this.ws = null;
+                // Close all local WS connections
+                for (const [, localWs] of this.localWsConnections) {
+                    try {
+                        localWs.close();
+                    }
+                    catch { }
+                }
+                this.localWsConnections.clear();
+                // Auto-reconnect
+                if (this.options.autoReconnect && !this.closed) {
+                    console.log(`Reconnecting in ${this.options.reconnectDelay}ms...`);
+                    setTimeout(() => {
+                        this.connect().catch(console.error);
+                    }, this.options.reconnectDelay);
+                }
+            });
+            this.ws.on('message', (data) => {
+                this.handleMessage(data.toString());
+            });
+        });
+    }
+    close() {
+        this.closed = true;
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        for (const [, localWs] of this.localWsConnections) {
+            try {
+                localWs.close();
+            }
+            catch { }
+        }
+        this.localWsConnections.clear();
+    }
+    handleMessage(rawMessage) {
+        let msg;
+        try {
+            msg = JSON.parse(rawMessage);
+        }
+        catch {
+            console.error('Failed to parse message:', rawMessage);
+            return;
+        }
+        switch (msg.type) {
+            case 'http_request':
+                this.handleHttpRequest(msg);
+                break;
+            case 'ws_open':
+                this.handleWsOpen(msg);
+                break;
+            case 'ws_frame':
+                this.handleWsFrame(msg);
+                break;
+            case 'ws_close':
+                this.handleWsClose(msg);
+                break;
+        }
+    }
+    async handleHttpRequest(msg) {
+        const { localHost, localPort, localHttps } = this.options;
+        const protocol = localHttps ? 'https' : 'http';
+        const url = `${protocol}://${localHost}:${localPort}${msg.path}`;
+        console.log(`HTTP ${msg.method} ${msg.path}`);
+        try {
+            // Decode body
+            let body;
+            if (msg.body) {
+                body = Buffer.from(msg.body, 'base64');
+            }
+            // Make local request
+            const res = await fetch(url, {
+                method: msg.method,
+                headers: msg.headers,
+                body: msg.method !== 'GET' && msg.method !== 'HEAD' ? body : undefined,
+            });
+            // Build response headers
+            const resHeaders = {};
+            res.headers.forEach((value, key) => {
+                resHeaders[key] = value;
+            });
+            // Check if we should stream the response
+            const contentType = res.headers.get('content-type') || '';
+            const transferEncoding = res.headers.get('transfer-encoding') || '';
+            const shouldStream = contentType.includes('text/event-stream') ||
+                contentType.includes('application/x-ndjson') ||
+                transferEncoding.includes('chunked');
+            if (shouldStream && res.body) {
+                console.log(`HTTP ${msg.method} ${msg.path} -> streaming response`);
+                // Send response start
+                const startMsg = {
+                    type: 'http_response_start',
+                    id: msg.id,
+                    status: res.status,
+                    headers: resHeaders,
+                };
+                this.send(startMsg);
+                // Stream chunks
+                const reader = res.body.getReader();
+                try {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done) {
+                            break;
+                        }
+                        const chunkMsg = {
+                            type: 'http_response_chunk',
+                            id: msg.id,
+                            chunk: Buffer.from(value).toString('base64'),
+                        };
+                        this.send(chunkMsg);
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                // Send response end
+                const endMsg = {
+                    type: 'http_response_end',
+                    id: msg.id,
+                };
+                this.send(endMsg);
+            }
+            else {
+                // Non-streaming: read full body
+                const resBuffer = await res.arrayBuffer();
+                const resBody = resBuffer.byteLength > 0
+                    ? Buffer.from(resBuffer).toString('base64')
+                    : null;
+                const response = {
+                    type: 'http_response',
+                    id: msg.id,
+                    status: res.status,
+                    headers: resHeaders,
+                    body: resBody,
+                };
+                this.send(response);
+            }
+        }
+        catch (err) {
+            console.error(`HTTP request failed:`, err);
+            const errorResponse = {
+                type: 'http_error',
+                id: msg.id,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            };
+            this.send(errorResponse);
+        }
+    }
+    handleWsOpen(msg) {
+        const { localHost, localPort, localHttps } = this.options;
+        const protocol = localHttps ? 'wss' : 'ws';
+        const url = `${protocol}://${localHost}:${localPort}${msg.path}`;
+        console.log(`WS OPEN ${msg.path} (${msg.connId})`);
+        try {
+            const localWs = new WebSocket(url);
+            localWs.on('open', () => {
+                console.log(`WS CONNECTED ${msg.connId}`);
+                this.localWsConnections.set(msg.connId, localWs);
+                const opened = {
+                    type: 'ws_opened',
+                    connId: msg.connId,
+                };
+                this.send(opened);
+            });
+            localWs.on('error', (err) => {
+                console.error(`WS ERROR ${msg.connId}:`, err.message);
+                const errorMsg = {
+                    type: 'ws_error',
+                    connId: msg.connId,
+                    error: err.message || 'Connection failed',
+                };
+                this.send(errorMsg);
+                this.localWsConnections.delete(msg.connId);
+            });
+            localWs.on('close', (code, reason) => {
+                console.log(`WS CLOSED ${msg.connId}: ${code} ${reason.toString()}`);
+                const closed = {
+                    type: 'ws_closed',
+                    connId: msg.connId,
+                    code,
+                    reason: reason.toString(),
+                };
+                this.send(closed);
+                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 frame = {
+                    type: 'ws_frame',
+                    connId: msg.connId,
+                    data: frameData,
+                    binary,
+                };
+                this.send(frame);
+            });
+        }
+        catch (err) {
+            console.error(`WS OPEN FAILED ${msg.connId}:`, err);
+            const errorMsg = {
+                type: 'ws_error',
+                connId: msg.connId,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            };
+            this.send(errorMsg);
+        }
+    }
+    handleWsFrame(msg) {
+        const localWs = this.localWsConnections.get(msg.connId);
+        if (!localWs) {
+            console.warn(`WS FRAME for unknown connection: ${msg.connId}`);
+            return;
+        }
+        try {
+            if (msg.binary) {
+                const buffer = Buffer.from(msg.data, 'base64');
+                localWs.send(buffer);
+            }
+            else {
+                localWs.send(msg.data);
+            }
+        }
+        catch (err) {
+            console.error(`WS SEND FAILED ${msg.connId}:`, err);
+        }
+    }
+    handleWsClose(msg) {
+        const localWs = this.localWsConnections.get(msg.connId);
+        if (!localWs) {
+            return;
+        }
+        console.log(`WS CLOSE ${msg.connId}: ${msg.code} ${msg.reason}`);
+        try {
+            localWs.close(msg.code, msg.reason);
+        }
+        catch { }
+        this.localWsConnections.delete(msg.connId);
+    }
+    send(msg) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            console.warn('Cannot send: WebSocket not connected');
+            return;
+        }
+        this.ws.send(JSON.stringify(msg));
+    }
+}

package/dist/run-tunnel.d.ts

@@ -0,0 +1,20 @@
+export declare const CLI_NAME = "traforo";
+export type RunTunnelOptions = {
+    port: number;
+    tunnelId?: string;
+    localHost?: string;
+    serverUrl?: string;
+    command?: string[];
+};
+/**
+ * Parse argv to extract command after `--` separator.
+ * Returns the command array and remaining argv without the command.
+ */
+export declare function parseCommandFromArgv(argv: string[]): {
+    command: string[];
+    argv: string[];
+};
+/**
+ * Run the tunnel, optionally spawning a child process first.
+ */
+export declare function runTunnel(options: RunTunnelOptions): Promise<void>;

package/dist/run-tunnel.js

@@ -0,0 +1,119 @@
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import { TunnelClient } from './client.js';
+export const CLI_NAME = 'traforo';
+/**
+ * Wait for a port to be available (accepting connections).
+ * Used when spawning a child process to wait for the server to start.
+ */
+async function waitForPort(port, host = 'localhost', timeoutMs = 60_000) {
+    const start = Date.now();
+    const checkInterval = 500;
+    return new Promise((resolve, reject) => {
+        const check = () => {
+            if (Date.now() - start > timeoutMs) {
+                reject(new Error(`Timeout waiting for port ${port} to be available`));
+                return;
+            }
+            const socket = new net.Socket();
+            socket.once('connect', () => {
+                socket.destroy();
+                resolve();
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                setTimeout(check, checkInterval);
+            });
+            socket.connect(port, host);
+        };
+        check();
+    });
+}
+/**
+ * Parse argv to extract command after `--` separator.
+ * Returns the command array and remaining argv without the command.
+ */
+export function parseCommandFromArgv(argv) {
+    const dashDashIndex = argv.indexOf('--');
+    if (dashDashIndex === -1) {
+        return { command: [], argv };
+    }
+    return {
+        command: argv.slice(dashDashIndex + 1),
+        argv: argv.slice(0, dashDashIndex),
+    };
+}
+/**
+ * Run the tunnel, optionally spawning a child process first.
+ */
+export async function runTunnel(options) {
+    const tunnelId = options.tunnelId || crypto.randomUUID().slice(0, 8);
+    const localHost = options.localHost || 'localhost';
+    const port = options.port;
+    let child = null;
+    // If command provided, spawn child process with PORT env
+    if (options.command && options.command.length > 0) {
+        const cmd = options.command[0];
+        const args = options.command.slice(1);
+        console.log(`Starting: ${options.command.join(' ')}`);
+        console.log(`PORT=${port}\n`);
+        const spawnedChild = spawn(cmd, args, {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                PORT: String(port),
+                // Disable clear/animations for common tools without lying about CI
+                FORCE_COLOR: '1',
+                VITE_CLS: 'false',
+                NEXT_TELEMETRY_DISABLED: '1',
+            },
+        });
+        child = spawnedChild;
+        spawnedChild.on('error', (err) => {
+            console.error(`Failed to start command: ${err.message}`);
+            process.exit(1);
+        });
+        spawnedChild.on('exit', (code) => {
+            console.log(`\nCommand exited with code ${code}`);
+            process.exit(code || 0);
+        });
+        // Wait for port to be available before connecting tunnel
+        console.log(`Waiting for port ${port}...`);
+        try {
+            await waitForPort(port, localHost);
+            console.log(`Port ${port} is ready!\n`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            spawnedChild.kill();
+            process.exit(1);
+        }
+    }
+    const client = new TunnelClient({
+        localPort: port,
+        tunnelId,
+        localHost,
+        ...(options.serverUrl && { serverUrl: options.serverUrl }),
+    });
+    // Handle shutdown
+    const cleanup = () => {
+        console.log('\nShutting down...');
+        client.close();
+        if (child) {
+            child.kill();
+        }
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    try {
+        await client.connect();
+    }
+    catch (err) {
+        console.error('Failed to connect:', err instanceof Error ? err.message : String(err));
+        if (child) {
+            child.kill();
+        }
+        process.exit(1);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+export type HttpRequestMessage = {
+    type: 'http_request';
+    id: string;
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body: string | null;
+};
+export type WsOpenMessage = {
+    type: 'ws_open';
+    connId: string;
+    path: string;
+    headers: Record<string, string>;
+};
+export type WsFrameMessage = {
+    type: 'ws_frame';
+    connId: string;
+    data: string;
+    binary?: boolean;
+};
+export type WsCloseMessage = {
+    type: 'ws_close';
+    connId: string;
+    code: number;
+    reason: string;
+};
+export type UpstreamMessage = HttpRequestMessage | WsOpenMessage | WsFrameMessage | WsCloseMessage;
+export type HttpResponseMessage = {
+    type: 'http_response';
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string | null;
+};
+export type HttpResponseStartMessage = {
+    type: 'http_response_start';
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+};
+export type HttpResponseChunkMessage = {
+    type: 'http_response_chunk';
+    id: string;
+    chunk: string;
+};
+export type HttpResponseEndMessage = {
+    type: 'http_response_end';
+    id: string;
+};
+export type HttpErrorMessage = {
+    type: 'http_error';
+    id: string;
+    error: string;
+};
+export type WsOpenedMessage = {
+    type: 'ws_opened';
+    connId: string;
+};
+export type WsFrameResponseMessage = {
+    type: 'ws_frame';
+    connId: string;
+    data: string;
+    binary?: boolean;
+};
+export type WsClosedMessage = {
+    type: 'ws_closed';
+    connId: string;
+    code: number;
+    reason: string;
+};
+export type WsErrorMessage = {
+    type: 'ws_error';
+    connId: string;
+    error: string;
+};
+export type DownstreamMessage = HttpResponseMessage | HttpResponseStartMessage | HttpResponseChunkMessage | HttpResponseEndMessage | HttpErrorMessage | WsOpenedMessage | WsFrameResponseMessage | WsClosedMessage | WsErrorMessage;
+export type UpstreamConnectedEvent = {
+    event: 'upstream_connected';
+};
+export type UpstreamDisconnectedEvent = {
+    event: 'upstream_disconnected';
+};
+export type DownstreamEvent = UpstreamConnectedEvent | UpstreamDisconnectedEvent;
+export declare function createMessage<T extends UpstreamMessage | DownstreamMessage>(msg: T): string;
+export declare function parseUpstreamMessage(data: string): UpstreamMessage | null;
+export declare function parseDownstreamMessage(data: string): DownstreamMessage | null;