sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Containers/ ContainerApplication.ts

import type { InlineDockerfile } from "@alchemy.run/docker/Dockerfile";
import type { DockerfileBuild, DockerfileBuildOptions } from "@alchemy.run/docker/ImageSource";
import * as Containers from "@distilled.cloud/cloudflare/containers";
import type * as Bundle from "alchemy/Bundle/Bundle";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import { type Main, type PlatformProps, type PlatformServices } from "alchemy/Platform";
import { Resource } from "alchemy/Resource";
import type { ProcessServices } from "alchemy/Runtime/Process";
import type * as Duration from "effect/Duration";
import * as Redacted from "effect/Redacted";
import type { Providers } from "../Providers.ts";
import { ContainerTypeId } from "./Container.ts";
import { LiveContainerProvider } from "./ContainerProvider.ts";
import { LocalContainerProvider } from "./LocalContainerProvider.ts";

export { Credentials } from "@distilled.cloud/cloudflare/Credentials";

export namespace ContainerApplication {
  export type InstanceType = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["instanceType"]
  >;
  export type SchedulingPolicy = NonNullable<
    Containers.CreateContainerApplicationRequest["schedulingPolicy"]
  >;
  export type Observability = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["observability"]
  >;
  export type Secret = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["secrets"]
  >[number];
  export type Disk = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["disk"]
  >;
  export type EnvironmentVariable = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["environmentVariables"]
  >[number];
  export type Label = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["labels"]
  >[number];
  export type Network = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["network"]
  >;
  export type Dns = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["dns"]
  >;
  export type Port = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["ports"]
  >[number];
  export type Check = NonNullable<
    Containers.CreateContainerApplicationRequest["configuration"]["checks"]
  >[number];
  export type Region =
    | "ENAM"
    | "WNAM"
    | "EEUR"
    | "WEUR"
    | "APAC"
    | "SAM"
    | "ME"
    | "OC"
    | "AFR"
    | (string & {});
  export type Jurisdiction = "eu" | "us" | "fedramp" | (string & {});
  export type Constraints = {
    tier?: number;
    /**
     * Geographic regions instances may run in. Limited-capacity regions
     * (`ME`, `OC`, `AFR`) cannot be used exclusively.
     */
    regions?: Region[];
    /**
     * Compliance boundary for instances. When `regions` is also set, every
     * region must belong to the jurisdiction.
     * @see https://developers.cloudflare.com/containers/concepts/placement/#jurisdictional-constraints
     */
    jurisdiction?: Jurisdiction;
  };
  export type Affinities = {
    colocation?: "datacenter";
  };
  export type Configuration = Containers.CreateContainerApplicationRequest["configuration"];
  export interface Rollout {
    strategy?: "rolling" | "immediate";
    kind?: "full_auto";
    stepPercentage?: number;
  }
}

/**
 * Configuration shared by every container image source: application naming,
 * scaling, placement, runtime environment, and rollout settings. The image
 * source itself is declared by the variant interfaces
 * ({@link EffectfulContainerProps} / {@link ExternalContainerProps} /
 * {@link RemoteContainerProps}) that extend this base.
 */
