The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Clock from "effect/Clock"; |
| 2 | import * as Context from "effect/Context"; |
| 3 | import * as Effect from "effect/Effect"; |
| 4 | import * as Exit from "effect/Exit"; |
| 5 | import * as Layer from "effect/Layer"; |
| 6 | import * as Queue from "effect/Queue"; |
| 7 | import * as Result from "effect/Result"; |
| 8 | import * as Scope from "effect/Scope"; |
| 9 | import * as Docker from "./Docker.ts"; |
| 10 | import type * as Globals from "./globals/Globals.ts"; |
| 11 | import * as Storage from "./globals/Storage.ts"; |
| 12 | import { |
| 13 | defaultDurableObjectUniqueKey, |
| 14 | SERVICE_USER_WORKER, |
| 15 | SOCKET_USER_ENTRY, |
| 16 | withDefaultFlags, |
| 17 | } from "./internal/constants.ts"; |
| 18 | import { moduleToWorkerd } from "./internal/internal-modules.ts"; |
| 19 | import type { BindingHook } from "./PluginContext.ts"; |
| 20 | import * as PluginContext from "./PluginContext.ts"; |
| 21 | import * as RegistryProxy from "./registry/RegistryProxy.ts"; |
| 22 | import { type RuntimeError, SystemError } from "./RuntimeError.shared.ts"; |
| 23 | import type { BindingHooks, RuntimeWorker } from "./RuntimeWorker.ts"; |
| 24 | import type * as WorkerdConfig from "./workerd/Config.ts"; |
| 25 | import * as Workerd from "./workerd/Workerd.ts"; |
| 26 | |
| 27 | export class Runtime extends Context.Service< |
| 28 | Runtime, |
| 29 | { |
| 30 | readonly start: <B extends BindingHooks>( |
| 31 | worker: RuntimeWorker<B>, |
| 32 | ) => Effect.Effect<URL, RuntimeError, BindingRequirements<B> | Scope.Scope>; |
| 33 | } |
| 34 | >()("cloudflare-runtime/Runtime") {} |
| 35 | |
| 36 | type BindingRequirements<B extends BindingHooks> = |
| 37 | B extends Array<never> ? never : B extends Array<BindingHook<infer R>> ? R : never; |
| 38 | |
| 39 | export const RuntimeLive = Layer.effect( |
| 40 | Runtime, |
| 41 | Effect.gen(function* () { |
| 42 | const workerd = yield* Workerd.Workerd; |
| 43 | const storage = yield* Storage.Storage; |
| 44 | const docker = yield* Docker.Docker; |
| 45 | const plugins = yield* PluginContext.pickPluginsFromContext<Globals.Globals>(); |
| 46 | |
| 47 | const preparePlugins = Effect.fnUntraced(function* (worker: RuntimeWorker) { |
| 48 | const context = yield* PluginContext.make(worker as RuntimeWorker, plugins); |
| 49 | const [bindings, { tails, streamingTails }] = yield* Effect.all( |
| 50 | [ |
| 51 | Effect.all(worker.bindings as ReadonlyArray<BindingHook<never>>, { |
| 52 | concurrency: "unbounded", |
| 53 | }).pipe(Effect.provideService(PluginContext.PluginContext, context)), |
| 54 | prepareTails(worker, context), |
| 55 | ], |
| 56 | { concurrency: "unbounded" }, |
| 57 | ); |
| 58 | return { config: yield* context.config, context, bindings, tails, streamingTails }; |
| 59 | }); |
| 60 | |
| 61 | /** |
| 62 | * Resolve each (streaming) tail consumer name to a `ServiceDesignator` |
| 63 | * through the dev registry proxy — the same path service bindings to other |
| 64 | * local workers take (`Service.local`). The registry proxy's |
| 65 | * `ExternalService` entrypoint forwards `tail()` batches and |
| 66 | * `tailStream()` sessions to the consumer's process via the workerd debug |
| 67 | * port, so consumers may live in other dev processes and may (re)start at |
| 68 | * any time. Subscriptions must be registered before `context.config` is |
| 69 | * computed, which is why this runs alongside the binding hooks in |
| 70 | * `preparePlugins`. |
| 71 | */ |
| 72 | const prepareTails = Effect.fnUntraced(function* ( |
| 73 | worker: RuntimeWorker, |
| 74 | context: PluginContext.PluginContext["Service"], |
| 75 | ) { |
| 76 | if (!worker.tails?.length && !worker.streamingTails?.length) { |
| 77 | return { tails: undefined, streamingTails: undefined }; |
| 78 | } |
| 79 | const proxy = yield* context.get(RegistryProxy.RegistryProxy); |
| 80 | const subscribeAll = (names: ReadonlyArray<string> | undefined) => |
| 81 | names?.length |
| 82 | ? Effect.forEach([...new Set(names)], (scriptName) => |
| 83 | proxy.api.subscribe({ kind: "worker", scriptName }), |
| 84 | ) |
| 85 | : Effect.undefined; |
| 86 | const [tails, streamingTails] = yield* Effect.all( |
| 87 | [subscribeAll(worker.tails), subscribeAll(worker.streamingTails)], |
| 88 | { concurrency: "unbounded" }, |
| 89 | ); |
| 90 | return { tails, streamingTails }; |
| 91 | }); |
| 92 | |
| 93 | const prepareContainers = Effect.fnUntraced(function* (worker: RuntimeWorker) { |
| 94 | const containers = (worker.durableObjectNamespaces ?? []).flatMap((namespace) => { |
| 95 | if (!namespace.container) return []; |
| 96 | return { className: namespace.className, container: namespace.container }; |
| 97 | }); |
| 98 | if (!containers.length) { |
| 99 | return { containerOptions: new Map() }; |
| 100 | } |
| 101 | // Local development with containers relies on pulling/building `linux/amd64` |
| 102 | // images, which the Docker daemon on Windows cannot do (it runs Windows |
| 103 | // containers). Upstream workers-sdk bails out on Windows for the same |
| 104 | // reason, directing users to WSL. |
| 105 | if (process.platform === "win32") { |
| 106 | return yield* SystemError.make({ |
| 107 | subtag: "ContainersUnsupportedOnWindows", |
| 108 | message: "Local development with containers is not supported on Windows.", |
| 109 | hint: "Use WSL to develop the container part of your application, or remove the container configuration if you do not need it.", |
| 110 | }); |
| 111 | } |
| 112 | // workerd container options per Durable Object class name. |
| 113 | const containerOptions = new Map< |
| 114 | string, |
| 115 | WorkerdConfig.Worker_DurableObjectNamespace_ContainerOptions |
| 116 | >(); |
| 117 | |
| 118 | /** |
| 119 | * Make an image available to Docker and return the name workerd should |
| 120 | * use for it. Images with env get a unique alias, which the Docker proxy |
| 121 | * maps back to the real tag while injecting the env. |
| 122 | */ |
| 123 | const prepareImage = Effect.fnUntraced(function* ( |
| 124 | className: string, |
| 125 | image: Docker.ContainerImage, |
| 126 | ) { |
| 127 | let tag: string; |
| 128 | if ("tag" in image) { |
| 129 | tag = image.tag; |
| 130 | } else { |
| 131 | tag = docker.generateImageTag(className); |
| 132 | if ("imageUri" in image) { |
| 133 | yield* docker.pull(tag, image); |
| 134 | } else { |
| 135 | yield* docker.build(tag, image); |
| 136 | } |
| 137 | // Each start cleans up ONLY its own image tag when its scope |
| 138 | // closes. Do NOT prune other same-name tags as "stale" here: a |
| 139 | // dev session starts the worker more than once (precreate stub |
| 140 | // → reconcile), and a cleanup that guesses which sibling tags |
| 141 | // are dead can untag the tag a live workerd is about to |
| 142 | // `docker create` from — every container start then fails and |
| 143 | // the session serves 500s until redeploy. |
| 144 | yield* Effect.addFinalizer(() => |
| 145 | docker |
| 146 | .removeContainer(tag) |
| 147 | .pipe(Effect.andThen(docker.removeImageTag(tag)), Effect.ignore), |
| 148 | ); |
| 149 | } |
| 150 | yield* docker.validate(tag); |
| 151 | if (image.env) { |
| 152 | return yield* docker.registerImageEnv(className, tag, image.env); |
| 153 | } |
| 154 | return tag; |
| 155 | }); |
| 156 | |
| 157 | /** A Durable Object-managed container exposes every image by name. */ |
| 158 | const prepareNamedImages = ( |
| 159 | className: string, |
| 160 | images: Record<string, Docker.ContainerImage>, |
| 161 | ) => |
| 162 | Effect.forEach( |
| 163 | Object.entries(images), |
| 164 | Effect.fnUntraced(function* ([name, image]) { |
| 165 | return { name, image: yield* prepareImage(className, image) }; |
| 166 | }), |
| 167 | { concurrency: "unbounded" }, |
| 168 | ); |
| 169 | |
| 170 | // FUSE privileges are decided once per runtime and |
| 171 | // resolve alongside the first image build or pull. |
| 172 | const [, containerEngine] = yield* Effect.forEach( |
| 173 | containers, |
| 174 | Effect.fnUntraced(function* ({ className, container }) { |
| 175 | if ("images" in container) { |
| 176 | const [images, privileges] = yield* Effect.zip( |
| 177 | prepareNamedImages(className, container.images), |
| 178 | docker.getContainerPrivileges, |
| 179 | { concurrent: true }, |
| 180 | ); |
| 181 | containerOptions.set(className, { images, privileges }); |
| 182 | } else { |
| 183 | const [imageName, privileges] = yield* Effect.zip( |
| 184 | prepareImage(className, container), |
| 185 | docker.getContainerPrivileges, |
| 186 | { concurrent: true }, |
| 187 | ); |
| 188 | containerOptions.set(className, { imageName, privileges }); |
| 189 | } |
| 190 | }), |
| 191 | { concurrency: "unbounded", discard: true }, |
| 192 | ).pipe(Effect.zip(docker.getWorkerdDockerConfiguration, { concurrent: true })); |
| 193 | return { containerOptions, containerEngine }; |
| 194 | }); |
| 195 | |
| 196 | return Runtime.of({ |
| 197 | start: Effect.fn(function* (worker) { |
| 198 | worker = { |
| 199 | ...worker, |
| 200 | compatibilityFlags: withDefaultFlags(worker.compatibilityFlags, { |
| 201 | date: worker.compatibilityDate, |
| 202 | }), |
| 203 | }; |
| 204 | const [ |
| 205 | { config, context, bindings, tails, streamingTails }, |
| 206 | { containerEngine, containerOptions }, |
| 207 | ] = yield* Effect.all([preparePlugins(worker), prepareContainers(worker)], { |
| 208 | concurrency: "unbounded", |
| 209 | }); |
| 210 | // Everything slow (image builds/pulls) is done; let the caller retire |
| 211 | // whatever must be gone before this workerd boots. |
| 212 | if (worker.beforeServe) yield* worker.beforeServe; |
| 213 | const sockets: Array<WorkerdConfig.Socket> = [ |
| 214 | { |
| 215 | name: SOCKET_USER_ENTRY, |
| 216 | address: "127.0.0.1:0", |
| 217 | service: { name: config.entry ?? SERVICE_USER_WORKER }, |
| 218 | }, |
| 219 | ...config.sockets, |
| 220 | ]; |
| 221 | const exits = yield* Queue.unbounded<Workerd.WorkerdExit>(); |
| 222 | /** |
| 223 | * Serves the Worker. `pinned` reuses the ports of a previous process, |
| 224 | * so a replacement is reachable through the same URL, proxy target |
| 225 | * and registry entry as the process it replaces. |
| 226 | */ |
| 227 | const serveWorker = (pinned?: Workerd.WorkerdPorts) => |
| 228 | workerd.serve( |
| 229 | { |
| 230 | sockets: pinned ? sockets.map(pinSocket(pinned)) : sockets, |
| 231 | services: [ |
| 232 | { |
| 233 | name: SERVICE_USER_WORKER, |
| 234 | worker: { |
| 235 | compatibilityDate: worker.compatibilityDate, |
| 236 | compatibilityFlags: worker.compatibilityFlags, |
| 237 | bindings, |
| 238 | modules: worker.modules.map(moduleToWorkerd), |
| 239 | durableObjectNamespaces: worker.durableObjectNamespaces?.map((namespace) => { |
| 240 | const container = containerOptions.get(namespace.className); |
| 241 | return { |
| 242 | className: namespace.className, |
| 243 | enableSql: namespace.sql, |
| 244 | uniqueKey: |
| 245 | namespace.uniqueKey ?? |
| 246 | defaultDurableObjectUniqueKey(worker.name, namespace.className), |
| 247 | ephemeralLocal: namespace.ephemeralLocal, |
| 248 | container, |
| 249 | }; |
| 250 | }), |
| 251 | durableObjectStorage: { localDisk: storage.name }, |
| 252 | containerEngine, |
| 253 | tails, |
| 254 | streamingTails, |
| 255 | ...config.userWorker, |
| 256 | ...worker.unsafe, |
| 257 | }, |
| 258 | }, |
| 259 | ...config.services, |
| 260 | ], |
| 261 | extensions: config.extensions, |
| 262 | v8Flags: worker.workerd?.v8Flags, |
| 263 | }, |
| 264 | { |
| 265 | "debug-port": `127.0.0.1:${pinned?.[SOCKET_DEBUG_PORT] ?? 0}`, |
| 266 | ...(worker.logging?.verbose ? { verbose: true } : undefined), |
| 267 | }, |
| 268 | { |
| 269 | bin: worker.workerd?.path, |
| 270 | env: worker.workerd?.env, |
| 271 | onOutput: worker.logging?.onOutput, |
| 272 | onExit: (exit) => { |
| 273 | Queue.offerUnsafe(exits, exit); |
| 274 | }, |
| 275 | }, |
| 276 | ); |
| 277 | const parentScope = yield* Effect.scope; |
| 278 | let processScope = yield* Scope.fork(parentScope); |
| 279 | const startProcess = (pinned?: Workerd.WorkerdPorts) => |
| 280 | serveWorker(pinned).pipe( |
| 281 | Effect.tap((ports) => context.start(ports)), |
| 282 | Scope.provide(processScope), |
| 283 | Effect.onExit((exit) => |
| 284 | Exit.isFailure(exit) ? Scope.close(processScope, exit) : Effect.void, |
| 285 | ), |
| 286 | ); |
| 287 | const ports = yield* startProcess(); |
| 288 | // A process that dies after startup (V8 aborting on heap exhaustion |
| 289 | // is the common case) is replaced on the same ports. Without this |
| 290 | // every request fails until the whole dev session is restarted. |
| 291 | yield* Effect.gen(function* () { |
| 292 | let restartTimes: Array<number> = []; |
| 293 | while (true) { |
| 294 | const exit = yield* Queue.take(exits); |
| 295 | // Release the old process, output listeners and plugin tasks before |
| 296 | // starting another generation. Closing also detaches this child |
| 297 | // scope from the parent, so repeated crashes do not retain it. |
| 298 | yield* Scope.close(processScope, Exit.void); |
| 299 | const now = yield* Clock.currentTimeMillis; |
| 300 | restartTimes = restartTimes.filter((time) => now - time < 60_000); |
| 301 | if (restartTimes.length >= 3) { |
| 302 | yield* Effect.logError( |
| 303 | `The Workers runtime for "${worker.name}" stopped after 3 restarts within 60 seconds. Fix the crash and restart the dev session.`, |
| 304 | ); |
| 305 | return; |
| 306 | } |
| 307 | restartTimes.push(now); |
| 308 | yield* Effect.sleep(250 * 2 ** (restartTimes.length - 1)); |
| 309 | yield* Effect.logWarning( |
| 310 | `The Workers runtime for "${worker.name}" exited unexpectedly (exit code ${exit.exitCode}, signal ${exit.signal}); starting a replacement on the same ports.${exit.stderr ? `\n${exit.stderr}` : ""}`, |
| 311 | ); |
| 312 | processScope = yield* Scope.fork(parentScope); |
| 313 | const restarted = yield* startProcess(ports).pipe(Effect.result); |
| 314 | if (Result.isFailure(restarted)) { |
| 315 | yield* Effect.logError( |
| 316 | `The Workers runtime for "${worker.name}" could not be restarted: ${restarted.failure.message}`, |
| 317 | ); |
| 318 | return; |
| 319 | } |
| 320 | worker.onRestart?.(exit); |
| 321 | } |
| 322 | }).pipe(Effect.forkScoped); |
| 323 | return new URL(`http://127.0.0.1:${ports[SOCKET_USER_ENTRY]}`); |
| 324 | }), |
| 325 | }); |
| 326 | }), |
| 327 | ); |
| 328 | |
| 329 | const SOCKET_DEBUG_PORT = "debug-port"; |
| 330 | |
| 331 | const pinSocket = |
| 332 | (ports: Workerd.WorkerdPorts) => |
| 333 | (socket: WorkerdConfig.Socket): WorkerdConfig.Socket => { |
| 334 | const port = socket.name === undefined ? undefined : ports[socket.name]; |
| 335 | return port === undefined ? socket : { ...socket, address: `127.0.0.1:${port}` }; |
| 336 | }; |