@shogo-ai/worker 2.3.12 → 2.3.13

package/src/lib/__tests__/helpers/fake-cloud.ts

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * A fake Shogo cloud, in its own process, for the tunnel-block test.
+ *
+ * It has to be a separate process and not an in-test server: the test blocks the
+ * main thread on purpose, and an observer on that thread cannot see the pings it
+ * is supposed to be policing. Here the pings keep flowing while the API's thread
+ * is busy, which is exactly how the real cloud behaves.
+ *
+ * Speaks the real protocol: `POST /api/instances/heartbeat` (asking for a socket
+ * and advertising its URL), `GET /api/instances/ws` upgrade, `{type:'ping'}`
+ * every 40ms answered by `{type:'pong'}`, and a close (1006) for a socket that
+ * misses the deadline — the same idle check the cloud runs.
+ *
+ * Reports over stdout, one JSON object per line: `ready`, `pong`, `kill`,
+ * `request`, `close`.
+ */
+
+const PING_INTERVAL_MS = Number(process.env.FAKE_CLOUD_PING_MS ?? 40)
+const PONG_DEADLINE_MS = Number(process.env.FAKE_CLOUD_DEADLINE_MS ?? 120)
+
+const say = (line: Record<string, unknown>) => {
+  process.stdout.write(`${JSON.stringify(line)}\n`)
+}
+
+let socket: any = null
+let awaitingPongSince: number | null = null
+let kills = 0
+
+const server = Bun.serve({
+  port: 0,
+  hostname: '127.0.0.1',
+  fetch(req, srv) {
+    const url = new URL(req.url)
+    if (url.pathname === '/api/instances/ws') {
+      if (srv.upgrade(req)) return undefined as any
+      return new Response('upgrade failed', { status: 400 })
+    }
+    if (url.pathname === '/api/instances/heartbeat') {
+      return Response.json({
+        instanceId: 'inst-worker-1',
+        wsRequested: true,
+        nextPollIn: 30,
+        wsUrl: `ws://127.0.0.1:${srv.port}`,
+      })
+    }
+    return new Response('{}', { status: 404 })
+  },
+  websocket: {
+    open(ws) {
+      socket = ws
+      awaitingPongSince = null
+    },
+    message(_ws, raw) {
+      let message: any
+      try {
+        message = JSON.parse(String(raw))
+      } catch {
+        return
+      }
+      if (message.type === 'pong') {
+        awaitingPongSince = null
+        say({ event: 'pong' })
+        return
+      }
+      if (message.type === 'response') {
+        say({ event: 'request', status: message.status, body: String(message.body ?? '').slice(0, 200) })
+        return
+      }
+      if (message.type === 'stream-chunk' || message.type === 'stream-end') {
+        say({ event: 'request', status: 200, body: 'stream' })
+      }
+    },
+    close(_ws, code) {
+      socket = null
+      say({ event: 'close', code })
+    },
+  },
+})
+
+setInterval(() => {
+  if (!socket) return
+  if (awaitingPongSince === null) {
+    awaitingPongSince = Date.now()
+  } else if (Date.now() - awaitingPongSince > PONG_DEADLINE_MS) {
+    kills += 1
+    say({ event: 'kill', kills })
+    try {
+      socket.close(1006, 'no pong')
+    } catch {
+      // already gone
+    }
+    socket = null
+    awaitingPongSince = null
+    return
+  }
+  try {
+    socket.send(JSON.stringify({ type: 'ping' }))
+  } catch {
+    // socket went away
+  }
+}, PING_INTERVAL_MS)
+
+// The test drives requests over stdin (one JSON object per line), because a
+// spawned child has no IPC channel to listen on.
+void (async () => {
+  let buffer = ''
+  const decoder = new TextDecoder()
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk as Uint8Array, { stream: true })
+    let newline = buffer.indexOf('\n')
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).trim()
+      buffer = buffer.slice(newline + 1)
+      newline = buffer.indexOf('\n')
+      if (!line) continue
+      let message: any
+      try {
+        message = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if (message?.type === 'request' && socket) {
+        socket.send(
+          JSON.stringify({
+            type: 'request',
+            requestId: message.requestId,
+            method: 'GET',
+            path: message.path,
+            headers: {},
+          }),
+        )
+      }
+    }
+  }
+})()
+
+say({ event: 'ready', port: server.port })

