typeclaw 0.1.0

package/src/portbroker/bind-with-forward.ts

@@ -0,0 +1,102 @@
+// Allocate an in-container port whose host-side forward succeeds.
+//
+// In-container LISTEN succeeds even when the host-side forward collides with
+// another container — each container has its own netns, so the procfs check
+// can't tell us anything about host-side availability. This helper closes
+// that gap: it calls a factory to bind a candidate port internally, waits
+// for the broker's `port-forward-result` event, and on failure tears the
+// candidate down and tries the next port. Used today by the agent-browser
+// plugin's dashboard proxy bind, where multiple typeclaw containers on one
+// host all want port 4848 externally and only the first to register wins.
+//
+// Returns the bound result on first success, or null after exhausting the
+// candidate list. Callers MUST treat null as "give up, no host-reachable
+// port available" — there is no further recourse without operator action
+// (e.g. stopping the colliding container).
+//
+// If the broker isn't reachable (no TYPECLAW_HOSTD_BROKER_TOKEN, broker
+// disconnected, etc.) the bus never receives results. The helper falls
+// through to optimistic mode: the first successful in-container bind is
+// returned without waiting, on the assumption that no broker means no
+// host-side cross-container collision is possible.
+
+import { subscribeForwardResult } from './forward-result-bus'
+
+export type BindResult<T> = {
+  port: number
+  hostPort: number | null
+  resource: T
+}
+
+export type BindFactory<T> = (port: number) => Promise<{ resource: T; close: () => void } | null>
+
+export type BindWithForwardOptions<T> = {
+  candidates: number[]
+  factory: BindFactory<T>
+  timeoutMs?: number
+  brokerEnabled?: boolean
+  onLog?: (msg: string) => void
+}
+
+const DEFAULT_TIMEOUT_MS = 2_000
+
+export async function bindWithForward<T>(opts: BindWithForwardOptions<T>): Promise<BindResult<T> | null> {
+  const log = opts.onLog ?? (() => {})
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const brokerEnabled = opts.brokerEnabled ?? defaultBrokerEnabled()
+
+  for (const port of opts.candidates) {
+    const bound = await opts.factory(port)
+    if (bound === null) {
+      log(`bind ${port}: factory returned null (in-container bind failed); trying next`)
+      continue
+    }
+
+    if (!brokerEnabled) {
+      log(`bind ${port}: broker disabled; returning optimistically`)
+      return { port, hostPort: null, resource: bound.resource }
+    }
+
+    const forward = await waitForForwardResult(port, timeoutMs)
+    if (forward.kind === 'ok') {
+      log(`bind ${port}: forwarded to host:${forward.hostPort}`)
+      return { port, hostPort: forward.hostPort, resource: bound.resource }
+    }
+
+    log(`bind ${port}: forward ${forward.kind === 'failed' ? `failed (${forward.reason})` : 'timed out'}; tearing down`)
+    try {
+      bound.close()
+    } catch {
+      // Close failures are non-fatal here; the next factory call may pick a
+      // different port and the orphaned listener will be reaped on process
+      // exit. Logging would just be noise.
+    }
+  }
+  return null
+}
+
+type WaitResult = { kind: 'ok'; hostPort: number } | { kind: 'failed'; reason: string } | { kind: 'timeout' }
+
+function waitForForwardResult(port: number, timeoutMs: number): Promise<WaitResult> {
+  return new Promise((resolve) => {
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      unsubscribe()
+      resolve({ kind: 'timeout' })
+    }, timeoutMs)
+    const unsubscribe = subscribeForwardResult((event) => {
+      if (event.port !== port || settled) return
+      settled = true
+      clearTimeout(timer)
+      unsubscribe()
+      resolve(event.ok ? { kind: 'ok', hostPort: event.hostPort } : { kind: 'failed', reason: event.reason })
+    })
+  })
+}
+
+function defaultBrokerEnabled(): boolean {
+  const token = process.env['TYPECLAW_HOSTD_BROKER_TOKEN']
+  return token !== undefined && token.length > 0
+}