export interface ContainerApplicationPropsBase extends PlatformProps {
  /**
   * Human-readable application name. If omitted, Alchemy derives a deterministic
   * physical name from the stack, stage, and logical ID.
   */
  name?: string;
  /**
   * Name of the exported Durable Object class this container backs when the
   * Container is bound on an **async** Worker's `env`. Defaults to the
   * binding name (the `env` key). Ignored by the Effect-native path, where
   * the class name comes from the hosting Durable Object.
   */
  className?: string;
  /**
   * Initial number of instances to maintain. Matches wrangler, which forces
   * this to 0 whenever {@link maxInstances} is set (pure scale-from-zero).
   * @default 0
   */
  instances?: number;
  /**
   * Maximum number of instances the application may scale to. Matches
   * wrangler's default of 20. A value of 1 serializes every Durable Object
   * instance through a single container slot, so the default lets containers
   * scale concurrently out of the box.
   * @default 20
   */
  maxInstances?: number;
  /**
   * Scheduling policy used by Cloudflare's containers control plane.
   * @default "default"
   */
  schedulingPolicy?: "default" | "regional";
  /**
   * Instance type for each deployment. Defaults to wrangler's `"lite"` tier
   * (1/16 vCPU, 256 MiB, 2 GB disk) when no explicit {@link vcpu}/{@link memory}/
   * {@link memoryMib}/{@link disk} is set. (`"dev"` is wrangler's deprecated
   * alias for `"lite"`.)
   * @default "lite"
   */
  instanceType?: ContainerApplication.InstanceType;
  /**
   * Observability settings for the deployment.
   */
  observability?: ContainerApplication.Observability;
  /**
   * SSH public keys to install into the deployment.
   */
  sshPublicKeyIds?: string[];
  /**
   * Secrets exposed to the container runtime as environment variables.
   */
  secrets?: ContainerApplication.Secret[];
  /**
   * CPU allocation override for each deployment.
   */
  vcpu?: number;
  /**
   * Memory allocation override for each deployment.
   */
  memory?: string;
  /**
   * Memory allocation override for each deployment, in MiB.
   * Custom sizing requires at least 1 {@link vcpu} and 3072 MiB of memory
   * per vCPU for the first 4 vCPUs.
   */
  memoryMib?: number;
  /**
   * Disk allocation override for each deployment.
   */
  disk?: ContainerApplication.Disk;
  /**
   * Plain environment variables passed to the container runtime.
   */
  environmentVariables?: ContainerApplication.EnvironmentVariable[];
  /**
   * Labels attached to the deployment.
   */
  labels?: ContainerApplication.Label[];
  /**
   * Network configuration for the deployment: IPv4/IPv6 address assignment
   * (`"none"` or `"predefined"`) and `mode` (`"private"` or `"public"`).
   * `assignIpv4: "predefined"` implies `mode: "public"`, so private-only
   * accounts set both families to `"none"`.
   */
  network?: ContainerApplication.Network;
  /**
   * Command override for the container image.
   */
  command?: string[];
  /**
   * Entrypoint override for the container image.
   */
  entrypoint?: string[];
  /**
   * DNS configuration for the deployment.
   */
  dns?: ContainerApplication.Dns;
  /**
   * Exposed ports for the deployment.
   */
  ports?: ContainerApplication.Port[];
  /**
   * Health and readiness checks for the deployment.
   */
  checks?: ContainerApplication.Check[];
  /**
   * Resource constraints for the application.
   */
  constraints?: ContainerApplication.Constraints;
  /**
   * Affinity hints for scheduling.
   */
  affinities?: ContainerApplication.Affinities;
  /**
   * Progressive rollout settings applied after updates.
   */
  rollout?: ContainerApplication.Rollout;
  /**
   * Container registry host to use for generated Dockerfile builds.
   * @default "registry.cloudflare.com"
   */
  registryId?: string;
  /**
   * Image publication configuration. Builds are cached by default in a
   * repository named after the application's physical name. Generated names
   * include the stage and resource instance, so updates within that stage can
   * reuse images. Replacement or destroy/recreate can select a new repository.
   * Set `repository` to share finished images and build layers across stages.
   *
   * @example
   * ```typescript
   * // Default: cached in this application's generated repository.
   * const app = yield* Cloudflare.Container("Web", { context: "./web" }).Application;
   * // Repository: registry.cloudflare.com/<account-id>/<app.applicationName>
   * ```
   */
  publish?: {
    /**
     * Destination repository name within the current Cloudflare account's
     * container registry, for example `"web"`. This is not a source image,
     * registry hostname, account ID, tag, or fully qualified image reference.
     * Alchemy lowercases the name and adds the registry host and account ID:
     * `registry.cloudflare.com/<account-id>/web` with the default `registryId`.
     * The container application's name is independent of this repository name.
     * Omitting `publish` uses the application's physical name instead and still
     * enables caching. Generated names are scoped to the stage and resource
     * instance; an explicit repository allows cross-stage reuse.
     *
     * For Dockerfile and Effect-native builds, Alchemy publishes a content-hash
     * tag and an inline layer-cache tag, then deploys an immutable manifest
     * digest. The build hash and manifest digest are different identifiers.
     * Builds targeting this repository import reusable layers from its shared
     * `:buildcache` tag, even when their full input hashes differ. The tag points
     * to the latest exported inline cache, not an aggregate of all historical
     * images. A finished-image cache hit leaves this layer-cache tag unchanged.
     *
     * Applications and stages in the same account can share `"web"`. Matching
     * build inputs reuse the published image; changed inputs produce another
     * hash tag in the same repository. Finished-image cache reuse applies to
     * builds, not to re-publishing remote images. Pin base images and downloaded
     * dependencies: changes outside the build context cannot invalidate its
     * content hash.
     *
     * External remote images are re-published into this repository without
     * building them. Images already in the target registry keep their existing
     * repository; setting this option does not copy them into another one.
     *
     * @example
     * ```typescript
     * const app = yield* Cloudflare.Container("WebProduction", {
     *   context: "./web",
     *   publish: { repository: "web" },
     * }).Application;
     *
     * // Published build:
     * // registry.cloudflare.com/<account-id>/web:<build-hash>
     * // Shared build-layer cache:
     * // registry.cloudflare.com/<account-id>/web:buildcache
     * // Deployed image (app.configuration.image):
     * // registry.cloudflare.com/<account-id>/web@sha256:<manifest-digest>
     * ```
     */
    repository: string;
  };
  /**
   * Environment variables passed to the container runtime.
   */
  env?: Record<string, any>;
  /**
   * Exports passed to the container runtime.
   */
  exports?: string[];
}

