traforo 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "traforo",
+  "version": "0.0.1",
+  "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets",
+  "type": "module",
+  "license": "MIT",
+  "repository": "https://github.com/remorses/kimaki",
+  "bin": {
+    "traforo": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "exports": {
+    ".": "./src/tunnel.ts",
+    "./client": "./src/client.ts",
+    "./types": "./src/types.ts",
+    "./run-tunnel": "./src/run-tunnel.ts"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250712.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4",
+    "wrangler": "^4.24.3"
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "ws": "^8.19.0"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:preview": "wrangler deploy --env preview",
+    "typecheck": "tsc --noEmit",
+    "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
+    "cli": "tsx src/cli.ts",
+    "test": "vitest --run"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { cac } from '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: {
+      port?: string
+      tunnelId?: string
+      host?: string
+      server?: string
+    }) => {
+      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/src/client.ts

@@ -0,0 +1,326 @@
+/**
+ * Local tunnel client - runs on user's machine to expose a local server.
+ */
+
+import WebSocket from 'ws'
+import type {
+  UpstreamMessage,
+  DownstreamMessage,
+  HttpRequestMessage,
+  HttpResponseMessage,
+  HttpErrorMessage,
+  WsOpenMessage,
+  WsFrameMessage,
+  WsCloseMessage,
+  WsOpenedMessage,
+  WsFrameResponseMessage,
+  WsClosedMessage,
+  WsErrorMessage,
+} from './types.js'
+
+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 class TunnelClient {
+  private options: Required<TunnelClientOptions>
+  private ws: WebSocket | null = null
+  private localWsConnections: Map<string, WebSocket> = new Map()
+  private closed = false
+
+  constructor(options: TunnelClientOptions) {
+    this.options = {
+      localHost: 'localhost',
+      serverUrl: `wss://${options.tunnelId}-tunnel.kimaki.xyz`,
+      localHttps: false,
+      autoReconnect: true,
+      reconnectDelay: 3000,
+      ...options,
+    }
+  }
+
+  get url(): string {
+    return `https://${this.options.tunnelId}-tunnel.kimaki.xyz`
+  }
+
+  async connect(): Promise<void> {
+    if (this.closed) {
+      throw new Error('Client is closed')
+    }
+
+    const wsUrl = `${this.options.serverUrl}/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! Tunnel URL: ${this.url}`)
+        resolve()
+      })
+
+      this.ws.on('error', (err: Error) => {
+        console.error('WebSocket error:', err.message)
+        reject(new Error('WebSocket connection failed'))
+      })
+
+      this.ws.on('close', (code: number, reason: Buffer) => {
+        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: WebSocket.RawData) => {
+        this.handleMessage(data.toString())
+      })
+    })
+  }
+
+  close(): void {
+    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()
+  }
+
+  private handleMessage(rawMessage: string): void {
+    let msg: UpstreamMessage
+    try {
+      msg = JSON.parse(rawMessage) as UpstreamMessage
+    } 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
+    }
+  }
+
+  private async handleHttpRequest(msg: HttpRequestMessage): Promise<void> {
+    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: Buffer | undefined
+      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,
+      })
+
+      // Read response body
+      const resBuffer = await res.arrayBuffer()
+      const resBody =
+        resBuffer.byteLength > 0
+          ? Buffer.from(resBuffer).toString('base64')
+          : null
+
+      // Build response headers
+      const resHeaders: Record<string, string> = {}
+      res.headers.forEach((value, key) => {
+        resHeaders[key] = value
+      })
+
+      // Send response
+      const response: HttpResponseMessage = {
+        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: HttpErrorMessage = {
+        type: 'http_error',
+        id: msg.id,
+        error: err instanceof Error ? err.message : 'Unknown error',
+      }
+
+      this.send(errorResponse)
+    }
+  }
+
+  private handleWsOpen(msg: WsOpenMessage): void {
+    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: WsOpenedMessage = {
+          type: 'ws_opened',
+          connId: msg.connId,
+        }
+        this.send(opened)
+      })
+
+      localWs.on('error', (err: Error) => {
+        console.error(`WS ERROR ${msg.connId}:`, err.message)
+
+        const errorMsg: WsErrorMessage = {
+          type: 'ws_error',
+          connId: msg.connId,
+          error: err.message || 'Connection failed',
+        }
+        this.send(errorMsg)
+
+        this.localWsConnections.delete(msg.connId)
+      })
+
+      localWs.on('close', (code: number, reason: Buffer) => {
+        console.log(`WS CLOSED ${msg.connId}: ${code} ${reason.toString()}`)
+
+        const closed: WsClosedMessage = {
+          type: 'ws_closed',
+          connId: msg.connId,
+          code,
+          reason: reason.toString(),
+        }
+        this.send(closed)
+
+        this.localWsConnections.delete(msg.connId)
+      })
+
+      localWs.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
+        let frameData: string
+        let binary = false
+
+        if (isBinary || data instanceof Buffer) {
+          frameData = Buffer.isBuffer(data)
+            ? data.toString('base64')
+            : Buffer.from(data as ArrayBuffer).toString('base64')
+          binary = true
+        } else {
+          frameData = data.toString()
+        }
+
+        const frame: WsFrameResponseMessage = {
+          type: 'ws_frame',
+          connId: msg.connId,
+          data: frameData,
+          binary,
+        }
+        this.send(frame)
+      })
+    } catch (err) {
+      console.error(`WS OPEN FAILED ${msg.connId}:`, err)
+
+      const errorMsg: WsErrorMessage = {
+        type: 'ws_error',
+        connId: msg.connId,
+        error: err instanceof Error ? err.message : 'Unknown error',
+      }
+      this.send(errorMsg)
+    }
+  }
+
+  private handleWsFrame(msg: WsFrameMessage): void {
+    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)
+    }
+  }
+
+  private handleWsClose(msg: WsCloseMessage): void {
+    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)
+  }
+
+  private send(msg: DownstreamMessage): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      console.warn('Cannot send: WebSocket not connected')
+      return
+    }
+
+    this.ws.send(JSON.stringify(msg))
+  }
+}

