typeclaw 0.1.0

package/src/portbroker/hostd-client.ts

@@ -0,0 +1,443 @@
+import type { Socket, TCPSocketListener } from 'bun'
+
+import type { PortForward } from '@/config'
+
+import { brokerEnabled, shouldForward } from './policy'
+import type { BindAddr } from './proc-net-tcp'
+import {
+  decodeBytes,
+  encodeBytes,
+  type ContainerToHostd,
+  type HostdToContainer,
+  type PortForwardEvent,
+  type StreamId,
+} from './protocol'
+
+export type BrokerOptions = {
+  containerName: string
+  cwd: string
+  policy: PortForward
+  // Resolves the host port currently published for this container's
+  // CONTAINER_PORT mapping. The broker calls this on each (re)connect attempt
+  // because the supervisor's restart can pick a different port if the previous
+  // one is now bound. Returning null signals "container not running yet" — the
+  // broker waits and retries.
+  resolveHostPort: () => Promise<number | null>
+  brokerToken: string
+  onEvent: (event: PortForwardEvent) => void
+  onLog?: (msg: string) => void
+  connectWs?: (url: string) => Promise<WsClient>
+  listenHost?: ListenHostFn
+  reconnectDelaysMs?: number[]
+  hostBindAddr?: string
+}
+
+export type WsClient = {
+  send: (msg: HostdToContainer) => void
+  close: () => void
+  onMessage: (cb: (msg: ContainerToHostd) => void) => void
+  onClose: (cb: () => void) => void
+}
+
+export type ListenHostFn = (
+  host: string,
+  port: number,
+  handlers: {
+    onConnection: (sock: HostSocket) => void
+  },
+) => Promise<HostListener>
+
+export type HostListener = {
+  port: number
+  stop: () => void
+}
+
+export type HostSocket = {
+  write: (chunk: Uint8Array) => void
+  end: () => void
+  onData: (cb: (chunk: Uint8Array) => void) => void
+  onClose: (cb: () => void) => void
+}
+
+export type Broker = {
+  start: () => void
+  stop: () => Promise<void>
+  forwardedPorts: () => number[]
+}
+
+const DEFAULT_RECONNECT_DELAYS = [1_000, 2_000, 4_000, 10_000]
+const DEFAULT_HOST_BIND = '127.0.0.1'
+
+export function createBroker(opts: BrokerOptions): Broker {
+  const log = opts.onLog ?? (() => {})
+  const reconnectDelays = opts.reconnectDelaysMs ?? DEFAULT_RECONNECT_DELAYS
+  const hostBind = opts.hostBindAddr ?? DEFAULT_HOST_BIND
+  const connectWs = opts.connectWs ?? defaultConnectWs
+  const listenHost = opts.listenHost ?? defaultListenHost
+
+  type ForwarderState = {
+    port: number
+    bindAddr: BindAddr
+    listener: HostListener
+    streams: Map<StreamId, { sock: HostSocket; opened: boolean; pending: Uint8Array[] }>
+  }
+
+  const forwarders = new Map<number, ForwarderState>()
+  let ws: WsClient | null = null
+  let nextStreamId: StreamId = 1
+  let stopped = false
+  let reconnectAttempt = 0
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+
+  const allocStreamId = (): StreamId => {
+    const id = nextStreamId
+    nextStreamId = nextStreamId >= 0x7fffffff ? 1 : nextStreamId + 1
+    return id
+  }
+
+  const emit = (event: PortForwardEvent): void => {
+    try {
+      opts.onEvent(event)
+    } catch (err) {
+      log(`onEvent threw: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  const closeStream = (port: number, streamId: StreamId, sendClose: boolean): void => {
+    const fwd = forwarders.get(port)
+    if (!fwd) return
+    const stream = fwd.streams.get(streamId)
+    if (!stream) return
+    fwd.streams.delete(streamId)
+    try {
+      stream.sock.end()
+    } catch {}
+    if (sendClose && ws) ws.send({ type: 'relay-close', streamId, side: 'downstream' })
+  }
+
+  const handleHostConnection = (port: number, sock: HostSocket): void => {
+    if (!ws) {
+      try {
+        sock.end()
+      } catch {}
+      return
+    }
+    const streamId = allocStreamId()
+    const fwd = forwarders.get(port)
+    if (!fwd) {
+      try {
+        sock.end()
+      } catch {}
+      return
+    }
+    fwd.streams.set(streamId, { sock, opened: false, pending: [] })
+
+    sock.onData((chunk) => {
+      const stream = fwd.streams.get(streamId)
+      if (!stream) return
+      const copy = new Uint8Array(chunk.byteLength)
+      copy.set(chunk)
+      if (stream.opened) {
+        if (ws) ws.send({ type: 'relay-data', streamId, bytes: encodeBytes(copy) })
+      } else {
+        stream.pending.push(copy)
+      }
+    })
+    sock.onClose(() => {
+      closeStream(port, streamId, true)
+    })
+
+    if (ws) ws.send({ type: 'relay-open', streamId, port })
+  }
+
+  const installForwarder = async (port: number, bindAddr: BindAddr): Promise<void> => {
+    if (forwarders.has(port)) return
+    if (!shouldForward({ policy: opts.policy, port })) {
+      // Policy excluded the port. Tell the container so it can stop waiting
+      // (e.g. the agent-browser plugin's bind-with-forward retry loop). Without
+      // this, the container would block on the forward-result timeout for
+      // every policy-denied port.
+      if (ws) ws.send({ type: 'port-forward-result', port, ok: false, reason: 'policy excluded' })
+      return
+    }
+    try {
+      const listener = await listenHost(hostBind, port, {
+        onConnection: (sock) => handleHostConnection(port, sock),
+      })
+      forwarders.set(port, { port, bindAddr, listener, streams: new Map() })
+      emit({ kind: 'port-forward-opened', containerName: opts.containerName, port, bindAddr })
+      if (ws) ws.send({ type: 'port-forward-result', port, ok: true, hostPort: listener.port })
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      log(`forward bind ${port}: ${reason}`)
+      emit({ kind: 'port-forward-failed', containerName: opts.containerName, port, reason })
+      if (ws) ws.send({ type: 'port-forward-result', port, ok: false, reason })
+    }
+  }
+
+  const removeForwarder = (port: number, reason: 'container-released' | 'host-error'): void => {
+    const fwd = forwarders.get(port)
+    if (!fwd) return
+    forwarders.delete(port)
+    try {
+      fwd.listener.stop()
+    } catch {}
+    for (const [streamId] of fwd.streams) closeStream(port, streamId, false)
+    emit({ kind: 'port-forward-closed', containerName: opts.containerName, port, reason })
+  }
+
+  const teardownAllForwarders = (reason: 'broker-stopped' | 'deregistered' | 'host-error'): void => {
+    for (const port of Array.from(forwarders.keys())) {
+      const fwd = forwarders.get(port)
+      if (!fwd) continue
+      forwarders.delete(port)
+      try {
+        fwd.listener.stop()
+      } catch {}
+      for (const [streamId] of fwd.streams) {
+        const stream = fwd.streams.get(streamId)
+        try {
+          stream?.sock.end()
+        } catch {}
+      }
+      emit({ kind: 'port-forward-closed', containerName: opts.containerName, port, reason })
+    }
+  }
+
+  const handleContainerMessage = (msg: ContainerToHostd): void => {
+    switch (msg.type) {
+      case 'broker-hello-ack':
+        if (ws) ws.send({ type: 'port-watch-subscribe' })
+        return
+      case 'broker-hello-nack':
+        log(`broker-hello rejected: ${msg.reason}`)
+        if (ws) ws.close()
+        return
+      case 'port-listen-snapshot':
+        for (const { port, bindAddr } of msg.ports) {
+          void installForwarder(port, bindAddr)
+        }
+        return
+      case 'port-listen-opened':
+        void installForwarder(msg.port, msg.bindAddr)
+        return
+      case 'port-listen-closed':
+        removeForwarder(msg.port, 'container-released')
+        return
+      case 'relay-open-ack': {
+        const port = findStreamPort(msg.streamId)
+        if (port === null) return
+        const fwd = forwarders.get(port)!
+        const stream = fwd.streams.get(msg.streamId)
+        if (!stream) return
+        stream.opened = true
+        if (ws) {
+          for (const buf of stream.pending)
+            ws.send({ type: 'relay-data', streamId: msg.streamId, bytes: encodeBytes(buf) })
+        }
+        stream.pending = []
+        return
+      }
+      case 'relay-open-nack': {
+        const port = findStreamPort(msg.streamId)
+        if (port !== null) closeStream(port, msg.streamId, false)
+        return
+      }
+      case 'relay-data': {
+        const port = findStreamPort(msg.streamId)
+        if (port === null) return
+        const stream = forwarders.get(port)?.streams.get(msg.streamId)
+        if (!stream) return
+        try {
+          stream.sock.write(decodeBytes(msg.bytes))
+        } catch {}
+        return
+      }
+      case 'relay-close': {
+        const port = findStreamPort(msg.streamId)
+        if (port !== null) closeStream(port, msg.streamId, false)
+        return
+      }
+    }
+  }
+
+  const findStreamPort = (streamId: StreamId): number | null => {
+    for (const [port, fwd] of forwarders) {
+      if (fwd.streams.has(streamId)) return port
+    }
+    return null
+  }
+
+  const connect = async (): Promise<void> => {
+    if (stopped) return
+    const hostPort = await opts.resolveHostPort()
+    if (hostPort === null) {
+      scheduleReconnect()
+      return
+    }
+    const url = `ws://127.0.0.1:${hostPort}/portbroker`
+    let client: WsClient
+    try {
+      client = await connectWs(url)
+    } catch (err) {
+      log(`ws connect ${url}: ${err instanceof Error ? err.message : String(err)}`)
+      scheduleReconnect()
+      return
+    }
+    ws = client
+    reconnectAttempt = 0
+
+    client.onMessage(handleContainerMessage)
+    client.onClose(() => {
+      ws = null
+      teardownAllForwarders('host-error')
+      scheduleReconnect()
+    })
+
+    client.send({ type: 'broker-hello', token: opts.brokerToken })
+  }
+
+  const scheduleReconnect = (): void => {
+    if (stopped) return
+    const delay = reconnectDelays[Math.min(reconnectAttempt, reconnectDelays.length - 1)] ?? 10_000
+    reconnectAttempt += 1
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null
+      void connect()
+    }, delay)
+  }
+
+  return {
+    start() {
+      if (!brokerEnabled(opts.policy)) {
+        log(`portForward disabled (allow:[]) — broker not started for ${opts.containerName}`)
+        return
+      }
+      void connect()
+    },
+    async stop() {
+      stopped = true
+      if (reconnectTimer !== null) {
+        clearTimeout(reconnectTimer)
+        reconnectTimer = null
+      }
+      teardownAllForwarders('broker-stopped')
+      if (ws) {
+        try {
+          ws.close()
+        } catch {}
+        ws = null
+      }
+    },
+    forwardedPorts() {
+      return Array.from(forwarders.keys())
+    },
+  }
+}
+
+async function defaultConnectWs(url: string): Promise<WsClient> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let resolved = false
+    const messageCbs: Array<(msg: ContainerToHostd) => void> = []
+    const closeCbs: Array<() => void> = []
+    const client: WsClient = {
+      send: (msg) => {
+        try {
+          ws.send(JSON.stringify(msg))
+        } catch {}
+      },
+      close: () => {
+        try {
+          ws.close()
+        } catch {}
+      },
+      onMessage: (cb) => {
+        messageCbs.push(cb)
+      },
+      onClose: (cb) => {
+        closeCbs.push(cb)
+      },
+    }
+    ws.onopen = (): void => {
+      resolved = true
+      resolve(client)
+    }
+    ws.onmessage = (ev: MessageEvent): void => {
+      let msg: ContainerToHostd
+      try {
+        msg = JSON.parse(typeof ev.data === 'string' ? ev.data : '') as ContainerToHostd
+      } catch {
+        return
+      }
+      for (const cb of messageCbs) cb(msg)
+    }
+    ws.onerror = (): void => {
+      if (!resolved) reject(new Error(`ws error connecting to ${url}`))
+    }
+    ws.onclose = (): void => {
+      for (const cb of closeCbs) cb()
+    }
+  })
+}
+
+function defaultListenHost(
+  host: string,
+  port: number,
+  handlers: { onConnection: (sock: HostSocket) => void },
+): Promise<HostListener> {
+  return new Promise((resolve, reject) => {
+    type SocketState = { dataCbs: Array<(c: Uint8Array) => void>; closeCbs: Array<() => void> }
+    let listener: TCPSocketListener<SocketState> | null = null
+    try {
+      listener = Bun.listen<SocketState>({
+        hostname: host,
+        port,
+        socket: {
+          open(s: Socket<SocketState>) {
+            s.data = { dataCbs: [], closeCbs: [] }
+            const sockApi: HostSocket = {
+              write: (chunk) => {
+                try {
+                  s.write(chunk)
+                } catch {}
+              },
+              end: () => {
+                try {
+                  s.end()
+                } catch {}
+              },
+              onData: (cb) => {
+                s.data.dataCbs.push(cb)
+              },
+              onClose: (cb) => {
+                s.data.closeCbs.push(cb)
+              },
+            }
+            handlers.onConnection(sockApi)
+          },
+          data(s: Socket<SocketState>, data: Buffer) {
+            const copy = new Uint8Array(data.byteLength)
+            copy.set(data)
+            for (const cb of s.data.dataCbs) cb(copy)
+          },
+          close(s: Socket<SocketState>) {
+            for (const cb of s.data.closeCbs) cb()
+          },
+          error() {},
+        },
+      })
+      const captured = listener
+      resolve({
+        port: captured?.port ?? port,
+        stop: () => {
+          try {
+            captured?.stop(true)
+          } catch {}
+        },
+      })
+    } catch (err) {
+      reject(err instanceof Error ? err : new Error(String(err)))
+    }
+  })
+}