/**
 * Bundle an Effect-native program into a generated image. Alchemy bundles
 * {@link main} and bakes it in as the container's entrypoint. The
 * environment the program runs in comes from {@link image} or an inline
 * {@link dockerfile} (exclusive with each other), defaulting to the
 * runtime's base image.
 */
export interface EffectfulContainerProps extends ContainerApplicationPropsBase {
  /** Entrypoint file for the Effect program, typically `import.meta.url`. */
  main: string;
  /**
   * Environment image for the generated Dockerfile — a plain registry
   * reference, e.g. `"oven/bun:latest"`. Alchemy synthesizes the `FROM` line
   * and appends the statements that copy the bundled program and set the
   * entrypoint. The image must be able to run the {@link runtime}.
   * Exclusive with {@link dockerfile}.
   *
   * @default `oven/bun:1` for `runtime: "bun"`, `node:22-slim` for `runtime: "node"`
   */
  image?: string;
  /**
   * Inline environment Dockerfile content (typically `Dockerfile.inline`).
   * Replaces the generated `FROM` line — carry your own `FROM` plus any
   * extra build steps (system packages, config); the bundled program is
   * layered on top. Exclusive with {@link image}. Never interpolate secrets
   * into inline content — it is baked into image layers.
   */
  dockerfile?: InlineDockerfile;
  /**
   * Exported handler symbol inside the bundled module.
   * @default "default"
   */
  handler?: string;
  /**
   * Runtime environment for the container program.
   *
   * @default "bun"
   */
  runtime?: "bun" | "node";
  /**
   * Module specifiers that Rolldown should mark as external when bundling
   * the container entrypoint. The matching packages are installed inside the
   * image via the runtime's package manager (`bun add` for `runtime: "bun"`,
   * `npm install` for `runtime: "node"`) before the entrypoint runs.
   *
   * Use this for native dependencies that must not be bundled (e.g. `sharp`,
   * `impit`) or for packages that intentionally ship in the base image.
   *
   * Install inside the image is controlled by {@link autoInstallExternals}
   * (default `true`); set it to `false` if your environment ({@link image}
   * or inline {@link dockerfile}) already ships these packages and you want
   * to avoid the redundant step.
   */
  external?: string[];
  /**
   * Whether to auto-install the packages listed in {@link external} inside
   * the container image (via `bun add` or `npm install`) before running the
   * entrypoint.
   *
   * @default true
   *
   * Set to `false` when your environment image already ships these packages
   * (for example, a base image that pre-installs `sharp`), to avoid the
   * redundant install step.
   */
  autoInstallExternals?: boolean;
  /**
   * Bundler configuration for {@link main}. Unused code is tree-shaken.
   * `effect`, alchemy, and `@distilled.cloud` are marked pure so unused
   * parts prune more aggressively. List extra packages with
   * `pure.packages`, or disable with `pure: false`.
   */
  build?: Bundle.BundleConfig;
}

/**
 * Build the container image from your own Dockerfile — no Effect program is
 * bundled. The image is shipped as-is.
 */
export interface ExternalContainerProps
  extends ContainerApplicationPropsBase, DockerfileBuildOptions {
  /**
   * The build context directory containing the Dockerfile and any files it
   * copies. Only valid with a `dockerfile` PATH (not inline content).
   *
   * @default `./`
   */
  context?: string;
  /**
   * The Dockerfile to build. A string is a **path** resolved relative to
   * {@link context} (default `<context>/Dockerfile`); an
   * {@link InlineDockerfile} (typically `Dockerfile.inline`) is the whole
   * Dockerfile's content, built in an empty generated context (exclusive
   * with {@link context}).
   */
  dockerfile?: string | InlineDockerfile;
}

/**
 * Deploy a pre-built remote image — Alchemy pulls it and re-pushes it to
 * Cloudflare's managed registry without building anything.
 */
