@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
ts 1,701 lines 76.2 KB
Raw
1 import * as os from "node:os";
2 import {
3 Runtime,
4 type RuntimeServices,
5 type BindingHook,
6 type BindingServices,
7 type HyperdriveOrigin,
8 type Module,
9 type DurableObjectNamespace as RuntimeDurableObject,
10 type QueueConsumer as RuntimeQueueConsumer,
11 type Workflow as RuntimeWorkflow,
12 } from "@alchemy.run/cloudflare-runtime/core";
13 import type { ContainerImage as RuntimeContainerImage } from "@alchemy.run/cloudflare-runtime/core/Docker";
14 import * as WorkerProxy from "@alchemy.run/cloudflare-runtime/core/proxy/WorkerProxy";
15 import { dotAlchemyDirectory } from "alchemy/AlchemyContext";
16 import {
17 Artifacts as AlchemyArtifacts,
18 createArtifactStore,
19 makeScopedArtifacts,
20 } from "alchemy/Artifacts";
21 import type * as Bundle from "alchemy/Bundle/Bundle";
22 import * as LocalProvider from "alchemy/Local/LocalProvider";
23 import { Stack } from "alchemy/Stack";
24 import { unwrapRedacted } from "alchemy/Util";
25 import { isPathWithin } from "alchemy/Util/isPathWithin";
26 import { LogAnnotation } from "alchemy/Util/LogAnnotation";
27 import { makeResourceLogger, makeResourceOutput } from "alchemy/Util/ResourceOutput";
28 import { sha256 } from "alchemy/Util/sha256";
29 import { ANSI_RESET, ansiFg, colorsEnabled } from "alchemy/Util/Terminal";
30 import { theme } from "alchemy/Util/Theme";
31 import * as Cause from "effect/Cause";
32 import * as Deferred from "effect/Deferred";
33 import * as Effect from "effect/Effect";
34 import * as Equal from "effect/Equal";
35 import * as Exit from "effect/Exit";
36 import * as Fiber from "effect/Fiber";
37 import type * as FileSystem from "effect/FileSystem";
38 import * as PlatformFileSystem from "effect/FileSystem";
39 import * as MutableHashMap from "effect/MutableHashMap";
40 import * as Option from "effect/Option";
41 import * as Path from "effect/Path";
42 import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
43 import * as Result from "effect/Result";
44 import * as Scope from "effect/Scope";
45 import * as Semaphore from "effect/Semaphore";
46 import * as Stream from "effect/Stream";
47 import type { DevContainerImage } from "../Containers/ContainerApplication.ts";
48 import {
49 assertBindingContainersOnAsyncClasses,
50 mergeWorkerContainers,
51 } from "../Containers/ContainerConfiguration.ts";
52 import { localAccountId } from "../LocalAccount.ts";
53 import {
54 isLiveId,
55 LOCAL_PROVIDERS_URL,
56 LocalRuntimeState,
57 localStorageDirectory,
58 } from "../LocalRuntime.ts";
59 import type { ConsumerSettings } from "../Queues/Consumer.ts";
60 import type { WorkerAssetsConfig, WorkerProps } from "../Workers/Worker.ts";
61 import { readAssetsConfigFiles } from "./Assets.ts";
62 import { getCompatibility } from "./Compatibility.ts";
63 import { isDurableObjectExport } from "./DurableObject.ts";
64 import { LocalEdge } from "./LocalEdge.ts";
65 import { routePatternHost } from "./RoutePattern.ts";
66 import { materializeRuntimeBindings, WorkerValidationError } from "./RuntimeBindings.ts";
67 import { resolveSource, SourceProviderError, type DevContext } from "./Source.ts";
68 import { workerBundleOptions } from "./Sources/Rolldown.ts";
69 import { DEFAULT_DEV_PORT, type ViteChildConfig } from "./ViteChild.shared.ts";
70 import { startViteChild } from "./ViteChild.ts";
71 import { resolveViteMain } from "./ViteMain.ts";
72 import { isSelfUrl, Worker } from "./Worker.ts";
73 import { getCronBindings } from "./WorkerAsyncBindings.ts";
74 import type { WorkerBinding } from "./WorkerBinding.ts";
75 import { createWorkerName } from "./WorkerName.ts";
76 import { resolveTailConsumers } from "./WorkerProvider.ts";
77
78 /** Local dev-server options (the worker-mode arm of `WorkerProps["dev"]`). */
79 type DevServerOptions = Extract<WorkerProps["dev"], { mode?: "worker" }> & {
80 port: number;
81 };
82
83 const workerStartedMessage = (elapsed: number, url: URL): string => {
84 const duration = `${Math.round(elapsed)}ms`;
85 if (!colorsEnabled()) {
86 return `Started in ${duration} → ${url}`;
87 }
88 return `Started in ${ansiFg(theme.color.success)}${duration}${ANSI_RESET} → ${ansiFg(theme.color.info)}\x1b[4m${url}${ANSI_RESET}`;
89 };
90
91 const workerUpdatedMessage = (elapsed: number): string => {
92 const duration = `${Math.round(elapsed)}ms`;
93 return colorsEnabled()
94 ? `Updated in ${ansiFg(theme.color.success)}${duration}${ANSI_RESET}`
95 : `Updated in ${duration}`;
96 };
97
98 // Hosts that bind every interface — the dev server is then reachable at
99 // `localhost` *and* at each LAN address, like Vite's `--host` output.
100 const isWildcardHost = (host: string) =>
101 host === "0.0.0.0" || host === "::" || host === "[::]" || host === "*";
102
103 /**
104 * Resolve every URL a local dev server is reachable at, most relevant
105 * first. A loopback or explicit host yields just that URL; a wildcard host
106 * (`0.0.0.0`, `::`) yields `http://localhost:<port>` followed by one URL
107 * per external IPv4 interface (`http://192.168.0.12:<port>`, ...) —
108 * mirroring Vite's "Local / Network" dev-server output.
109 */
110 const resolveLocalUrls = (serverUrl: URL): Effect.Effect<string[]> =>
111 Effect.sync(() => {
112 const port = serverUrl.port;
113 const host = serverUrl.hostname;
114 if (!isWildcardHost(host)) {
115 return [serverUrl.origin];
116 }
117 // `os.networkInterfaces()` is a sync, CPU-only syscall with no Effect
118 // platform equivalent — wrapped in `Effect.sync` so it participates in
119 // the runtime.
120 const interfaces = os.networkInterfaces();
121 const lanAddresses = Object.values(interfaces)
122 .flatMap((addresses) => addresses ?? [])
123 .filter((address) => address.family === "IPv4" && !address.internal)
124 .map((address) => address.address);
125 return [
126 `http://localhost:${port}`,
127 ...lanAddresses.map((address) => `http://${address}:${port}`),
128 ];
129 });
130
131 export const LocalWorkerProvider = () =>
132 LocalProvider.make(
133 Worker,
134 LOCAL_PROVIDERS_URL,
135 Effect.gen(function* () {
136 const runtimeBase = process.cwd();
137 const dotAlchemy = yield* dotAlchemyDirectory;
138 const runtime = yield* Runtime;
139 const stack = yield* Stack;
140 const storageDirectory = yield* localStorageDirectory;
141 const path = yield* Path.Path;
142 const localRuntimeState = yield* LocalRuntimeState;
143 const workerProxy = yield* WorkerProxy.WorkerProxy;
144 const edge = yield* LocalEdge;
145 const context = yield* Effect.context<RuntimeServices>();
146 const rootScope = yield* Effect.scope;
147
148 // Proxies are deliberately NOT owned by the per-instance scope: they
149 // survive restarts so the worker's URL stays stable across rebuilds
150 // and config changes. Torn down by `stop` on delete.
151 const proxyInstances = new Map<
152 string,
153 {
154 serverOptions: DevServerOptions;
155 instance: WorkerProxy.WorkerProxyInstance;
156 scope: Scope.Closeable;
157 }
158 >();
159
160 // ConsumerSettings speaks the Cloudflare API's dialect (batchSize,
161 // maxWaitTimeMs in milliseconds); the runtime's QueueConsumer speaks
162 // wrangler's (maxBatchSize, maxBatchTimeout in seconds). Map
163 // explicitly — a spread silently drops the mismatched fields.
164 const toRuntimeConsumerSettings = (
165 settings: ConsumerSettings | undefined,
166 ): Pick<
167 RuntimeQueueConsumer,
168 "maxBatchSize" | "maxBatchTimeout" | "maxRetries" | "retryDelay"
169 > => ({
170 maxBatchSize: settings?.batchSize,
171 maxBatchTimeout:
172 settings?.maxWaitTimeMs !== undefined ? settings.maxWaitTimeMs / 1000 : undefined,
173 maxRetries: settings?.maxRetries,
174 retryDelay: settings?.retryDelay,
175 });
176
177 const getQueueConsumers = Effect.fn(function* (scriptName: string) {
178 const consumers: RuntimeQueueConsumer[] = [];
179 for (const consumer of MutableHashMap.values(localRuntimeState.queueConsumers)) {
180 if (consumer.scriptName === scriptName) {
181 // A LIVE queue (`Alchemy.remote()`) consumed locally: the broker
182 // is still local, but it is fed by the runtime's pull loop
183 // draining the real queue over the HTTP pull API (the
184 // Consumer's local provider attached the `http_pull` consumer
185 // and resolved the queue's real name).
186 if (isLiveId(consumer.queueId)) {
187 if (!consumer.queueName) {
188 return yield* Effect.die(
189 `Consumer of live queue ${consumer.queueId} is missing its resolved queueName — re-deploy the consumer`,
190 );
191 }
192 consumers.push({
193 queueName: consumer.queueName,
194 deadLetterQueue: consumer.deadLetterQueue,
195 ...toRuntimeConsumerSettings(consumer.settings),
196 pull: {
197 queueId: consumer.queueId,
198 accountId: consumer.accountId,
199 },
200 });
201 continue;
202 }
203 const queue = MutableHashMap.get(localRuntimeState.queues, consumer.queueId).pipe(
204 Option.getOrUndefined,
205 );
206 if (queue) {
207 consumers.push({
208 queueName: queue.queueName,
209 deadLetterQueue: consumer.deadLetterQueue,
210 ...toRuntimeConsumerSettings(consumer.settings),
211 });
212 } else {
213 return yield* Effect.die(`Queue ${String(consumer.queueId)} not found`);
214 }
215 }
216 }
217 return consumers;
218 });
219
220 const startProxy = Effect.fn(function* (id: string, serverOptions: DevServerOptions) {
221 const scope = yield* Scope.fork(rootScope);
222 const instance = yield* workerProxy.serve(serverOptions).pipe(Scope.provide(scope));
223 proxyInstances.set(id, { serverOptions, instance, scope });
224 return instance;
225 });
226
227 const stopProxy = Effect.fn(function* (id: string) {
228 const existing = proxyInstances.get(id);
229 if (existing) {
230 yield* Scope.close(existing.scope, Exit.void);
231 proxyInstances.delete(id);
232 }
233 });
234
235 const maybeStartProxy = Effect.fn(function* (id: string, serverOptions: DevServerOptions) {
236 const existing = proxyInstances.get(id);
237 if (existing) {
238 if (Equal.equals(existing.serverOptions, serverOptions)) {
239 return existing.instance;
240 }
241 yield* stopProxy(id);
242 }
243 return yield* startProxy(id, serverOptions);
244 });
245
246 const toRuntimeModules = Effect.fn(function* (bundle: Bundle.BundleOutput) {
247 const modules: Module[] = [];
248 for (const file of bundle.files) {
249 // Vendored Python packages are opaque Data modules named by their
250 // `python_modules/<relpath>` — mirroring the deploy path — except
251 // the `workers-runtime-sdk` JS shims, which the runtime imports
252 // as ES modules via `import_from_javascript()`.
253 if (file.path.startsWith("python_modules/")) {
254 const isJsShim =
255 file.path.startsWith("python_modules/workers/") && /\.m?js$/.test(file.path);
256 modules.push(
257 isJsShim
258 ? {
259 name: file.path,
260 type: "ESModule",
261 content:
262 typeof file.content === "string"
263 ? file.content
264 : new TextDecoder().decode(file.content),
265 }
266 : {
267 name: file.path,
268 type: "Data",
269 content:
270 typeof file.content === "string"
271 ? new TextEncoder().encode(file.content)
272 : file.content,
273 },
274 );
275 continue;
276 }
277 const type =
278 file.type === "Text"
279 ? "Text"
280 : file.type === "Data"
281 ? "Data"
282 : file.type === "CompiledWasm"
283 ? "Wasm"
284 : moduleTypeFromExtension(path.extname(file.path));
285 if (type === "SourceMap") continue;
286 if (type === "Data" && typeof file.content === "string") {
287 modules.push({
288 name: file.path,
289 type,
290 content: new TextEncoder().encode(file.content),
291 });
292 } else if (type === "Data" || type === "Wasm") {
293 if (!(file.content instanceof Uint8Array)) {
294 return yield* WorkerValidationError.make({
295 message: `Expected Uint8Array for ${file.path} (${type})`,
296 value: file.content,
297 });
298 }
299 modules.push({
300 name: file.path,
301 type,
302 content: file.content,
303 });
304 } else {
305 // Prebuilt (`bundle: false`) workers read every module as raw
306 // bytes; string-typed workerd modules (ESModule, Text, ...)
307 // are decoded here, mirroring the deploy path which uploads
308 // the same bytes with a text content type.
309 modules.push({
310 name: file.path,
311 type,
312 content:
313 typeof file.content === "string"
314 ? file.content
315 : new TextDecoder().decode(file.content),
316 });
317 }
318 }
319 return modules;
320 });
321
322 /**
323 * The restart-relevant, canonically-hashable view of a local Worker's
324 * desired state — `LocalProvider`'s `resolveConfig`. Everything here
325 * is plain data: binding *descriptors* (not `BindingHook` closures —
326 * those are materialized in `start` via {@link toRuntimeBinding}),
327 * DO-namespace/hyperdrive/container-image records, bundle options.
328 *
329 * Queue consumers are deliberately EXCLUDED: `getQueueConsumers`
330 * reads `LocalRuntimeState` at serve time and sibling `Consumer`
331 * reconciles drive restarts through the `workerRestarts` hook — they
332 * are runtime wiring observed at start, not desired-state config.
333 */
334 const resolveConfig = Effect.fn(function* ({
335 id,
336 fqn,
337 news,
338 bindings,
339 }: LocalProvider.LocalProviderInput<Worker>) {
340 const props = news as WorkerProps;
341 const name = yield* createWorkerName(id, props.name);
342 const compatibility = getCompatibility(props);
343 const bindingDescriptors: WorkerBinding[] = [];
344 const durableObjectNamespaces: Record<
345 string,
346 RuntimeDurableObject & { uniqueKey: string }
347 > = {};
348 const workflows: Record<string, RuntimeWorkflow> = {};
349 const hyperdrives: Record<string, Required<HyperdriveOrigin>> = {};
350 // Dev-only channel (like `hyperdrives`): binding name → opt-out of
351 // local emulation (the binding was piped through `Alchemy.remote()`). Read
352 // by `toRuntimeBinding` when lowering browser/images/stream/
353 // send_email descriptors. Part of the hashed config: flipping the
354 // opt-out restarts the instance.
355 const devRemote: Record<string, boolean> = {};
356 const containers: Record<string, NonNullable<RuntimeDurableObject["container"]>> = {};
357 // Content hashes of the container images, keyed like `containers`.
358 // `ContainerImage` itself only carries stable paths (context /
359 // dockerfile / imageUri), so without the hash an image CONTENT
360 // change (a Dockerfile edit, a rebuilt bundle) would never change
361 // the config and the running container would serve stale code.
362 const containerHashes: Record<string, string> = {};
363 const containerRows: NonNullable<Worker["Binding"]["containers"]> = [];
364 const boundEnv: Record<string, any> = { ...props.env };
365 for (const { data } of bindings) {
366 if (data.env) Object.assign(boundEnv, data.env);
367 for (const binding of data.bindings ?? []) {
368 if (
369 binding.type === "durable_object_namespace" &&
370 // The `durableObjectNamespaces` property is only used to declare DOs in this worker.
371 // Otherwise, it's a cross-worker durable object binding, which cloudflare-runtime handles automatically.
372 (!binding.scriptName || binding.scriptName === name)
373 ) {
374 // Reuse the existing namespace id if it was provided, otherwise generate a new one.
375 // `workerd` uses this for the object's storage path, so it must be safe to use as a file name.
376 const namespaceId =
377 binding.namespaceId ?? encodeURIComponent(`${name}-${binding.className}`);
378 durableObjectNamespaces[binding.className] = {
379 className: binding.className,
380 uniqueKey: namespaceId,
381 // A key-value backed class has no SQL storage, as on Cloudflare.
382 sql: binding.storage !== "legacy-kv",
383 };
384 bindingDescriptors.push({ ...binding, namespaceId });
385 } else {
386 if (
387 binding.type === "workflow" &&
388 // Same ownership rule as DOs: only declare workflows hosted by
389 // this worker. Cross-script workflow bindings are routed via
390 // the registry proxy.
391 (!binding.scriptName || binding.scriptName === name)
392 ) {
393 workflows[binding.workflowName] = {
394 workflowName: binding.workflowName,
395 className: binding.className,
396 };
397 }
398 bindingDescriptors.push(binding);
399 }
400 }
401 if (data.devRemote) {
402 for (const [name, remote] of Object.entries(data.devRemote)) {
403 devRemote[name] = remote;
404 }
405 }
406 if (data.hyperdrives) {
407 for (const [id, origin] of Object.entries(data.hyperdrives)) {
408 hyperdrives[id] = {
409 scheme: origin.scheme,
410 host: origin.host,
411 port: origin.port,
412 user: origin.user,
413 database: origin.database,
414 password: unwrapRedacted(origin.password),
415 sslmode: origin.sslmode,
416 };
417 }
418 }
419 if (data.containers) containerRows.push(...data.containers);
420 }
421 // A Durable Object-managed class merges the images of every bound
422 // Container (keyed by Container id); a fleet class has one image.
423 // Build paths resolve against the stack's working directory here: a
424 // Vite Worker's runtime runs in a child whose cwd is the site root.
425 const toRuntimeImage = (image: DevContainerImage) =>
426 "dockerfile" in image
427 ? {
428 ...image,
429 ...(image.context !== undefined
430 ? { context: path.resolve(runtimeBase, image.context) }
431 : { dockerfile: path.resolve(runtimeBase, image.dockerfile) }),
432 env: unwrapRedacted(image.env),
433 buildSecrets: unwrapRedacted(image.buildSecrets),
434 }
435 : { ...image, env: unwrapRedacted(image.env) };
436 const exportMap = (props.exports ?? {}) as Record<string, unknown>;
437 yield* assertBindingContainersOnAsyncClasses(
438 containerRows,
439 Object.keys(exportMap).filter((name) => isDurableObjectExport(exportMap[name])),
440 );
441 for (const container of yield* mergeWorkerContainers(containerRows)) {
442 if (container.devImages !== undefined) {
443 const images: Record<string, RuntimeContainerImage> = {};
444 for (const [key, image] of Object.entries(container.devImages)) {
445 images[key] = toRuntimeImage(image);
446 }
447 containers[container.className] = { images };
448 } else if (container.dev) {
449 containers[container.className] = toRuntimeImage(container.dev);
450 } else {
451 return yield* Effect.die(`Container ${container.className} has no dev image`);
452 }
453 if (container.hash !== undefined) {
454 containerHashes[container.className] = container.hash;
455 }
456 }
457 for (const [className, dev] of Object.entries(containers)) {
458 if (!durableObjectNamespaces[className]) {
459 return yield* Effect.die(`Durable Object namespace ${className} not found`);
460 }
461 durableObjectNamespaces[className].container = dev;
462 }
463 const dev: DevServerOptions | { readonly mode: "external"; readonly url?: string } =
464 props.dev?.mode === "external"
465 ? props.dev
466 : {
467 ...props.dev,
468 mode: "worker" as const,
469 // This is the default. Vite and cloudflare-runtime will retry
470 // if unavailable, unless `strictPort` is true.
471 port: props.dev?.port ?? DEFAULT_DEV_PORT,
472 };
473 return {
474 id,
475 /** Namespace-qualified id — the display prefix for every log line. */
476 fqn,
477 name,
478 compatibility,
479 /** User env (Redacted preserved — the canonical hasher unwraps). */
480 env: Object.keys(boundEnv).length > 0 ? boundEnv : props.env,
481 /**
482 * Raw inline module source (mutually exclusive with `main`).
483 * Serves as-is without the bundler; part of the hashed config so
484 * editing the script restarts the instance.
485 */
486 script: props.script,
487 // External source providers (`props.source`) opt in through
488 // `devAssetsBinding` instead (see `ViteChildRunner`): injecting
489 // the hook for every source would fail in dev hosts with no
490 // assets service configured (the hook errors when the Assets
491 // service is unconfigured).
492 hasAssets: !!(props.assets || props.vite) && !props.source,
493 /**
494 * Assets-only Worker (no entry module at all): served locally by
495 * a stub that delegates every request to the ASSETS binding.
496 */
497 assetsOnly:
498 props.main === undefined && props.script === undefined && !props.vite && !!props.assets,
499 bindingDescriptors,
500 durableObjectNamespaces: Object.values(durableObjectNamespaces),
501 workflows: Object.values(workflows),
502 hyperdrives,
503 /**
504 * Container image CONTENT hashes (className → hash). The DO
505 * namespace records above only carry the image's stable paths, so
506 * this is what makes an image content change — a Dockerfile edit,
507 * a rebuilt effectful bundle — restart the instance (which is
508 * what re-runs the docker build).
509 */
510 containerHashes,
511 /**
512 * External source-provider descriptor (plain JSON). Part of the
513 * hashed config so changing the provider or its options restarts
514 * the instance.
515 */
516 source: props.source,
517 /**
518 * Prebuilt worker (`bundle: false`): local dev must serve the
519 * entry + rule-matched sibling modules byte-for-byte (fs-watch +
520 * re-read) — never re-bundle the prebuilt artifact with rolldown.
521 */
522 prebuilt: props.bundle === false,
523 rules: props.rules,
524 devRemote,
525 vite: !!props.vite,
526 // Relative `vite.main` resolves from the Vite root (see the
527 // matching normalization in WorkerProvider's `viteBuild`).
528 viteMain: props.vite?.main
529 ? yield* resolveViteMain(
530 path.resolve(props.vite.rootDir ?? process.cwd()),
531 props.vite.main,
532 )
533 : undefined,
534 viteEnvironments: props.vite?.viteEnvironments,
535 viteRootDir: props.vite?.rootDir,
536 bundleOptions: workerBundleOptions({
537 id,
538 props,
539 compatibility,
540 stack: { name: stack.name, stage: stack.stage },
541 }),
542 assets: props.assets,
543 dev,
544 crons: Array.from(new Set([...getCronBindings(bindings), ...(props.crons ?? [])])),
545 // Tail consumers, resolved to plain `{ service }` records exactly
546 // like the live provider hashes/uploads them (script names only,
547 // deliberately hash-safe). Restart-relevant: serve lowers the list
548 // into workerd's native `tails` service designators.
549 tailConsumers: resolveTailConsumers(props.tailConsumers),
550 // Streaming tail consumers, same resolution — serve lowers the
551 // list into workerd's `streamingTails` designators, which deliver
552 // the producer's events live via the consumer's `tailStream()`.
553 streamingTailConsumers: resolveTailConsumers(props.streamingTailConsumers),
554 /**
555 * Zone routes, emulated by the local edge (see `LocalEdge`). The
556 * zone is never resolved in dev — `zoneId` is the declared id or
557 * a `dev:`-marked stand-in.
558 */
559 routes: (props.routes ?? []).map((route) => {
560 const pattern = route.pattern.trim();
561 const zone =
562 route.zoneName ??
563 (typeof route.zone === "string" ? route.zone : route.zone?.zoneId) ??
564 routePatternHost(pattern) ??
565 pattern;
566 return { id: `dev:${pattern}`, pattern, zoneId: route.zoneId ?? `dev:${zone}` };
567 }),
568 /**
569 * The custom-domain hostname. In dev the Worker's own URL serves
570 * it, with zone routes for the hostname applied in front.
571 */
572 edgeDomain:
573 typeof props.domain === "string" ? props.domain : (props.domain?.name ?? undefined),
574 /**
575 * The zone outbound `fetch()`es report in `CF-Worker`: the custom
576 * domain, else the first route's zone, as Wrangler derives it.
577 */
578 zone:
579 (typeof props.domain === "string" ? props.domain : props.domain?.name) ??
580 props.routes?.[0]?.zoneName ??
581 (props.routes?.[0] ? routePatternHost(props.routes[0].pattern.trim()) : undefined),
582 };
583 });
584
585 type WorkerConfig = Effect.Success<ReturnType<typeof resolveConfig>>;
586 /** A worker-mode config with its runtime `BindingHook`s materialized. */
587 type RunnableWorkerConfig = Omit<WorkerConfig, "dev"> & {
588 dev: DevServerOptions;
589 workerBindings: BindingHook<BindingServices>[];
590 };
591
592 /**
593 * Materialize the plain binding descriptors from {@link resolveConfig}
594 * into live cloudflare-runtime `BindingHook`s. This is the non-plain
595 * half of the old `buildConfig` — kept out of the hashed config.
596 */
597 const materializeWorkerBindings = Effect.fn(function* (
598 config: WorkerConfig,
599 selfUrl: string | undefined,
600 ) {
601 const accountId = yield* localAccountId;
602 return yield* materializeRuntimeBindings(
603 {
604 ...config,
605 devAccess: config.dev.mode === "external" ? undefined : config.dev.access,
606 },
607 {
608 accountId,
609 selfUrl,
610 stack: { name: stack.name, stage: stack.stage },
611 },
612 );
613 });
614
615 // Latest successful serve per worker FQN, so runtime wiring changes
616 // that arrive AFTER workerd started (e.g. a sibling `Consumer`
617 // resource registering this script as a queue consumer) can restart
618 // the instance with the same bundle.
619 const latestServes = new Map<
620 string,
621 {
622 worker: RunnableWorkerConfig;
623 bundle: Bundle.BundleOutput;
624 proxy: WorkerProxy.WorkerProxyInstance;
625 }
626 >();
627 // Serializes serves per worker FQN: a restart triggered by a sibling
628 // resource may otherwise interleave with a rebuild-triggered serve
629 // and leak a workerd scope.
630 const serveLocks = new Map<string, Semaphore.Semaphore>();
631 const serveLock = (id: string) => {
632 let lock = serveLocks.get(id);
633 if (!lock) {
634 lock = Semaphore.makeUnsafe(1);
635 serveLocks.set(id, lock);
636 }
637 return lock;
638 };
639
640 const workerdScopes = new Map<string, Scope.Closeable>();
641
642 // Serve with make-before-break semantics: start the replacement
643 // workerd while the previous instance (if any) keeps serving — and
644 // stays registered in the dev registry — then cut the proxy over and
645 // tear the previous instance down. Cross-script consumers (e.g. a DO
646 // bound via `scriptName` from another Worker) therefore never observe
647 // a window where the script has no running instance and no registry
648 // entry, even when `runtime.start` is slow (container image builds).
649 // Workers with containers are the exception: their previous instance
650 // is retired after the images are ready but before the new workerd
651 // boots (see `beforeServe` in `serveWith`).
652 // Both instances use the same registry key; the registry's entry
653 // removal is owner-aware, so closing the old scope after the
654 // replacement has re-registered cannot delete the replacement's
655 // registration.
656 //
657 // The workerd scope is forked from the provider's `rootScope`, NOT
658 // the instance scope: a reconcile that replaces the instance (or a
659 // restart triggered from a sibling provider's fiber) tears down the
660 // bundle watcher without killing the currently serving workerd — the
661 // last good instance keeps serving until the replacement's first
662 // serve completes. Ownership is tracked in `workerdScopes`, closed by
663 // the next successful serve, by `delete`, or by provider shutdown.
664 /**
665 * One container-context watcher per worker FQN, keyed by the watched
666 * path set. Registry-held (NOT per-serve-scope): a worker restarts
667 * through several code paths that overlap scopes, and a watcher per
668 * serve produced DUPLICATES whose simultaneous restarts storm the
669 * instance until the DO's container link breaks.
670 */
671 const containerWatchers = new Map<string, { key: string; fiber: Fiber.Fiber<void> }>();
672
673 const stopContainerWatcher = (id: string) =>
674 Effect.suspend(() => {
675 const existing = containerWatchers.get(id);
676 if (existing === undefined) return Effect.void;
677 containerWatchers.delete(id);
678 return Fiber.interrupt(existing.fiber).pipe(Effect.asVoid);
679 });
680
681 /**
682 * Watch a worker's Build-variant container contexts and restart the
683 * instance when their CONTENT changes — the docker build happens at
684 * instance start, so a restart IS the image rebuild.
685 *
686 * This is the reload path for USER-supplied Dockerfile/context
687 * containers: those files are not imported by the stack, so
688 * `bun --watch` never re-runs the exec child for them and no replan
689 * (hence no config-hash restart) ever fires. Generated contexts
690 * (under `.alchemy/`) are excluded — the effectful `main` variant
691 * rewrites its bundle there on every plan, which would loop; that
692 * variant reloads through the config's `containerHashes` instead.
693 *
694 * Events are debounced and gated on a content fingerprint
695 * (`node_modules`/`.git` skipped), so editor double-saves and
696 * metadata-only churn don't bounce the instance.
697 */
698 const ensureContainerWatcher = (
699 worker: RunnableWorkerConfig,
700 restart: Effect.Effect<
701 void,
702 never,
703 ChildProcessSpawner.ChildProcessSpawner | PlatformFileSystem.FileSystem | Path.Path
704 >,
705 ) =>
706 Effect.gen(function* () {
707 const fs = yield* PlatformFileSystem.FileSystem;
708 const watched = new Map<string, { dockerfile: string | undefined }>();
709 for (const namespace of worker.durableObjectNamespaces) {
710 const container = namespace.container;
711 if (container === undefined) continue;
712 const images = "images" in container ? Object.values(container.images) : [container];
713 for (const image of images) {
714 if (!("dockerfile" in image)) continue;
715 const context = path.resolve(runtimeBase, image.context ?? ".");
716 if (isPathWithin(dotAlchemy, context, runtimeBase)) continue;
717 watched.set(context, {
718 dockerfile:
719 image.dockerfile !== undefined
720 ? path.resolve(context, image.dockerfile)
721 : undefined,
722 });
723 }
724 }
725 const key = JSON.stringify(
726 [...watched.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
727 );
728 const existing = containerWatchers.get(worker.fqn);
729 if (existing !== undefined) {
730 if (existing.key === key) return; // same watcher keeps running
731 yield* stopContainerWatcher(worker.fqn);
732 }
733 if (watched.size === 0) return;
734
735 const fingerprint = Effect.gen(function* () {
736 const hashes: string[] = [];
737 const walk = (dir: string): Effect.Effect<void, any> =>
738 Effect.gen(function* () {
739 const entries = yield* fs.readDirectory(dir);
740 for (const entry of entries.sort()) {
741 if (entry === "node_modules" || entry === ".git") continue;
742 const file = path.join(dir, entry);
743 const stat = yield* fs.stat(file);
744 if (stat.type === "Directory") {
745 yield* walk(file);
746 } else {
747 hashes.push(`${file}:${yield* fs.readFile(file).pipe(Effect.flatMap(sha256))}`);
748 }
749 }
750 });
751 for (const [context, { dockerfile }] of watched) {
752 yield* walk(context);
753 if (dockerfile !== undefined && !dockerfile.startsWith(context)) {
754 hashes.push(
755 `${dockerfile}:${yield* fs.readFile(dockerfile).pipe(Effect.flatMap(sha256))}`,
756 );
757 }
758 }
759 return yield* sha256(hashes.join("\n"));
760 }).pipe(Effect.orElseSucceed(() => undefined));
761
762 const streams = [...watched.entries()].flatMap(([context, { dockerfile }]) => [
763 fs.watch(context, { recursive: true }),
764 ...(dockerfile !== undefined && !dockerfile.startsWith(context)
765 ? [fs.watch(path.dirname(dockerfile))]
766 : []),
767 ]);
768 const watchLoop = Effect.gen(function* () {
769 let last = yield* fingerprint;
770 yield* Stream.mergeAll(streams, {
771 concurrency: streams.length,
772 }).pipe(
773 Stream.debounce("500 millis"),
774 Stream.runForEach(() =>
775 Effect.gen(function* () {
776 const next = yield* fingerprint;
777 if (next === undefined || next === last) return;
778 last = next;
779 yield* Effect.logInfo(`Container build context changed, restarting instance`);
780 yield* restart;
781 }),
782 ),
783 Effect.catchCause((cause) =>
784 Effect.logWarning(`Container context watch failed`, Cause.squash(cause)),
785 ),
786 );
787 });
788 const fiber = yield* watchLoop.pipe(
789 Effect.ensuring(
790 Effect.sync(() => {
791 const current = containerWatchers.get(worker.fqn);
792 if (current?.fiber === fiber) {
793 containerWatchers.delete(worker.fqn);
794 }
795 }),
796 ),
797 Effect.forkIn(rootScope),
798 );
799 containerWatchers.set(worker.fqn, { key, fiber });
800 });
801
802 // Custom-domain hostnames handed to the local edge, per worker FQN.
803 const edgeDomains = new Map<string, { host: string; script: string }>();
804
805 const releaseEdgeDomain = Effect.fn(function* (fqn: string) {
806 const previous = edgeDomains.get(fqn);
807 if (previous) {
808 edgeDomains.delete(fqn);
809 yield* edge.removeDomain(previous.host, previous.script);
810 }
811 });
812
813 /**
814 * Point the worker's stable proxy at a freshly served workerd. A
815 * custom-domain worker is handed to the local edge instead, which
816 * fronts it with the zone-route router whenever routes match its
817 * hostname (Cloudflare's routes-over-custom-domain precedence).
818 */
819 const exposeWorker = Effect.fn(function* (
820 worker: RunnableWorkerConfig,
821 proxy: WorkerProxy.WorkerProxyInstance,
822 url: URL,
823 ) {
824 const previous = edgeDomains.get(worker.fqn);
825 if (previous && (previous.host !== worker.edgeDomain || previous.script !== worker.name)) {
826 yield* releaseEdgeDomain(worker.fqn);
827 }
828 if (worker.edgeDomain === undefined) {
829 return yield* proxy.set(url);
830 }
831 edgeDomains.set(worker.fqn, { host: worker.edgeDomain, script: worker.name });
832 yield* edge.serveDomain(worker.edgeDomain, { script: worker.name, proxy, upstream: url });
833 });
834
835 const serveWith = (
836 worker: RunnableWorkerConfig,
837 bundle: Bundle.BundleOutput,
838 proxy: WorkerProxy.WorkerProxyInstance,
839 ) =>
840 Semaphore.withPermits(
841 serveLock(worker.fqn),
842 1,
843 )(
844 // The bookkeeping around `runtime.start` must not be torn in half
845 // by an interrupt: once a replacement workerd is up, it must be
846 // recorded in `workerdScopes` and the superseded instances must be
847 // closed, or one of the workerds would leak until provider
848 // shutdown while holding the shared registry key.
849 Effect.uninterruptibleMask((restore) =>
850 Effect.gen(function* () {
851 const previous = workerdScopes.get(worker.fqn);
852 // Instances to tear down once the replacement is up: `previous`
853 // plus any instance whose queue-consumer wiring went stale
854 // while it was starting (never exposed via the proxy).
855 const retiring: Scope.Closeable[] = previous ? [previous] : [];
856 const closeRetiring = Effect.suspend(() =>
857 Effect.forEach(
858 retiring.splice(0),
859 (replaced) =>
860 Scope.close(replaced, Exit.void).pipe(
861 Effect.catchCause((cause) =>
862 Effect.logWarning(
863 `Failed to stop previous local worker instance`,
864 Cause.squash(cause),
865 ),
866 ),
867 ),
868 { discard: true },
869 ),
870 ).pipe(Effect.uninterruptible);
871 // Container names are deterministic per Durable Object, so a
872 // new workerd would "recover" the previous instance's
873 // still-running container — which the previous instance's
874 // teardown then removes (with its networking sidecar) out from
875 // under it. For workers with containers, break before make:
876 // retire the previous instance after the slow part of the start
877 // (image builds/pulls) but before the new workerd boots, parking
878 // requests on the proxy until the cutover.
879 const hasContainers = worker.durableObjectNamespaces.some(
880 (namespace) => namespace.container !== undefined,
881 );
882 const beforeServe = hasContainers
883 ? Effect.suspend(() =>
884 retiring.length > 0
885 ? Effect.andThen(proxy.unset(), closeRetiring)
886 : Effect.void,
887 )
888 : undefined;
889 let scope!: Scope.Closeable;
890 let url!: URL;
891 // Queue-consumer wiring can change while `runtime.start` is in
892 // flight (a sibling `Consumer` reconcile), before the restart
893 // hook below exists to pick it up. We hold the serve lock, so a
894 // restart would deadlock — instead, loop and serve again until
895 // the wiring is stable across a start.
896 while (true) {
897 const queueConsumers = yield* getQueueConsumers(worker.name);
898 scope = yield* Scope.fork(rootScope);
899 // `logging.onOutput` REPLACES workerd's stdio inheritance, so
900 // this is the only path its output takes: complete lines become
901 // log records tagged with the worker.
902 // One splitter per channel: a shared buffer would splice a
903 // partial stdout line onto the next stderr chunk, and stderr
904 // would lose its severity on the way to the console.
905 const splitters = yield* makeResourceOutput(worker.fqn);
906 yield* Scope.addFinalizer(
907 scope,
908 Effect.sync(() => {
909 splitters.stdout.flush();
910 splitters.stderr.flush();
911 }),
912 );
913 url = yield* restore(
914 runtime
915 .start({
916 name: worker.name,
917 logging: {
918 // `(chunk, stream)` — chunk first; the stream name
919 // indexes the splitters directly.
920 onOutput: (chunk, stream) => splitters[stream].push(chunk),
921 },
922 compatibilityDate: worker.compatibility.date,
923 compatibilityFlags: worker.compatibility.flags,
924 zone: worker.zone,
925 // `dev.access` populates the Worker's native `ctx.access`.
926 access: worker.dev.access,
927 // Stream preview and Images variant URLs use the stable URL
928 // clients reach the Worker at, as Miniflare uses its public URL.
929 publicUrl: proxy.url.toString().replace(/\/$/, ""),
930 bindings: worker.workerBindings as never,
931 hyperdrives: worker.hyperdrives,
932 durableObjectNamespaces: worker.durableObjectNamespaces,
933 workflows: worker.workflows,
934 queueConsumers,
935 // Cron triggers: the runtime starts a Node-side timer
936 // per expression and exposes the Miniflare-compatible
937 // manual trigger route `/cdn-cgi/handler/scheduled`.
938 crons: worker.crons,
939 // Tail consumers by script name — each resolves through
940 // the dev registry proxy exactly like cross-worker
941 // service bindings; a consumer that isn't running yet
942 // drops events with a `[registry]` warning until it
943 // registers (wrangler dev-registry semantics).
944 tails: worker.tailConsumers?.map((c) => c.service),
945 // Streaming tail consumers by script name — resolved
946 // through the same registry proxy; the consumer's
947 // `tailStream()` receives the onset while the producer
948 // is still executing (dropped with a `[registry]`
949 // warning until the consumer registers).
950 streamingTails: worker.streamingTailConsumers?.map((c) => c.service),
951 // Cache API opt-out (`dev: { cache: false }`) — matches
952 // production workers.dev, where the Cache API is a no-op.
953 cache: worker.dev.cache,
954 // Per-worker request.cf override (`dev: { cf: {...} }`).
955 cf: worker.dev.cf,
956 workerd: worker.dev.workerd,
957 modules: yield* toRuntimeModules(bundle),
958 assets: yield* toRuntimeAssets(worker.assets),
959 beforeServe,
960 })
961 .pipe(Scope.provide(scope)),
962 ).pipe(
963 // The scope hangs off `rootScope`, so a failed or
964 // interrupted start must close it here — nothing else owns
965 // it yet.
966 Effect.onExit((exit) =>
967 exit._tag === "Failure" ? Scope.close(scope, exit) : Effect.void,
968 ),
969 );
970 workerdScopes.set(worker.fqn, scope);
971 latestServes.set(worker.fqn, { worker, bundle, proxy });
972 // Register the restart hook before the re-check below: changes
973 // landing after the re-check find the hook; changes before it
974 // are caught by the re-check. Nothing falls in between.
975 MutableHashMap.set(
976 localRuntimeState.workerRestarts,
977 worker.name,
978 restartWorker(worker.fqn),
979 );
980 // Idempotent: the registry keeps ONE watcher per worker FQN
981 // across restarts (a new one only when the watched path set
982 // changed).
983 yield* ensureContainerWatcher(
984 worker,
985 Effect.suspend(() => restartWorker(worker.fqn)),
986 );
987 const currentConsumers = yield* getQueueConsumers(worker.name);
988 if (JSON.stringify(currentConsumers) !== JSON.stringify(queueConsumers)) {
989 // Wiring changed while workerd was starting — serve again
990 // with the fresh consumers before exposing the instance.
991 retiring.push(scope);
992 continue;
993 }
994 break;
995 }
996 yield* exposeWorker(worker, proxy, url);
997 // Only now tear the replaced instances down (unless
998 // `beforeServe` already did): `previous` kept serving — and
999 // stayed registered in the dev registry — until the cutover
1000 // above. The registry's entry removal is owner-aware, so these
1001 // closes cannot delete the replacement's registration.
1002 yield* closeRetiring;
1003 return url;
1004 }),
1005 ),
1006 );
1007
1008 /**
1009 * Restart a running worker with its latest bundle (or its latest Vite
1010 * dev-server child) so start-time runtime wiring (queue consumers) is
1011 * re-read from {@link LocalRuntimeState}. No-op if the worker hasn't
1012 * served yet — the pending first serve will already observe the
1013 * updated state.
1014 */
1015 const logRestartFailure = (fqn: string) =>
1016 Effect.catchCause((cause: Cause.Cause<unknown>) =>
1017 Effect.logWarning(`Failed to restart local worker`, Cause.squash(cause)).pipe(
1018 Effect.annotateLogs(LogAnnotation.fqn, fqn),
1019 ),
1020 );
1021
1022 const restartWorker = (
1023 id: string,
1024 ): Effect.Effect<
1025 void,
1026 never,
1027 ChildProcessSpawner.ChildProcessSpawner | PlatformFileSystem.FileSystem | Path.Path
1028 > =>
1029 Effect.suspend(() => {
1030 const latest = latestServes.get(id);
1031 if (latest) {
1032 return serveWith(latest.worker, latest.bundle, latest.proxy).pipe(
1033 Effect.asVoid,
1034 logRestartFailure(latest.worker.fqn),
1035 );
1036 }
1037 const vite = latestViteServes.get(id);
1038 if (vite) {
1039 // A Vite boot is expensive, so skip the restart if the running
1040 // child already serves the current wiring (the in-flight serve's
1041 // re-check loop may have picked it up while this restart waited
1042 // on the serve lock).
1043 return serveVite(vite, { onlyIfConsumersChanged: true }).pipe(
1044 Effect.asVoid,
1045 logRestartFailure(vite.worker.fqn),
1046 );
1047 }
1048 return Effect.void;
1049 });
1050
1051 // Tear down the running workerd for a worker FQN, if any. Used when the
1052 // Worker is deleted or handed off to an external dev process —
1053 // instance replacement does NOT go through this: the previous workerd
1054 // keeps serving until the replacement's first serve closes it.
1055 const closeWorkerd = Effect.fn(function* (id: string) {
1056 yield* stopContainerWatcher(id);
1057 const scope = workerdScopes.get(id);
1058 if (scope) {
1059 workerdScopes.delete(id);
1060 yield* Scope.close(scope, Exit.void);
1061 }
1062 });
1063
1064 // Note: `serveLocks` entries are intentionally retained — an
1065 // in-flight restart may still hold the semaphore when the instance
1066 // is torn down, and a same-id re-create must serialize against it.
1067 const dropServeState = (id: string) => {
1068 const latest = latestServes.get(id) ?? latestViteServes.get(id);
1069 if (latest) {
1070 MutableHashMap.remove(localRuntimeState.workerRestarts, latest.worker.name);
1071 latestServes.delete(id);
1072 latestViteServes.delete(id);
1073 servedViteConsumers.delete(id);
1074 servedViteHttps.delete(id);
1075 }
1076 };
1077
1078 /**
1079 * Drain a stream of bundle-watch events into the make-before-break
1080 * `serveWith` path, forked into the instance scope: queue requests
1081 * while a rebuild is in flight, serve every successful bundle, and
1082 * log build/serve errors without tearing the instance down.
1083 *
1084 * Used by every bundle-mode source (`runSource`), which all speak the
1085 * {@link Bundle.BundleWatchEvent} protocol.
1086 */
1087 const serveBundleStream = Effect.fn(function* <E, R>(
1088 worker: RunnableWorkerConfig,
1089 proxy: WorkerProxy.WorkerProxyInstance,
1090 bundles: Stream.Stream<Bundle.BundleWatchEvent, E, R>,
1091 ) {
1092 let start = Date.now();
1093 let status: "start" | "update" = "start";
1094 // Resolved once the first bundle is served (or its build or serve
1095 // failed): the instance's `start` returns at readiness, so a restart
1096 // never completes while the previous bundle is still the latest
1097 // serve (`latestServes`) that restart hooks re-serve.
1098 const firstServe = yield* Deferred.make<void>();
1099 yield* bundles.pipe(
1100 Stream.tap((event) => {
1101 if (event._tag === "Start") {
1102 start = Date.now();
1103 if (status === "update") {
1104 return Effect.all([
1105 Effect.log(`Rebuilding`),
1106 // Tells the proxy to queue requests until the updated
1107 // worker is ready.
1108 proxy.unset(),
1109 ]);
1110 }
1111 } else if (event._tag === "Error") {
1112 return Effect.all([
1113 Effect.logError(`Bundle error`, event.error),
1114 // No updated worker is coming from this build: answer
1115 // parked requests with the error now instead of after the
1116 // pending timeout.
1117 proxy.fail(event.error.message),
1118 Deferred.succeed(firstServe, undefined),
1119 ]);
1120 }
1121 return Effect.void;
1122 }),
1123 Stream.filterMap((event) =>
1124 event._tag === "Success" ? Result.succeed(event.output) : Result.failVoid,
1125 ),
1126 Stream.mapEffect((bundle) =>
1127 serveWith(worker, bundle, proxy).pipe(
1128 Effect.exit,
1129 Effect.tap((exit) => {
1130 if (exit._tag === "Success") {
1131 // URL on first start only — vite-banner style; rebuild
1132 // lines stay compact.
1133 const message = Effect.log(
1134 status === "update"
1135 ? workerUpdatedMessage(Date.now() - start)
1136 : workerStartedMessage(Date.now() - start, proxy.url),
1137 );
1138 status = "update";
1139 return message;
1140 } else {
1141 return Effect.all([
1142 Effect.logError(`Error`, Cause.squash(exit.cause)),
1143 proxy.fail(Cause.pretty(exit.cause)),
1144 ]);
1145 }
1146 }),
1147 Effect.ensuring(Deferred.succeed(firstServe, undefined)),
1148 ),
1149 ),
1150 Stream.runDrain,
1151 // A stream that ends or fails before any bundle must not park
1152 // `start` forever.
1153 Effect.ensuring(Deferred.succeed(firstServe, undefined)),
1154 Effect.forkScoped,
1155 );
1156 yield* Deferred.await(firstServe);
1157 });
1158
1159 // Assets-only Worker: there is no entry module to bundle or watch.
1160 // The local runtime requires a user worker module, so serve a stub
1161 // that delegates every request to the ASSETS binding — the assets
1162 // worker applies `htmlHandling` / `notFoundHandling` (including SPA
1163 // fallback) itself, matching Cloudflare's deployed assets-only
1164 // behavior.
1165 const assetsOnlyBundle: Bundle.BundleOutput = {
1166 files: [
1167 {
1168 path: "main.js",
1169 content: "export default { fetch: (request, env) => env.ASSETS.fetch(request) };",
1170 hash: "assets-only-stub",
1171 },
1172 ],
1173 hash: "assets-only-stub",
1174 };
1175
1176 const runAssetsOnly = Effect.fn(function* (worker: RunnableWorkerConfig) {
1177 const start = Date.now();
1178 const proxy = yield* maybeStartProxy(worker.fqn, worker.dev);
1179 yield* serveWith(worker, assetsOnlyBundle, proxy);
1180 yield* Effect.log(workerStartedMessage(Date.now() - start, proxy.url));
1181 return proxy.url;
1182 });
1183
1184 /** Everything needed to serve (or re-serve) a Vite dev-server child. */
1185 interface ViteServeArgs {
1186 worker: RunnableWorkerConfig;
1187 rootDir: string | undefined;
1188 invalidate: Effect.Effect<void>;
1189 source: NonNullable<ViteChildConfig["source"]> | undefined;
1190 proxy: WorkerProxy.WorkerProxyInstance;
1191 }
1192
1193 /** The Vite analogue of `latestServes`: everything needed to restart
1194 * the dev-server child when a sibling `Consumer` reconcile changes the
1195 * queue-consumer wiring (see `workerRestarts`). */
1196 const latestViteServes = new Map<string, ViteServeArgs>();
1197
1198 /** The queue-consumer wiring (canonical JSON) each running Vite child
1199 * was started with, for the restart path's changed-wiring check. */
1200 const servedViteConsumers = new Map<string, string>();
1201
1202 /** Whether each running Vite child serves HTTPS (the app's
1203 * `server.https`): the proxy relays TLS untouched, so its URL takes the
1204 * child's scheme. */
1205 const servedViteHttps = new Map<string, boolean>();
1206
1207 // Serve a Vite dev-server child with the same two guarantees
1208 // `serveWith` gives a plain worker: a `workerRestarts` hook so sibling
1209 // `Consumer` reconciles can restart the child with fresh queue-consumer
1210 // wiring, and a post-start re-check so wiring that lands while the
1211 // child is starting is not lost. Unlike `serveWith` this is
1212 // break-before-make — two Vite dev servers rooted at the same app
1213 // would race file watchers and Durable Object storage — so the proxy
1214 // queues requests across the gap. The child's scope is forked from
1215 // `rootScope` and tracked in `workerdScopes`, so it survives instance
1216 // restarts and is reclaimed by `stop`/handoff/`serveWith` like any
1217 // other running instance.
1218 const serveVite = (args: ViteServeArgs, options?: { onlyIfConsumersChanged?: boolean }) =>
1219 Semaphore.withPermits(
1220 serveLock(args.worker.fqn),
1221 1,
1222 )(
1223 // The bookkeeping around `startViteChild` must not be torn in half
1224 // by an interrupt: once a replacement child is up it must be
1225 // recorded in `workerdScopes`, or it would leak until provider
1226 // shutdown while holding the worker's registry key.
1227 Effect.uninterruptibleMask((restore) =>
1228 Effect.gen(function* () {
1229 const { worker, rootDir, invalidate, source, proxy } = args;
1230 if (options?.onlyIfConsumersChanged) {
1231 const current = yield* getQueueConsumers(worker.name);
1232 if (
1233 workerdScopes.has(worker.fqn) &&
1234 JSON.stringify(current) === servedViteConsumers.get(worker.fqn)
1235 ) {
1236 return;
1237 }
1238 }
1239 // Queue requests while the child is (re)starting.
1240 yield* proxy.unset();
1241 // The dev server and its workerd run in a child process rooted
1242 // at the app.
1243 const root = path.resolve(rootDir ?? process.cwd());
1244 const accountId = yield* localAccountId;
1245 // Queue-consumer wiring can change while the child is starting
1246 // (a sibling `Consumer` reconcile), before the restart hook
1247 // below exists to pick it up. We hold the serve lock, so a
1248 // restart would deadlock — instead, loop and serve again until
1249 // the wiring is stable across a start.
1250 while (true) {
1251 const queueConsumers = yield* getQueueConsumers(worker.name);
1252 // Break-before-make: tear the previous child down before
1253 // starting its replacement (also covers a superseded child
1254 // from the previous loop iteration).
1255 yield* closeWorkerd(worker.fqn);
1256 const scope = yield* Scope.fork(rootScope);
1257 const logResourceOutput = makeResourceLogger(worker.fqn);
1258 const child = yield* restore(
1259 startViteChild(
1260 {
1261 rootDir: root,
1262 publicUrl: proxy.url.toString().replace(/\/$/, ""),
1263 accountId,
1264 storageDirectory,
1265 stack: { name: stack.name, stage: stack.stage },
1266 // Already resolved to plain values by `start`
1267 // (`Worker.URL` sentinels substituted); Redacted
1268 // unwraps at the process boundary inside
1269 // `startViteChild`.
1270 env: worker.env ?? {},
1271 source,
1272 worker: {
1273 name: worker.name,
1274 compatibility: worker.compatibility,
1275 main: worker.viteMain,
1276 viteEnvironments: worker.viteEnvironments,
1277 hasAssets: worker.hasAssets,
1278 bindingDescriptors: worker.bindingDescriptors,
1279 devRemote: worker.devRemote,
1280 devAccess: worker.dev.access,
1281 durableObjectNamespaces: worker.durableObjectNamespaces,
1282 workflows: worker.workflows,
1283 hyperdrives: worker.hyperdrives,
1284 queueConsumers,
1285 crons: worker.crons,
1286 tails: worker.tailConsumers?.map((c) => c.service),
1287 streamingTails: worker.streamingTailConsumers?.map((c) => c.service),
1288 cache: worker.dev.cache,
1289 cf: worker.dev.cf,
1290 workerd: worker.dev.workerd,
1291 zone: worker.zone,
1292 assets: yield* toRuntimeAssets(worker.assets),
1293 },
1294 },
1295 logResourceOutput,
1296 ).pipe(Scope.provide(scope)),
1297 ).pipe(
1298 // The scope hangs off `rootScope`, so a failed or
1299 // interrupted start must close it here — nothing else owns
1300 // it yet.
1301 Effect.onExit((exit) =>
1302 exit._tag === "Failure" ? Scope.close(scope, exit) : Effect.void,
1303 ),
1304 );
1305 workerdScopes.set(worker.fqn, scope);
1306 latestViteServes.set(worker.fqn, args);
1307 // Unexpected child death: log, fail the proxy so requests
1308 // see why instead of parking, and mark the instance for
1309 // update on the next plan. Forked into the child's scope so
1310 // a deliberate restart or teardown interrupts the watcher
1311 // before the process is killed.
1312 yield* child.exitCode.pipe(
1313 Effect.flatMap((exitCode) => {
1314 const message = `Dev server child exited unexpectedly with code ${exitCode}`;
1315 return Effect.all([Effect.logWarning(message), proxy.fail(message)]);
1316 }),
1317 Effect.andThen(invalidate),
1318 Effect.forkIn(scope),
1319 );
1320 // Register the restart hook before the re-check below:
1321 // changes landing after the re-check find the hook; changes
1322 // before it are caught by the re-check. Nothing falls in
1323 // between.
1324 MutableHashMap.set(
1325 localRuntimeState.workerRestarts,
1326 worker.name,
1327 restartWorker(worker.fqn),
1328 );
1329 const currentConsumers = yield* getQueueConsumers(worker.name);
1330 if (JSON.stringify(currentConsumers) !== JSON.stringify(queueConsumers)) {
1331 // Wiring changed while the child was starting — serve
1332 // again with the fresh consumers before exposing it.
1333 continue;
1334 }
1335 servedViteConsumers.set(worker.fqn, JSON.stringify(queueConsumers));
1336 servedViteHttps.set(worker.fqn, child.url.protocol === "https:");
1337 yield* proxy.set(child.url);
1338 return;
1339 }
1340 }),
1341 ),
1342 );
1343
1344 const runVite = Effect.fn(function* (
1345 worker: RunnableWorkerConfig,
1346 rootDir: string | undefined,
1347 invalidate: Effect.Effect<void>,
1348 source?: NonNullable<ViteChildConfig["source"]>,
1349 ) {
1350 const start = Date.now();
1351 const proxy = yield* maybeStartProxy(worker.fqn, worker.dev);
1352 yield* serveVite({ worker, rootDir, invalidate, source, proxy });
1353 const url = new URL(proxy.url);
1354 if (servedViteHttps.get(worker.fqn)) url.protocol = "https:";
1355 // The programmatic vite API never prints the CLI's URL banner — and
1356 // vite's own URL is the internal (port-shuffled) server behind the
1357 // stable proxy, so advertise the proxy instead.
1358 yield* Effect.log(workerStartedMessage(Date.now() - start, url));
1359 return url;
1360 });
1361
1362 // Every Worker served from bundles goes through its source provider's
1363 // `dev()`, as deploy goes through its `build()` (see `resolveSource`):
1364 // the built-in sources (inline script, Python, prebuilt, rolldown)
1365 // and external ones (`props.source`). Two modes (see
1366 // `SourceDevHandle`); `server` sources are run by `runVite`, so this
1367 // serves `bundle`: each successful bundle is served through the
1368 // make-before-break `serveWith` path.
1369 const runSource = Effect.fn(function* (worker: RunnableWorkerConfig) {
1370 const proxy = yield* maybeStartProxy(worker.fqn, worker.dev);
1371 // Queue requests until the source's first bundle is served.
1372 yield* proxy.unset();
1373 // `resolveSource` is typed against the full `SourceServices` union
1374 // (which includes the per-run Artifacts cache the live provider
1375 // supplies); local dev has no run-scoped cache, so hand the
1376 // source a fresh in-memory one.
1377 const source = yield* resolveSource({
1378 source: worker.source,
1379 script: worker.script,
1380 main: worker.source ? undefined : worker.bundleOptions.main,
1381 bundle: worker.prebuilt ? false : undefined,
1382 rules: worker.rules,
1383 }).pipe(
1384 Effect.provideService(
1385 AlchemyArtifacts,
1386 makeScopedArtifacts(createArtifactStore(), worker.fqn),
1387 ),
1388 );
1389 const devCtx: DevContext = {
1390 dotAlchemy,
1391 id: worker.id,
1392 fqn: worker.fqn,
1393 workerName: worker.name,
1394 compatibility: worker.compatibility,
1395 entry: worker.bundleOptions.entry,
1396 stack: { name: stack.name, stage: stack.stage },
1397 env: worker.env,
1398 // Dev hands `env` to the source unresolved; the Worker's own URL
1399 // is only substituted into a build's inlined env on deploy.
1400 selfUrl: undefined,
1401 extraOptions: worker.bundleOptions.extraOptions,
1402 assets: worker.assets,
1403 worker: {
1404 bindings: worker.workerBindings,
1405 durableObjectNamespaces: worker.durableObjectNamespaces,
1406 hyperdrives: worker.hyperdrives,
1407 queueConsumers: getQueueConsumers(worker.name),
1408 assets: yield* toRuntimeAssets(worker.assets),
1409 options: {
1410 workflows: worker.workflows,
1411 crons: worker.crons,
1412 tails: worker.tailConsumers?.map((c) => c.service),
1413 streamingTails: worker.streamingTailConsumers?.map((c) => c.service),
1414 cache: worker.dev.cache,
1415 cf: worker.dev.cf,
1416 zone: worker.zone,
1417 access: worker.dev.access,
1418 workerd: worker.dev.workerd,
1419 },
1420 },
1421 runtimeContext: context,
1422 };
1423 const handle = yield* source.dev(devCtx);
1424 if (handle.mode !== "bundle") {
1425 return yield* new SourceProviderError({
1426 provider: worker.source?.provider ?? "built-in",
1427 message: "A source declared devMode 'bundle' but returned a server-mode dev handle.",
1428 });
1429 }
1430 yield* serveBundleStream(worker, proxy, handle.bundles);
1431 return proxy.url;
1432 });
1433
1434 return {
1435 resolveConfig,
1436
1437 // The physical name only survives an update when it isn't changing.
1438 stables: ({ output, config }) =>
1439 Effect.succeed(
1440 output?.workerName === config.name ? (["workerName"] as ["workerName"]) : undefined,
1441 ),
1442
1443 precreate: Effect.fn(function* ({ id, fqn, news, bindings }) {
1444 const name = yield* createWorkerName(id, news.name);
1445 const durableObjectNamespaces: Record<string, string> = {};
1446 for (const { data } of bindings) {
1447 for (const binding of data?.bindings ?? []) {
1448 if (binding.type === "durable_object_namespace") {
1449 // Only classes this Worker hosts get a namespace, as in the
1450 // live provider's `getDurableObjectBindings`. A cross-script
1451 // reference names another Worker, by an Output that is still
1452 // unresolved here.
1453 if (binding.scriptName !== undefined && binding.scriptName !== name) continue;
1454 durableObjectNamespaces[binding.className] =
1455 binding.namespaceId ?? encodeURIComponent(`${name}-${binding.className}`);
1456 }
1457 }
1458 }
1459 const accountId = yield* localAccountId;
1460 const urls =
1461 news.dev?.mode === "external"
1462 ? // news.dev.url may be an unresolved output; avoid trying to resolve it here.
1463 []
1464 : yield* maybeStartProxy(fqn, {
1465 ...news.dev,
1466 mode: "worker" as const,
1467 port: news.dev?.port ?? DEFAULT_DEV_PORT,
1468 }).pipe(Effect.flatMap((proxy) => resolveLocalUrls(proxy.url)));
1469 return {
1470 // No cloud script exists in dev — fabricate a `dev:`-marked
1471 // identity (the shared local-provider convention, and the
1472 // legacy-row mode marker; see LOCAL_ID_PREFIX).
1473 workerId: `dev:${name}`,
1474 workerName: name,
1475 namespace: undefined,
1476 logpush: undefined,
1477 url: urls[0],
1478 urls,
1479 domain: undefined,
1480 tags: [],
1481 durableObjectNamespaces,
1482 routes: [],
1483 crons: Array.from(new Set([...getCronBindings(bindings), ...(news.crons ?? [])])),
1484 accountId,
1485 };
1486 }),
1487
1488 start: Effect.fn(function* ({ fqn, config, invalidate }) {
1489 const accountId = yield* localAccountId;
1490
1491 // `dev: { mode: "external" }` opts out of running a local Worker
1492 // entirely — typically because an external dev process
1493 // (Command.Dev) is serving requests. The instance exists in the
1494 // registry (with an empty scope) but has no workerd behind it. A
1495 // previous worker-mode instance for this FQN may have registered
1496 // serve/restart state — drop it, and tear down its workerd (with
1497 // make-before-break the running workerd outlives instance scopes
1498 // and must be closed explicitly on handoff).
1499 if (config.dev.mode === "external") {
1500 dropServeState(fqn);
1501 yield* closeWorkerd(fqn);
1502 yield* edge.removeRoutes(fqn);
1503 yield* releaseEdgeDomain(fqn);
1504 const urls = config.dev.url ? [config.dev.url] : [];
1505 return {
1506 workerId: `dev:${config.name}`,
1507 workerName: config.name,
1508 namespace: undefined,
1509 logpush: undefined,
1510 url: urls[0],
1511 urls,
1512 domain: undefined,
1513 tags: [],
1514 durableObjectNamespaces: {},
1515 accountId,
1516 routes: [],
1517 crons: config.crons,
1518 tailConsumers: config.tailConsumers,
1519 streamingTailConsumers: config.streamingTailConsumers,
1520 } satisfies Worker["Attributes"];
1521 }
1522
1523 // `Worker.URL` locally resolves to the worker's dev-proxy URL —
1524 // the proxy is stable per worker FQN (the same instance `runWorker`
1525 // / `runVite` attach to below), so the URL is known before workerd
1526 // starts. Trailing slash stripped to match the cloud value's shape.
1527 const needsSelfUrl =
1528 config.bindingDescriptors.some(
1529 (b) => b.type === "self_url" || b.type === "r2_s3_credentials",
1530 ) || Object.values(config.env ?? {}).some(isSelfUrl);
1531 const selfUrl = needsSelfUrl
1532 ? (yield* maybeStartProxy(fqn, config.dev)).url.toString().replace(/\/$/, "")
1533 : undefined;
1534 // Substitute `Worker.URL` sentinels once, up front — the runtime
1535 // bindings, the Vite define entries, and the child-process config
1536 // all consume the resolved URL as a plain string.
1537 const env =
1538 config.env && selfUrl !== undefined
1539 ? Object.fromEntries(
1540 Object.entries(config.env).map(([key, value]) => [
1541 key,
1542 isSelfUrl(value) ? selfUrl : value,
1543 ]),
1544 )
1545 : config.env;
1546 const workerBindings = yield* materializeWorkerBindings({ ...config, env }, selfUrl);
1547 const worker: RunnableWorkerConfig = {
1548 ...config,
1549 env,
1550 dev: config.dev,
1551 workerBindings,
1552 };
1553 // Zone routes target this script through the local edge's router.
1554 yield* edge.setRoutes(
1555 fqn,
1556 config.routes.map((route) => ({ pattern: route.pattern, script: config.name })),
1557 );
1558 // Only workerd-served workers can sit behind the edge router (it
1559 // reaches them over service bindings); dev-server modes keep
1560 // their proxy pointed at the dev server.
1561 if (config.vite || config.source?.devMode === "server") {
1562 yield* releaseEdgeDomain(fqn);
1563 }
1564 const serverUrl = yield* config.source
1565 ? config.source.devMode === "server"
1566 ? runVite(worker, config.source.rootDir, invalidate, {
1567 descriptor: config.source,
1568 id: worker.id,
1569 fqn: worker.fqn,
1570 assets: worker.assets,
1571 })
1572 : runSource(worker)
1573 : config.vite
1574 ? runVite(worker, config.viteRootDir, invalidate)
1575 : config.assetsOnly
1576 ? runAssetsOnly(worker)
1577 : runSource(worker);
1578 // In dev, `urls` is the dev server's actual surface — localhost
1579 // first, then LAN addresses for wildcard hosts. Deployed domains
1580 // are not served by this session, so they don't appear.
1581 const urls = yield* resolveLocalUrls(serverUrl);
1582 return {
1583 workerId: `dev:${config.name}`,
1584 workerName: config.name,
1585 namespace: undefined,
1586 logpush: undefined,
1587 url: urls[0],
1588 urls,
1589 domain: undefined,
1590 tags: [],
1591 durableObjectNamespaces: Object.fromEntries(
1592 config.durableObjectNamespaces.map((namespace) => [
1593 namespace.className,
1594 namespace.uniqueKey,
1595 ]),
1596 ),
1597 // Each route reports the edge listener serving its hostname.
1598 routes: yield* Effect.forEach(config.routes, (route) => {
1599 const host = routePatternHost(route.pattern);
1600 return host === undefined
1601 ? Effect.succeed(route)
1602 : edge.url(host).pipe(Effect.map((url) => ({ ...route, url: url?.origin })));
1603 }),
1604 crons: config.crons,
1605 tailConsumers: config.tailConsumers,
1606 streamingTailConsumers: config.streamingTailConsumers,
1607 accountId,
1608 } satisfies Worker["Attributes"];
1609 }),
1610
1611 stop: Effect.fn(function* ({ fqn }) {
1612 // Cross-restart state: the serve/restart bookkeeping, the running
1613 // workerd (which outlives instance scopes for make-before-break),
1614 // and the URL proxy live outside instance scopes and are only
1615 // reclaimed on a real delete.
1616 dropServeState(fqn);
1617 yield* edge.removeRoutes(fqn);
1618 yield* releaseEdgeDomain(fqn);
1619 yield* closeWorkerd(fqn);
1620 yield* stopProxy(fqn);
1621 }),
1622 } satisfies LocalProvider.LocalProviderSpec<
1623 Worker,
1624 Effect.Success<ReturnType<typeof resolveConfig>>,
1625 // The Python-bundle watcher spawns `uv` (ChildProcessSpawner) and
1626 // reads vendored modules (FileSystem) from inside `start`;
1627 // `readAssetsConfigFiles` (assets `_headers`/`_redirects`) needs
1628 // FileSystem + Path.
1629 ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
1630 >;
1631 }),
1632 );
1633
1634 const toRuntimeAssets = Effect.fn(function* (assets: WorkerAssetsConfig | undefined) {
1635 if (!assets) return undefined;
1636 // Mirror the deploy path: the special `_headers` / `_redirects` files
1637 // in the assets directory carry the rules unless overridden by
1638 // explicit `headers` / `redirects` props. The local runtime parses
1639 // the raw string contents just like Cloudflare does.
1640 //
1641 // A Vite website's `assets` is config-only (`{ runWorkerFirst: true }`) —
1642 // the client output directory is the build's business, and in `dev` the
1643 // vite plugin serves assets from the dev server, so there is no directory
1644 // to read here.
1645 const directory: string | undefined = typeof assets === "string" ? assets : assets.directory;
1646 // An unreadable file just means no rules here — the assets plugin
1647 // reports directory problems itself.
1648 const files = yield* readAssetsConfigFiles(directory).pipe(
1649 Effect.orElseSucceed(() => ({
1650 _headers: undefined,
1651 _redirects: undefined,
1652 })),
1653 );
1654 if (typeof assets === "string") {
1655 return {
1656 directory: assets,
1657 headers: files._headers,
1658 redirects: files._redirects,
1659 };
1660 }
1661 return {
1662 directory: assets.directory,
1663 headers: assets.headers ?? files._headers,
1664 redirects: assets.redirects ?? files._redirects,
1665 htmlHandling: assets.htmlHandling,
1666 notFoundHandling: assets.notFoundHandling,
1667 // The deployed default is assets-first (`run_worker_first` omitted =
1668 // false on the cloud API), but the runtime's router inverts it — it
1669 // treats anything `!== false` (including `undefined`) as worker-first.
1670 // Pin the cloud default explicitly so a Worker with an assets directory
1671 // and a `main` serves asset paths from the asset layer locally exactly
1672 // like it does deployed.
1673 runWorkerFirst: assets.runWorkerFirst ?? false,
1674 serveDirectly: assets.serveDirectly,
1675 };
1676 });
1677
1678 const moduleTypeFromExtension = (ext: string): Module["type"] | "SourceMap" => {
1679 switch (ext) {
1680 case ".wasm":
1681 return "Wasm";
1682 case ".txt":
1683 case ".html":
1684 case ".sql":
1685 case ".custom":
1686 return "Text";
1687 case ".bin":
1688 return "Data";
1689 case ".mjs":
1690 case ".js":
1691 return "ESModule";
1692 case ".cjs":
1693 return "CommonJsModule";
1694 case ".py":
1695 return "PythonModule";
1696 case ".map":
1697 return "SourceMap";
1698 default:
1699 return "Data";
1700 }
1701 };