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

main
ts 838 lines 34.1 KB
Raw
1 import * as NodeHttp from "node:http";
2 import type * as NodeStream from "node:stream";
3 import * as Cache from "effect/Cache";
4 import * as Cause from "effect/Cause";
5 import * as Config from "effect/Config";
6 import * as Context from "effect/Context";
7 import * as Effect from "effect/Effect";
8 import * as Exit from "effect/Exit";
9 import * as Fiber from "effect/Fiber";
10 import * as FiberSet from "effect/FiberSet";
11 import * as FileSystem from "effect/FileSystem";
12 import * as Layer from "effect/Layer";
13 import * as Path from "effect/Path";
14 import * as ChildProcess from "effect/process/ChildProcess";
15 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
16 import * as Scope from "effect/Scope";
17 import * as Stream from "effect/Stream";
18 import {
19 CONTAINER_LOOPBACK_ALIAS,
20 containerIdFromPath,
21 ensureLoopbackUnixSockets,
22 isContainerStartPath,
23 loopbackPortsFromEnv,
24 mergeSidecarLoopbackHostConfig,
25 } from "./DockerLoopback.ts";
26 import { makeDockerLoopbackForwarders } from "./internal/docker-loopback-forwarders.ts";
27 import { makeDockerUpgradeRouter } from "./internal/docker-upgrade-router.ts";
28 import { listenOnLoopback } from "./internal/listen-on-loopback.ts";
29 import { ConfigError, SystemError } from "./RuntimeError.shared.ts";
30 import type * as WorkerdConfig from "./workerd/Config.ts";
31
32 export { CONTAINER_LOOPBACK_ALIAS };
33
34 export class Docker extends Context.Service<
35 Docker,
36 {
37 readonly getWorkerdDockerConfiguration: Effect.Effect<
38 WorkerdConfig.Worker_ContainerEngine,
39 SystemError
40 >;
41 /** Docker privileges for every local container (see {@link FUSE_CONTAINER_PRIVILEGES}). */
42 readonly getContainerPrivileges: Effect.Effect<WorkerdConfig.Worker_DurableObjectNamespace_ContainerOptions_ContainerPrivileges>;
43 readonly generateImageTag: (className: string, suffix?: string) => string;
44 readonly registerImageEnv: (
45 className: string,
46 tag: string,
47 env: Record<string, string>,
48 ) => Effect.Effect<string, never, Scope.Scope>;
49 readonly build: (tag: string, image: ContainerImage.Build) => Effect.Effect<void, SystemError>;
50 readonly pull: (tag: string, image: ContainerImage.Pull) => Effect.Effect<void, SystemError>;
51 readonly validate: (tag: string) => Effect.Effect<void, ConfigError>;
52 readonly removeImageTag: (tag: string) => Effect.Effect<void>;
53 readonly removeContainer: (tag: string) => Effect.Effect<void, SystemError>;
54 }
55 >()("cloudflare-runtime/Docker") {}
56
57 export type ContainerImage = ContainerImage.Build | ContainerImage.Pull | ContainerImage.Ref;
58
59 export declare namespace ContainerImage {
60 interface Base {
61 readonly env?: Record<string, string>;
62 }
63 export interface Build extends Base {
64 readonly dockerfile: string;
65 readonly context?: string;
66 readonly buildArgs?: Record<string, string>;
67 /** BuildKit secrets by id, handed to `docker build` through its environment. */
68 readonly buildSecrets?: Record<string, string>;
69 }
70 export interface Pull extends Base {
71 readonly imageUri: string;
72 }
73 export interface Ref extends Base {
74 readonly tag: string;
75 }
76 }
77
78 const DEFAULT_DOCKER_HOST =
79 process.platform === "win32" ? "//./pipe/docker_engine" : "unix:///var/run/docker.sock";
80 const DEV_CONTAINER_PREFIX = "alchemy-dev";
81
82 const DockerHost = Config.String("DOCKER_HOST");
83 const DockerBin = Config.String("DOCKER_BIN").pipe(Config.orElse(() => Config.succeed("docker")));
84 const ContainerEgressInterceptorImage = Config.String("CONTAINER_EGRESS_INTERCEPTOR_IMAGE").pipe(
85 Config.orElse(() =>
86 Config.succeed(
87 "cloudflare/proxy-everything:3cb1195@sha256:0ef6716c52430096900b150d84a3302057d6cd2319dae7987128c85d0733e3c8",
88 ),
89 ),
90 );
91
92 /**
93 * The Docker privileges FUSE filesystems (s3fs, tigrisfs, …) need to mount
94 * inside a container. Deployed Containers can always mount FUSE, so every
95 * local container gets them too.
96 */
97 export const FUSE_CONTAINER_PRIVILEGES = {
98 capabilities: ["SYS_ADMIN"],
99 devices: [{ pathOnHost: "/dev/fuse", pathInContainer: "/dev/fuse", cgroupPermissions: "rwm" }],
100 securityOpt: ["apparmor:unconfined"],
101 } satisfies WorkerdConfig.Worker_DurableObjectNamespace_ContainerOptions_ContainerPrivileges;
102
103 /**
104 * Docker's containerd image store rejects combined `repo:tag@digest` pull
105 * refs ("cannot overwrite digest"); the digest fully pins the image, so the
106 * tag is dropped when both are present.
107 */
108 export const toPullRef = (imageUri: string) => imageUri.replace(/:[^@/]+(?=@sha256:)/, "");
109
110 /**
111 * Stderr signatures of a docker CLI that cannot run our build. Image builds
112 * use BuildKit flags (`--load`, `--provenance=false`), which a CLI without
113 * the buildx plugin rejects outright. Its stderr names the flag rather than
114 * the missing component, and several distros package the two separately
115 * (Arch/CachyOS `docker` vs `docker-buildx`, Debian `docker.io` vs
116 * `docker-buildx`), so this is a first-run trap rather than a broken setup.
117 */
118 const BUILDKIT_MISSING_MARKERS = [
119 "unknown flag: --load",
120 "unknown flag: --provenance",
121 "'buildx' is not a docker command",
122 "buildx component is missing",
123 ];
124
125 /**
126 * What to do when a Container `image` can be neither pulled nor found in the
127 * local Docker.
128 */
129 export const imageUnavailableHint = (imageUri: string) =>
130 `If "${imageUri}" is in a registry, check the name and tag, and run \`docker login\` for a private registry. ` +
131 `If it is built on this machine, build or load it before starting: ` +
132 `\`docker build --platform linux/amd64 -t ${imageUri} .\` or \`docker load\`.`;
133
134 /** Names the missing buildx plugin when docker's own stderr only names the flag. */
135 export const buildFailureHint = (stderr: string): string | undefined =>
136 BUILDKIT_MISSING_MARKERS.some((marker) => stderr.includes(marker))
137 ? "This docker CLI has no BuildKit (buildx) plugin, which building container images requires. Install it and retry — e.g. `pacman -S docker-buildx` (Arch/CachyOS), `apt install docker-buildx` (Debian/Ubuntu), or Docker Desktop, which bundles it."
138 : undefined;
139
140 /**
141 * Matches a loopback host (`localhost`, `127.0.0.1`, `0.0.0.0`, `[::1]`)
142 * where it denotes a connection target inside an env value: at the start of
143 * the value, after a `scheme://` (with optional userinfo), after `=` (DSN
144 * keyword form, `host=localhost`), or after whitespace/comma/semicolon
145 * delimiters — and followed by a port, path, delimiter, or the end.
146 */
147 const LOOPBACK_HOST =
148 /(^|[\s,;=]|\/\/(?:[^/\s@]*@)?)(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?=[:/?#]|[\s,;]|$)/g;
149
150 /**
151 * Rewrite loopback hosts in a container env value to
152 * {@link CONTAINER_LOOPBACK_ALIAS} so the value keeps meaning "the developer's
153 * machine" from inside the container. Prisma's `prisma+postgres://` client
154 * only speaks plain HTTP when the host looks local (contains `localhost`).
155 * Applied at container create; production URLs are cloud hosts, so this
156 * only fires against local emulators.
157 *
158 * Native Linux: the alias is `/etc/hosts`-mapped to `127.0.0.1` in the
159 * sidecar netns, and a unix-socket tunnel reaches the host process — a
160 * SYN to Docker's bridge IP would hit UFW INPUT. Docker Desktop: mapped
161 * to `host-gateway`, which already forwards to host loopback.
162 */
163 export const rewriteLoopbackHosts = (value: string) =>
164 value.replace(LOOPBACK_HOST, `$1${CONTAINER_LOOPBACK_ALIAS}`);
165
166 /**
167 * Merge workerd's create-body `Env` with the deployment env alchemy injects,
168 * rewriting loopback hosts and **replacing by name**.
169 *
170 * Appending would leave the original `DATABASE_URL=…127.0.0.1…` in place and
171 * add a rewritten copy. glibc/`os.Getenv` (Go, C, Python, Node on Linux)
172 * return the first match, so the container would still dial `127.0.0.1`
173 * inside its own netns.
174 */
175 export const mergeContainerCreateEnv = (
176 originalEnv: ReadonlyArray<string> | undefined,
177 imageEnv: Record<string, string> | undefined,
178 ): string[] => {
179 const order: string[] = [];
180 const values = new Map<string, string | undefined>();
181 const set = (name: string, value: string | undefined) => {
182 if (!values.has(name)) order.push(name);
183 values.set(name, value);
184 };
185 for (const entry of originalEnv ?? []) {
186 const eq = entry.indexOf("=");
187 if (eq === -1) {
188 set(entry, undefined);
189 } else {
190 set(entry.slice(0, eq), rewriteLoopbackHosts(entry.slice(eq + 1)));
191 }
192 }
193 for (const [name, value] of Object.entries(imageEnv ?? {})) {
194 set(name, rewriteLoopbackHosts(value));
195 }
196 return order.map((name) => {
197 const value = values.get(name);
198 return value === undefined ? name : `${name}=${value}`;
199 });
200 };
201
202 export const DockerLive = Layer.effect(
203 Docker,
204 Effect.gen(function* () {
205 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
206 const fs = yield* FileSystem.FileSystem;
207 const path = yield* Path.Path;
208 const runFork = yield* FiberSet.makeRuntime();
209
210 const bin = yield* DockerBin;
211 const containerEgressInterceptorImage = yield* ContainerEgressInterceptorImage;
212 const registeredImages = new Map<string, { tag: string; env: Record<string, string> }>();
213 // Every container created through the proxy carries this runtime's label.
214 // Native containers can start from images nobody prepared (snapshots,
215 // managed `cloudflare/*` images), so per-image cleanup cannot find them.
216 const runtimeLabels = { [RUNTIME_LABEL]: crypto.randomUUID() };
217 // Set once workerd asks the proxy to create a container. A runtime that
218 // never did has nothing to remove and must not wait on the daemon.
219 let createdContainers = false;
220
221 const registeredLoopbackPorts = () => {
222 const ports = new Set<number>();
223 for (const { env } of registeredImages.values()) {
224 for (const port of loopbackPortsFromEnv(env)) ports.add(port);
225 }
226 return [...ports];
227 };
228
229 const getSocketPathFromContext = () =>
230 ChildProcess.make(bin, ["context", "ls", "--format", "json"], {
231 stdin: "ignore",
232 stdout: "pipe",
233 stderr: "pipe",
234 detached: false,
235 }).pipe(
236 (command) => spawner.spawn(command),
237 Effect.flatMap((child) =>
238 child.stdout.pipe(
239 Stream.decodeText,
240 Stream.splitLines,
241 Stream.filter((line) => line.trim() !== ""),
242 Stream.map(
243 (line) =>
244 JSON.parse(line) as {
245 Current: boolean;
246 DockerEndpoint: string;
247 },
248 ),
249 Stream.runCollect,
250 Effect.flatMap((items) => {
251 const endpoint = items.find((item) => item.Current)?.DockerEndpoint;
252 return endpoint
253 ? Effect.succeed(endpoint)
254 : Effect.fail(
255 ConfigError.make({
256 subtag: "DockerHostNotFound",
257 message: "Docker host not found",
258 }),
259 );
260 }),
261 ),
262 ),
263 Effect.scoped,
264 );
265
266 const makeDockerProxyServer = (
267 socketPath: string,
268 forwarders: Effect.Success<ReturnType<typeof makeDockerLoopbackForwarders>>,
269 ) => {
270 const forward = (
271 req: NodeHttp.IncomingMessage,
272 res: NodeHttp.ServerResponse,
273 options: { body?: string; afterStart?: Effect.Effect<void, SystemError> } = {},
274 ) =>
275 Effect.gen(function* () {
276 const upstream = yield* sendDockerRequest(socketPath, req, options.body);
277 const status = upstream.statusCode ?? 500;
278 // Docker answers a repeated start with 304; attaching again repairs
279 // forwarding when an earlier start succeeded but its helper failed.
280 if (options.afterStart === undefined || (status >= 300 && status !== 304)) {
281 res.writeHead(status, upstream.headers);
282 upstream.pipe(res, { end: true });
283 return;
284 }
285 const body = yield* readBody(upstream);
286 yield* options.afterStart;
287 res.writeHead(status, upstream.headers);
288 res.end(status === 204 || status === 304 || body.length === 0 ? undefined : body);
289 });
290
291 const handle = (req: NodeHttp.IncomingMessage, res: NodeHttp.ServerResponse) =>
292 Effect.gen(function* () {
293 const isCreateRequest =
294 req.method === "POST" && req.url?.startsWith("/containers/create");
295 if (isCreateRequest) createdContainers = true;
296 if (isCreateRequest && !req.url!.endsWith("-proxy")) {
297 const original = yield* readJson<{
298 Image: string;
299 Env: Array<string>;
300 Labels?: Record<string, string>;
301 }>(req);
302 const image = registeredImages.get(original.Image);
303 // A native `start({ image })` can name an image that was never
304 // prepared (e.g. a managed `cloudflare/*` image): pull it on demand.
305 const pulled = yield* Effect.exit(
306 Cache.get(ensuredImages, image?.tag ?? original.Image),
307 );
308 if (Exit.isFailure(pulled)) return sendError(res, 500, Cause.pretty(pulled.cause));
309 return yield* forward(req, res, {
310 body: JSON.stringify({
311 ...original,
312 Image: image?.tag ?? original.Image,
313 Env: mergeContainerCreateEnv(original.Env, image?.env),
314 Labels: { ...original.Labels, ...runtimeLabels },
315 }),
316 });
317 }
318 if (isCreateRequest) {
319 // workerd creates two containers per instance: the user container
320 // and a `<name>-proxy` networking sidecar whose namespace the user
321 // container joins (`NetworkMode: container:<sidecar>`) — so the
322 // sidecar's /etc/hosts is what the user container resolves against.
323 // Docker Desktop maps the alias through host-gateway (reaches host
324 // 127.0.0.1). Native Linux maps it to 127.0.0.1 in this netns and
325 // bind-mounts unix sockets; a SYN to the bridge IP is host INPUT (UFW).
326 const original = yield* readJson<{
327 Labels?: Record<string, string>;
328 HostConfig?: {
329 ExtraHosts?: Array<string>;
330 Binds?: Array<string>;
331 Sysctls?: Record<string, string>;
332 };
333 }>(req);
334 const ports = registeredLoopbackPorts();
335 ensureLoopbackUnixSockets(ports);
336 return yield* forward(req, res, {
337 body: JSON.stringify({
338 ...original,
339 Labels: { ...original.Labels, ...runtimeLabels },
340 HostConfig: {
341 ...mergeSidecarLoopbackHostConfig(original.HostConfig, ports),
342 Sysctls: {
343 ...original.HostConfig?.Sysctls,
344 // Hosts such as Tailscale routers enable src_valid_mark.
345 // The sidecar marks inbound TCP packets for transparent proxying;
346 // including that mark in reverse-path validation drops their ACKs.
347 // Override only the sidecar's network namespace, never the host.
348 "net.ipv4.conf.all.src_valid_mark": "0",
349 },
350 },
351 }),
352 });
353 }
354 const id = containerIdFromPath(req.url);
355 if (req.method === "POST" && isContainerStartPath(req.url) && id !== undefined) {
356 return yield* forward(req, res, {
357 afterStart: forwarders.attach(id, registeredLoopbackPorts()),
358 });
359 }
360 if (req.method === "DELETE" && id !== undefined) {
361 yield* forwarders.detach(id);
362 }
363 return yield* forward(req, res);
364 }).pipe(
365 Effect.catchCause((cause) =>
366 Effect.sync(() => {
367 if (res.headersSent) res.destroy();
368 else sendError(res, 502, Cause.pretty(cause));
369 }),
370 ),
371 );
372
373 return NodeHttp.createServer((req, res) => {
374 runFork(handle(req, res));
375 });
376 };
377
378 const run = (
379 args: Array<string>,
380 stdin: ChildProcess.CommandInput = "ignore",
381 env?: Record<string, string>,
382 ) =>
383 ChildProcess.make(bin, args, {
384 stdin,
385 stdout: "pipe",
386 stderr: "pipe",
387 detached: false,
388 ...(env === undefined ? {} : { env, extendEnv: true }),
389 }).pipe(
390 (command) => spawner.spawn(command),
391 Effect.flatMap((child) =>
392 Effect.all(
393 {
394 exitCode: child.exitCode,
395 stdout: child.stdout.pipe(
396 Stream.decodeText,
397 Stream.tap(Effect.logDebug),
398 Stream.mkString,
399 ),
400 stderr: child.stderr.pipe(
401 Stream.decodeText,
402 Stream.tap(Effect.logDebug),
403 Stream.mkString,
404 ),
405 },
406 { concurrency: "unbounded" },
407 ),
408 ),
409 Effect.scoped,
410 );
411
412 /**
413 * `run` resolves with the command's exit code instead of failing on it
414 * (some callers, e.g. `inspect`, treat a non-zero exit as a legitimate
415 * "not present" answer). Every command whose failure actually matters
416 * therefore has to check the code itself: without this, a `docker build`
417 * that exits 1 is indistinguishable from a successful build, the image
418 * is never created, and the only symptom the user ever sees is workerd
419 * reporting `Container exited while waiting for port <port>` on a loop.
420 */
421 const ensureExitZero = <E>(
422 result: { exitCode: number; stdout: string; stderr: string },
423 onNonZero: (result: { exitCode: number; stdout: string; stderr: string }) => E,
424 ): Effect.Effect<void, E> =>
425 result.exitCode === 0 ? Effect.void : Effect.fail(onNonZero(result));
426
427 /**
428 * `platform` is omitted for the egress interceptor: it is a host-side
429 * sidecar, not a deployable image, so Docker must resolve the
430 * host-native variant. Forcing `linux/amd64` there runs it under
431 * emulation on arm64 hosts, where its transparent-proxy setup dies at
432 * startup with `Fatal error: setsockoptint: protocol not available`.
433 * Deployable user images pass `linux/amd64` explicitly, because that is
434 * the architecture Cloudflare's container runtime executes.
435 */
436 const pull = ({ imageUri, platform }: ContainerImage.Pull & { readonly platform?: string }) =>
437 run(["pull", toPullRef(imageUri), ...(platform ? ["--platform", platform] : [])]).pipe(
438 Effect.mapError((cause) =>
439 SystemError.make({
440 subtag: "DockerPullFailed",
441 message: `Failed to pull image "${imageUri}".`,
442 hint: "Ensure Docker is running and the image is available.",
443 detail: { bin, imageUri },
444 cause,
445 }),
446 ),
447 Effect.flatMap((result) => {
448 if (result.exitCode !== 0) {
449 return Effect.fail(
450 SystemError.make({
451 subtag: "DockerPullFailed",
452 message: `Failed to pull image "${imageUri}".`,
453 hint: "Ensure Docker is running and the image is available.",
454 detail: {
455 bin,
456 imageUri,
457 exitCode: result.exitCode,
458 stdout: result.stdout,
459 stderr: result.stderr,
460 },
461 }),
462 );
463 }
464 return Effect.succeed(result.stdout);
465 }),
466 );
467
468 const inspect = (tag: string, format: string) =>
469 Effect.map(run(["image", "inspect", tag, "--format", format]), (result) => result.stdout);
470
471 // `docker image inspect` prints the image id when present and empty
472 // stdout when absent, so only pull when the image is genuinely missing.
473 const pullIfMissing = (imageUri: string, platform?: string) =>
474 inspect(imageUri, "{{.Id}}").pipe(
475 Effect.orElseSucceed(() => undefined),
476 Effect.flatMap((id) =>
477 id?.trim() ? Effect.void : Effect.asVoid(pull({ imageUri, platform })),
478 ),
479 );
480 // workerd may create a container from an image nobody prepared, such as a
481 // managed `cloudflare/*` image. Failed pulls are forgotten and retried.
482 const ensuredImages = yield* Cache.makeWith(
483 (image: string) => pullIfMissing(image, "linux/amd64"),
484 {
485 capacity: Number.MAX_SAFE_INTEGER,
486 timeToLive: (exit) => (Exit.isFailure(exit) ? 0 : Infinity),
487 },
488 );
489
490 const list = (ancestor: string) =>
491 run([
492 "ps",
493 "-a",
494 "--no-trunc",
495 "--filter",
496 `ancestor=${ancestor}`,
497 "--format",
498 "{{.ID}} {{.Names}} {{.Image}}",
499 ]).pipe(
500 Effect.map((result) =>
501 result.stdout
502 .split("\n")
503 .filter((line) => line.trim() !== "")
504 .map((line) => {
505 const [id, name, image] = line.split(" ");
506 return { id, name, image };
507 })
508 .filter((container) => container.image === ancestor),
509 ),
510 );
511
512 const removeRuntimeContainers = run([
513 "ps",
514 "--all",
515 "--quiet",
516 "--filter",
517 `label=${RUNTIME_LABEL}=${runtimeLabels[RUNTIME_LABEL]}`,
518 ]).pipe(
519 Effect.flatMap(({ stdout }) => {
520 const ids = stdout.split("\n").filter((id) => id.trim() !== "");
521 return ids.length === 0 ? Effect.void : Effect.asVoid(run(["rm", "--force", ...ids]));
522 }),
523 Effect.timeout("30 seconds"),
524 Effect.withLogSpan("docker: remove runtime containers"),
525 Effect.ignore,
526 );
527 // Runs after the runtime (and its workerd) has shut down.
528 yield* Effect.addFinalizer(() =>
529 Effect.suspend(() => (createdContainers ? removeRuntimeContainers : Effect.void)),
530 );
531
532 // Connect to the daemon on first use. Only Workers with containers ask for
533 // the engine configuration, so every other runtime never touches Docker.
534 // It runs in the layer's scope, so it outlives the caller that started it.
535 const context = yield* Effect.context<Scope.Scope | ChildProcessSpawner.ChildProcessSpawner>();
536 const startDocker = Effect.zipWith(
537 DockerHost.pipe(
538 Effect.catchTag("ConfigError", getSocketPathFromContext),
539 Effect.orElseSucceed(() => DEFAULT_DOCKER_HOST),
540 Effect.flatMap(
541 Effect.fnUntraced(function* (socketPath) {
542 const forwarders = yield* makeDockerLoopbackForwarders({ bin, socketPath });
543 const httpProxyPort = yield* listenOnLoopback(
544 makeDockerProxyServer(socketPath, forwarders),
545 );
546 // workerd connects to the router, which forwards `docker exec`
547 // streams to Docker directly and everything else to the proxy.
548 const router = yield* makeDockerUpgradeRouter({
549 dockerSocketPath: socketPath,
550 httpProxyPort,
551 });
552 return `127.0.0.1:${yield* listenOnLoopback(router)}`;
553 }),
554 ),
555 ),
556 // Skip the eager pull when the interceptor image is already present
557 // locally. `CONTAINER_EGRESS_INTERCEPTOR_IMAGE` can point at a
558 // local-only tag that exists in the Docker daemon but resolves in no
559 // registry (e.g. a locally-built dev image) — an unconditional
560 // `docker pull` there fails, this startup fiber dies, and every
561 // caller of `getWorkerdDockerConfiguration` (joined on first use)
562 // fails with it. `docker image inspect` prints the image id when
563 // present and empty stdout when absent (`run` reports the non-zero
564 // exit rather than failing the effect), so only pull when the image
565 // is genuinely missing. The sidecar needs the host-native image.
566 pullIfMissing(containerEgressInterceptorImage),
567 (socketPath) => ({
568 localDocker: {
569 socketPath,
570 containerEgressInterceptorImage,
571 },
572 }),
573 { concurrent: true },
574 ).pipe(Effect.provide(context), Effect.forkIn(Context.get(context, Scope.Scope)));
575 const docker = yield* Effect.cached(startDocker);
576
577 // Docker refuses to create a container whose device is missing on the
578 // host, so a Linux host without /dev/fuse gets the capability alone.
579 // VM-based engines (macOS, Windows) always have /dev/fuse in the VM.
580 const getContainerPrivileges = yield* Effect.cached(
581 Effect.gen(function* () {
582 const platform = yield* Effect.sync(() => process.platform);
583 const hasFuse =
584 platform !== "linux" ||
585 (yield* fs.exists("/dev/fuse").pipe(Effect.orElseSucceed(() => false)));
586 return hasFuse ? FUSE_CONTAINER_PRIVILEGES : { ...FUSE_CONTAINER_PRIVILEGES, devices: [] };
587 }),
588 );
589
590 return Docker.of({
591 getWorkerdDockerConfiguration: Effect.flatMap(docker, Fiber.join),
592 getContainerPrivileges,
593 registerImageEnv: (className, tag, env) => {
594 const alias = generateImageTag(className);
595 return Effect.acquireRelease(
596 Effect.sync(() => {
597 registeredImages.set(alias, { tag, env });
598 ensureLoopbackUnixSockets(loopbackPortsFromEnv(env));
599 }),
600 () => Effect.sync(() => registeredImages.delete(alias)),
601 ).pipe(Effect.as(alias));
602 },
603 generateImageTag,
604 build: (tag, image) =>
605 Effect.suspend(() => {
606 // Values ride in generated variables: a secret id is the
607 // Dockerfile's choice and may shadow one Docker reads itself.
608 const secrets = Object.entries(image.buildSecrets ?? {}).map(([id, value], index) => ({
609 id,
610 variable: `ALCHEMY_BUILD_SECRET_${index}`,
611 value,
612 }));
613 const args = [
614 "build",
615 "--load",
616 "-t",
617 tag,
618 "--platform",
619 "linux/amd64",
620 "--provenance=false",
621 ...Object.entries(image.buildArgs ?? {}).flatMap(([name, value]) => [
622 "--build-arg",
623 `${name}=${value}`,
624 ]),
625 ...secrets.flatMap(({ id, variable }) => ["--secret", `id=${id},env=${variable}`]),
626 "-f",
627 "-",
628 path.resolve(image.context ?? path.dirname(image.dockerfile)),
629 ];
630 return run(
631 args,
632 fs.stream(
633 image.context
634 ? path.resolve(image.context, image.dockerfile)
635 : path.resolve(image.dockerfile),
636 ),
637 secrets.length === 0
638 ? undefined
639 : Object.fromEntries(secrets.map(({ variable, value }) => [variable, value])),
640 ).pipe(
641 Effect.withLogSpan(`docker: build ${tag}`),
642 Effect.mapError((cause) =>
643 SystemError.make({
644 subtag: "DockerBuildFailed",
645 message: `Failed to build image "${tag}".`,
646 cause,
647 }),
648 ),
649 Effect.flatMap((result) =>
650 ensureExitZero(result, ({ exitCode, stdout, stderr }) =>
651 SystemError.make({
652 subtag: "DockerBuildFailed",
653 message: `Failed to build image "${tag}".`,
654 hint: buildFailureHint(stderr),
655 detail: { bin, tag, exitCode, stdout, stderr },
656 }),
657 ),
658 ),
659 );
660 }),
661 // Pull every time so a mutable tag picks up a newly pushed image and
662 // the `linux/amd64` variant replaces any native build under the tag.
663 // An image that exists only locally (built on the machine or
664 // `docker load`ed) has nothing to pull from, so when the pull fails
665 // and the image is present, use the local copy.
666 pull: (tag, image) =>
667 pull({ ...image, platform: "linux/amd64" }).pipe(
668 Effect.catchTag("SystemError", (error) =>
669 inspect(image.imageUri, "{{.Id}}").pipe(
670 Effect.orElseSucceed(() => ""),
671 Effect.flatMap((id) =>
672 id.trim()
673 ? Effect.logDebug(
674 `docker: pull ${image.imageUri} failed, using the local image ${id.trim()}`,
675 )
676 : Effect.fail(
677 SystemError.make({
678 subtag: "DockerPullFailed",
679 message: `Image "${image.imageUri}" could not be pulled and is not in the local Docker.`,
680 hint: imageUnavailableHint(image.imageUri),
681 detail: error.detail,
682 cause: error,
683 }),
684 ),
685 ),
686 ),
687 ),
688 Effect.andThen(
689 run(["tag", image.imageUri, tag]).pipe(
690 Effect.mapError((cause) =>
691 SystemError.make({
692 subtag: "DockerTagFailed",
693 message: `Failed to tag image "${image.imageUri}" as "${tag}".`,
694 cause,
695 }),
696 ),
697 Effect.flatMap((result) =>
698 ensureExitZero(result, ({ exitCode, stdout, stderr }) =>
699 SystemError.make({
700 subtag: "DockerTagFailed",
701 message: `Failed to tag image "${image.imageUri}" as "${tag}".`,
702 detail: {
703 bin,
704 imageUri: image.imageUri,
705 tag,
706 exitCode,
707 stdout,
708 stderr,
709 },
710 }),
711 ),
712 ),
713 ),
714 ),
715 Effect.withLogSpan(`docker: pull ${image.imageUri}`),
716 Effect.asVoid,
717 ),
718 validate: (tag) =>
719 inspect(tag, "{{ len .Config.ExposedPorts }}").pipe(
720 Effect.withLogSpan(`docker: inspect ${tag} for exposed ports`),
721 Effect.orElseSucceed(() => "0"),
722 Effect.flatMap((output) =>
723 output === "0"
724 ? Effect.fail(
725 ConfigError.make({
726 subtag: "ContainerNoExposedPorts",
727 message: `The container for "${tag}" does not expose any ports.`,
728 hint: "Add an EXPOSE instruction to the Dockerfile for any ports you intend to connect to.",
729 }),
730 )
731 : Effect.void,
732 ),
733 ),
734 // Untag ONLY the given tag (used by each runtime start's finalizer for
735 // the tag it created). Deliberately does not guess at sibling
736 // "<name>:<otherSuffix>" tags: concurrent/successive dev sessions of
737 // the same container class each hold their own random-suffix tag on
738 // the same underlying image, and pruning siblings untags an image a
739 // live workerd still needs (its container creates then fail forever).
740 removeImageTag: (tag) =>
741 Effect.asVoid(run(["rmi", tag])).pipe(
742 Effect.withLogSpan(`docker: remove image tag ${tag}`),
743 Effect.ignore,
744 ),
745 removeContainer: (tag) =>
746 list(tag).pipe(
747 Effect.flatMap((containers) => {
748 if (containers.length === 0) return Effect.void;
749 return Effect.asVoid(
750 run([
751 "rm",
752 "--force",
753 ...containers.flatMap((container) => [container.id, `${container.name}-proxy`]),
754 ]),
755 );
756 }),
757 Effect.withLogSpan(`docker: remove containers for ${tag}`),
758 Effect.mapError((cause) =>
759 SystemError.make({
760 subtag: "DockerRemoveContainerFailed",
761 message: `Failed to remove containers for "${tag}".`,
762 cause,
763 }),
764 ),
765 ),
766 });
767 }),
768 );
769
770 /** Label identifying the runtime that created a container through the proxy. */
771 export const RUNTIME_LABEL = "alchemy.runtime";
772
773 const generateImageTag = (className: string, suffix?: string) =>
774 `${DEV_CONTAINER_PREFIX}/${className.toLowerCase()}:${suffix ?? crypto.randomUUID().slice(0, 8)}`;
775
776 const dockerProxyError = (subtag: string, message: string) => (cause: unknown) =>
777 SystemError.make({ subtag, message, cause });
778
779 /** Forward `req` to the Docker socket, replacing its body when one is given. */
780 const sendDockerRequest = (
781 socketPath: string,
782 req: NodeHttp.IncomingMessage,
783 body: string | undefined,
784 ) =>
785 Effect.callback<NodeHttp.IncomingMessage, SystemError>((resume) => {
786 const headers: NodeHttp.OutgoingHttpHeaders = { ...req.headers };
787 // `transfer-encoding` is a hop-by-hop header and must not be forwarded
788 // verbatim. workerd sends its `DELETE /containers/<name>-proxy?force=true`
789 // cleanup request with `transfer-encoding: chunked` and an empty body;
790 // Bun's `node:http` client hangs indefinitely on such a request to a
791 // unix socket (it never flushes the terminating zero-chunk), so the
792 // docker daemon never responds and workerd blocks forever before it can
793 // create the container. Strip the header and let the runtime derive the
794 // framing from the body we actually write. (Node tolerates it, Bun does
795 // not — and Alchemy dev runs the runtime under Bun.)
796 delete headers["transfer-encoding"];
797 if (body !== undefined) headers["content-length"] = Buffer.byteLength(body).toString();
798 const upstream = NodeHttp.request(
799 {
800 socketPath: socketPath.replace(/^unix:/, ""),
801 path: req.url,
802 method: req.method,
803 headers,
804 },
805 (res) => {
806 delete res.headers["transfer-encoding"];
807 resume(Effect.succeed(res));
808 },
809 );
810 upstream.on("error", (cause) =>
811 resume(Effect.fail(dockerProxyError("DockerProxyRequest", "Docker request failed.")(cause))),
812 );
813 if (body === undefined) req.pipe(upstream, { end: true });
814 else upstream.end(body);
815 return Effect.sync(() => upstream.destroy());
816 });
817
818 const readBody = (stream: NodeStream.Readable) =>
819 Stream.fromAsyncIterable<Uint8Array, SystemError>(
820 stream,
821 dockerProxyError("DockerProxyBody", "Failed to read a Docker proxy body."),
822 ).pipe(
823 Stream.runCollect,
824 Effect.map((chunks) => Buffer.concat(chunks)),
825 );
826
827 const readJson = <T>(req: NodeHttp.IncomingMessage) =>
828 Effect.flatMap(readBody(req), (body) =>
829 Effect.try({
830 try: () => JSON.parse(body.toString()) as T,
831 catch: dockerProxyError("DockerProxyBody", "Docker request body is not valid JSON."),
832 }),
833 );
834
835 const sendError = (res: NodeHttp.ServerResponse, status: number, message: string) => {
836 res.writeHead(status, { "content-type": "application/json" });
837 res.end(JSON.stringify({ message }));
838 };