export interface RemoteContainerProps extends ContainerApplicationPropsBase {
  /**
   * The pre-built image to pull and re-push.
   *
   * E.g. `ghcr.io/alpine/alpine:latest`
   *
   * Alchemy pulls the image as `linux/amd64` on every deploy and every
   * `alchemy dev` start, so a mutable tag picks up a newly pushed image.
   * An image that exists only in the local Docker (built on this machine
   * or `docker load`ed) is used as-is when the pull fails; build it with
   * `--platform linux/amd64`, the platform Cloudflare runs.
   *
   * When the reference already points at the target registry (the
   * {@link ContainerApplicationPropsBase.registryId | registryId} host,
   * `registry.cloudflare.com` by default) — e.g. a digest reference pushed
   * by CI like `registry.cloudflare.com/<accountId>/app@sha256:...` — it is
   * deployed as-is and the docker pull/push round-trip is skipped entirely.
   */
  image: string;
}

/** SSH access to a container application's instances. */
export interface ContainerSshConfiguration {
  /** Whether instances accept SSH connections. */
  enabled: boolean;
  /** Port the SSH server listens on inside each instance. */
  port?: number;
}

/**
 * Application-wide settings of a Durable Object class's container application.
 * Every Container bound to the class may declare them; declarations must agree.
 */
export interface DurableObjectApplicationSettings {
  /**
   * SSH access to every instance of the application. Removing a previously
   * declared value disables SSH.
   */
  ssh?: ContainerSshConfiguration;
  /** SSH public keys allowed to access instances. Removing this property clears previously managed keys. */
  authorizedKeys?: Containers.UserSSHPublicKeyList;
  /** Application-wide logging. Removing a previously declared value disables logs. Changes do not restart running containers. */
  observability?: Containers.ContainerApplicationObservability;
}

/**
 * One image a Durable Object starts with `ctx.container.start()`.
 *
 * Cloudflare allows one container application per Durable Object class. Every
 * `durable_object` Container bound to the class adds its image to that
 * application, under the Container's id. Bind several Containers to start
 * different images from the same class, one at a time. One Container may be
 * bound to several classes.
 *
 * An Effect-native Durable Object binds a Container with `yield*`. An async
 * Worker attaches it to a class with
 * `Cloudflare.DurableObject(className, { containers })`.
 *
 * The policy is immutable: migrating an existing fleet application requires a
 * new application and Durable Object namespace.
 */
export interface DurableObjectContainerProps
  extends DurableObjectApplicationSettings, PlatformProps, DockerfileBuildOptions {
  /** Select images and instance sizes in `ctx.container.start()`. */
  schedulingPolicy: "durable_object";
  /**
   * Registry image to copy into Cloudflare's managed registry, e.g.
   * `"node:24-slim"`. Exclusive with {@link context} and {@link dockerfile}.
   * Omit every image source to contribute no image: `start()` then uses the
   * managed `cloudflare/debian-trixie` image unless given another.
   *
   * Alchemy pulls the image as `linux/amd64` on every deploy and every
   * `alchemy dev` start, so a mutable tag picks up a newly pushed image.
   * An image that exists only in the local Docker (built on this machine
   * or `docker load`ed) is used as-is when the pull fails; build it with
   * `--platform linux/amd64`, the platform Cloudflare runs.
   */
  image?: string;
  /**
   * Docker build context. Setting `context` or `dockerfile` builds the image;
   * `context` defaults to the current directory.
   */
  context?: string;
  /** Dockerfile path or inline content. Defaults to the context's Dockerfile. */
  dockerfile?: string | InlineDockerfile;
  /** Image publication and build-cache configuration. */
  publish?: ContainerApplicationPropsBase["publish"];
  /**
   * Maximum wait for Cloudflare to prepare the published image, including API calls.
   * Accepts an Effect duration such as "45 minutes". Must be finite and positive.
   * Cancellation stops waiting; another deployment reuses the published registry image.
   * Use an immutable source digest or change the image reference to refresh the image.
   * @default "30 minutes"
   */
  imagePreparationTimeout?: Duration.Input;
}

/**
 * Fleet-scheduled applications select a deployment image through `main`
 * (bundled Effect program), `context`/`dockerfile`, or a pre-built `image`.
 * A Durable Object-managed Container publishes one image that its Durable
 * Object selects at runtime.
 */
export type ContainerApplicationProps =
  | EffectfulContainerProps
  | ExternalContainerProps
  | RemoteContainerProps
  | DurableObjectContainerProps;

