GitHub - remorses/traforo: Expose local servers via tunnels. Supports WebSockets, SSE, password protection, Cloudflare CDN caching.

# TRAFORO

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

    npm install -g traforo

## USAGE

Expose a local server:

    traforo -p 3000

Or let traforo auto-detect the port from a dev server command:

    traforo -- pnpm dev
    traforo -- next start

With a custom tunnel ID (only for services safe to expose publicly):

    traforo -p 3000 -t my-app

Run a command and tunnel it:

    traforo -- next start
    traforo -- pnpm dev
    traforo -p 5173 -- vite
    traforo -p 3000 -- next start    # explicit port overrides auto-detection

The tunnel URL will be:

    https://{tunnel-id}-tunnel.traforo.dev

## OPTIONS

    -p, --port <port>          Local port to expose (optional with -- command)
    -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

## AUTO PORT DETECTION

When you pass a command after `--`, traforo can detect the local port from the
process output. It watches stdout and stderr for addresses like these:

    http://localhost:3000
    localhost:5173
    127.0.0.1:8080
    0.0.0.0:4321

This works well with common dev servers that print their local URL when they start.

If you also pass `-p`, traforo uses that explicit port instead of auto-detecting.

## 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.

## 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
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
    /traforo-login          POST endpoint for password login
    /*                      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',
      cacheKey: 'v1',       // optional: enable edge caching
      password: 'mysecret', // optional: password protection
    })

    await client.connect()

## LICENSE

MIT