feat(dev): run worker code in a Bun Worker thread per generation

[jonasnobile]

Summary

Refactors lopata's dev runtime so user worker code always runs in a Bun Worker thread (one per generation). Reload = terminate + respawn, which gives correct transitive HMR for free.

Why now: Bun 1.3.14 removed globalThis.Loader.registry (the JSC-internal API the previous in-process cache-bust trick depended on), and the existing ?v=<ts> invalidation only ever cleared the entry — transitive deps stayed cached across reloads. The thread-per-generation model sidesteps the registry entirely: a fresh worker re-evaluates every module from disk.

The branch is structured as a 13-phase arc (Phase 0 → 8e), each phase a feat commit followed by a refactor "tighten" pass from a 3-agent simplify review. The final phase (3af2998) flips the default and drops the in-process path; subsequent commits fill in two integration gaps the simplify pass surfaced (DO worker WebSocket bridging, ContainerRuntime wiring, env-binding RPC for DOs).

What changed

Runtime

• All user worker code runs in a Bun Worker spawned per Generation. Main thread owns Bun.serve, file watcher, dashboard, stateful bindings; the worker imports the user module and holds stateless bindings + proxies to main.
• New src/worker-thread/ directory: executor.ts, entry.ts, protocol.ts, rpc-client.ts, serialize.ts, thread-env.ts, main-ws-bridge.ts, ws-bridge.ts, wire-handlers.ts, remote-trace-store.ts, execution-context.ts.
• Generation shrank from 376 → ~120 LOC (in-process branches, patchFrameworkDispatch, stitchAsyncStack are gone).
• WorkerIsolation config / --worker-isolation CLI flag / src/module-cache.ts all removed.

Cross-thread bridges

• Stateful bindings (queues, email, service bindings, DOs, workflows) become RPC proxies that round-trip through binding-call / binding-fetch messages. Service-binding RPC + fetch both work cross-worker via WorkerRegistry.
• ctx.waitUntil posts wait-until-add / wait-until-settle; reload drains pending promises before terminating.
• Tracing (AsyncLocalStorage-based) bridges via ParentSpanContext + runWithParentContext so worker-side spans link to the main-side request span.
• WebSocket upgrades through three bridges:
  • MainWsBridge ↔ WorkerWsBridge for the main user worker.
  • FetchDoBridgePeer (new) for WebSockets returned by a DO's fetch() — main adopts the peer, ships the wsId back so Bun.serve.upgrade receives the real CFWebSocket end-to-end.
  • MainWsBridge._pendingEvents buffers events that race ahead of createSocket (when the worker dispatches queued events during accept() before the fetch result has reached main). Cleared in disposeAll().
• Container runtime for DOs extending ContainerBase is now instantiated inside the DO worker (ContainerRuntime + per-worker DockerManager) — previously only InProcessExecutor wired it.
• Env-binding RPC for DO workers: DOs can now call this.env.SERVICE.fetch(...) / this.env.WORKFLOW.create(...) / this.env.MAILER.send(...). New env-call / env-fetch messages on the DO-worker channel; WorkerExecutor resolves against the executor's mainEnv reference (the same proxies the main user-worker uses).

Bug fixes uncovered along the way

• NON_RPC_PROPS drift: a local copy in do-worker-env.ts dropped toJSON / valueOf / toString from the skiplist — JSON.stringify(env.X) from a DO would have dispatched an RPC method call. Now imports the canonical set from rpc-stub.ts.
• Listener-before-accept: three bridges (ws-bridge.ts, do-worker-entry.ts, testing/durable-object.ts:connectWebSocket) called accept() before attaching listeners. accept() flushes the event queue — pre-shipped messages were silently lost. Listeners now attach first.
• _disposed guard on the new env dispatchers so side-effecting env calls (KV writes, cross-worker fetches) don't complete after the requesting DO worker has been terminated.

Playground

• Counter DO grew a WebSocket fetch() that broadcasts count changes to subscribers; new /ws/counter/<name> route exercises the DO WS bridge, /ws/echo exercises the plain-worker bridge.
• Approve / Reject buttons for the workflow demo so instances can actually be driven to complete from the UI.
• Dockerfile.sandbox pins to --platform=linux/amd64 (Cloudflare publishes the sandbox image amd64-only on purpose for dev/prod parity).

Tests

• New e2e fixtures + tests under tests/: thread-stateless-, thread-stateful-, thread-ws-, thread-do-, thread-multi-worker-, thread-workflow-, thread-queue-e2e.test.ts.
• tests/main-ws-bridge.test.ts — unit coverage for the pending-event buffer + disposeAll cleanup that the simplify review flagged.
• Final: 1285 pass, 2 skip, 0 fail (1287 across 51 files in ~55s locally).

User-visible behavior change

Active WebSockets do not survive a reload. Previously, the in-process executor could hot-swap the DO class while keeping hibernated WS connections alive. With worker-thread isolation, reload disposes the worker (that's what gives us correct transitive HMR) and active clients receive 1012 Service Restart — they need to reconnect. Two HMR-WS tests are marked .skip with a comment.

DO instances spawn their own Bun Worker (was opt-in via isolation: 'isolated', now always). For workloads with many short-lived DO instances this adds cold-start cost; bounded by the existing 30s eviction timer.

Test plan

• bun run typecheck clean
• bun run lint clean
• bun run format:check clean
• bun run test — 1285 pass, 2 skip, 0 fail
• Playground smoke tests: WS echo, WS-over-DO counter, workflow create → approve → complete, service-binding RPC + fetch, container sandbox exec
• Manual review: CF Workers reference projects (webmaster, oblaka) — verify nothing in the wider Cloudflare-stack codebase relied on the in-process path

🤖 Generated with Claude Code