package/src/lib/__tests__/tunnel-worker-block.test.ts

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * The tunnel's socket survives a busy main thread (SHO-185 §5).
+ *
+ * This is the test the whole Worker move exists for. The fake cloud lives in its
+ * own process (`helpers/fake-cloud.ts`) because the point of the test is to block
+ * *this* thread: an observer here would be blocked too and could not see the
+ * pings it is supposed to be policing.
+ *
+ * Two cases, same cloud, same block:
+ *   • on its own thread — pongs keep flowing, the socket stays open, and a
+ *     tunneled request still round-trips afterwards;
+ *   • on the API's thread — the deadline passes unanswered and the cloud closes
+ *     the socket (1006). That is the bug, and without it the first case would
+ *     only prove that a socket somewhere stayed open.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { fileURLToPath } from 'node:url'
+import { startTunnelInWorker } from '../tunnel-host'
+import { WorkerTunnel, type RuntimeResolver } from '../tunnel'
+
+const BLOCK_MS = 400
+
+interface FakeCloud {
+  cloudUrl: string
+  pongs: number
+  kills: number
+  closeCodes: number[]
+  requests: { status: number; body: string }[]
+  sendRequest: (requestId: string, path: string) => void
+  stop: () => void
+}
+
+/**
+ * Spawn the fake cloud and read its stdout, one JSON event per line.
+ *
+ * The child is `bun --no-env-file` so the workspace's `.env` cannot point it at a
+ * real cloud, and it prints `ready` with the port it bound before anything else.
+ */
+async function startFakeCloud(): Promise<FakeCloud> {
+  // `pathname` stays percent-encoded, and this checkout's path has a space in it.
+  const entry = fileURLToPath(new URL('./helpers/fake-cloud.ts', import.meta.url))
+  const child = Bun.spawn(['bun', '--no-env-file', entry], {
+    stdout: 'pipe',
+    stdin: 'pipe',
+    stderr: 'inherit',
+    env: { ...process.env, FAKE_CLOUD_PING_MS: '40', FAKE_CLOUD_DEADLINE_MS: '120' },
+  })
+
+  const state = {
+    pongs: 0,
+    kills: 0,
+    closeCodes: [] as number[],
+    requests: [] as { status: number; body: string }[],
+  }
+
+  let port = 0
+  let buffer = ''
+  let settleReady: (port: number) => void = () => {}
+  const ready = new Promise<number>((resolve) => {
+    settleReady = resolve
+  })
+
+  const drain = (async () => {
+    const stream = child.stdout as ReadableStream<Uint8Array>
+    const reader = stream.getReader()
+    const decoder = new TextDecoder()
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      let newline = buffer.indexOf('\n')
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline).trim()
+        buffer = buffer.slice(newline + 1)
+        newline = buffer.indexOf('\n')
+        if (!line) continue
+        let event: any
+        try {
+          event = JSON.parse(line)
+        } catch {
+          continue
+        }
+        if (event.event === 'ready') {
+          port = Number(event.port)
+          settleReady(port)
+        } else if (event.event === 'pong') state.pongs += 1
+        else if (event.event === 'kill') state.kills += 1
+        else if (event.event === 'close') state.closeCodes.push(Number(event.code))
+        else if (event.event === 'request') {
+          state.requests.push({ status: Number(event.status), body: String(event.body ?? '') })
+        }
+      }
+    }
+  })().catch(() => {})
+
+  await ready
+
+  return {
+    cloudUrl: `http://127.0.0.1:${port}`,
+    get pongs() {
+      return state.pongs
+    },
+    get kills() {
+      return state.kills
+    },
+    get closeCodes() {
+      return state.closeCodes
+    },
+    get requests() {
+      return state.requests
+    },
+    sendRequest(requestId: string, path: string) {
+      child.stdin?.write(`${JSON.stringify({ type: 'request', requestId, path })}\n`)
+    },
+    stop() {
+      try {
+        child.kill()
+      } catch {
+        // already gone
+      }
+      void drain
+    },
+  }
+}
+
+let localApi: Server
+let localPort = 0
+
+const resolver: RuntimeResolver = {
+  async resolveLocalUrl(pathWithQuery: string) {
+    return `http://127.0.0.1:${localPort}${pathWithQuery}`
+  },
+  async deriveRuntimeToken() {
+    return 'runtime-token'
+  },
+  getActiveProjects() {
+    return ['proj-1']
+  },
+  status() {
+    return { status: 'running', agentPort: 1234 }
+  },
+}
+
+beforeAll(async () => {
+  localApi = createServer((req, res) => {
+    res.setHeader('content-type', 'application/json')
+    res.end(JSON.stringify({ answeredBy: 'local-api', path: req.url }))
+  })
+  await new Promise<void>((resolve) => localApi.listen(0, '127.0.0.1', () => resolve()))
+  localPort = (localApi.address() as AddressInfo).port
+})
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => localApi.close(() => resolve()))
+})
+
+/** Burn this thread — the local API's thread — past the cloud's deadline. */
+function blockMainThread(ms: number): void {
+  const until = Date.now() + ms
+  while (Date.now() < until) {
+    // A busy loop is the honest stand-in for a `lsof` or a big write.
+  }
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+async function waitFor(predicate: () => boolean, timeoutMs = 8_000): Promise<void> {
+  const started = Date.now()
+  while (Date.now() < started + timeoutMs) {
+    if (predicate()) return
+    await wait(20)
+  }
+  throw new Error(`timed out after ${timeoutMs}ms waiting for a condition that never held`)
+}
+
+describe('a tunnel on its own thread', () => {
+  test('keeps its socket through a main thread blocked for 4× the ping interval', async () => {
+    const cloud = await startFakeCloud()
+    const host = startTunnelInWorker({
+      apiKey: 'test-key',
+      cloudUrl: cloud.cloudUrl,
+      name: 'worker-test',
+      kind: 'desktop',
+      resolver,
+      logger: { log: () => {}, warn: () => {}, error: () => {} },
+    })
+
+    try {
+      await host.ready()
+      // The socket only opens once the cloud asks for it on a heartbeat.
+      await waitFor(() => cloud.pongs > 0)
+      const before = cloud.pongs
+
+      blockMainThread(BLOCK_MS)
+
+      // The cloud never reached for the close code, and the pongs never stopped.
+      expect(cloud.kills).toBe(0)
+      expect(cloud.closeCodes).toEqual([])
+      await waitFor(() => cloud.pongs > before, 3_000)
+
+      // And the tunnel still forwards afterwards: a request pushed down the
+      // socket comes back from the local API.
+      cloud.sendRequest('req-after-block', '/api/projects')
+      await waitFor(() => cloud.requests.some((entry) => entry.status === 200), 8_000)
+      expect(cloud.requests.find((entry) => entry.status === 200)?.body).toContain('local-api')
+    } finally {
+      host.stop()
+      cloud.stop()
+    }
+  }, 40_000)
+
+  test('the same block kills an in-process tunnel — the bug §5 fixes', async () => {
+    const cloud = await startFakeCloud()
+    const tunnel = new WorkerTunnel({
+      apiKey: 'test-key',
+      cloudUrl: cloud.cloudUrl,
+      name: 'in-process',
+      kind: 'desktop',
+      resolver,
+      logger: { log: () => {}, warn: () => {}, error: () => {} },
+    })
+
+    try {
+      tunnel.start()
+      await waitFor(() => cloud.pongs > 0)
+
+      blockMainThread(BLOCK_MS)
+
+      // The cloud's deadline passed with the pong stuck behind the block, so it
+      // closed the socket: this is the 1006 the person sees as "machine offline".
+      await waitFor(() => cloud.kills > 0)
+      expect(cloud.kills).toBeGreaterThan(0)
+    } finally {
+      tunnel.stop()
+      cloud.stop()
+    }
+  }, 40_000)
+})

package/src/lib/tunnel-host.ts

@@ -0,0 +1,253 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Main-thread side of the tunnel Worker (SHO-185 §5)
+ *
+ * `startTunnelInWorker()` puts `WorkerTunnel` on its own thread and answers the
+ * questions it cannot answer itself: which local URL a path maps to, the runtime
+ * token for a project, and — once per heartbeat — which runtimes are up. The
+ * socket, its timers and its local `fetch`es never touch this thread, so a busy
+ * local API cannot cost the machine its connection any more.
+ */
+
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import type { ResolveRejection, RuntimeResolver } from './tunnel'
+import type { HostProjectStatus, HostReply, WorkerEvent, WorkerRequest } from './tunnel-worker'
+
+/**
+ * How long the worker gets to answer `ready` before it is written off.
+ *
+ * The worker posts `ready` from its `init` handler, before it touches the
+ * network, so this is only ever spent on a worker that never came up at all
+ * (crashed on load, wrong entry file, a runtime that quietly refuses to spawn
+ * one). A tunnel that is slow to connect is not slow to be ready.
+ */
+const READY_TIMEOUT_MS = 10_000
+
+/** This module's directory: `resources/bundle/` once packaged, `src/lib/` in a checkout. */
+const HOST_DIR = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * The Worker entry file that sits next to this module.
+ *
+ * A source checkout has only `tunnel-worker.ts`; the desktop ships the compiled
+ * `resources/bundle/tunnel-worker.js` (see `apps/desktop/scripts/bundle-api.mjs`)
+ * and no source tree at all. Relative to `import.meta.url` — which inside
+ * `resources/bundle/api.js` is the bundle itself — `new URL('./tunnel-worker.ts')`
+ * could only ever name the checkout, so the packaged app asked for a `.ts` file
+ * that was never shipped, the worker never started, and the tunnel vanished.
+ *
+ * `SHOGO_TUNNEL_WORKER_PATH` overrides the search for packagers that relocate
+ * the bundle.
+ */
+export function resolveTunnelWorkerEntry(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.SHOGO_TUNNEL_WORKER_PATH?.trim()
+  if (override) return override
+
+  const candidates = [join(HOST_DIR, 'tunnel-worker.js'), join(HOST_DIR, 'tunnel-worker.ts')]
+  const found = candidates.find((candidate) => existsSync(candidate))
+  if (found) return found
+
+  throw new Error(
+    `no tunnel worker entry next to ${HOST_DIR} (looked for ${candidates.join(', ')}); ` +
+      `packaging must ship the tunnel-worker build output beside the API bundle`,
+  )
+}
+
+export interface TunnelHostOptions {
+  apiKey: string
+  cloudUrl: string
+  name?: string
+  kind?: string
+  wsUrlOverride?: string
+  /** Everything the tunnel asks about the local machine. */
+  resolver: RuntimeResolver
+  logger?: Pick<Console, 'log' | 'warn' | 'error'>
+  onAuthRevoked?: (reason: string) => void
+  /** Called when the cloud tells us this machine's instance id (or forgets it). */
+  onInstanceId?: (instanceId: string | null) => void
+  /** Called when the socket's connected state changes. */
+  onConnection?: (connected: boolean) => void
+  /** The worker died (on load or later). The host is not usable after this. */
+  onWorkerError?: (error: Error) => void
+  /** Overrides the readiness deadline. Tests only. */
+  readyTimeoutMs?: number
+}
+
+export interface TunnelHost {
+  stop(): void
+  instanceId(): string | null
+  isConnected(): boolean
+  /** Resolves once the worker has the tunnel running. */
+  ready(): Promise<void>
+}
+
+/**
+ * Start the tunnel on its own thread.
+ *
+ * Throws if the worker cannot be created (a bundle without the entry file, a
+ * runtime that will not spawn one), which is the caller's cue to fall back to an
+ * in-process tunnel rather than lose remote control entirely. A worker that is
+ * created but never answers `ready` rejects `ready()` for the same reason — the
+ * throw alone is not enough, because a missing entry file does not always fail
+ * synchronously.
+ */
+export function startTunnelInWorker(options: TunnelHostOptions): TunnelHost {
+  const log = options.logger ?? console
+  const entry = resolveTunnelWorkerEntry()
+  // The web Worker API, which is what Bun implements (and what the worker file
+  // uses on its side with `self.postMessage`). `node:worker_threads` needs
+  // `parentPort` instead, and mixing the two silently never delivers a message.
+  const worker = new Worker(pathToFileURL(entry))
+
+  const readyTimeoutMs = options.readyTimeoutMs ?? READY_TIMEOUT_MS
+  let instanceId: string | null = null
+  let connected = false
+  let stopped = false
+  let readySettled = false
+  let settleReady: () => void = () => {}
+  let failReady: (error: Error) => void = () => {}
+  const ready = new Promise<void>((resolve, reject) => {
+    settleReady = resolve
+    failReady = reject
+  })
+  // Nobody is obliged to await `ready()`; an unobserved rejection would take the
+  // process down instead of letting the caller fall back.
+  void ready.catch(() => {})
+
+  const readyTimer = setTimeout(() => {
+    failReady(new Error(`tunnel worker (${entry}) did not answer ready within ${readyTimeoutMs}ms`))
+  }, readyTimeoutMs)
+  void ready.then(
+    () => {
+      readySettled = true
+      clearTimeout(readyTimer)
+    },
+    () => {
+      readySettled = true
+      clearTimeout(readyTimer)
+    },
+  )
+
+  /** What the last `resolve` decided, so a rejection needs no extra round trip. */
+  const rejections = new Map<string, ResolveRejection>()
+
+  worker.onmessage = (event: MessageEvent) => {
+    const data = event.data as any
+    if (!data || typeof data !== 'object') return
+
+    if (data.type === 'ready') {
+      settleReady()
+      return
+    }
+
+    if (data.type === 'log') {
+      const sink = data.level === 'error' ? log.error : data.level === 'warn' ? log.warn : log.log
+      sink.call(log, data.message)
+      return
+    }
+
+    if (data.type === 'event') {
+      if (data.name === 'instance') {
+        instanceId = data.instanceId ?? null
+        options.onInstanceId?.(instanceId)
+      } else if (data.name === 'connection') {
+        connected = Boolean(data.connected)
+        options.onConnection?.(connected)
+      } else if (data.name === 'auth-revoked') {
+        options.onAuthRevoked?.(String(data.reason ?? 'auth revoked'))
+      }
+      return
+    }
+
+    void answer(data as WorkerRequest)
+  }
+
+  worker.onerror = (event: any) => {
+    const message = event?.message ?? event
+    log.error(`[TunnelHost] worker error: ${message}`)
+    const error = new Error(`tunnel worker failed: ${message}`)
+    // A worker that dies on load never posts `ready`. Reject now so the caller
+    // can fall back instead of waiting out the whole deadline.
+    if (!readySettled) failReady(error)
+    // A worker that dies later leaves a socket nobody is watching, which looks
+    // exactly like an offline machine. Same answer: hand it back to the caller.
+    options.onWorkerError?.(error)
+  }
+
+  async function answer(request: WorkerRequest): Promise<void> {
+    const resolver = options.resolver
+    try {
+      if (request.type === 'resolve') {
+        const url = await resolver.resolveLocalUrl(request.path, request.projectId)
+        const rejection =
+          url === null
+            ? await Promise.resolve(resolver.describeRejection?.(request.path, request.projectId))
+            : undefined
+        if (rejection) rejections.set(`${request.path}|${request.projectId ?? ''}`, rejection)
+        reply({ type: 'resolved', id: request.id, url, rejection })
+        return
+      }
+
+      if (request.type === 'token') {
+        const token = await resolver.deriveRuntimeToken(request.projectId)
+        reply({ type: 'token-result', id: request.id, token })
+        return
+      }
+
+      if (request.type === 'refresh') {
+        const projects: HostProjectStatus[] = resolver.getActiveProjects().map((projectId) => {
+          const status = resolver.status(projectId)
+          return { projectId, status: status?.status ?? 'unknown', agentPort: status?.agentPort }
+        })
+        reply({
+          type: 'refresh-result',
+          id: request.id,
+          projects,
+          rejections: Object.fromEntries(rejections),
+        })
+        return
+      }
+
+      if (request.type === 'machineSnapshot') {
+        const snapshot = (await resolver.machineSnapshot?.()) ?? null
+        reply({ type: 'machine-snapshot-result', id: request.id, snapshot })
+      }
+    } catch (error: any) {
+      log.warn(`[TunnelHost] ${request.type} failed: ${error?.message ?? error}`)
+      if (request.type === 'resolve') reply({ type: 'resolved', id: request.id, url: null })
+      else if (request.type === 'token') reply({ type: 'token-result', id: request.id, token: null })
+      else if (request.type === 'refresh') reply({ type: 'refresh-result', id: request.id, projects: [] })
+      else reply({ type: 'machine-snapshot-result', id: request.id, snapshot: null })
+    }
+  }
+
+  function reply(message: HostReply): void {
+    if (stopped) return
+    worker.postMessage(message)
+  }
+
+  worker.postMessage({
+    type: 'init',
+    config: {
+      apiKey: options.apiKey,
+      cloudUrl: options.cloudUrl,
+      name: options.name,
+      kind: options.kind,
+      wsUrlOverride: options.wsUrlOverride,
+    },
+  })
+
+  return {
+    stop() {
+      stopped = true
+      clearTimeout(readyTimer)
+      void worker.terminate()
+    },
+    instanceId: () => instanceId,
+    isConnected: () => connected,
+    ready: () => ready,
+  }
+}