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
| 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 | ); |