/**
 * INTERNAL — the loose provider-side view across the variants: every
 * variant-specific field optional at its widest type. Each union member is
 * assignable to this shape, so provider/bundle code annotates helper params
 * with it instead of narrowing the union at every property access.
 */
export interface AnyContainerApplicationProps extends Omit<
  ContainerApplicationPropsBase,
  "schedulingPolicy"
> {
  schedulingPolicy?: ContainerApplication.SchedulingPolicy;
  ssh?: ContainerSshConfiguration;
  authorizedKeys?: Containers.UserSSHPublicKeyList;
  imagePreparationTimeout?: Duration.Input;
  main?: string;
  image?: string;
  context?: string;
  dockerfile?: string | InlineDockerfile;
  handler?: string;
  runtime?: "bun" | "node";
  external?: string[];
  autoInstallExternals?: boolean;
  /** Bundler config for `main`; Docker build args and secrets for `context`. */
  build?: Bundle.BundleConfig & DockerfileBuild;
}

export type ContainerServices = ContainerApplication | PlatformServices | ProcessServices;

export type ContainerShape = Main<ContainerServices>;

/**
 * A Cloudflare Container Application — the deployed, scalable unit that runs a
 * containerized program on Cloudflare's compute platform. Alchemy bundles the
 * `main` entrypoint, builds a Docker image, pushes it to the Cloudflare
 * registry, and reconciles the application's scaling and runtime configuration.
 *
 * This is the lower-level resource backing the {@link Container} platform
 * binding; in application code you typically extend `Cloudflare.Container` to
 * define and bind a container to a Durable Object rather than referencing this
 * resource directly. The same props shape (`main`, `instanceType`, `instances`,
 * etc.) is accepted by the `Cloudflare.Container(...)` class form shown below.
 *
 * @internal
 * ### Defining a Container Application
 * Point `main` at the container's entrypoint file; Alchemy bundles it and uses
 * it as the image's entrypoint. The application name is derived deterministically
 * from the stack, stage, and logical ID unless you set an explicit `name`, and
 * `handler` selects which export to run when it isn't the default.
 *
 * **Example:** Minimal container
 * ```typescript
 * import * as Cloudflare from "@alchemy.run/cloudflare";
 *
 * export class Sandbox extends Cloudflare.Container<Sandbox>()("Sandbox", {
 *   main: import.meta.url,
 * }) {}
 * ```
 *
 * The single `main` prop is enough to ship a container: Alchemy bundles the
 * entrypoint, builds and pushes the image, and provisions an application with
 * one instance. Reach for the other props only when you need to scale, expose
 * ports, or customize the build.
 *
 * **Example:** Named container with a non-default handler export
 * ```typescript
 * export class Worker extends Cloudflare.Container<Worker>()("Worker", {
 *   main: import.meta.url,
 *   handler: "runWorker",
 *   name: "background-worker",
 * }) {}
 * ```
 *
 * `name` pins a stable application name (instead of the generated one), which is
 * useful for adopting an existing application, while `handler` runs the named
 * `runWorker` export rather than the module's default.
 *
 * ### Image Sources
 * The image is resolved from exactly one of three props, checked in order:
 * `main` (bundle an Effect program into a generated image), then `image`
 * (pull and re-push a remote image), then `context` / `dockerfile` (build
 * your own Dockerfile). Only `main` injects an Effect runtime; the other two
 * ship an arbitrary image unchanged.
 *
 * **Example:** Build your own Dockerfile (`context` / `dockerfile`)
 * ```typescript
 * export class Web extends Cloudflare.Container<Web>()("Web", {
 *   context: `${import.meta.dirname}/context`,
 *   dockerfile: "Dockerfile",
 * }) {}
 * ```
 *
 * Alchemy builds `dockerfile` against the `context` directory with no `main`
 * bundling. `dockerfile` is resolved relative to `context` and defaults to
 * `<context>/Dockerfile`.
 *
 * **Example:** Remote image (`image`)
 * ```typescript
 * export class Echo extends Cloudflare.Container<Echo>()("Echo", {
 *   image: "mendhak/http-https-echo:latest",
 * }) {}
 * ```
 *
 * Alchemy pulls the pre-built public image and re-pushes it to Cloudflare's
 * managed registry instead of building anything.
 *
 * ### Bundling & Dependencies
 * By default the entrypoint is bundled for the `bun` runtime. Use `runtime` to
 * switch to Node, `external` to keep native/precompiled packages out of the
 * bundle (auto-installed in the image unless `autoInstallExternals` is `false`),
 * `image` (or an inline `dockerfile`) to pick the environment the generated
 * Dockerfile starts `FROM`, and `registryId` to override the registry host.
 *
 * **Example:** Node runtime with external native deps
 * ```typescript
 * export class ImageApi extends Cloudflare.Container<ImageApi>()("ImageApi", {
 *   main: import.meta.url,
 *   runtime: "node",
 *   external: ["sharp"],
 *   autoInstallExternals: true,
 * }) {}
 * ```
 *
 * Marking `sharp` as `external` stops Rolldown from bundling the native module;
 * because `autoInstallExternals` is `true`, Alchemy runs `npm install sharp`
 * inside the image so the dependency is present at runtime.
 *
 * **Example:** Custom environment image and registry
 * ```typescript
 * export class Custom extends Cloudflare.Container<Custom>()("Custom", {
 *   main: import.meta.url,
 *   image: "oven/bun:1",
 *   autoInstallExternals: false,
 *   registryId: "registry.cloudflare.com",
 * }) {}
 * ```
 *
 * Alchemy generates the Dockerfile — `FROM` your `image`, then the
 * program-copy and entrypoint steps — so you control the starting image;
 * `autoInstallExternals: false` skips the redundant install step when the
 * environment already ships your `external` packages.
 *
 * **Example:** Inline environment Dockerfile (extra build steps)
 * ```typescript
 * import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
 *
 * export class Transcoder extends Cloudflare.Container<Transcoder>()(
 *   "Transcoder",
 *   {
 *     main: import.meta.url,
 *     dockerfile: Dockerfile.inline`
 *       FROM oven/bun:1
 *       RUN apt-get update && apt-get install -y ffmpeg
 *     `,
 *   },
 * ) {}
 * ```
 *
 * Inline `dockerfile` content replaces the generated `FROM` line, so the
 * environment can run extra build steps (system packages, config) while the
 * bundled program is still layered on top.
 *
 * ### Bundling & Tree-shaking
 * `main` is bundled with rolldown at deploy time. Unused code is
 * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
 * pure so unused parts prune more aggressively. Your app is not
 * marked pure.
 *
 * **Example:** Mark additional packages as pure
 * Only list packages with no top-level side effects.
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: {
 *     pure: { packages: ["my-lib", "@my-scope/*"] },
 *   },
 * }
 * ```
 *
 * **Example:** Turn it off
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: { pure: false },
 * }
 * ```
 *
 * ### Scaling & Instance Types
 * Control the desired and maximum instance counts with `instances`/`maxInstances`
 * and pick a compute size with `instanceType`. For finer control, override
 * `vcpu`, `memory`, and `disk` directly.
 *
 * **Example:** Autoscaling with a larger instance type
 * ```typescript
 * export class Sandbox extends Cloudflare.Container<Sandbox>()("Sandbox", {
 *   main: import.meta.url,
 *   instanceType: "standard-1",
 *   instances: 1,
 *   maxInstances: 5,
 * }) {}
 * ```
 *
 * The application keeps one instance running and may scale out to five under
 * load, each on the `standard-1` size. Use a larger `instanceType` (or the
 * explicit overrides below) when the default `dev` size is too small.
 *
 * **Example:** Explicit CPU, memory, and disk overrides
 * ```typescript
 * export class Heavy extends Cloudflare.Container<Heavy>()("Heavy", {
 *   main: import.meta.url,
 *   vcpu: 2,
 *   memory: "4GB",
 *   disk: { size: "10GB" },
 * }) {}
 * ```
 *
 * These props override the per-instance resource allocation independently of
 * `instanceType`, which is handy when a workload needs, say, extra disk for
 * scratch space without bumping every other dimension.
 *
 * ### Runtime Configuration
 * Inject configuration with `environmentVariables` (plain values) and `secrets`
 * (references to stored secrets), and override the image's `command` or
 * `entrypoint`. `labels` attach metadata to the deployment.
 *
 * **Example:** Environment variables, secrets, and a command override
 * ```typescript
 * export class Api extends Cloudflare.Container<Api>()("Api", {
 *   main: import.meta.url,
 *   environmentVariables: [{ name: "LOG_LEVEL", value: "info" }],
 *   secrets: [{ name: "API_KEY", type: "env", secret: "my-stored-secret" }],
 *   command: ["bun", "run", "start"],
 *   labels: [{ name: "team", value: "payments" }],
 * }) {}
 * ```
 *
 * `environmentVariables` are visible plain values, while `secrets` map a stored
 * secret into the runtime as an env var without exposing it in config; `command`
 * overrides the container's startup command and `labels` tag the deployment for
 * organization.
 *
 * **Example:** Passing env and selecting runtime exports
 * ```typescript
 * export class Job extends Cloudflare.Container<Job>()("Job", {
 *   main: import.meta.url,
 *   env: { REGION: "wnam", FEATURE_FLAG: "on" },
 *   exports: ["default"],
 * }) {}
 * ```
 *
 * `env` injects values into the bundled program's runtime context (as opposed to
 * the deployment-level `environmentVariables`), and `exports` declares which
 * symbols from the entrypoint module the runtime should wire up.
 *
 * ### Networking & Health Checks
 * Configure outbound/inbound networking with `network` and `dns`, expose
 * `ports`, and gate readiness with `checks`.
 *
 * **Example:** Ports, network mode, DNS, and a health check
 * ```typescript
 * export class Web extends Cloudflare.Container<Web>()("Web", {
 *   main: import.meta.url,
 *   ports: [{ name: "http", port: 8080 }],
 *   network: { assignIpv4: "none", assignIpv6: "none", mode: "private" },
 *   dns: { servers: ["1.1.1.1"], searches: ["internal"] },
 *   checks: [{ name: "ready", type: "http", port: "8080", tls: false }],
 * }) {}
 * ```
 *
 * `ports` publishes the named port the program listens on, `network` controls IP
 * assignment and public/private reachability, `dns` overrides resolver settings,
 * and `checks` tells Cloudflare how to probe the container before routing
 * traffic to it.
 *
 * The example is the private shape, which every account accepts.
 * `assignIpv4: "predefined"` requests public reachability: Cloudflare infers
 * `mode: "public"` when `mode` is omitted, rejects it on accounts that only
 * permit private networking, and refuses it alongside `mode: "private"`.
 *
 * ### Observability & Access
 * Turn on log shipping with `observability` and install `sshPublicKeyIds` for
 * interactive access to running instances.
 *
 * **Example:** Enable logs and grant SSH access
 * ```typescript
 * export class Api extends Cloudflare.Container<Api>()("Api", {
 *   main: import.meta.url,
 *   observability: { logs: { enabled: true } },
 *   sshPublicKeyIds: ["ssh-key-id-123"],
 * }) {}
 * ```
 *
 * `observability.logs.enabled` streams the container's logs into Cloudflare's
 * telemetry pipeline (queryable via the resource's `logs`/`tail` operations),
 * and `sshPublicKeyIds` authorizes the listed keys to connect to instances for
 * debugging.
 *
 * ### Scheduling & Placement
 * Influence where and how Cloudflare schedules instances with `schedulingPolicy`,
 * `constraints`, and `affinities`.
 *
 * **Example:** Pin scheduling policy and placement
 * ```typescript
 * export class Edge extends Cloudflare.Container<Edge>()("Edge", {
 *   main: import.meta.url,
 *   schedulingPolicy: "regional",
 *   constraints: { tier: 1 },
 *   affinities: { colocation: "datacenter" },
 * }) {}
 * ```
 *
 * `schedulingPolicy` selects the control-plane placement strategy,
 * `constraints.tier` restricts which capacity tier instances may land on, and
 * `affinities.colocation` keeps related instances in the same datacenter to
 * reduce inter-instance latency.
 *
 * **Example:** Keep instances inside the EU for data residency
 * ```typescript
 * export class Verifier extends Cloudflare.Container<Verifier>()("Verifier", {
 *   main: import.meta.url,
 *   constraints: { jurisdiction: "eu" },
 * }) {}
 * ```
 *
 * `constraints.jurisdiction` restricts instances to a compliance boundary
 * (`"eu"` is `EEUR` and `WEUR`), and `constraints.regions` narrows placement to
 * specific regions within it.
 *
 * ### Rollouts
 * When an update changes the configuration, `rollout` controls how the new
 * version is rolled out across instances.
 *
 * **Example:** Progressive rollout on update
 * ```typescript
 * export class Api extends Cloudflare.Container<Api>()("Api", {
 *   main: import.meta.url,
 *   instances: 4,
 *   maxInstances: 4,
 *   rollout: { strategy: "rolling", stepPercentage: 25 },
 * }) {}
 * ```
 *
 * A `rolling` strategy with `stepPercentage: 25` replaces instances in 25%
 * increments so the application stays available during the update; the default
 * `immediate` strategy swaps everything at once. Steps advance automatically
 * as new instances become healthy; each replaced instance receives `SIGTERM`
 * and has 15 minutes to shut down cleanly before `SIGKILL`.
 *
 * Rollouts replace instances — they do not split requests between two image
 * versions (request-level traffic splitting exists one layer up, on the
 * Worker, via `version.traffic`). The fronting Worker and Durable Object cut
 * over immediately while instances roll, so keep the Worker-to-container
 * protocol compatible across both image versions until a rollout completes.
 *
 * @resource
 * @product Containers
 * @category Workers & Compute
 */
