@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, 04:45 UTC

main
ts 998 lines 37.5 KB
Raw
1 import type { InlineDockerfile } from "@alchemy.run/docker/Dockerfile";
2 import type { DockerfileBuild, DockerfileBuildOptions } from "@alchemy.run/docker/ImageSource";
3 import * as Containers from "@distilled.cloud/cloudflare/containers";
4 import type * as Bundle from "alchemy/Bundle/Bundle";
5 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
6 import { type Main, type PlatformProps, type PlatformServices } from "alchemy/Platform";
7 import { Resource } from "alchemy/Resource";
8 import type { ProcessServices } from "alchemy/Runtime/Process";
9 import type * as Duration from "effect/Duration";
10 import * as Redacted from "effect/Redacted";
11 import type { Providers } from "../Providers.ts";
12 import { ContainerTypeId } from "./Container.ts";
13 import { LiveContainerProvider } from "./ContainerProvider.ts";
14 import { LocalContainerProvider } from "./LocalContainerProvider.ts";
15
16 export { Credentials } from "@distilled.cloud/cloudflare/Credentials";
17
18 export namespace ContainerApplication {
19 export type InstanceType = NonNullable<
20 Containers.CreateContainerApplicationRequest["configuration"]["instanceType"]
21 >;
22 export type SchedulingPolicy = NonNullable<
23 Containers.CreateContainerApplicationRequest["schedulingPolicy"]
24 >;
25 export type Observability = NonNullable<
26 Containers.CreateContainerApplicationRequest["configuration"]["observability"]
27 >;
28 export type Secret = NonNullable<
29 Containers.CreateContainerApplicationRequest["configuration"]["secrets"]
30 >[number];
31 export type Disk = NonNullable<
32 Containers.CreateContainerApplicationRequest["configuration"]["disk"]
33 >;
34 export type EnvironmentVariable = NonNullable<
35 Containers.CreateContainerApplicationRequest["configuration"]["environmentVariables"]
36 >[number];
37 export type Label = NonNullable<
38 Containers.CreateContainerApplicationRequest["configuration"]["labels"]
39 >[number];
40 export type Network = NonNullable<
41 Containers.CreateContainerApplicationRequest["configuration"]["network"]
42 >;
43 export type Dns = NonNullable<
44 Containers.CreateContainerApplicationRequest["configuration"]["dns"]
45 >;
46 export type Port = NonNullable<
47 Containers.CreateContainerApplicationRequest["configuration"]["ports"]
48 >[number];
49 export type Check = NonNullable<
50 Containers.CreateContainerApplicationRequest["configuration"]["checks"]
51 >[number];
52 export type Region =
53 | "ENAM"
54 | "WNAM"
55 | "EEUR"
56 | "WEUR"
57 | "APAC"
58 | "SAM"
59 | "ME"
60 | "OC"
61 | "AFR"
62 | (string & {});
63 export type Jurisdiction = "eu" | "us" | "fedramp" | (string & {});
64 export type Constraints = {
65 tier?: number;
66 /**
67 * Geographic regions instances may run in. Limited-capacity regions
68 * (`ME`, `OC`, `AFR`) cannot be used exclusively.
69 */
70 regions?: Region[];
71 /**
72 * Compliance boundary for instances. When `regions` is also set, every
73 * region must belong to the jurisdiction.
74 * @see https://developers.cloudflare.com/containers/concepts/placement/#jurisdictional-constraints
75 */
76 jurisdiction?: Jurisdiction;
77 };
78 export type Affinities = {
79 colocation?: "datacenter";
80 };
81 export type Configuration = Containers.CreateContainerApplicationRequest["configuration"];
82 export interface Rollout {
83 strategy?: "rolling" | "immediate";
84 kind?: "full_auto";
85 stepPercentage?: number;
86 }
87 }
88
89 /**
90 * Configuration shared by every container image source: application naming,
91 * scaling, placement, runtime environment, and rollout settings. The image
92 * source itself is declared by the variant interfaces
93 * ({@link EffectfulContainerProps} / {@link ExternalContainerProps} /
94 * {@link RemoteContainerProps}) that extend this base.
95 */
96 export interface ContainerApplicationPropsBase extends PlatformProps {
97 /**
98 * Human-readable application name. If omitted, Alchemy derives a deterministic
99 * physical name from the stack, stage, and logical ID.
100 */
101 name?: string;
102 /**
103 * Name of the exported Durable Object class this container backs when the
104 * Container is bound on an **async** Worker's `env`. Defaults to the
105 * binding name (the `env` key). Ignored by the Effect-native path, where
106 * the class name comes from the hosting Durable Object.
107 */
108 className?: string;
109 /**
110 * Initial number of instances to maintain. Matches wrangler, which forces
111 * this to 0 whenever {@link maxInstances} is set (pure scale-from-zero).
112 * @default 0
113 */
114 instances?: number;
115 /**
116 * Maximum number of instances the application may scale to. Matches
117 * wrangler's default of 20. A value of 1 serializes every Durable Object
118 * instance through a single container slot, so the default lets containers
119 * scale concurrently out of the box.
120 * @default 20
121 */
122 maxInstances?: number;
123 /**
124 * Scheduling policy used by Cloudflare's containers control plane.
125 * @default "default"
126 */
127 schedulingPolicy?: "default" | "regional";
128 /**
129 * Instance type for each deployment. Defaults to wrangler's `"lite"` tier
130 * (1/16 vCPU, 256 MiB, 2 GB disk) when no explicit {@link vcpu}/{@link memory}/
131 * {@link memoryMib}/{@link disk} is set. (`"dev"` is wrangler's deprecated
132 * alias for `"lite"`.)
133 * @default "lite"
134 */
135 instanceType?: ContainerApplication.InstanceType;
136 /**
137 * Observability settings for the deployment.
138 */
139 observability?: ContainerApplication.Observability;
140 /**
141 * SSH public keys to install into the deployment.
142 */
143 sshPublicKeyIds?: string[];
144 /**
145 * Secrets exposed to the container runtime as environment variables.
146 */
147 secrets?: ContainerApplication.Secret[];
148 /**
149 * CPU allocation override for each deployment.
150 */
151 vcpu?: number;
152 /**
153 * Memory allocation override for each deployment.
154 */
155 memory?: string;
156 /**
157 * Memory allocation override for each deployment, in MiB.
158 * Custom sizing requires at least 1 {@link vcpu} and 3072 MiB of memory
159 * per vCPU for the first 4 vCPUs.
160 */
161 memoryMib?: number;
162 /**
163 * Disk allocation override for each deployment.
164 */
165 disk?: ContainerApplication.Disk;
166 /**
167 * Plain environment variables passed to the container runtime.
168 */
169 environmentVariables?: ContainerApplication.EnvironmentVariable[];
170 /**
171 * Labels attached to the deployment.
172 */
173 labels?: ContainerApplication.Label[];
174 /**
175 * Network configuration for the deployment: IPv4/IPv6 address assignment
176 * (`"none"` or `"predefined"`) and `mode` (`"private"` or `"public"`).
177 * `assignIpv4: "predefined"` implies `mode: "public"`, so private-only
178 * accounts set both families to `"none"`.
179 */
180 network?: ContainerApplication.Network;
181 /**
182 * Command override for the container image.
183 */
184 command?: string[];
185 /**
186 * Entrypoint override for the container image.
187 */
188 entrypoint?: string[];
189 /**
190 * DNS configuration for the deployment.
191 */
192 dns?: ContainerApplication.Dns;
193 /**
194 * Exposed ports for the deployment.
195 */
196 ports?: ContainerApplication.Port[];
197 /**
198 * Health and readiness checks for the deployment.
199 */
200 checks?: ContainerApplication.Check[];
201 /**
202 * Resource constraints for the application.
203 */
204 constraints?: ContainerApplication.Constraints;
205 /**
206 * Affinity hints for scheduling.
207 */
208 affinities?: ContainerApplication.Affinities;
209 /**
210 * Progressive rollout settings applied after updates.
211 */
212 rollout?: ContainerApplication.Rollout;
213 /**
214 * Container registry host to use for generated Dockerfile builds.
215 * @default "registry.cloudflare.com"
216 */
217 registryId?: string;
218 /**
219 * Image publication configuration. Builds are cached by default in a
220 * repository named after the application's physical name. Generated names
221 * include the stage and resource instance, so updates within that stage can
222 * reuse images. Replacement or destroy/recreate can select a new repository.
223 * Set `repository` to share finished images and build layers across stages.
224 *
225 * @example
226 * ```typescript
227 * // Default: cached in this application's generated repository.
228 * const app = yield* Cloudflare.Container("Web", { context: "./web" }).Application;
229 * // Repository: registry.cloudflare.com/<account-id>/<app.applicationName>
230 * ```
231 */
232 publish?: {
233 /**
234 * Destination repository name within the current Cloudflare account's
235 * container registry, for example `"web"`. This is not a source image,
236 * registry hostname, account ID, tag, or fully qualified image reference.
237 * Alchemy lowercases the name and adds the registry host and account ID:
238 * `registry.cloudflare.com/<account-id>/web` with the default `registryId`.
239 * The container application's name is independent of this repository name.
240 * Omitting `publish` uses the application's physical name instead and still
241 * enables caching. Generated names are scoped to the stage and resource
242 * instance; an explicit repository allows cross-stage reuse.
243 *
244 * For Dockerfile and Effect-native builds, Alchemy publishes a content-hash
245 * tag and an inline layer-cache tag, then deploys an immutable manifest
246 * digest. The build hash and manifest digest are different identifiers.
247 * Builds targeting this repository import reusable layers from its shared
248 * `:buildcache` tag, even when their full input hashes differ. The tag points
249 * to the latest exported inline cache, not an aggregate of all historical
250 * images. A finished-image cache hit leaves this layer-cache tag unchanged.
251 *
252 * Applications and stages in the same account can share `"web"`. Matching
253 * build inputs reuse the published image; changed inputs produce another
254 * hash tag in the same repository. Finished-image cache reuse applies to
255 * builds, not to re-publishing remote images. Pin base images and downloaded
256 * dependencies: changes outside the build context cannot invalidate its
257 * content hash.
258 *
259 * External remote images are re-published into this repository without
260 * building them. Images already in the target registry keep their existing
261 * repository; setting this option does not copy them into another one.
262 *
263 * @example
264 * ```typescript
265 * const app = yield* Cloudflare.Container("WebProduction", {
266 * context: "./web",
267 * publish: { repository: "web" },
268 * }).Application;
269 *
270 * // Published build:
271 * // registry.cloudflare.com/<account-id>/web:<build-hash>
272 * // Shared build-layer cache:
273 * // registry.cloudflare.com/<account-id>/web:buildcache
274 * // Deployed image (app.configuration.image):
275 * // registry.cloudflare.com/<account-id>/web@sha256:<manifest-digest>
276 * ```
277 */
278 repository: string;
279 };
280 /**
281 * Environment variables passed to the container runtime.
282 */
283 env?: Record<string, any>;
284 /**
285 * Exports passed to the container runtime.
286 */
287 exports?: string[];
288 }
289
290 /**
291 * Bundle an Effect-native program into a generated image. Alchemy bundles
292 * {@link main} and bakes it in as the container's entrypoint. The
293 * environment the program runs in comes from {@link image} or an inline
294 * {@link dockerfile} (exclusive with each other), defaulting to the
295 * runtime's base image.
296 */
297 export interface EffectfulContainerProps extends ContainerApplicationPropsBase {
298 /** Entrypoint file for the Effect program, typically `import.meta.url`. */
299 main: string;
300 /**
301 * Environment image for the generated Dockerfile — a plain registry
302 * reference, e.g. `"oven/bun:latest"`. Alchemy synthesizes the `FROM` line
303 * and appends the statements that copy the bundled program and set the
304 * entrypoint. The image must be able to run the {@link runtime}.
305 * Exclusive with {@link dockerfile}.
306 *
307 * @default `oven/bun:1` for `runtime: "bun"`, `node:22-slim` for `runtime: "node"`
308 */
309 image?: string;
310 /**
311 * Inline environment Dockerfile content (typically `Dockerfile.inline`).
312 * Replaces the generated `FROM` line — carry your own `FROM` plus any
313 * extra build steps (system packages, config); the bundled program is
314 * layered on top. Exclusive with {@link image}. Never interpolate secrets
315 * into inline content — it is baked into image layers.
316 */
317 dockerfile?: InlineDockerfile;
318 /**
319 * Exported handler symbol inside the bundled module.
320 * @default "default"
321 */
322 handler?: string;
323 /**
324 * Runtime environment for the container program.
325 *
326 * @default "bun"
327 */
328 runtime?: "bun" | "node";
329 /**
330 * Module specifiers that Rolldown should mark as external when bundling
331 * the container entrypoint. The matching packages are installed inside the
332 * image via the runtime's package manager (`bun add` for `runtime: "bun"`,
333 * `npm install` for `runtime: "node"`) before the entrypoint runs.
334 *
335 * Use this for native dependencies that must not be bundled (e.g. `sharp`,
336 * `impit`) or for packages that intentionally ship in the base image.
337 *
338 * Install inside the image is controlled by {@link autoInstallExternals}
339 * (default `true`); set it to `false` if your environment ({@link image}
340 * or inline {@link dockerfile}) already ships these packages and you want
341 * to avoid the redundant step.
342 */
343 external?: string[];
344 /**
345 * Whether to auto-install the packages listed in {@link external} inside
346 * the container image (via `bun add` or `npm install`) before running the
347 * entrypoint.
348 *
349 * @default true
350 *
351 * Set to `false` when your environment image already ships these packages
352 * (for example, a base image that pre-installs `sharp`), to avoid the
353 * redundant install step.
354 */
355 autoInstallExternals?: boolean;
356 /**
357 * Bundler configuration for {@link main}. Unused code is tree-shaken.
358 * `effect`, alchemy, and `@distilled.cloud` are marked pure so unused
359 * parts prune more aggressively. List extra packages with
360 * `pure.packages`, or disable with `pure: false`.
361 */
362 build?: Bundle.BundleConfig;
363 }
364
365 /**
366 * Build the container image from your own Dockerfile — no Effect program is
367 * bundled. The image is shipped as-is.
368 */
369 export interface ExternalContainerProps
370 extends ContainerApplicationPropsBase, DockerfileBuildOptions {
371 /**
372 * The build context directory containing the Dockerfile and any files it
373 * copies. Only valid with a `dockerfile` PATH (not inline content).
374 *
375 * @default `./`
376 */
377 context?: string;
378 /**
379 * The Dockerfile to build. A string is a **path** resolved relative to
380 * {@link context} (default `<context>/Dockerfile`); an
381 * {@link InlineDockerfile} (typically `Dockerfile.inline`) is the whole
382 * Dockerfile's content, built in an empty generated context (exclusive
383 * with {@link context}).
384 */
385 dockerfile?: string | InlineDockerfile;
386 }
387
388 /**
389 * Deploy a pre-built remote image — Alchemy pulls it and re-pushes it to
390 * Cloudflare's managed registry without building anything.
391 */
392 export interface RemoteContainerProps extends ContainerApplicationPropsBase {
393 /**
394 * The pre-built image to pull and re-push.
395 *
396 * E.g. `ghcr.io/alpine/alpine:latest`
397 *
398 * Alchemy pulls the image as `linux/amd64` on every deploy and every
399 * `alchemy dev` start, so a mutable tag picks up a newly pushed image.
400 * An image that exists only in the local Docker (built on this machine
401 * or `docker load`ed) is used as-is when the pull fails; build it with
402 * `--platform linux/amd64`, the platform Cloudflare runs.
403 *
404 * When the reference already points at the target registry (the
405 * {@link ContainerApplicationPropsBase.registryId | registryId} host,
406 * `registry.cloudflare.com` by default) — e.g. a digest reference pushed
407 * by CI like `registry.cloudflare.com/<accountId>/app@sha256:...` — it is
408 * deployed as-is and the docker pull/push round-trip is skipped entirely.
409 */
410 image: string;
411 }
412
413 /** SSH access to a container application's instances. */
414 export interface ContainerSshConfiguration {
415 /** Whether instances accept SSH connections. */
416 enabled: boolean;
417 /** Port the SSH server listens on inside each instance. */
418 port?: number;
419 }
420
421 /**
422 * Application-wide settings of a Durable Object class's container application.
423 * Every Container bound to the class may declare them; declarations must agree.
424 */
425 export interface DurableObjectApplicationSettings {
426 /**
427 * SSH access to every instance of the application. Removing a previously
428 * declared value disables SSH.
429 */
430 ssh?: ContainerSshConfiguration;
431 /** SSH public keys allowed to access instances. Removing this property clears previously managed keys. */
432 authorizedKeys?: Containers.UserSSHPublicKeyList;
433 /** Application-wide logging. Removing a previously declared value disables logs. Changes do not restart running containers. */
434 observability?: Containers.ContainerApplicationObservability;
435 }
436
437 /**
438 * One image a Durable Object starts with `ctx.container.start()`.
439 *
440 * Cloudflare allows one container application per Durable Object class. Every
441 * `durable_object` Container bound to the class adds its image to that
442 * application, under the Container's id. Bind several Containers to start
443 * different images from the same class, one at a time. One Container may be
444 * bound to several classes.
445 *
446 * An Effect-native Durable Object binds a Container with `yield*`. An async
447 * Worker attaches it to a class with
448 * `Cloudflare.DurableObject(className, { containers })`.
449 *
450 * The policy is immutable: migrating an existing fleet application requires a
451 * new application and Durable Object namespace.
452 */
453 export interface DurableObjectContainerProps
454 extends DurableObjectApplicationSettings, PlatformProps, DockerfileBuildOptions {
455 /** Select images and instance sizes in `ctx.container.start()`. */
456 schedulingPolicy: "durable_object";
457 /**
458 * Registry image to copy into Cloudflare's managed registry, e.g.
459 * `"node:24-slim"`. Exclusive with {@link context} and {@link dockerfile}.
460 * Omit every image source to contribute no image: `start()` then uses the
461 * managed `cloudflare/debian-trixie` image unless given another.
462 *
463 * Alchemy pulls the image as `linux/amd64` on every deploy and every
464 * `alchemy dev` start, so a mutable tag picks up a newly pushed image.
465 * An image that exists only in the local Docker (built on this machine
466 * or `docker load`ed) is used as-is when the pull fails; build it with
467 * `--platform linux/amd64`, the platform Cloudflare runs.
468 */
469 image?: string;
470 /**
471 * Docker build context. Setting `context` or `dockerfile` builds the image;
472 * `context` defaults to the current directory.
473 */
474 context?: string;
475 /** Dockerfile path or inline content. Defaults to the context's Dockerfile. */
476 dockerfile?: string | InlineDockerfile;
477 /** Image publication and build-cache configuration. */
478 publish?: ContainerApplicationPropsBase["publish"];
479 /**
480 * Maximum wait for Cloudflare to prepare the published image, including API calls.
481 * Accepts an Effect duration such as "45 minutes". Must be finite and positive.
482 * Cancellation stops waiting; another deployment reuses the published registry image.
483 * Use an immutable source digest or change the image reference to refresh the image.
484 * @default "30 minutes"
485 */
486 imagePreparationTimeout?: Duration.Input;
487 }
488
489 /**
490 * Fleet-scheduled applications select a deployment image through `main`
491 * (bundled Effect program), `context`/`dockerfile`, or a pre-built `image`.
492 * A Durable Object-managed Container publishes one image that its Durable
493 * Object selects at runtime.
494 */
495 export type ContainerApplicationProps =
496 | EffectfulContainerProps
497 | ExternalContainerProps
498 | RemoteContainerProps
499 | DurableObjectContainerProps;
500
501 /**
502 * INTERNAL — the loose provider-side view across the variants: every
503 * variant-specific field optional at its widest type. Each union member is
504 * assignable to this shape, so provider/bundle code annotates helper params
505 * with it instead of narrowing the union at every property access.
506 */
507 export interface AnyContainerApplicationProps extends Omit<
508 ContainerApplicationPropsBase,
509 "schedulingPolicy"
510 > {
511 schedulingPolicy?: ContainerApplication.SchedulingPolicy;
512 ssh?: ContainerSshConfiguration;
513 authorizedKeys?: Containers.UserSSHPublicKeyList;
514 imagePreparationTimeout?: Duration.Input;
515 main?: string;
516 image?: string;
517 context?: string;
518 dockerfile?: string | InlineDockerfile;
519 handler?: string;
520 runtime?: "bun" | "node";
521 external?: string[];
522 autoInstallExternals?: boolean;
523 /** Bundler config for `main`; Docker build args and secrets for `context`. */
524 build?: Bundle.BundleConfig & DockerfileBuild;
525 }
526
527 export type ContainerServices = ContainerApplication | PlatformServices | ProcessServices;
528
529 export type ContainerShape = Main<ContainerServices>;
530
531 /**
532 * A Cloudflare Container Application — the deployed, scalable unit that runs a
533 * containerized program on Cloudflare's compute platform. Alchemy bundles the
534 * `main` entrypoint, builds a Docker image, pushes it to the Cloudflare
535 * registry, and reconciles the application's scaling and runtime configuration.
536 *
537 * This is the lower-level resource backing the {@link Container} platform
538 * binding; in application code you typically extend `Cloudflare.Container` to
539 * define and bind a container to a Durable Object rather than referencing this
540 * resource directly. The same props shape (`main`, `instanceType`, `instances`,
541 * etc.) is accepted by the `Cloudflare.Container(...)` class form shown below.
542 *
543 * @internal
544 * ### Defining a Container Application
545 * Point `main` at the container's entrypoint file; Alchemy bundles it and uses
546 * it as the image's entrypoint. The application name is derived deterministically
547 * from the stack, stage, and logical ID unless you set an explicit `name`, and
548 * `handler` selects which export to run when it isn't the default.
549 *
550 * **Example:** Minimal container
551 * ```typescript
552 * import * as Cloudflare from "@alchemy.run/cloudflare";
553 *
554 * export class Sandbox extends Cloudflare.Container<Sandbox>()("Sandbox", {
555 * main: import.meta.url,
556 * }) {}
557 * ```
558 *
559 * The single `main` prop is enough to ship a container: Alchemy bundles the
560 * entrypoint, builds and pushes the image, and provisions an application with
561 * one instance. Reach for the other props only when you need to scale, expose
562 * ports, or customize the build.
563 *
564 * **Example:** Named container with a non-default handler export
565 * ```typescript
566 * export class Worker extends Cloudflare.Container<Worker>()("Worker", {
567 * main: import.meta.url,
568 * handler: "runWorker",
569 * name: "background-worker",
570 * }) {}
571 * ```
572 *
573 * `name` pins a stable application name (instead of the generated one), which is
574 * useful for adopting an existing application, while `handler` runs the named
575 * `runWorker` export rather than the module's default.
576 *
577 * ### Image Sources
578 * The image is resolved from exactly one of three props, checked in order:
579 * `main` (bundle an Effect program into a generated image), then `image`
580 * (pull and re-push a remote image), then `context` / `dockerfile` (build
581 * your own Dockerfile). Only `main` injects an Effect runtime; the other two
582 * ship an arbitrary image unchanged.
583 *
584 * **Example:** Build your own Dockerfile (`context` / `dockerfile`)
585 * ```typescript
586 * export class Web extends Cloudflare.Container<Web>()("Web", {
587 * context: `${import.meta.dirname}/context`,
588 * dockerfile: "Dockerfile",
589 * }) {}
590 * ```
591 *
592 * Alchemy builds `dockerfile` against the `context` directory with no `main`
593 * bundling. `dockerfile` is resolved relative to `context` and defaults to
594 * `<context>/Dockerfile`.
595 *
596 * **Example:** Remote image (`image`)
597 * ```typescript
598 * export class Echo extends Cloudflare.Container<Echo>()("Echo", {
599 * image: "mendhak/http-https-echo:latest",
600 * }) {}
601 * ```
602 *
603 * Alchemy pulls the pre-built public image and re-pushes it to Cloudflare's
604 * managed registry instead of building anything.
605 *
606 * ### Bundling & Dependencies
607 * By default the entrypoint is bundled for the `bun` runtime. Use `runtime` to
608 * switch to Node, `external` to keep native/precompiled packages out of the
609 * bundle (auto-installed in the image unless `autoInstallExternals` is `false`),
610 * `image` (or an inline `dockerfile`) to pick the environment the generated
611 * Dockerfile starts `FROM`, and `registryId` to override the registry host.
612 *
613 * **Example:** Node runtime with external native deps
614 * ```typescript
615 * export class ImageApi extends Cloudflare.Container<ImageApi>()("ImageApi", {
616 * main: import.meta.url,
617 * runtime: "node",
618 * external: ["sharp"],
619 * autoInstallExternals: true,
620 * }) {}
621 * ```
622 *
623 * Marking `sharp` as `external` stops Rolldown from bundling the native module;
624 * because `autoInstallExternals` is `true`, Alchemy runs `npm install sharp`
625 * inside the image so the dependency is present at runtime.
626 *
627 * **Example:** Custom environment image and registry
628 * ```typescript
629 * export class Custom extends Cloudflare.Container<Custom>()("Custom", {
630 * main: import.meta.url,
631 * image: "oven/bun:1",
632 * autoInstallExternals: false,
633 * registryId: "registry.cloudflare.com",
634 * }) {}
635 * ```
636 *
637 * Alchemy generates the Dockerfile — `FROM` your `image`, then the
638 * program-copy and entrypoint steps — so you control the starting image;
639 * `autoInstallExternals: false` skips the redundant install step when the
640 * environment already ships your `external` packages.
641 *
642 * **Example:** Inline environment Dockerfile (extra build steps)
643 * ```typescript
644 * import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
645 *
646 * export class Transcoder extends Cloudflare.Container<Transcoder>()(
647 * "Transcoder",
648 * {
649 * main: import.meta.url,
650 * dockerfile: Dockerfile.inline`
651 * FROM oven/bun:1
652 * RUN apt-get update && apt-get install -y ffmpeg
653 * `,
654 * },
655 * ) {}
656 * ```
657 *
658 * Inline `dockerfile` content replaces the generated `FROM` line, so the
659 * environment can run extra build steps (system packages, config) while the
660 * bundled program is still layered on top.
661 *
662 * ### Bundling & Tree-shaking
663 * `main` is bundled with rolldown at deploy time. Unused code is
664 * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
665 * pure so unused parts prune more aggressively. Your app is not
666 * marked pure.
667 *
668 * **Example:** Mark additional packages as pure
669 * Only list packages with no top-level side effects.
670 * ```typescript
671 * {
672 * main: import.meta.url,
673 * build: {
674 * pure: { packages: ["my-lib", "@my-scope/*"] },
675 * },
676 * }
677 * ```
678 *
679 * **Example:** Turn it off
680 * ```typescript
681 * {
682 * main: import.meta.url,
683 * build: { pure: false },
684 * }
685 * ```
686 *
687 * ### Scaling & Instance Types
688 * Control the desired and maximum instance counts with `instances`/`maxInstances`
689 * and pick a compute size with `instanceType`. For finer control, override
690 * `vcpu`, `memory`, and `disk` directly.
691 *
692 * **Example:** Autoscaling with a larger instance type
693 * ```typescript
694 * export class Sandbox extends Cloudflare.Container<Sandbox>()("Sandbox", {
695 * main: import.meta.url,
696 * instanceType: "standard-1",
697 * instances: 1,
698 * maxInstances: 5,
699 * }) {}
700 * ```
701 *
702 * The application keeps one instance running and may scale out to five under
703 * load, each on the `standard-1` size. Use a larger `instanceType` (or the
704 * explicit overrides below) when the default `dev` size is too small.
705 *
706 * **Example:** Explicit CPU, memory, and disk overrides
707 * ```typescript
708 * export class Heavy extends Cloudflare.Container<Heavy>()("Heavy", {
709 * main: import.meta.url,
710 * vcpu: 2,
711 * memory: "4GB",
712 * disk: { size: "10GB" },
713 * }) {}
714 * ```
715 *
716 * These props override the per-instance resource allocation independently of
717 * `instanceType`, which is handy when a workload needs, say, extra disk for
718 * scratch space without bumping every other dimension.
719 *
720 * ### Runtime Configuration
721 * Inject configuration with `environmentVariables` (plain values) and `secrets`
722 * (references to stored secrets), and override the image's `command` or
723 * `entrypoint`. `labels` attach metadata to the deployment.
724 *
725 * **Example:** Environment variables, secrets, and a command override
726 * ```typescript
727 * export class Api extends Cloudflare.Container<Api>()("Api", {
728 * main: import.meta.url,
729 * environmentVariables: [{ name: "LOG_LEVEL", value: "info" }],
730 * secrets: [{ name: "API_KEY", type: "env", secret: "my-stored-secret" }],
731 * command: ["bun", "run", "start"],
732 * labels: [{ name: "team", value: "payments" }],
733 * }) {}
734 * ```
735 *
736 * `environmentVariables` are visible plain values, while `secrets` map a stored
737 * secret into the runtime as an env var without exposing it in config; `command`
738 * overrides the container's startup command and `labels` tag the deployment for
739 * organization.
740 *
741 * **Example:** Passing env and selecting runtime exports
742 * ```typescript
743 * export class Job extends Cloudflare.Container<Job>()("Job", {
744 * main: import.meta.url,
745 * env: { REGION: "wnam", FEATURE_FLAG: "on" },
746 * exports: ["default"],
747 * }) {}
748 * ```
749 *
750 * `env` injects values into the bundled program's runtime context (as opposed to
751 * the deployment-level `environmentVariables`), and `exports` declares which
752 * symbols from the entrypoint module the runtime should wire up.
753 *
754 * ### Networking & Health Checks
755 * Configure outbound/inbound networking with `network` and `dns`, expose
756 * `ports`, and gate readiness with `checks`.
757 *
758 * **Example:** Ports, network mode, DNS, and a health check
759 * ```typescript
760 * export class Web extends Cloudflare.Container<Web>()("Web", {
761 * main: import.meta.url,
762 * ports: [{ name: "http", port: 8080 }],
763 * network: { assignIpv4: "none", assignIpv6: "none", mode: "private" },
764 * dns: { servers: ["1.1.1.1"], searches: ["internal"] },
765 * checks: [{ name: "ready", type: "http", port: "8080", tls: false }],
766 * }) {}
767 * ```
768 *
769 * `ports` publishes the named port the program listens on, `network` controls IP
770 * assignment and public/private reachability, `dns` overrides resolver settings,
771 * and `checks` tells Cloudflare how to probe the container before routing
772 * traffic to it.
773 *
774 * The example is the private shape, which every account accepts.
775 * `assignIpv4: "predefined"` requests public reachability: Cloudflare infers
776 * `mode: "public"` when `mode` is omitted, rejects it on accounts that only
777 * permit private networking, and refuses it alongside `mode: "private"`.
778 *
779 * ### Observability & Access
780 * Turn on log shipping with `observability` and install `sshPublicKeyIds` for
781 * interactive access to running instances.
782 *
783 * **Example:** Enable logs and grant SSH access
784 * ```typescript
785 * export class Api extends Cloudflare.Container<Api>()("Api", {
786 * main: import.meta.url,
787 * observability: { logs: { enabled: true } },
788 * sshPublicKeyIds: ["ssh-key-id-123"],
789 * }) {}
790 * ```
791 *
792 * `observability.logs.enabled` streams the container's logs into Cloudflare's
793 * telemetry pipeline (queryable via the resource's `logs`/`tail` operations),
794 * and `sshPublicKeyIds` authorizes the listed keys to connect to instances for
795 * debugging.
796 *
797 * ### Scheduling & Placement
798 * Influence where and how Cloudflare schedules instances with `schedulingPolicy`,
799 * `constraints`, and `affinities`.
800 *
801 * **Example:** Pin scheduling policy and placement
802 * ```typescript
803 * export class Edge extends Cloudflare.Container<Edge>()("Edge", {
804 * main: import.meta.url,
805 * schedulingPolicy: "regional",
806 * constraints: { tier: 1 },
807 * affinities: { colocation: "datacenter" },
808 * }) {}
809 * ```
810 *
811 * `schedulingPolicy` selects the control-plane placement strategy,
812 * `constraints.tier` restricts which capacity tier instances may land on, and
813 * `affinities.colocation` keeps related instances in the same datacenter to
814 * reduce inter-instance latency.
815 *
816 * **Example:** Keep instances inside the EU for data residency
817 * ```typescript
818 * export class Verifier extends Cloudflare.Container<Verifier>()("Verifier", {
819 * main: import.meta.url,
820 * constraints: { jurisdiction: "eu" },
821 * }) {}
822 * ```
823 *
824 * `constraints.jurisdiction` restricts instances to a compliance boundary
825 * (`"eu"` is `EEUR` and `WEUR`), and `constraints.regions` narrows placement to
826 * specific regions within it.
827 *
828 * ### Rollouts
829 * When an update changes the configuration, `rollout` controls how the new
830 * version is rolled out across instances.
831 *
832 * **Example:** Progressive rollout on update
833 * ```typescript
834 * export class Api extends Cloudflare.Container<Api>()("Api", {
835 * main: import.meta.url,
836 * instances: 4,
837 * maxInstances: 4,
838 * rollout: { strategy: "rolling", stepPercentage: 25 },
839 * }) {}
840 * ```
841 *
842 * A `rolling` strategy with `stepPercentage: 25` replaces instances in 25%
843 * increments so the application stays available during the update; the default
844 * `immediate` strategy swaps everything at once. Steps advance automatically
845 * as new instances become healthy; each replaced instance receives `SIGTERM`
846 * and has 15 minutes to shut down cleanly before `SIGKILL`.
847 *
848 * Rollouts replace instances — they do not split requests between two image
849 * versions (request-level traffic splitting exists one layer up, on the
850 * Worker, via `version.traffic`). The fronting Worker and Durable Object cut
851 * over immediately while instances roll, so keep the Worker-to-container
852 * protocol compatible across both image versions until a rollout completes.
853 *
854 * @resource
855 * @product Containers
856 * @category Workers & Compute
857 */
858 export interface ContainerApplication<Shape = unknown> extends Resource<
859 ContainerTypeId,
860 ContainerApplicationProps,
861 {
862 /**
863 * Cloudflare-assigned unique identifier of the container application.
864 * Empty for a Durable Object-managed Container: the application belongs
865 * to the Durable Object class that binds it.
866 */
867 applicationId: string;
868 /**
869 * The resolved application name (either the provided `name` or the
870 * deterministic physical name derived from the stack, stage, and logical ID).
871 * For a Durable Object-managed Container, the name of its default image
872 * repository.
873 */
874 applicationName: string;
875 /**
876 * The Cloudflare account ID that owns the application.
877 */
878 accountId: string;
879 /**
880 * The scheduling policy in effect for the application's deployments.
881 */
882 schedulingPolicy: ContainerApplication.SchedulingPolicy;
883 /**
884 * The current desired number of instances. Unset for Durable Object-managed applications.
885 */
886 instances: number | undefined;
887 /**
888 * The maximum number of instances the application may scale to.
889 * Unset for Durable Object-managed applications.
890 */
891 maxInstances: number | undefined;
892 /**
893 * Resource constraints applied to the application, if any.
894 */
895 constraints: ContainerApplication.Constraints | undefined;
896 /**
897 * Scheduling affinity hints applied to the application, if any.
898 */
899 affinities: ContainerApplication.Affinities | undefined;
900 /**
901 * The resolved deployment configuration (image, networking, secrets, ports,
902 * checks, etc.) currently applied to the application.
903 * Durable Object-managed applications configure each instance at start().
904 */
905 configuration: Partial<ContainerApplication.Configuration> &
906 Containers.DurableObjectContainerConfiguration;
907 /** Application-wide logging declared by a Durable Object-managed Container. */
908 observability?: Containers.ContainerApplicationObservability;
909 /**
910 * The prepared, digest-pinned image of a Durable Object-managed Container,
911 * or its local image key in `alchemy dev`. Unset when the Container
912 * declares no image source.
913 */
914 image?: string;
915 /**
916 * The Durable Object namespace attached to the application, if it is bound
917 * to one.
918 */
919 durableObjects:
920 | {
921 namespaceId: string;
922 }
923 | undefined;
924 /**
925 * ISO-8601 timestamp of when the application was created.
926 */
927 createdAt: string;
928 /**
929 * The application's configuration version, incremented on each update.
930 * Unset for Durable Object-managed applications.
931 */
932 version: number | undefined;
933 /**
934 * Internal hashes of the built image and desired application
935 * configuration, used to skip unchanged builds and updates.
936 */
937 hash?: {
938 image: string;
939 digest?: string;
940 configuration?: string;
941 };
942 dev: DevContainerImage | undefined;
943 },
944 {
945 /**
946 * Durable Object namespace attached to the container application.
947 */
948 durableObjects?: {
949 namespaceId: string;
950 };
951 /**
952 * Environment variables injected into the container runtime via the binding.
953 */
954 env?: Record<string, any>;
955 },
956 Providers
957 > {
958 /** @internal phantom */
959 Shape: Shape;
960 }
961
962 // `DevContainerImage` stays here (consumed by the Attrs `dev` field above and
963 // imported by Worker.ts). The provider helpers that previously lived here
964 // (resolveDurableObjectApplicationRecovery, the readiness schedule/retry, etc.)
965 // were extracted to ContainerProvider.ts on this branch.
966 export type DevContainerImage =
967 | DevContainerImage.Build
968 | DevContainerImage.Pull
969 | DevContainerImage.Ref;
970
971 export declare namespace DevContainerImage {
972 interface Base {
973 readonly env?: Record<string, string | Redacted.Redacted<string>>;
974 }
975 export interface Build extends Base {
976 readonly dockerfile: string;
977 readonly context?: string;
978 readonly buildArgs?: Record<string, string>;
979 readonly buildSecrets?: Record<string, string | Redacted.Redacted<string>>;
980 }
981 export interface Pull extends Base {
982 readonly imageUri: string;
983 }
984 export interface Ref extends Base {
985 readonly tag: string;
986 }
987 }
988
989 export const ContainerProvider = () =>
990 // `{ Type }` instead of `ContainerPlatform` — importing the platform here
991 // would create a module cycle (ContainerPlatform.ts imports this file).
992 ProviderLayer.dual(
993 { Type: ContainerTypeId },
994 {
995 live: () => LiveContainerProvider(),
996 local: () => LocalContainerProvider(),
997 },
998 );