package/src/portbroker/index.ts

@@ -0,0 +1,33 @@
+export { brokerEnabled, shouldForward } from './policy'
+export { parseProcNetTcp, type BindAddr, type ListenEntry } from './proc-net-tcp'
+export {
+  decodeBytes,
+  encodeBytes,
+  type ContainerToHostd,
+  type HostdToContainer,
+  type PortForwardCloseReason,
+  type PortForwardEvent,
+  type StreamId,
+} from './protocol'
+export {
+  createContainerBroker,
+  type BrokerSocket,
+  type BrokerWsData,
+  type ContainerBroker,
+  type ContainerBrokerLogEvent,
+  type ContainerBrokerOptions,
+  type ForwardResultEvent,
+  type UpstreamConnection,
+  type UpstreamHandlers,
+} from './container-server'
+export { __resetForwardResultBus, publishForwardResult, subscribeForwardResult } from './forward-result-bus'
+export { bindWithForward, type BindFactory, type BindResult, type BindWithForwardOptions } from './bind-with-forward'
+export {
+  createBroker,
+  type Broker,
+  type BrokerOptions,
+  type HostListener,
+  type HostSocket,
+  type ListenHostFn,
+  type WsClient,
+} from './hostd-client'

package/src/portbroker/policy.ts

@@ -0,0 +1,24 @@
+import type { PortForward } from '@/config'
+import { CONTAINER_PORT } from '@/container'
+
+export type ShouldForwardOptions = {
+  policy: PortForward
+  port: number
+  containerPort?: number
+}
+
+// CONTAINER_PORT is always implicitly excluded: that mapping is owned by
+// `docker run -p ${hostPort}:${CONTAINER_PORT}` and forwarding it again would
+// fight the published port. Tests can override containerPort to verify the
+// implicit exclusion independently of the global constant.
+export function shouldForward({ policy, port, containerPort = CONTAINER_PORT }: ShouldForwardOptions): boolean {
+  if (port === containerPort) return false
+  if (Array.isArray(policy.allow)) return policy.allow.includes(port)
+  if (policy.deny?.includes(port)) return false
+  return true
+}
+
+export function brokerEnabled(policy: PortForward): boolean {
+  if (Array.isArray(policy.allow) && policy.allow.length === 0) return false
+  return true
+}