export interface ContainerApplication<Shape = unknown> extends Resource<
  ContainerTypeId,
  ContainerApplicationProps,
  {
    /**
     * Cloudflare-assigned unique identifier of the container application.
     * Empty for a Durable Object-managed Container: the application belongs
     * to the Durable Object class that binds it.
     */
    applicationId: string;
    /**
     * The resolved application name (either the provided `name` or the
     * deterministic physical name derived from the stack, stage, and logical ID).
     * For a Durable Object-managed Container, the name of its default image
     * repository.
     */
    applicationName: string;
    /**
     * The Cloudflare account ID that owns the application.
     */
    accountId: string;
    /**
     * The scheduling policy in effect for the application's deployments.
     */
    schedulingPolicy: ContainerApplication.SchedulingPolicy;
    /**
     * The current desired number of instances. Unset for Durable Object-managed applications.
     */
    instances: number | undefined;
    /**
     * The maximum number of instances the application may scale to.
     * Unset for Durable Object-managed applications.
     */
    maxInstances: number | undefined;
    /**
     * Resource constraints applied to the application, if any.
     */
    constraints: ContainerApplication.Constraints | undefined;
    /**
     * Scheduling affinity hints applied to the application, if any.
     */
    affinities: ContainerApplication.Affinities | undefined;
    /**
     * The resolved deployment configuration (image, networking, secrets, ports,
     * checks, etc.) currently applied to the application.
     * Durable Object-managed applications configure each instance at start().
     */
    configuration: Partial<ContainerApplication.Configuration> &
      Containers.DurableObjectContainerConfiguration;
    /** Application-wide logging declared by a Durable Object-managed Container. */
    observability?: Containers.ContainerApplicationObservability;
    /**
     * The prepared, digest-pinned image of a Durable Object-managed Container,
     * or its local image key in `alchemy dev`. Unset when the Container
     * declares no image source.
     */
    image?: string;
    /**
     * The Durable Object namespace attached to the application, if it is bound
     * to one.
     */
    durableObjects:
      | {
          namespaceId: string;
        }
      | undefined;
    /**
     * ISO-8601 timestamp of when the application was created.
     */
    createdAt: string;
    /**
     * The application's configuration version, incremented on each update.
     * Unset for Durable Object-managed applications.
     */
    version: number | undefined;
    /**
     * Internal hashes of the built image and desired application
     * configuration, used to skip unchanged builds and updates.
     */
    hash?: {
      image: string;
      digest?: string;
      configuration?: string;
    };
    dev: DevContainerImage | undefined;
  },
  {
    /**
     * Durable Object namespace attached to the container application.
     */
    durableObjects?: {
      namespaceId: string;
    };
    /**
     * Environment variables injected into the container runtime via the binding.
     */
    env?: Record<string, any>;
  },
  Providers
