@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, 06:00 UTC

main
ts 681 lines 28.7 KB
Raw
1 import { execFile } from "node:child_process";
2 import * as fs from "node:fs/promises";
3 import * as net from "node:net";
4 import * as os from "node:os";
5 import * as path from "node:path";
6 /**
7 * `@alchemy.run/aws/Local/Floci` — Effect-native manager for the
8 * [floci](https://floci.io) local cloud emulator.
9 *
10 * alchemy's AWS local dev points its providers at a floci endpoint. This
11 * package owns the emulator lifecycle with a strict resolution order that
12 * keeps every local loop registry-free. `ALCHEMY_FLOCI_EXTERNAL=1` requires an
13 * existing server and disables Docker fallback, for source development,
14 * unless the caller passes an explicit {@link FlociConfig.external}:
15 *
16 * 1. **Already serving** — if anything answers on the endpoint (e.g.
17 * `bun floci:dev` running `mvn quarkus:dev` from a floci checkout, or a
18 * hand-run container), it wins. Nothing is started, nothing owned.
19 * 2. **`ALCHEMY_FLOCI_IMAGE`** — run a specific image (e.g. a locally
20 * built `floci:dev` from a patched fork).
21 * 3. **The pinned release** — {@link DEFAULT_FLOCI_IMAGE}, alchemy's
22 * distribution of floci (upstream + alchemy patch set, published from
23 * github.com/alchemy-run/floci).
24 *
25 * The container is started detached with a stable name — the DOCKER DAEMON
26 * is the supervisor, not alchemy: it outlives `alchemy dev` sessions, so
27 * queues/tables/functions stay warm between runs and the next session
28 * reattaches via the health probe in milliseconds.
29 */
30 import * as Data from "effect/Data";
31 import * as Duration from "effect/Duration";
32 import * as Effect from "effect/Effect";
33 import * as Result from "effect/Result";
34 import * as Schedule from "effect/Schedule";
35 import * as Semaphore from "effect/Semaphore";
36
37 /**
38 * The pinned floci release alchemy ships: upstream + the alchemy patch
39 * set, built and published by the alchemy-run/floci fork's release
40 * workflow. Bumping this pin (with a new `x.y.z-alchemy.N` tag) is how an
41 * emulator change reaches users.
42 */
43 export const DEFAULT_FLOCI_IMAGE = "ghcr.io/alchemy-run/floci:2.1.0-alchemy.3";
44
45 /** Default gateway port (LocalStack-compatible). */
46 export const DEFAULT_FLOCI_PORT = 4566;
47
48 /**
49 * ELB listener ports published on the managed container. Floci's ELBv2
50 * data plane serves each listener on the listener's OWN port inside the
51 * container (see floci's ports doc) — its `*.elb.localhost.floci.io` DNS
52 * resolves to 127.0.0.1, so the port must be published for the emulated
53 * load balancer to be reachable from the host. Ports already taken on the
54 * host are skipped (the gateway still works without them). A warning is
55 * emitted only when the caller asked for those ports via
56 * {@link FlociConfig.elbListenerPorts} — the default 80/443 publish is
57 * opportunistic and a taken privileged port is the common case on a
58 * developer machine, not a problem.
59 */
60 export const DEFAULT_ELB_LISTENER_PORTS = [80, 443];
61
62 /**
63 * Ports published for floci's emulated CloudFront edge. Each emulated
64 * distribution is served on one of these as plain HTTP, so `alchemy dev`
65 * hands out a `router.url` a browser can open — a distribution's
66 * `*.cloudfront.net` domain resolves to nothing on a developer's machine.
67 * The emulator assigns a port per distribution and reports it back; it can
68 * only use ports the container actually published, so the resolved list is
69 * passed in as `FLOCI_SERVICES_CLOUDFRONT_EDGE_PORTS`. Taken host ports are
70 * skipped, exactly like the ELB listener ports above.
71 */
72 export const DEFAULT_CLOUDFRONT_EDGE_PORTS = Array.from({ length: 20 }, (_, index) => 9500 + index);
73
74 /**
75 * Label recording the ports the caller asked the managed container to
76 * publish (see {@link requestedPortsLabel}).
77 */
78 const PORTS_LABEL = "run.alchemy.floci.requested-ports";
79
80 /**
81 * Canonical form of the caller's port request: the configured lists, or
82 * `default` for an omitted one.
83 */
84 const requestedPortsLabel = (config?: FlociConfig) =>
85 `elb=${config?.elbListenerPorts?.join(",") ?? "default"};edge=${config?.cloudfrontEdgePorts?.join(",") ?? "default"}`;
86
87 /** Default name of the managed container. */
88 export const DEFAULT_CONTAINER_NAME = "alchemy-floci";
89
90 /**
91 * Stable host path of the emulator's self-signed CA bundle, refreshed by
92 * {@link ensureFloci} on every successful health check (the CA is minted
93 * inside the container, so it changes whenever the container is recreated).
94 * Home-anchored (not cwd-relative) so every process in a dev session — test
95 * runner, RPC sidecars, workerd children — resolves the same file; consumers
96 * point TLS trust at it (e.g. `NODE_EXTRA_CA_CERTS`, which the local workerd
97 * runtime folds into its outbound `trustedCertificates`).
98 */
99 export const FLOCI_CA_PATH = path.join(os.homedir(), ".floci", "ca.pem");
100
101 /**
102 * Host directory mounted at the container's TLS dir (`/app/data/tls`) so
103 * the self-signed CA (which floci reuses when the files already exist)
104 * SURVIVES container recreations. Without it, every recreate — an image
105 * bump, a port-config change, a Docker daemon restart — mints a fresh CA,
106 * and every process that loaded the previous bundle (workerd trust stores
107 * read once at spawn) fails TLS against the emulator until restarted.
108 */
109 export const FLOCI_TLS_DIR = path.join(os.homedir(), ".floci", "tls");
110
111 /**
112 * Best-effort download of the emulator's CA bundle to {@link FLOCI_CA_PATH}.
113 * Never fails the ensure: an emulator predating `/_floci/tls/ca` (or a
114 * filesystem error) just leaves the previous bundle in place.
115 */
116 const syncCaBundle = (endpoint: string): Effect.Effect<void> =>
117 Effect.tryPromise({
118 try: async (signal) => {
119 const res = await fetch(`${endpoint}/_floci/tls/ca`, { signal });
120 if (!res.ok) return;
121 const pem = await res.text();
122 if (!pem.includes("BEGIN CERTIFICATE")) return;
123 await fs.mkdir(path.dirname(FLOCI_CA_PATH), { recursive: true });
124 await fs.writeFile(FLOCI_CA_PATH, pem);
125 // Point local workerd (and any other child process spawned after this)
126 // at the emulator CA so cross-cloud MicroVM data-plane TLS is trusted
127 // under `alchemy dev` — Node reads NODE_EXTRA_CA_CERTS once at startup,
128 // so setting it here (before local workers spawn during the apply) only
129 // affects children, which is exactly the target. Never clobber a value
130 // the caller set deliberately.
131 if (process.env.NODE_EXTRA_CA_CERTS === undefined) {
132 process.env.NODE_EXTRA_CA_CERTS = FLOCI_CA_PATH;
133 }
134 },
135 catch: (cause) => new FlociError({ message: "ca sync failed", cause }),
136 }).pipe(Effect.ignore);
137
138 export class FlociError extends Data.TaggedError("FlociError")<{
139 readonly message: string;
140 readonly cause?: unknown;
141 }> {}
142
143 export interface FlociConfig {
144 /**
145 * Use an existing server without starting or replacing Docker containers.
146 * When omitted, `ALCHEMY_FLOCI_EXTERNAL=1` enables it for source
147 * development; an explicit value overrides the env var.
148 */
149 readonly external?: boolean | undefined;
150 /**
151 * Image to run when the emulator is not already serving.
152 * Resolution order: `ALCHEMY_FLOCI_IMAGE` env var, this field,
153 * {@link DEFAULT_FLOCI_IMAGE}.
154 */
155 readonly image?: string | undefined;
156 /**
157 * Gateway port on the host.
158 * @default 4566
159 */
160 readonly port?: number | undefined;
161 /**
162 * Name of the managed container (stable so `docker start` can revive a
163 * stopped one).
164 * @default "alchemy-floci"
165 */
166 readonly containerName?: string | undefined;
167 /**
168 * Host directory persisted into the container's data dir. Omit for
169 * floci's default in-memory storage (state lives as long as the
170 * container).
171 */
172 readonly storageDir?: string | undefined;
173 /**
174 * Mount the host Docker socket so floci's container-backed engines
175 * (Lambda, ECS, EC2, RDS, ElastiCache) work.
176 * @default true
177 */
178 readonly dockerSocket?: boolean | undefined;
179 /**
180 * Extra environment variables for the emulator (e.g.
181 * `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED`).
182 */
183 readonly env?: Record<string, string> | undefined;
184 /**
185 * ELB listener ports to publish on the managed container (floci's ALB
186 * data plane serves each listener on the listener's own port). Ports
187 * already taken on the host, or that Docker refuses to publish (e.g. a
188 * privileged port under rootless Docker), are skipped — with a warning
189 * only when this field is set; the default 80/443 publish is
190 * opportunistic.
191 * @default [80, 443]
192 */
193 readonly elbListenerPorts?: readonly number[] | undefined;
194 /**
195 * Ports to publish for the emulated CloudFront edge (floci serves each
196 * distribution on its own port). Ports already taken on the host, or that
197 * Docker refuses to publish, are skipped; an empty result turns the feature off in the emulator so it
198 * never binds a port nothing can reach.
199 * @default 9500-9519
200 */
201 readonly cloudfrontEdgePorts?: readonly number[] | undefined;
202 /**
203 * How long to wait for the emulator to become healthy after starting it
204 * (first run includes the image pull).
205 * @default 180 seconds
206 */
207 readonly readinessTimeout?: Duration.Input | undefined;
208 }
209
210 /** A running (or reused) emulator. */
211 export interface FlociInstance {
212 /** Gateway endpoint, e.g. `http://localhost:4566`. */
213 readonly endpoint: string;
214 /**
215 * Whether this manager started the container (`false` when something was
216 * already serving on the endpoint — a dev-mode JVM, a hand-run
217 * container, or a previous session's container).
218 */
219 readonly managed: boolean;
220 /** Container name when {@link managed} is true. */
221 readonly containerName?: string | undefined;
222 }
223
224 const docker = (args: ReadonlyArray<string>) =>
225 Effect.callback<{ stdout: string; stderr: string }, FlociError>((resume) => {
226 const child = execFile(
227 "docker",
228 args as Array<string>,
229 { maxBuffer: 16 * 1024 * 1024 },
230 (error, stdout, stderr) => {
231 if (error) {
232 resume(
233 Effect.fail(
234 new FlociError({
235 message: `docker ${args[0]} failed: ${stderr.trim() || error.message}`,
236 cause: error,
237 }),
238 ),
239 );
240 } else {
241 resume(Effect.succeed({ stdout, stderr }));
242 }
243 },
244 );
245 return Effect.sync(() => child.kill());
246 });
247
248 /**
249 * Whether anything answers HTTP on the endpoint. Any response — even an
250 * error status — counts as serving; only a transport failure means down.
251 */
252 export const isServing = (endpoint: string): Effect.Effect<boolean> =>
253 Effect.tryPromise({
254 try: async (signal) => {
255 await fetch(`${endpoint}/_floci/health`, { signal });
256 return true;
257 },
258 catch: () => new FlociError({ message: "unreachable" }),
259 }).pipe(Effect.orElseSucceed(() => false));
260
261 /** Fail unless `GET /_floci/health` answers 200. */
262 export const checkHealth = (endpoint: string): Effect.Effect<void, FlociError> =>
263 Effect.tryPromise({
264 try: async (signal) => {
265 const res = await fetch(`${endpoint}/_floci/health`, { signal });
266 if (!res.ok) {
267 throw new Error(`health returned ${res.status}`);
268 }
269 },
270 catch: (cause) =>
271 new FlociError({
272 message: `floci health check failed: ${String(cause)}`,
273 cause,
274 }),
275 });
276
277 /** Resolve the image to run: env override, config, pinned default. */
278 export const resolveImage = (config?: FlociConfig): Effect.Effect<string> =>
279 Effect.sync(
280 () =>
281 // `|| undefined`: an empty env var (`ALCHEMY_FLOCI_IMAGE= cmd`) means
282 // "no override", not "run the image named ''" (an unrunnable docker ref).
283 (process.env.ALCHEMY_FLOCI_IMAGE || undefined) ?? config?.image ?? DEFAULT_FLOCI_IMAGE,
284 );
285
286 /** Whether a host TCP port is free (nothing is listening on it). */
287 const isHostPortFree = (port: number): Effect.Effect<boolean> =>
288 Effect.callback<boolean>((resume) => {
289 const server = net.createServer();
290 server.once("error", (error: NodeJS.ErrnoException) => {
291 if (error.code === "EACCES") {
292 // Binding low ports (<1024) is privileged for THIS process. Rootful
293 // Docker and Docker Desktop can still publish them, rootless Docker
294 // cannot — fall back to a connect probe (a refused connection means
295 // nothing listens). If Docker then refuses to publish the port, the
296 // run is retried without the optional ports.
297 const socket = net.connect({ port, host: "127.0.0.1" });
298 socket.once("connect", () => {
299 socket.destroy();
300 resume(Effect.succeed(false));
301 });
302 socket.once("error", () => resume(Effect.succeed(true)));
303 return;
304 }
305 resume(Effect.succeed(false));
306 });
307 server.once("listening", () => server.close(() => resume(Effect.succeed(true))));
308 server.listen(port, "127.0.0.1");
309 return Effect.sync(() => server.close());
310 });
311
312 /**
313 * The host ports the named container publishes, or `undefined` when the
314 * container does not exist.
315 */
316 const publishedPorts = (containerName: string): Effect.Effect<Set<number> | undefined> =>
317 docker(["inspect", "--format", "{{json .HostConfig.PortBindings}}", containerName]).pipe(
318 Effect.map(({ stdout }) => {
319 let bindings: Record<string, Array<{ HostPort?: string }> | null> | null;
320 try {
321 bindings = JSON.parse(stdout.trim());
322 } catch {
323 // Racing a concurrent create/remove of the container can produce
324 // partial output — treat it as "unknown", not a crash.
325 return undefined;
326 }
327 const ports = new Set<number>();
328 for (const spec of Object.values(bindings ?? {})) {
329 for (const bind of spec ?? []) {
330 const hostPort = Number(bind.HostPort);
331 if (Number.isFinite(hostPort)) ports.add(hostPort);
332 }
333 }
334 return ports;
335 }),
336 Effect.orElseSucceed(() => undefined),
337 );
338
339 /**
340 * Whether the named container ACTUALLY has a host binding for its gateway
341 * port. `.HostConfig.PortBindings` only records what was requested: when
342 * Docker fails to program a binding (rootless Docker refusing a privileged
343 * port, a port held on another interface) the container can still end up
344 * running with nothing published, and polling the endpoint would wait out
345 * the whole readiness timeout.
346 */
347 const gatewayBound = (containerName: string): Effect.Effect<boolean> =>
348 docker(["port", containerName, "4566/tcp"]).pipe(
349 Effect.map(({ stdout }) => stdout.trim() !== ""),
350 Effect.orElseSucceed(() => false),
351 );
352
353 /**
354 * The requested ports the managed container should publish: every port that
355 * is either already published by the container or still free on the host.
356 * Taken ports are skipped (with a warning only when the caller asked for
357 * them explicitly) so a busy host port never blocks the emulator from
358 * starting.
359 */
360 const resolvePublishablePorts = Effect.fn(function* (
361 requested: readonly number[],
362 published: ReadonlySet<number>,
363 onTaken?: (port: number) => Effect.Effect<void>,
364 ) {
365 const desired: number[] = [];
366 for (const port of requested) {
367 if (published.has(port) || (yield* isHostPortFree(port))) {
368 desired.push(port);
369 } else if (onTaken !== undefined) {
370 yield* onTaken(port);
371 }
372 }
373 return desired;
374 });
375
376 /**
377 * Ensure a floci emulator is serving and healthy, starting the managed
378 * container if needed. Idempotent and cheap when already up (one HTTP
379 * probe); see the module doc for the resolution order.
380 */
381 /**
382 * One `ensureFloci` at a time per process. Callers memoize per stack
383 * build, but separate builds (concurrent tests, parallel dev commands) can
384 * ensure at the same moment: when the managed container needs recreating,
385 * two callers would both `docker rm -f` it ("removal of container … is
386 * already in progress") and then race `docker run` on the name. Under the
387 * mutex the second caller observes the container the first one started.
388 */
389 const ensureMutex = Semaphore.makeUnsafe(1);
390
391 export const ensureFloci = (config?: FlociConfig): Effect.Effect<FlociInstance, FlociError> =>
392 ensureMutex.withPermits(1)(
393 // The mutex serializes ensures within THIS process; across processes
394 // (a test runner and a dev CLI booting together) the recreate path can
395 // still race — one process's `rm -f` can delete the container the
396 // other just created, and the loser's `docker run` fails (sometimes
397 // with an empty stderr). Re-running the whole ensure converges: the
398 // retry re-observes whatever the winner left serving and reuses it.
399 ensureFlociUnsynchronized(config).pipe(
400 Effect.retry({
401 schedule: Schedule.spaced("2 seconds"),
402 times: 3,
403 }),
404 ),
405 );
406
407 const ensureFlociUnsynchronized = (
408 config?: FlociConfig,
409 ): Effect.Effect<FlociInstance, FlociError> =>
410 Effect.gen(function* () {
411 const port = config?.port ?? DEFAULT_FLOCI_PORT;
412 const endpoint = `http://localhost:${port}`;
413 if (config?.external ?? process.env.ALCHEMY_FLOCI_EXTERNAL === "1") {
414 yield* checkHealth(endpoint).pipe(
415 Effect.timeout("5 seconds"),
416 Effect.mapError(
417 (cause) =>
418 new FlociError({
419 message: `external floci server unavailable at ${endpoint}`,
420 cause,
421 }),
422 ),
423 );
424 yield* syncCaBundle(endpoint);
425 return { endpoint, managed: false };
426 }
427 const containerName = config?.containerName ?? DEFAULT_CONTAINER_NAME;
428 const published = yield* publishedPorts(containerName);
429 const elbPorts = yield* resolvePublishablePorts(
430 config?.elbListenerPorts ?? DEFAULT_ELB_LISTENER_PORTS,
431 published ?? new Set(),
432 // Default 80/443 are opportunistic (most stacks have no ELB). A taken
433 // privileged port is the common case on a developer machine, not a
434 // problem — warn only when the caller asked for those ports.
435 config?.elbListenerPorts === undefined
436 ? undefined
437 : (port) =>
438 Effect.logWarning(
439 `floci: host port ${port} is taken — emulated load balancer listeners on ${port} will not be reachable from the host`,
440 ),
441 );
442 const edgePorts = yield* resolvePublishablePorts(
443 config?.cloudfrontEdgePorts ?? DEFAULT_CLOUDFRONT_EDGE_PORTS,
444 published ?? new Set(),
445 );
446
447 // Converge the managed container's EXPLICITLY-requested ports and its
448 // image: a container missing ports the caller configured can't serve
449 // them, and one running a superseded emulator image (a floci release
450 // bump, or a switch of `ALCHEMY_FLOCI_IMAGE`) would silently miss
451 // emulator features the providers now rely on — so either is recreated
452 // (emulated state is ephemeral by design; the next apply reconciles
453 // it). The OPPORTUNISTIC defaults (80/443, the CloudFront edge range)
454 // deliberately do NOT trigger recreation: which of them resolve as
455 // publishable depends on what happens to be free in the observing
456 // process, so keying recreation on them makes concurrent consumers
457 // (a test run and a dev CLI) recreate each other's container forever.
458 // An UNMANAGED server (a dev-mode JVM, a hand-run container) is never
459 // touched. To keep running a hand-built image under the managed name,
460 // keep `ALCHEMY_FLOCI_IMAGE` set — the resolution order is the
461 // contract.
462 //
463 // The container is labelled with the ports the caller ASKED for, and
464 // recreation keys on a change to that request — never on which ports
465 // ended up published, which depends on what the host and Docker would
466 // allow at creation time. A configured port Docker refused stays
467 // dropped until the request changes, instead of recreating (and
468 // wiping) the container on every ensure.
469 const publishPorts = [...elbPorts, ...edgePorts];
470 const requestedPorts = requestedPortsLabel(config);
471 const image = yield* resolveImage(config);
472 const running =
473 published !== undefined
474 ? yield* docker([
475 "inspect",
476 "--format",
477 `{{.Config.Image}}|{{index .Config.Labels "${PORTS_LABEL}"}}`,
478 containerName,
479 ]).pipe(
480 Effect.map(({ stdout }) => {
481 const [runningImage, label] = stdout.trim().split("|");
482 return {
483 image: runningImage || undefined,
484 requestedPorts: label && label !== "<no value>" ? label : undefined,
485 };
486 }),
487 Effect.orElseSucceed(() => undefined),
488 )
489 : undefined;
490 const runningImage = running?.image;
491 const needsRecreate =
492 published !== undefined &&
493 ((running?.requestedPorts !== undefined
494 ? running.requestedPorts !== requestedPorts
495 : // Containers created before the label: recreate when they miss
496 // a configured port that is publishable now.
497 [
498 ...(config?.elbListenerPorts ?? []).filter((p) => elbPorts.includes(p)),
499 ...(config?.cloudfrontEdgePorts ?? []).filter((p) => edgePorts.includes(p)),
500 ].some((p) => !published.has(p))) ||
501 (runningImage !== undefined && runningImage !== image));
502
503 if (yield* isServing(endpoint)) {
504 if (!needsRecreate) {
505 // Something may be serving but still starting — the readiness
506 // poll tolerates transient unhealthiness.
507 yield* checkHealth(endpoint).pipe(Effect.catch(() => waitForHealth(endpoint, config)));
508 yield* syncCaBundle(endpoint);
509 return { endpoint, managed: false };
510 }
511 // Only recreate when the server IS our managed container (otherwise
512 // removing the container would not free the endpoint anyway).
513 yield* Effect.logInfo(
514 `floci: recreating ${containerName} (image ${runningImage} -> ${image}, ports [${publishPorts.join(", ")}])`,
515 );
516 yield* docker(["rm", "-f", containerName]);
517 } else if (needsRecreate) {
518 yield* Effect.logInfo(
519 `floci: recreating ${containerName} (image ${runningImage} -> ${image}, ports [${publishPorts.join(", ")}])`,
520 );
521 yield* docker(["rm", "-f", containerName]);
522 } else {
523 // Revive a stopped container from a previous session, else run fresh.
524 const started = yield* docker(["start", containerName]).pipe(
525 Effect.map(() => true),
526 Effect.orElseSucceed(() => false),
527 );
528 if (started && (yield* gatewayBound(containerName))) {
529 yield* waitForHealth(endpoint, config);
530 yield* syncCaBundle(endpoint);
531 return { endpoint, managed: true, containerName };
532 }
533 // Missing, or revived without its gateway published (`docker start`
534 // on a container whose port setup failed is a no-op success) —
535 // remove whatever is left and run fresh.
536 yield* docker(["rm", "-f", containerName]).pipe(Effect.ignore);
537 }
538
539 yield* Effect.tryPromise({
540 try: () => fs.mkdir(FLOCI_TLS_DIR, { recursive: true }),
541 catch: (cause) => new FlociError({ message: "tls dir", cause }),
542 }).pipe(Effect.ignore);
543 const runContainer = (elb: readonly number[], edge: readonly number[]) => {
544 const args = [
545 "run",
546 "-d",
547 "--name",
548 containerName,
549 "-p",
550 `${port}:4566`,
551 // Docker Desktop injects `host.docker.internal` automatically; native
552 // Linux Docker does not. The emulator needs it to reach a dev server
553 // running on the developer's machine (a CloudFront origin pointed at
554 // `localhost:<port>`, for one).
555 "--add-host",
556 "host.docker.internal:host-gateway",
557 "--label",
558 `${PORTS_LABEL}=${requestedPorts}`,
559 ...[...elb, ...edge].flatMap((p) => ["-p", `${p}:${p}`]),
560 // The emulator can only hand a distribution a port the container
561 // published, so it gets the resolved list rather than its own default
562 // range — and the feature is switched off outright when nothing could
563 // be published, so it never binds a port nothing can reach.
564 "-e",
565 edge.length > 0
566 ? `FLOCI_SERVICES_CLOUDFRONT_EDGE_PORTS=${edge.join(",")}`
567 : "FLOCI_SERVICES_CLOUDFRONT_EDGE_PORTS_ENABLED=false",
568 ...(config?.dockerSocket === false
569 ? []
570 : ["-v", "/var/run/docker.sock:/var/run/docker.sock", "-u", "root"]),
571 ...(config?.storageDir !== undefined
572 ? ["-v", `${config.storageDir}:/app/data`, "-e", "FLOCI_STORAGE_MODE=hybrid"]
573 : // No full storage mount: still persist the TLS dir so the
574 // self-signed CA is stable across container recreations (floci
575 // reuses existing cert files).
576 ["-v", `${FLOCI_TLS_DIR}:/app/data/tls`]),
577 ...Object.entries(config?.env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`]),
578 image,
579 ];
580 return docker(args).pipe(
581 // A concurrent ensureFloci (e.g. the dev sidecar racing the CLI's
582 // exec child on a machine where floci is not yet running) may have
583 // created the container between our checks and this run. Docker
584 // reports that as a name conflict — but not reliably: the losing
585 // `docker run` has been observed exiting non-zero with an EMPTY
586 // stderr right after a Docker Desktop restart, so the error text
587 // cannot be trusted. Ask Docker whether the container exists now and
588 // reuse it if so; only a run that left nothing behind is a failure.
589 Effect.catch((error) =>
590 docker(["inspect", "--format", "{{.Id}}", containerName]).pipe(
591 Effect.flatMap(({ stdout }) => (stdout.trim() ? Effect.void : Effect.fail(error))),
592 Effect.mapError(() => error),
593 ),
594 ),
595 );
596 };
597
598 // Docker is the authority on which ports it can publish — the host-side
599 // probe can't see rootless Docker's privileged-port limit or a port held
600 // by another container on Docker Desktop. Only the gateway is required:
601 // if the run fails or leaves the gateway unpublished, run once more
602 // without the ELB/CloudFront edge ports.
603 yield* Effect.logInfo(`floci: starting ${containerName} (${image}) on ${endpoint}`);
604 const first = yield* Effect.result(runContainer(elbPorts, edgePorts));
605 if (!(Result.isSuccess(first) && (yield* gatewayBound(containerName)))) {
606 const reason = Result.isFailure(first)
607 ? first.failure.message
608 : `host port ${port} was not published`;
609 yield* docker(["rm", "-f", containerName]).pipe(Effect.ignore);
610 if (publishPorts.length === 0) {
611 return yield* new FlociError({
612 message: `floci: could not start ${containerName}: ${reason}`,
613 cause: Result.isFailure(first) ? first.failure : undefined,
614 });
615 }
616 yield* Effect.logWarning(
617 `floci: ${reason} — starting ${containerName} without ports [${publishPorts.join(", ")}]; emulated load balancers and CloudFront distributions on them will not be reachable from the host`,
618 );
619 yield* runContainer([], []);
620 if (!(yield* gatewayBound(containerName))) {
621 yield* docker(["rm", "-f", containerName]).pipe(Effect.ignore);
622 return yield* new FlociError({
623 message: `floci: ${containerName} started but host port ${port} is not published — check \`docker port ${containerName}\` and the Docker daemon logs`,
624 });
625 }
626 }
627
628 yield* waitForHealth(endpoint, config);
629 yield* syncCaBundle(endpoint);
630 return { endpoint, managed: true, containerName };
631 });
632
633 const waitForHealth = (endpoint: string, config?: FlociConfig) =>
634 checkHealth(endpoint).pipe(
635 Effect.retry({
636 schedule: Schedule.spaced("1 second"),
637 times: Math.max(
638 1,
639 Math.ceil(
640 Duration.toSeconds(
641 // 300s: a freshly (re)started Docker daemon can take minutes to
642 // create the first container from the 1.3GB image; giving up
643 // early parks `alchemy dev` on a FlociError until the next file
644 // edit, which reads as a wedge.
645 Duration.fromInputUnsafe(config?.readinessTimeout ?? "300 seconds"),
646 ),
647 ),
648 ),
649 }),
650 Effect.mapError(
651 (error) =>
652 new FlociError({
653 message:
654 `floci did not become healthy at ${endpoint}: ${error.message}. ` +
655 "Check `docker logs " +
656 (config?.containerName ?? DEFAULT_CONTAINER_NAME) +
657 "`.",
658 cause: error,
659 }),
660 ),
661 );
662
663 /** Stop (not remove) the managed container. */
664 export const stopFloci = (
665 containerName: string = DEFAULT_CONTAINER_NAME,
666 ): Effect.Effect<void, FlociError> => Effect.asVoid(docker(["stop", containerName]));
667
668 /** Remove the managed container (and its in-memory state). */
669 export const destroyFloci = (
670 containerName: string = DEFAULT_CONTAINER_NAME,
671 ): Effect.Effect<void, FlociError> => Effect.asVoid(docker(["rm", "-f", containerName]));
672
673 /** Tail of the managed container's logs. */
674 export const flociLogs = (
675 containerName: string = DEFAULT_CONTAINER_NAME,
676 lines = 200,
677 ): Effect.Effect<string, FlociError> =>
678 Effect.map(
679 docker(["logs", "--tail", String(lines), containerName]),
680 ({ stdout, stderr }) => stdout + stderr,
681 );