package/src/portbroker/container-server.ts

@@ -0,0 +1,305 @@
+import { readFile } from 'node:fs/promises'
+
+import type { ServerWebSocket } from 'bun'
+
+import { parseProcNetTcp } from './proc-net-tcp'
+import { decodeBytes, encodeBytes, type ContainerToHostd, type HostdToContainer, type StreamId } from './protocol'
+
+export type BrokerWsData = { kind: 'portbroker'; authed: boolean }
+
+export type ContainerBrokerOptions = {
+  expectedToken: string
+  pollIntervalMs?: number
+  // Test seam: defaults to reading /proc/net/tcp + /proc/net/tcp6. Tests inject
+  // a fake. The function MUST resolve with the *concatenated* contents of both
+  // files (or just one if the system is IPv4-only) — the parser handles a
+  // mixed input gracefully.
+  readProcNetTcp?: () => Promise<string>
+  // Test seam: replaces Bun.connect for unit tests.
+  upstreamConnect?: (port: number, handlers: UpstreamHandlers) => Promise<UpstreamConnection>
+  onLog?: (event: ContainerBrokerLogEvent) => void
+  // In-container consumers (e.g. the agent-browser plugin) call this to learn
+  // whether a port that just opened a LISTEN socket got successfully forwarded
+  // to the host side. Without it, code that picks an in-container port has no
+  // way to detect host-side EADDRINUSE collisions across containers.
+  onForwardResult?: (event: ForwardResultEvent) => void
+}
+
+export type ForwardResultEvent =
+  | { port: number; ok: true; hostPort: number }
+  | { port: number; ok: false; reason: string }
+
+export type UpstreamHandlers = {
+  onData: (chunk: Uint8Array) => void
+  onClose: () => void
+  onError: (err: Error) => void
+}
+
+export type UpstreamConnection = {
+  write: (chunk: Uint8Array) => void
+  end: () => void
+}
+
+export type ContainerBrokerLogEvent =
+  | { kind: 'auth-failed'; reason: string }
+  | { kind: 'authed' }
+  | { kind: 'subscribed' }
+  | { kind: 'unsubscribed' }
+  | { kind: 'relay-open-failed'; streamId: StreamId; port: number; reason: string }
+  | { kind: 'relay-data-error'; streamId: StreamId; reason: string }
+  | { kind: 'unexpected'; reason: string }
+
+export type ContainerBroker = {
+  open: (ws: BrokerSocket) => void
+  message: (ws: BrokerSocket, raw: string | Buffer) => Promise<void>
+  close: (ws: BrokerSocket) => void
+}
+
+export type BrokerSocket = ServerWebSocket<BrokerWsData>
+
+const DEFAULT_POLL_MS = 500
+
+export function createContainerBroker(opts: ContainerBrokerOptions): ContainerBroker {
+  const log = opts.onLog ?? (() => {})
+  const pollMs = opts.pollIntervalMs ?? DEFAULT_POLL_MS
+  const readProc = opts.readProcNetTcp ?? defaultReadProcNetTcp
+  const connectUpstream = opts.upstreamConnect ?? defaultUpstreamConnect
+
+  type SessionState = {
+    pollTimer: ReturnType<typeof setInterval> | null
+    lastSnapshot: Map<number, '0.0.0.0' | '127.0.0.1'>
+    upstreams: Map<StreamId, UpstreamConnection>
+  }
+
+  const sessions = new WeakMap<BrokerSocket, SessionState>()
+
+  const send = (ws: BrokerSocket, msg: ContainerToHostd): void => {
+    try {
+      ws.send(JSON.stringify(msg))
+    } catch {}
+  }
+
+  const startWatcher = async (ws: BrokerSocket, state: SessionState): Promise<void> => {
+    const initial = await snapshotPorts()
+    state.lastSnapshot = initial
+    send(ws, {
+      type: 'port-listen-snapshot',
+      ports: Array.from(initial.entries()).map(([port, bindAddr]) => ({ port, bindAddr })),
+    })
+    state.pollTimer = setInterval(() => {
+      void tickWatcher(ws, state).catch(() => {})
+    }, pollMs)
+  }
+
+  const stopWatcher = (state: SessionState): void => {
+    if (state.pollTimer !== null) {
+      clearInterval(state.pollTimer)
+      state.pollTimer = null
+    }
+  }
+
+  const tickWatcher = async (ws: BrokerSocket, state: SessionState): Promise<void> => {
+    const next = await snapshotPorts()
+    for (const [port, bindAddr] of next) {
+      if (!state.lastSnapshot.has(port)) {
+        send(ws, { type: 'port-listen-opened', port, bindAddr })
+      }
+    }
+    for (const port of state.lastSnapshot.keys()) {
+      if (!next.has(port)) {
+        send(ws, { type: 'port-listen-closed', port })
+      }
+    }
+    state.lastSnapshot = next
+  }
+
+  const snapshotPorts = async (): Promise<Map<number, '0.0.0.0' | '127.0.0.1'>> => {
+    let raw: string
+    try {
+      raw = await readProc()
+    } catch {
+      return new Map()
+    }
+    const entries = parseProcNetTcp(raw)
+    const m = new Map<number, '0.0.0.0' | '127.0.0.1'>()
+    for (const e of entries) m.set(e.port, e.bindAddr)
+    return m
+  }
+
+  const handleRelayOpen = async (ws: BrokerSocket, state: SessionState, msg: HostdToContainer): Promise<void> => {
+    if (msg.type !== 'relay-open') return
+    const { streamId, port } = msg
+    try {
+      const conn = await connectUpstream(port, {
+        onData: (chunk) => {
+          send(ws, { type: 'relay-data', streamId, bytes: encodeBytes(chunk) })
+        },
+        onClose: () => {
+          if (state.upstreams.delete(streamId)) {
+            send(ws, { type: 'relay-close', streamId, side: 'upstream' })
+          }
+        },
+        onError: (err) => {
+          if (state.upstreams.delete(streamId)) {
+            log({ kind: 'relay-data-error', streamId, reason: err.message })
+            send(ws, { type: 'relay-close', streamId, side: 'upstream' })
+          }
+        },
+      })
+      state.upstreams.set(streamId, conn)
+      send(ws, { type: 'relay-open-ack', streamId })
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      log({ kind: 'relay-open-failed', streamId, port, reason })
+      send(ws, { type: 'relay-open-nack', streamId, reason })
+    }
+  }
+
+  return {
+    open(ws) {
+      sessions.set(ws, { pollTimer: null, lastSnapshot: new Map(), upstreams: new Map() })
+    },
+
+    async message(ws, raw) {
+      const state = sessions.get(ws)
+      if (!state) return
+      let msg: HostdToContainer
+      try {
+        msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf8')) as HostdToContainer
+      } catch {
+        log({ kind: 'unexpected', reason: 'invalid json' })
+        return
+      }
+
+      if (!ws.data.authed) {
+        if (msg.type !== 'broker-hello') {
+          log({ kind: 'auth-failed', reason: 'first message was not broker-hello' })
+          send(ws, { type: 'broker-hello-nack', reason: 'expected broker-hello first' })
+          ws.close(1008, 'auth required')
+          return
+        }
+        if (msg.token !== opts.expectedToken) {
+          log({ kind: 'auth-failed', reason: 'token mismatch' })
+          send(ws, { type: 'broker-hello-nack', reason: 'invalid token' })
+          ws.close(1008, 'invalid token')
+          return
+        }
+        ws.data.authed = true
+        log({ kind: 'authed' })
+        send(ws, { type: 'broker-hello-ack' })
+        return
+      }
+
+      switch (msg.type) {
+        case 'broker-hello':
+          return
+        case 'port-watch-subscribe':
+          if (state.pollTimer === null) {
+            log({ kind: 'subscribed' })
+            await startWatcher(ws, state)
+          }
+          return
+        case 'port-watch-unsubscribe':
+          if (state.pollTimer !== null) {
+            log({ kind: 'unsubscribed' })
+            stopWatcher(state)
+          }
+          return
+        case 'port-forward-result':
+          if (opts.onForwardResult) {
+            try {
+              opts.onForwardResult(
+                msg.ok
+                  ? { port: msg.port, ok: true, hostPort: msg.hostPort }
+                  : { port: msg.port, ok: false, reason: msg.reason },
+              )
+            } catch (err) {
+              log({
+                kind: 'unexpected',
+                reason: `onForwardResult threw: ${err instanceof Error ? err.message : String(err)}`,
+              })
+            }
+          }
+          return
+        case 'relay-open':
+          await handleRelayOpen(ws, state, msg)
+          return
+        case 'relay-data': {
+          const conn = state.upstreams.get(msg.streamId)
+          if (conn) conn.write(decodeBytes(msg.bytes))
+          return
+        }
+        case 'relay-close': {
+          const conn = state.upstreams.get(msg.streamId)
+          if (conn) {
+            state.upstreams.delete(msg.streamId)
+            try {
+              conn.end()
+            } catch {}
+          }
+          return
+        }
+      }
+    },
+
+    close(ws) {
+      const state = sessions.get(ws)
+      if (!state) return
+      stopWatcher(state)
+      for (const conn of state.upstreams.values()) {
+        try {
+          conn.end()
+        } catch {}
+      }
+      state.upstreams.clear()
+      sessions.delete(ws)
+    },
+  }
+}
+
+async function defaultReadProcNetTcp(): Promise<string> {
+  const tcp4 = await readFile('/proc/net/tcp', 'utf8').catch(() => '')
+  const tcp6 = await readFile('/proc/net/tcp6', 'utf8').catch(() => '')
+  return `${tcp4}\n${tcp6}`
+}
+
+function defaultUpstreamConnect(port: number, handlers: UpstreamHandlers): Promise<UpstreamConnection> {
+  return new Promise((resolve, reject) => {
+    let resolved = false
+    const sock = Bun.connect({
+      hostname: '127.0.0.1',
+      port,
+      socket: {
+        open(s) {
+          resolved = true
+          resolve({
+            write: (chunk: Uint8Array) => {
+              try {
+                s.write(chunk)
+              } catch {}
+            },
+            end: () => {
+              try {
+                s.end()
+              } catch {}
+            },
+          })
+        },
+        data(_s, data) {
+          handlers.onData(new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice())
+        },
+        close() {
+          handlers.onClose()
+        },
+        error(_s, error) {
+          if (!resolved) {
+            reject(error instanceof Error ? error : new Error(String(error)))
+          } else {
+            handlers.onError(error instanceof Error ? error : new Error(String(error)))
+          }
+        },
+      },
+    })
+    void sock
+  })
+}

package/src/portbroker/forward-result-bus.ts

@@ -0,0 +1,36 @@
+// In-process event bus for `port-forward-result` events emitted by the
+// host-side broker over the WS to the container side. Lives as a module-level
+// singleton so the run-loop wiring (src/run/index.ts) can publish events from
+// the broker callback while consumers (e.g. the agent-browser plugin's
+// bind-with-forward retry loop) subscribe by importing this module without
+// needing a reference to the ContainerBroker itself.
+//
+// Tests should call `__resetForwardResultBus()` in afterEach so subscriptions
+// from a previous test don't leak.
+
+import type { ForwardResultEvent } from './container-server'
+
+type Subscriber = (event: ForwardResultEvent) => void
+
+const subscribers = new Set<Subscriber>()
+
+export function publishForwardResult(event: ForwardResultEvent): void {
+  for (const sub of subscribers) {
+    try {
+      sub(event)
+    } catch {
+      // Subscriber failures must not block the bus or affect peer subscribers.
+    }
+  }
+}
+
+export function subscribeForwardResult(cb: Subscriber): () => void {
+  subscribers.add(cb)
+  return () => {
+    subscribers.delete(cb)
+  }
+}
+
+export function __resetForwardResultBus(): void {
+  subscribers.clear()
+}