package/src/run-tunnel.ts

@@ -0,0 +1,155 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import net from 'node:net'
+import { TunnelClient } from './client.js'
+
+export const CLI_NAME = 'traforo'
+
+export type RunTunnelOptions = {
+  port: number
+  tunnelId?: string
+  localHost?: string
+  serverUrl?: string
+  command?: string[]
+}
+
+/**
+ * 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: number,
+  host = 'localhost',
+  timeoutMs = 60_000
+): Promise<void> {
+  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: string[]): {
+  command: string[]
+  argv: string[]
+} {
+  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: RunTunnelOptions): Promise<void> {
+  const tunnelId = options.tunnelId || crypto.randomUUID().slice(0, 8)
+  const localHost = options.localHost || 'localhost'
+  const port = options.port
+
+  let child: ChildProcess | null = 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,
+    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/src/tunnel.ts

@@ -0,0 +1,574 @@
+import type {
+  UpstreamMessage,
+  DownstreamMessage,
+  HttpRequestMessage,
+  HttpResponseMessage,
+  HttpErrorMessage,
+  WsOpenMessage,
+  WsFrameMessage,
+  WsCloseMessage,
+  WsOpenedMessage,
+  WsFrameResponseMessage,
+  WsClosedMessage,
+  WsErrorMessage,
+} from './types.js'
+
+// Cloudflare-specific types
+export type Env = {
+  TUNNEL_DO: DurableObjectNamespace
+}
+
+type Attachment = {
+  role: 'upstream' | 'downstream'
+  tunnelId: string
+}
+
+type PendingHttpRequest = {
+  resolve: (response: Response) => void
+  reject: (error: Error) => void
+  timeout: ReturnType<typeof setTimeout>
+}
+
+type PendingWsConnection = {
+  userWs: WebSocket
+  timeout: ReturnType<typeof setTimeout>
+}
+
+const HTTP_TIMEOUT_MS = 30_000
+const WS_OPEN_TIMEOUT_MS = 10_000
+
+// Worker entrypoint
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    if (req.method === 'OPTIONS') {
+      return addCors(new Response(null, { status: 204 }))
+    }
+
+    const url = new URL(req.url)
+    const host = url.hostname
+
+    // Extract tunnel ID from subdomain: {tunnelId}-tunnel.kimaki.xyz
+    const tunnelId = extractTunnelId(host)
+    if (!tunnelId) {
+      return addCors(new Response('Invalid tunnel URL', { status: 400 }))
+    }
+
+    // Get the Durable Object for this tunnel
+    const doId = env.TUNNEL_DO.idFromName(tunnelId)
+    const stub = env.TUNNEL_DO.get(doId)
+
+    // Forward request to DO
+    const doUrl = new URL(req.url)
+    doUrl.searchParams.set('_tunnelId', tunnelId)
+    const res = await stub.fetch(new Request(doUrl.toString(), req))
+
+    return addCors(res)
+  },
+}
+
+function extractTunnelId(host: string): string | null {
+  // Match: {tunnelId}-tunnel.kimaki.xyz or {tunnelId}-tunnel.localhost
+  const match = host.match(/^([a-z0-9-]+)-tunnel\./)
+  if (!match) {
+    return null
+  }
+  return match[1]
+}
+
+// Durable Object
+export class Tunnel {
+  private ctx: DurableObjectState
+  private env: Env
+  private pendingHttpRequests: Map<string, PendingHttpRequest> = new Map()
+  private pendingWsConnections: Map<string, PendingWsConnection> = new Map()
+
+  constructor(state: DurableObjectState, env: Env) {
+    this.ctx = state
+    this.env = env
+
+    // Auto-respond to ping messages without waking DO
+    this.ctx.setWebSocketAutoResponse(
+      new WebSocketRequestResponsePair('ping', 'pong')
+    )
+    this.ctx.setWebSocketAutoResponse(
+      new WebSocketRequestResponsePair('{"type":"ping"}', '{"type":"pong"}')
+    )
+  }
+
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url)
+    const tunnelId = url.searchParams.get('_tunnelId') || 'default'
+    const isUpgrade = req.headers.get('Upgrade') === 'websocket'
+
+    // WebSocket upgrade requests
+    if (isUpgrade) {
+      if (url.pathname === '/upstream') {
+        return this.handleUpstreamConnection(tunnelId)
+      }
+      // User WebSocket connection to be proxied
+      return this.handleUserWsConnection(tunnelId, url.pathname, req.headers)
+    }
+
+    // Status endpoint
+    if (url.pathname === '/status') {
+      const upstream = this.getUpstream(tunnelId)
+      return Response.json({
+        online: !!upstream,
+        tunnelId,
+      })
+    }
+
+    // HTTP request to be proxied
+    return this.handleHttpProxy(tunnelId, req)
+  }
+
+  // ============================================
+  // Upstream (local client) connection
+  // ============================================
+
+  private handleUpstreamConnection(tunnelId: string): Response {
+    // Close any existing upstream connection
+    const existing = this.getUpstream(tunnelId)
+    if (existing) {
+      try {
+        existing.close(4009, 'Replaced by new connection')
+      } catch {}
+    }
+
+    const pair = new WebSocketPair()
+    const [client, server] = Object.values(pair)
+
+    this.ctx.acceptWebSocket(server, [`upstream:${tunnelId}`])
+    server.serializeAttachment({
+      role: 'upstream',
+      tunnelId,
+    } satisfies Attachment)
+
+    // Notify any waiting downstream connections
+    const downstreams = this.ctx.getWebSockets(`downstream:${tunnelId}`)
+    for (const ws of downstreams) {
+      try {
+        ws.send(JSON.stringify({ event: 'upstream_connected' }))
+      } catch {}
+    }
+
+    return new Response(null, { status: 101, webSocket: client })
+  }
+
+  private getUpstream(tunnelId: string): WebSocket | null {
+    const sockets = this.ctx.getWebSockets(`upstream:${tunnelId}`)
+    return sockets[0] || null
+  }
+
+  // ============================================
+  // HTTP Proxy
+  // ============================================
+
+  private async handleHttpProxy(
+    tunnelId: string,
+    req: Request
+  ): Promise<Response> {
+    const upstream = this.getUpstream(tunnelId)
+    if (!upstream) {
+      return new Response('Tunnel offline', { status: 503 })
+    }
+
+    const reqId = crypto.randomUUID()
+    const url = new URL(req.url)
+
+    // Read request body
+    let body: string | null = null
+    if (req.body) {
+      const buffer = await req.arrayBuffer()
+      if (buffer.byteLength > 0) {
+        body = arrayBufferToBase64(buffer)
+      }
+    }
+
+    // Build headers object
+    const headers: Record<string, string> = {}
+    req.headers.forEach((value, key) => {
+      // Skip hop-by-hop headers
+      if (!isHopByHopHeader(key)) {
+        headers[key] = value
+      }
+    })
+
+    // Send request to local client
+    const message: HttpRequestMessage = {
+      type: 'http_request',
+      id: reqId,
+      method: req.method,
+      path: url.pathname + url.search,
+      headers,
+      body,
+    }
+
+    try {
+      upstream.send(JSON.stringify(message) satisfies string)
+    } catch {
+      return new Response('Failed to send to tunnel', { status: 502 })
+    }
+
+    // Wait for response
+    return new Promise<Response>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingHttpRequests.delete(reqId)
+        resolve(new Response('Tunnel timeout', { status: 504 }))
+      }, HTTP_TIMEOUT_MS)
+
+      this.pendingHttpRequests.set(reqId, { resolve, reject, timeout })
+    })
+  }
+
+  // ============================================
+  // User WebSocket Proxy
+  // ============================================
+
+  private handleUserWsConnection(
+    tunnelId: string,
+    path: string,
+    reqHeaders: Headers
+  ): Response {
+    const upstream = this.getUpstream(tunnelId)
+    if (!upstream) {
+      const pair = new WebSocketPair()
+      const [client, server] = Object.values(pair)
+      server.accept()
+      server.close(4008, 'Tunnel offline')
+      return new Response(null, { status: 101, webSocket: client })
+    }
+
+    const pair = new WebSocketPair()
+    const [client, server] = Object.values(pair)
+
+    const connId = crypto.randomUUID()
+
+    this.ctx.acceptWebSocket(server, [`downstream:${tunnelId}`, `ws:${connId}`])
+    server.serializeAttachment({
+      role: 'downstream',
+      tunnelId,
+    } satisfies Attachment)
+
+    // Build headers object
+    const headers: Record<string, string> = {}
+    reqHeaders.forEach((value, key) => {
+      if (!isHopByHopHeader(key) && key.toLowerCase() !== 'upgrade') {
+        headers[key] = value
+      }
+    })
+
+    // Request local client to open WebSocket
+    const message: WsOpenMessage = {
+      type: 'ws_open',
+      connId,
+      path,
+      headers,
+    }
+
+    try {
+      upstream.send(JSON.stringify(message) satisfies string)
+    } catch {
+      server.close(4009, 'Failed to contact tunnel')
+      return new Response(null, { status: 101, webSocket: client })
+    }
+
+    // Set timeout for WS open
+    const timeout = setTimeout(() => {
+      this.pendingWsConnections.delete(connId)
+      try {
+        server.close(4010, 'Local connection timeout')
+      } catch {}
+    }, WS_OPEN_TIMEOUT_MS)
+
+    this.pendingWsConnections.set(connId, { userWs: server, timeout })
+
+    return new Response(null, { status: 101, webSocket: client })
+  }
+
+  // ============================================
+  // WebSocket Hibernation Handlers
+  // ============================================
+
+  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
+    if (typeof message !== 'string') {
+      return
+    }
+
+    const attachment = ws.deserializeAttachment() as Attachment | undefined
+    if (!attachment) {
+      return
+    }
+
+    if (attachment.role === 'upstream') {
+      this.handleUpstreamMessage(attachment.tunnelId, message)
+    } else if (attachment.role === 'downstream') {
+      this.handleDownstreamMessage(attachment.tunnelId, ws, message)
+    }
+  }
+
+  async webSocketClose(
+    ws: WebSocket,
+    code: number,
+    reason: string,
+    _wasClean: boolean
+  ) {
+    const attachment = ws.deserializeAttachment() as Attachment | undefined
+    if (!attachment) {
+      return
+    }
+
+    if (attachment.role === 'upstream') {
+      // Upstream disconnected - notify all downstream connections
+      const downstreams = this.ctx.getWebSockets(
+        `downstream:${attachment.tunnelId}`
+      )
+      for (const down of downstreams) {
+        try {
+          down.send(JSON.stringify({ event: 'upstream_disconnected' }))
+          down.close(1012, 'Upstream disconnected')
+        } catch {}
+      }
+
+      // Reject all pending HTTP requests
+      for (const [reqId, pending] of this.pendingHttpRequests) {
+        clearTimeout(pending.timeout)
+        pending.resolve(new Response('Tunnel disconnected', { status: 502 }))
+      }
+      this.pendingHttpRequests.clear()
+
+      // Close all pending WS connections
+      for (const [connId, pending] of this.pendingWsConnections) {
+        clearTimeout(pending.timeout)
+        try {
+          pending.userWs.close(4011, 'Tunnel disconnected')
+        } catch {}
+      }
+      this.pendingWsConnections.clear()
+    }
+  }
+
+  async webSocketError(ws: WebSocket, error: unknown) {
+    // Treat errors same as close
+    await this.webSocketClose(ws, 1011, 'WebSocket error', false)
+  }
+
+  // ============================================
+  // Message Handlers
+  // ============================================
+
+  private handleUpstreamMessage(tunnelId: string, rawMessage: string) {
+    let msg: DownstreamMessage
+    try {
+      msg = JSON.parse(rawMessage) as DownstreamMessage
+    } catch {
+      return
+    }
+
+    switch (msg.type) {
+      case 'http_response':
+        this.handleHttpResponse(msg)
+        break
+      case 'http_error':
+        this.handleHttpError(msg)
+        break
+      case 'ws_opened':
+        this.handleWsOpened(msg)
+        break
+      case 'ws_frame':
+        this.handleWsFrame(tunnelId, msg)
+        break
+      case 'ws_closed':
+        this.handleWsClosed(msg)
+        break
+      case 'ws_error':
+        this.handleWsError(msg)
+        break
+    }
+  }
+
+  private handleDownstreamMessage(
+    tunnelId: string,
+    ws: WebSocket,
+    rawMessage: string
+  ) {
+    // Forward message from user WebSocket to upstream
+    const upstream = this.getUpstream(tunnelId)
+    if (!upstream) {
+      return
+    }
+
+    // Try to parse to get connId for routing
+    let parsed: { connId?: string; data?: string }
+    try {
+      parsed = JSON.parse(rawMessage)
+    } catch {
+      return
+    }
+
+    // Find the connId for this downstream WebSocket
+    const tags = this.ctx.getTags(ws)
+    const wsTag = tags.find((t) => t.startsWith('ws:'))
+    if (!wsTag) {
+      return
+    }
+    const connId = wsTag.replace('ws:', '')
+
+    // Forward as WsFrameMessage
+    const message: WsFrameMessage = {
+      type: 'ws_frame',
+      connId,
+      data: rawMessage,
+    }
+
+    try {
+      upstream.send(JSON.stringify(message) satisfies string)
+    } catch {}
+  }
+
+  private handleHttpResponse(msg: HttpResponseMessage) {
+    const pending = this.pendingHttpRequests.get(msg.id)
+    if (!pending) {
+      return
+    }
+
+    clearTimeout(pending.timeout)
+    this.pendingHttpRequests.delete(msg.id)
+
+    // Decode body
+    let body: BodyInit | null = null
+    if (msg.body) {
+      body = base64ToArrayBuffer(msg.body)
+    }
+
+    // Build response headers
+    const headers = new Headers()
+    for (const [key, value] of Object.entries(msg.headers)) {
+      if (!isHopByHopHeader(key)) {
+        headers.set(key, value)
+      }
+    }
+
+    pending.resolve(new Response(body, { status: msg.status, headers }))
+  }
+
+  private handleHttpError(msg: HttpErrorMessage) {
+    const pending = this.pendingHttpRequests.get(msg.id)
+    if (!pending) {
+      return
+    }
+
+    clearTimeout(pending.timeout)
+    this.pendingHttpRequests.delete(msg.id)
+
+    pending.resolve(new Response(msg.error, { status: 502 }))
+  }
+
+  private handleWsOpened(msg: WsOpenedMessage) {
+    const pending = this.pendingWsConnections.get(msg.connId)
+    if (!pending) {
+      return
+    }
+
+    clearTimeout(pending.timeout)
+    this.pendingWsConnections.delete(msg.connId)
+    // WebSocket is now fully connected, messages will flow via webSocketMessage
+  }
+
+  private handleWsFrame(tunnelId: string, msg: WsFrameResponseMessage) {
+    const sockets = this.ctx.getWebSockets(`ws:${msg.connId}`)
+    for (const ws of sockets) {
+      try {
+        if (msg.binary) {
+          ws.send(base64ToArrayBuffer(msg.data))
+        } else {
+          ws.send(msg.data)
+        }
+      } catch {}
+    }
+  }
+
+  private handleWsClosed(msg: WsClosedMessage) {
+    // Clear pending if still waiting
+    const pending = this.pendingWsConnections.get(msg.connId)
+    if (pending) {
+      clearTimeout(pending.timeout)
+      this.pendingWsConnections.delete(msg.connId)
+    }
+
+    // Close user WebSocket
+    const sockets = this.ctx.getWebSockets(`ws:${msg.connId}`)
+    for (const ws of sockets) {
+      try {
+        ws.close(msg.code, msg.reason)
+      } catch {}
+    }
+  }
+
+  private handleWsError(msg: WsErrorMessage) {
+    // Clear pending if still waiting
+    const pending = this.pendingWsConnections.get(msg.connId)
+    if (pending) {
+      clearTimeout(pending.timeout)
+      this.pendingWsConnections.delete(msg.connId)
+    }
+
+    // Close user WebSocket with error
+    const sockets = this.ctx.getWebSockets(`ws:${msg.connId}`)
+    for (const ws of sockets) {
+      try {
+        ws.close(4012, msg.error)
+      } catch {}
+    }
+  }
+}
+
+// ============================================
+// Utilities
+// ============================================
+
+function addCors(res: Response): Response {
+  const headers = new Headers(res.headers)
+  headers.set('Access-Control-Allow-Origin', '*')
+  headers.set('Access-Control-Allow-Headers', '*')
+  headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+    webSocket: (res as Response & { webSocket?: WebSocket }).webSocket,
+  })
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer)
+  let binary = ''
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i])
+  }
+  return btoa(binary)
+}
+
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes.buffer
+}
+
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailers',
+  'transfer-encoding',
+  'upgrade',
+])
+
+function isHopByHopHeader(header: string): boolean {
+  return HOP_BY_HOP_HEADERS.has(header.toLowerCase())
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+// ============================================
+// Messages: Worker/DO → Local Client (upstream)
+// ============================================
+
+// HTTP request to be proxied to local server
+export type HttpRequestMessage = {
+  type: 'http_request'
+  id: string
+  method: string
+  path: string
+  headers: Record<string, string>
+  body: string | null // base64 encoded for binary safety
+}
+
+// WebSocket connection request from remote user
+export type WsOpenMessage = {
+  type: 'ws_open'
+  connId: string
+  path: string
+  headers: Record<string, string>
+}
+
+// WebSocket frame from remote user
+export type WsFrameMessage = {
+  type: 'ws_frame'
+  connId: string
+  data: string // text or base64 for binary
+  binary?: boolean
+}
+
+// WebSocket close from remote user
+export type WsCloseMessage = {
+  type: 'ws_close'
+  connId: string
+  code: number
+  reason: string
+}
+
+// All messages that can be sent TO the local client
+export type UpstreamMessage =
+  | HttpRequestMessage
+  | WsOpenMessage
+  | WsFrameMessage
+  | WsCloseMessage
+
+// ============================================
+// Messages: Local Client → Worker/DO
+// ============================================
+
+// HTTP response from local server
+export type HttpResponseMessage = {
+  type: 'http_response'
+  id: string
+  status: number
+  headers: Record<string, string>
+  body: string | null // base64 encoded
+}
+
+// HTTP error (local server unavailable, timeout, etc)
+export type HttpErrorMessage = {
+  type: 'http_error'
+  id: string
+  error: string
+}
+
+// WebSocket opened successfully to local server
+export type WsOpenedMessage = {
+  type: 'ws_opened'
+  connId: string
+}
+
+// WebSocket frame from local server
+export type WsFrameResponseMessage = {
+  type: 'ws_frame'
+  connId: string
+  data: string
+  binary?: boolean
+}
+
+// WebSocket closed by local server
+export type WsClosedMessage = {
+  type: 'ws_closed'
+  connId: string
+  code: number
+  reason: string
+}
+
+// WebSocket error connecting to local server
+export type WsErrorMessage = {
+  type: 'ws_error'
+  connId: string
+  error: string
+}
+
+// All messages that can be sent FROM the local client
+export type DownstreamMessage =
+  | HttpResponseMessage
+  | HttpErrorMessage
+  | WsOpenedMessage
+  | WsFrameResponseMessage
+  | WsClosedMessage
+  | WsErrorMessage
+
+// ============================================
+// Events: DO → Remote Users (downstream WebSocket)
+// ============================================
+
+export type UpstreamConnectedEvent = {
+  event: 'upstream_connected'
+}
+
+export type UpstreamDisconnectedEvent = {
+  event: 'upstream_disconnected'
+}
+
+export type DownstreamEvent = UpstreamConnectedEvent | UpstreamDisconnectedEvent
+
+// ============================================
+// Helper functions
+// ============================================
+
+// Helper to create type-safe messages
+export function createMessage<T extends UpstreamMessage | DownstreamMessage>(
+  msg: T
+): string {
+  return JSON.stringify(msg)
+}
+
+// Helper to parse messages with type narrowing
+export function parseUpstreamMessage(data: string): UpstreamMessage | null {
+  try {
+    const msg = JSON.parse(data) as UpstreamMessage
+    if (!msg.type) {
+      return null
+    }
+    return msg
+  } catch {
+    return null
+  }
+}
+
+export function parseDownstreamMessage(data: string): DownstreamMessage | null {
+  try {
+    const msg = JSON.parse(data) as DownstreamMessage
+    if (!msg.type) {
+      return null
+    }
+    return msg
+  } catch {
+    return null
+  }
+}