package/src/portbroker/proc-net-tcp.ts

@@ -0,0 +1,72 @@
+export type BindAddr = '0.0.0.0' | '127.0.0.1'
+
+export type ListenEntry = {
+  port: number
+  bindAddr: BindAddr
+}
+
+const STATE_LISTEN = '0A'
+
+// /proc/net/tcp[6] format (one row per connection):
+//   sl  local_address          rem_address            st  tx_queue:rx_queue  ...
+//   0:  0100007F:1F90          00000000:0000          0A  00000000:00000000  ...
+//
+// `local_address` is `<ip-hex>:<port-hex>`. The IP is little-endian for IPv4
+// (so "0100007F" = 127.0.0.1) and big-endian-grouped for IPv6. We only care
+// about the LISTEN state (st === '0A') and the bind side (loopback vs any).
+//
+// Parser is loose-by-design: anything that doesn't look like a LISTEN row is
+// silently skipped (header rows, partial reads, kernel format additions). We
+// never throw — the procfs file changes between syscalls and a transient
+// parse failure must not propagate up.
+export function parseProcNetTcp(input: string): ListenEntry[] {
+  const out: ListenEntry[] = []
+  for (const raw of input.split('\n')) {
+    const line = raw.trim()
+    if (line.length === 0) continue
+    const cols = line.split(/\s+/)
+    if (cols.length < 4) continue
+    const localAddr = cols[1]
+    const state = cols[3]
+    if (state !== STATE_LISTEN || localAddr === undefined) continue
+    const colonIdx = localAddr.lastIndexOf(':')
+    if (colonIdx < 0) continue
+    const ipHex = localAddr.slice(0, colonIdx)
+    const portHex = localAddr.slice(colonIdx + 1)
+    const port = Number.parseInt(portHex, 16)
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) continue
+    const bindAddr = classifyBindAddr(ipHex)
+    if (bindAddr === null) continue
+    out.push({ port, bindAddr })
+  }
+  return dedupePreferringLoopback(out)
+}
+
+function classifyBindAddr(ipHex: string): BindAddr | null {
+  if (ipHex.length === 8) {
+    if (ipHex === '00000000') return '0.0.0.0'
+    if (ipHex.toUpperCase() === '0100007F') return '127.0.0.1'
+    return null
+  }
+  if (ipHex.length === 32) {
+    if (ipHex === '00000000000000000000000000000000') return '0.0.0.0'
+    if (ipHex === '00000000000000000000000001000000') return '127.0.0.1'
+    return null
+  }
+  return null
+}
+
+// A server bound to both 0.0.0.0 (IPv4) and ::1 (IPv6) appears twice in our
+// merged tcp+tcp6 input. Collapse to one entry per port. If the same port has
+// both classifications, prefer 127.0.0.1 (the more restrictive one) so the
+// downstream forwarder routes through `Bun.connect('127.0.0.1', port)` either
+// way — the loopback path works for both bind addresses.
+function dedupePreferringLoopback(entries: ListenEntry[]): ListenEntry[] {
+  const byPort = new Map<number, BindAddr>()
+  for (const e of entries) {
+    const existing = byPort.get(e.port)
+    if (existing === undefined) byPort.set(e.port, e.bindAddr)
+    else if (existing === '0.0.0.0' && e.bindAddr === '127.0.0.1') byPort.set(e.port, '127.0.0.1')
+  }
+  return Array.from(byPort.entries()).map(([port, bindAddr]) => ({ port, bindAddr }))
+}