> {
  /** @internal phantom */
  Shape: Shape;
}

// `DevContainerImage` stays here (consumed by the Attrs `dev` field above and
// imported by Worker.ts). The provider helpers that previously lived here
// (resolveDurableObjectApplicationRecovery, the readiness schedule/retry, etc.)
// were extracted to ContainerProvider.ts on this branch.
export type DevContainerImage =
  | DevContainerImage.Build
  | DevContainerImage.Pull
  | DevContainerImage.Ref;

export declare namespace DevContainerImage {
  interface Base {
    readonly env?: Record<string, string | Redacted.Redacted<string>>;
  }
  export interface Build extends Base {
    readonly dockerfile: string;
    readonly context?: string;
    readonly buildArgs?: Record<string, string>;
    readonly buildSecrets?: Record<string, string | Redacted.Redacted<string>>;
  }
  export interface Pull extends Base {
    readonly imageUri: string;
  }
  export interface Ref extends Base {
    readonly tag: string;
  }
}

export const ContainerProvider = () =>
  // `{ Type }` instead of `ContainerPlatform` — importing the platform here
  // would create a module cycle (ContainerPlatform.ts imports this file).
  ProviderLayer.dual(
    { Type: ContainerTypeId },
    {
      live: () => LiveContainerProvider(),
      local: () => LocalContainerProvider(),
    },
  );