package/src/portbroker/protocol.ts

@@ -0,0 +1,39 @@
+import type { BindAddr } from './proc-net-tcp'
+
+export type StreamId = number
+
+export type HostdToContainer =
+  | { type: 'broker-hello'; token: string }
+  | { type: 'port-watch-subscribe' }
+  | { type: 'port-watch-unsubscribe' }
+  | { type: 'port-forward-result'; port: number; ok: true; hostPort: number }
+  | { type: 'port-forward-result'; port: number; ok: false; reason: string }
+  | { type: 'relay-open'; streamId: StreamId; port: number }
+  | { type: 'relay-data'; streamId: StreamId; bytes: string }
+  | { type: 'relay-close'; streamId: StreamId; side: 'upstream' | 'downstream' }
+
+export type ContainerToHostd =
+  | { type: 'broker-hello-ack' }
+  | { type: 'broker-hello-nack'; reason: string }
+  | { type: 'port-listen-snapshot'; ports: Array<{ port: number; bindAddr: BindAddr }> }
+  | { type: 'port-listen-opened'; port: number; bindAddr: BindAddr }
+  | { type: 'port-listen-closed'; port: number }
+  | { type: 'relay-open-ack'; streamId: StreamId }
+  | { type: 'relay-open-nack'; streamId: StreamId; reason: string }
+  | { type: 'relay-data'; streamId: StreamId; bytes: string }
+  | { type: 'relay-close'; streamId: StreamId; side: 'upstream' | 'downstream' }
+
+export type PortForwardEvent =
+  | { kind: 'port-forward-opened'; containerName: string; port: number; bindAddr: BindAddr }
+  | { kind: 'port-forward-closed'; containerName: string; port: number; reason: PortForwardCloseReason }
+  | { kind: 'port-forward-failed'; containerName: string; port: number; reason: string }
+
+export type PortForwardCloseReason = 'container-released' | 'host-error' | 'deregistered' | 'broker-stopped'
+
+export function encodeBytes(buf: Uint8Array): string {
+  return Buffer.from(buf).toString('base64')
+}
+
+export function decodeBytes(s: string): Uint8Array {
+  return new Uint8Array(Buffer.from(s, 'base64'))
+}

package/src/reload/client.ts

@@ -0,0 +1,59 @@
+import type { ClientMessage, ServerMessage } from '@/shared'
+
+import type { ReloadResult } from './types'
+
+export type RequestReloadOptions = {
+  url: string
+  scope?: string
+  timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+export async function requestReload({
+  url,
+  scope,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}: RequestReloadOptions): Promise<ReloadResult[]> {
+  const ws = new WebSocket(url)
+
+  await new Promise<void>((resolve, reject) => {
+    const onOpen = () => {
+      cleanup()
+      resolve()
+    }
+    const onError = (err: unknown) => {
+      cleanup()
+      reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+    }
+    const cleanup = () => {
+      ws.removeEventListener('open', onOpen)
+      ws.removeEventListener('error', onError)
+    }
+    ws.addEventListener('open', onOpen, { once: true })
+    ws.addEventListener('error', onError, { once: true })
+  })
+
+  try {
+    const request: ClientMessage = scope ? { type: 'reload', scope } : { type: 'reload' }
+    ws.send(JSON.stringify(request))
+
+    return await new Promise<ReloadResult[]>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        ws.removeEventListener('message', onMessage)
+        reject(new Error(`timed out waiting for reload_result after ${timeoutMs}ms`))
+      }, timeoutMs)
+
+      const onMessage = (event: MessageEvent) => {
+        const msg = JSON.parse(String(event.data)) as ServerMessage
+        if (msg.type !== 'reload_result') return
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve(msg.results)
+      }
+      ws.addEventListener('message', onMessage)
+    })
+  } finally {
+    ws.close()
+  }
+}

package/src/reload/index.ts

@@ -0,0 +1,3 @@
+export { requestReload, type RequestReloadOptions } from './client'
+export { ReloadRegistry } from './registry'
+export type { Reloadable, ReloadAllResult, ReloadResult } from './types'