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

import type * as cf from "@cloudflare/workers-types";
import type { InputProps } from "alchemy/Input";
import type { Named } from "alchemy/Named";
import type { ResourceClass, ResourceClassLike } from "alchemy/Resource";
import type { Rpc } from "alchemy/Rpc";
import { effectClass } from "alchemy/Util/effect";
import * as Config from "effect/Config";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import type { Providers } from "../Providers.ts";
import { type WorkerShape } from "../Workers/Worker.ts";
import type { ContainerApplication } from "./ContainerApplication.ts";
import {
  makeContainerHandle,
  type ContainerClient,
  type ReservedContainerKey,
} from "./ContainerClient.ts";
import { ContainerPlatform } from "./ContainerPlatform.ts";

export const ContainerTypeId = "Cloudflare.Container";
export type ContainerTypeId = typeof ContainerTypeId;

export const isContainer = <T>(value: T): value is T & Container =>
  typeof value === "object" && value !== null && "Type" in value && value.Type === ContainerTypeId;

export class ContainerError extends Data.TaggedError("ContainerError")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * No container instance could be allocated within the start budget — the
 * account is at its concurrent-instance cap (`maxInstances`) or the platform
 * is still provisioning. Mirrors `@cloudflare/containers`'
 * `NO_CONTAINER_INSTANCE_ERROR` (surfaced as HTTP 503 by native).
 */
export class NoContainerInstanceError extends Data.TaggedError("NoContainerInstanceError")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * Cloudflare is rate limiting container starts ("too many containers per
 * second"). Mirrors `@cloudflare/containers`' `RATE_LIMITED_ERROR` (HTTP 429).
 * Hammering `start()` while rate limited only prolongs it, so callers should
 * back off rather than retry tightly.
 */
export class ContainerRateLimitedError extends Data.TaggedError("ContainerRateLimitedError")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * The container instance exited/crashed while we were waiting for its port —
 * the entrypoint failed to bind or died. Mirrors native's "container exited"
 * detection (`!this.container.running` mid-wait); not curable by continuing to
 * poll the same instance.
 */
export class ContainerCrashedError extends Data.TaggedError("ContainerCrashedError")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * The container is not running. Ports and RPC methods never start it; call
 * `start()` first.
 */
export class ContainerNotRunningError extends Data.TaggedError("ContainerNotRunningError")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

// Upstream changed ContainerStartupOptions to an intersection with an
// image/containerSnapshot union, which an interface cannot extend.
export type ContainerStartupOptions = cf.ContainerStartupOptions;

import type {
  DurableObjectContainerProps,
  EffectfulContainerProps,
  ExternalContainerProps,
  RemoteContainerProps,
} from "./ContainerApplication.ts";

export type {
  DurableObjectContainerProps,
  EffectfulContainerProps,
  ExternalContainerProps,
  RemoteContainerProps,
};

/**
 * Props for an image-backed container declaration — either the plain props
 * object, or an Effect that produces it.
 *
 * The Effect form is how a container reaches another resource's outputs. A
 * class body is module scope, so there is nowhere to `yield*` a database,
 * queue, or bucket; wrapping the props in `Effect.gen` moves the declaration
 * into an Effect where sibling resources resolve normally and their
 * attributes can be threaded into `env`:
 *
 * ```typescript
 * export class Api extends Cloudflare.Container<Api>()(
 *   "Api",
 *   Effect.gen(function* () {
 *     const { connection } = yield* Db;
 *     return {
 *       context: `${import.meta.dirname}/api`,
 *       env: { DATABASE_URL: connection.databaseUrl },
 *     };
 *   }),
 * ) {}
 * ```
 *
 * A plain props object cannot do this: a module-scope resource declaration
 * is an Effect, not a resolved handle, so `Db.connectionString` is
 * `undefined` until something yields it.
 */
export type ImageContainerProps<Req = never> =
  | InputProps<ExternalContainerProps>
  | InputProps<RemoteContainerProps>
  | InputProps<DurableObjectContainerProps>
  | Effect.Effect<
      | InputProps<ExternalContainerProps>
      | InputProps<RemoteContainerProps>
      | InputProps<DurableObjectContainerProps>,
      Config.ConfigError,
      Req
    >;

/**
 * The handle `yield* MyContainer` returns inside a Durable Object. See
 * {@link ContainerClient}.
 */
export type Container<Id extends string = string> = Named<Id> & ContainerClient;

/** An RPC shape may not redeclare the container handle's own methods. */
type ContainerShape<Shape> = {
  [K in keyof Shape]: K extends ReservedContainerKey ? never : Shape[K];
};

/**
 * A Cloudflare Container that runs a long-lived process alongside a
 * Durable Object.
 *
 * Containers always use the **Container Layer** pattern — the class
 * and `.make()` must live in separate files. A Container must be
 * bound to a Durable Object, and the DO imports the class to get a
 * typed handle. If the class and `.make()` lived in the same file,
 * the DO's bundle would pull in all of the container's runtime
 * dependencies (process spawners, Node APIs, SDKs, etc.), which
 * would bloat the bundle and likely break the Cloudflare Workers
 * runtime. Keeping them separate ensures the bundler only includes
 * the tiny class in the DO's output.
 *
 * See the [Runtime concept](/infrastructure-as-effects/runtime)
 * page for how this fits into the async / effect / layer
 * progression.
 * ### Container Layer
 * Define the class and `.make()` in separate files. The class
 * declares the container's identity, configuration, and typed
 * shape. `.make()` provides the runtime implementation as a
 * default export. Use `Container.of` to construct the typed
 * shape — it ensures your implementation matches the methods
 * declared on the class.
 *
 * **Example:** Container class
 * ```typescript
 * // src/Sandbox.ts — the tag carries only the name + typed shape;
 * // configuration lives on `.make()`.
 * export class Sandbox extends Cloudflare.Container<
 *   Sandbox,
 *   {
 *     shell: (cmd: string) => Effect.Effect<{
 *       exitCode: number;
 *       stdout: string;
 *       stderr: string;
 *     }>;
 *   }
 * >()("Sandbox") {}
 * ```
 *
 * **Example:** Container .make()
 * ```typescript
 * // src/Sandbox.runtime.ts — props are the first argument to `.make()`
 * export default Sandbox.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const cp = yield* ChildProcessSpawner;
 *
 *     return Sandbox.of({
 *       shell: (command) =>
 *         cp.spawn(ChildProcess.make(command, { shell: true })).pipe(
 *           Effect.flatMap(({ exitCode, stdout, stderr }) =>
 *             Effect.all({
 *               exitCode,
 *               stdout: stdout.pipe(Stream.decodeText, Stream.mkString),
 *               stderr: stderr.pipe(Stream.decodeText, Stream.mkString),
 *             }),
 *           ),
 *           Effect.scoped,
 *         ),
 *       fetch: Effect.succeed(
 *         HttpServerResponse.text("Hello from container!"),
 *       ),
 *     });
 *   }),
 * );
 * ```
 *
 * ### Async Workers
 * An async Worker can host a container-backed Durable Object class that
 * ships as plain JavaScript — `@cloudflare/sandbox`'s `Sandbox`, or your
 * own class extending `@cloudflare/containers`' `Container`. The class
 * lives in the worker script; `Container` (the npm one) handles the
 * lifecycle and forwards `fetch` to the port inside the container.
 *
 * **Example:** The worker script exports the container-backed class
 * ```typescript
 * // src/worker.ts
 * import { Container } from "@cloudflare/containers";
 *
 * export class Sandbox extends Container {
 *   defaultPort = 8080;
 * }
 * ```
 *
 * Declare it in the stack by binding a `Cloudflare.Container` in the
 * Worker's `env` — the Container **is** the Durable Object binding and its
 * ContainerApplication together. Alchemy emits the
 * `durable_object_namespace` binding, marks the class as container-backed
 * in the script metadata, provisions the ContainerApplication, and attaches
 * it to the class's namespace. The Durable Object class name defaults to
 * the binding name (the `env` key); set `className` when the exported class
 * is named differently.
 *
 * **Example:** Binding the container-backed class in the stack
 * ```typescript
 * // alchemy.run.ts
 * import type { Sandbox } from "./src/worker.ts";
 *
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     Sandbox: Cloudflare.Container<Sandbox>("Sandbox", {
 *       image: "docker.io/cloudflare/sandbox:0.1.3",
 *     }),
 *   },
 * });
 * ```
 *
 * The type parameter (`Container<Sandbox>`) is the class from `worker.ts` —
 * it types `env.Sandbox` as `DurableObjectNamespace<Sandbox>` via
 * `Cloudflare.InferEnv`, so the handler reaches the container with full
 * types.
 *
 * **Example:** Reaching the container from the async handler
 * ```typescript
 * // src/worker.ts
 * import { getContainer } from "@cloudflare/containers";
 * import type * as Cloudflare from "@alchemy.run/cloudflare";
 * import type { Worker } from "../alchemy.run.ts";
 *
 * export default {
 *   async fetch(request: Request, env: Cloudflare.InferEnv<typeof Worker>) {
 *     return getContainer(env.Sandbox, "default").fetch(request);
 *   },
 * };
 * ```
 *
 * ### Native Durable Object Containers
 * Use `schedulingPolicy: "durable_object"` to let a Durable Object pick its
 * image and instance size at runtime. One Container is one image: `image`
 * copies a registry image, `context`/`dockerfile` builds one. Alchemy pins the
 * image to a digest and prepares it before the Worker is uploaded.
 *
 * `yield* Node` returns the container's handle without starting it.
 * `start()` starts the Container's own image. Its `exec` takes an argument
 * vector and returns a scoped process with streams, an exit code, and an
 * `output()` collector.
 *
 * **Example:** Execute a command in a Container's image
 * ```typescript
 * export class Node extends Cloudflare.Container<Node>()("Node", {
 *   schedulingPolicy: "durable_object",
 *   image: "node:24-slim",
 * }) {}
 *
 * export class Agent extends Cloudflare.DurableObject<Agent>()(
 *   "Agent",
 *   Effect.gen(function* () {
 *     const node = yield* Node;
 *     return Effect.succeed({
 *       exec: (args: string[]) =>
 *         Effect.gen(function* () {
 *           // Starts the Node image; a no-op when the container is running.
 *           yield* node.start({
 *             instance: "lite",
 *             entrypoint: ["sleep", "infinity"],
 *             enableInternet: false,
 *           });
 *           const process = yield* node.exec(args);
 *           const result = yield* process.output();
 *           return { text: new TextDecoder().decode(result.stdout), exitCode: result.exitCode };
 *         }).pipe(Effect.scoped),
 *     });
 *   }),
 * ) {}
 * ```
 *
 * ### Several Images in One Durable Object
 * Cloudflare gives each Durable Object class one container application and
 * each object one container instance. Bind several Containers to choose
 * between their images. Every binding adds its image to the class's
 * application under the Container's id. Each handle's `start()` starts its
 * own image; start one at a time and `destroy()` before switching.
 *
 * **Example:** A Durable Object with Node and Python images
 * ```typescript
 * export class Node extends Cloudflare.Container<Node>()("Node", {
 *   schedulingPolicy: "durable_object",
 *   image: "node:24-slim",
 * }) {}
 *
 * export class Python extends Cloudflare.Container<Python>()("Python", {
 *   schedulingPolicy: "durable_object",
 *   context: "./python",
 * }) {}
 *
 * export class Agent extends Cloudflare.DurableObject<Agent>()(
 *   "Agent",
 *   Effect.gen(function* () {
 *     const node = yield* Node;
 *     const python = yield* Python;
 *     const run = (cmd: string[]) =>
 *       Effect.scoped(Effect.flatMap(node.exec(cmd), (process) => process.output()));
 *     return Effect.succeed({
 *       node: (cmd: string[]) =>
 *         node
 *           .start({ entrypoint: ["sleep", "infinity"], enableInternet: false })
 *           .pipe(Effect.andThen(run(cmd))),
 *       python: (cmd: string[]) =>
 *         Effect.gen(function* () {
 *           // Every handle controls the same instance: switch images explicitly.
 *           if (yield* node.running) yield* node.destroy();
 *           yield* python.start({ entrypoint: ["sleep", "infinity"], enableInternet: false });
 *           return yield* Effect.scoped(
 *             Effect.flatMap(python.exec(cmd), (process) => process.output()),
 *           );
 *         }),
 *     });
 *   }),
 * ) {}
 * ```
 *
 * Application-wide settings (`ssh`, `authorizedKeys`, `observability`) may be
 * declared on any of the class's Containers. Two Containers declaring
 * different values fail the deploy with `ContainerApplicationSettingsConflict`.
 *
 * **Example:** Save and restore the writable filesystem
 * ```typescript
 * const snapshot = yield* node.snapshotContainer({ name: "workspace" });
 * // Persist this handle in Durable Object storage before stopping the instance.
 * yield* state.storage.put("snapshot", snapshot);
 * yield* node.destroy();
 * yield* node.start({
 *   containerSnapshot: snapshot,
 *   entrypoint: ["sleep", "infinity"],
 *   enableInternet: false,
 * });
 * ```
 *
 * Snapshots capture the writable root filesystem, not memory, processes, or
 * mounted filesystems. Restoring starts a new entrypoint process. Snapshot
 * handles expire after 30 days without a restore. `exec` does not start a
 * stopped container or invoke a shell; pass `['sh', '-c', command]` explicitly
 * when needed. Scope closure kills an unfinished exec process, but does not
 * signal its descendants. Use an Effect timeout to bound a command's lifetime.
 *
 * ### Native Durable Objects on Async Workers
 * A plain Durable Object class on an async Worker attaches its Containers
 * through its Durable Object binding:
 * `Cloudflare.DurableObject(className, { containers })`. Each Container adds
 * its image to the class's application, and the class reads it from
 * `ctx.container.images` under the Container's id. A Container may be listed
 * by several classes; each class gets its own copy of the image key.
 *
 * **Example:** Two classes sharing the Node image
 * ```typescript
 * // alchemy.run.ts
 * const Node = Cloudflare.Container("Node", {
 *   schedulingPolicy: "durable_object",
 *   image: "node:24-slim",
 * });
 * const Python = Cloudflare.Container("Python", {
 *   schedulingPolicy: "durable_object",
 *   image: "python:3.13-slim",
 * });
 * const Rust = Cloudflare.Container("Rust", {
 *   schedulingPolicy: "durable_object",
 *   image: "rust:1.90-slim",
 * });
 * export const Worker = Cloudflare.Worker("App", {
 *   main: "./src/worker.ts",
 *   env: {
 *     AGENT: Cloudflare.DurableObject("Agent", { containers: [Node, Python] }),
 *     REVIEWER: Cloudflare.DurableObject("Reviewer", { containers: [Node, Rust] }),
 *   },
 * });
 * ```
 *
 * A Durable Object-managed Container placed directly in `env` fails with
 * `DurableObjectContainerBindingError`; only fleet Containers bind that way.
 *
 * **Example:** Starting an image from the class
 * ```typescript
 * // src/worker.ts
 * import { DurableObject } from "cloudflare:workers";
 *
 * export class Agent extends DurableObject {
 *   async run(cmd: string[]) {
 *     const container = this.ctx.container!;
 *     if (!container.running) {
 *       container.start({
 *         image: container.images.Node,
 *         entrypoint: ["sleep", "infinity"],
 *         enableInternet: false,
 *       });
 *     }
 *     return (await container.exec(cmd)).output();
 *   }
 * }
 * ```
 *
 * Local development runs every image through workerd and Docker.
 *
 * Switching an existing application to this scheduling policy requires a new
 * application and a new Durable Object class/namespace. Alchemy rejects an
 * in-place policy change; existing Durable Object storage is not transferred.
 * Replacing only a wrapper with the native API while retaining the original
 * policy and class preserves the namespace. Deployment properties such as
 * `maxInstances`, `instanceType`, `env`, and `rollout` are not valid with the
 * new policy; pass per-instance settings to `start()`.
 *
 * ### Image Sources
 * A container's image comes from one of three sources, picked by which
 * prop you set:
 *
 * - `main` — bundle your Effect program into a generated image.
 * - `context` (+ optional `dockerfile`) — build your own Dockerfile.
 * - `image` — pull a pre-built image and re-push it.
 *
 * Only the `main` source bundles and injects an Effect runtime — so it
 * has a typed shape and a `.make(props, impl)` runtime. The other two
 * ship an arbitrary image as-is: they have no runtime to provide, so
 * you declare the class with its props inline and bind it with
 * `yield* MyContainer` from the hosting Durable Object.
 *
 * **Example:** Effect-native image (`main`)
 * ```typescript
 * // Alchemy bundles this file's Effect program and bakes it into a
 * // generated image as the entrypoint.
 * export class Sandbox extends Cloudflare.Container<
 *   Sandbox,
 *   { ping: () => Effect.Effect<string> }
 * >()("Sandbox") {}
 *
 * export default Sandbox.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     return Sandbox.of({
 *       ping: () => Effect.succeed("pong"),
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     });
 *   }),
 * );
 * ```
 *
 * **Example:** Build your own Dockerfile (`context` / `dockerfile`)
 * ```typescript
 * // Alchemy builds the Dockerfile against the context directory — no
 * // Effect bundling, no `.make()`. `dockerfile` defaults to
 * // `<context>/Dockerfile`. The props are declared inline on the tag.
 * export class Web extends Cloudflare.Container<Web>()("Web", {
 *   context: `${import.meta.dirname}/context`,
 * }) {}
 * ```
 *
 * **Example:** Build args and secrets
 * ```typescript
 * // Dockerfile:
 * //   ARG NODE_ENV
 * //   RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
 * export class Api extends Cloudflare.Container<Api>()("Api", {
 *   context: `${import.meta.dirname}/api`,
 *   build: {
 *     args: { NODE_ENV: "production" },
 *     // Resolved at deploy time; mounted only into the `RUN` step that asks
 *     // for it, never written to a layer or the build history.
 *     secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
 *   },
 * }) {}
 * ```
 *
 * `build.args` are part of the image hash, so changing one rebuilds the
 * image. `build.secrets` are not: rotating a token reuses the published image.
 *
 * Builds are cached by default at
 * `registry.cloudflare.com/<account-id>/<application-physical-name>`.
 * The generated physical name includes the stage and resource instance, so
 * subsequent updates in that stage can reuse matching images. Replacement or
 * destroy/recreate can change the name and start a new cache. This does not
 * automatically share one repository across every container in the stage.
 * The same defaults apply to inline Dockerfiles and Effect-native `main` builds.
 *
 * **Example:** Reuse builds across stages
 * ```typescript
 * export class Web extends Cloudflare.Container<Web>()("Web", {
 *   context: `${import.meta.dirname}/context`,
 *   publish: { repository: "web" },
 * }) {}
 * ```
 *
 * `repository: "web"` names the destination repository, not a source image or
 * the container application. With the default registry host, Alchemy lowercases
 * the name and expands it to `registry.cloudflare.com/<account-id>/web`.
 * Supply only the repository name, without a registry host, account ID, tag,
 * or digest. A build produces these references:
 *
 * ```text
 * Published build:  registry.cloudflare.com/<account-id>/web:<build-hash>
 * Build cache:      registry.cloudflare.com/<account-id>/web:buildcache
 * Deployed image:   registry.cloudflare.com/<account-id>/web@sha256:<manifest-digest>
 * ```
 *
 * The build hash identifies the inputs; the manifest digest identifies the
 * published artifact. Applications and stages in the same account can use
 * `publish: { repository: "web" }` to reuse matching published builds. Changed
 * inputs produce another hash tag in the same repository. Builds targeting
 * that repository import reusable layers from its shared `:buildcache` tag,
 * including when full input hashes differ. This mutable tag points to the
 * latest exported inline cache, not a combined cache of every historical
 * image. Reusing a finished image does not move the layer-cache tag.
 *
 * Pin base images and downloaded dependencies: changes outside the build
 * context cannot invalidate the input hash. Each stage still has its own
 * Container application, runtime settings, and instances; only images and
 * build layers are shared.
 *
 * **Example:** Publish an existing image into a named repository
 * ```typescript
 * export class Proxy extends Cloudflare.Container<Proxy>()("Proxy", {
 *   image: "nginx:alpine",
 *   publish: { repository: "web-proxy" },
 * }) {}
 * // Re-publishes nginx into registry.cloudflare.com/<account-id>/web-proxy
 * // and deploys registry.cloudflare.com/<account-id>/web-proxy@sha256:<manifest-digest>.
 * ```
 *
 * Remote images are re-published without building them. An image already in
 * the target registry keeps its existing repository; `publish.repository`
 * does not copy it into another one.
 *
 * **Example:** Remote image (`image`)
 * ```typescript
 * // Alchemy pulls the public image and re-pushes it to Cloudflare's
 * // registry — no build, no bundling, no `.make()`.
 * export class Echo extends Cloudflare.Container<Echo>()("Echo", {
 *   image: "mendhak/http-https-echo:latest",
 * }) {}
 * ```
 *
 * Alchemy pulls an `image` as `linux/amd64` on every deploy and every
 * `alchemy dev` start, so a mutable tag like `:latest` picks up a newly
 * pushed image. A private registry needs a `docker login` first.
 *
 * **Example:** Image built on this machine
 * ```typescript
 * // docker build --platform linux/amd64 -t local-only/app:dev .
 * export class App extends Cloudflare.Container<App>()("App", {
 *   image: "local-only/app:dev",
 * }) {}
 * ```
 *
 * An image only in the local Docker, built on this machine or loaded with
 * `docker load`, has no registry to pull from. When the pull fails and the
 * image is present locally, Alchemy uses the local copy, in `alchemy dev`
 * and on deploy. Build it with `--platform linux/amd64`, the platform
 * Cloudflare runs: deploy fails on an image built only for another
 * platform. When the image can be neither pulled nor found locally,
 * Alchemy fails with the image name and the commands that fix it. The
 * image name alone is the identity, so rebuilding under the same tag does
 * not redeploy; give each build its own tag.
 *
 * **Example:** Reaching an arbitrary image's port from a Durable Object
 * ```typescript
 * // `external` and `remote` images expose no RPC methods, so the DO
 * // talks to them purely over their TCP port via `getTcpPort`.
 * export class WebObject extends Cloudflare.DurableObject<WebObject>()(
 *   "WebObject",
 *   Effect.gen(function* () {
 *     const web = yield* Web;
 *     return Effect.gen(function* () {
 *       const { fetch } = yield* web.getTcpPort(8080);
 *       return {
 *         hello: () =>
 *           Effect.gen(function* () {
 *             yield* web.start();
 *             const res = yield* fetch(HttpClientRequest.get("http://container/"));
 *             return yield* res.text;
 *           }),
 *       };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * ### 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 },
 * }
 * ```
 *
 * ### Configuration
 * The props object — the first argument to `.make()` — accepts `main`
 * (entrypoint file), `instanceType` (compute size), `runtime`
 * (`"bun"` or `"node"`), and `observability` settings. Use
 * `Stack.useSync` to read the surrounding stack and pick a beefier
 * `instanceType` in prod while keeping the cheap `dev` instance for
 * preview environments.
 *
 * **Example:** Stage-dependent configuration
 * ```typescript
 * export const SandboxLive = Sandbox.make(
 *   Stack.useSync((stack) => ({
 *     main: import.meta.url,
 *     instanceType: stack.stage === "prod" ? "standard-1" : "dev",
 *     observability: { logs: { enabled: true } },
 *   })),
 *   Effect.gen(function* () {
 *     return Sandbox.of({ shell: (cmd) => ... });
 *   }),
 * );
 * ```
 *
 * ### Environment Variables
 * A container is a process, not a Worker: it has no bindings, so every
 * piece of configuration reaches it through `env`. Each entry lands on
 * the deployment and shows up in `process.env` inside the image —
 * generated (`main`), built (`context`), or pre-built (`image`) alike.
 * Wrap a secret in `Redacted` to keep it encrypted in state and out of
 * plan output; the container still reads a plain string.
 *
 * **Example:** Plain and secret env values
 * ```typescript
 * export class Api extends Cloudflare.Container<Api>()("Api", {
 *   context: `${import.meta.dirname}/api`,
 *   ports: [{ name: "http", port: 8080 }],
 *   env: {
 *     PORT: "8080",
 *     SESSION_KEY: Redacted.make(process.env.SESSION_KEY!),
 *   },
 * }) {}
 * ```
 *
 * ### Props from Other Resources
 * A class body is module scope, so there is nowhere to `yield*` the
 * database, queue, or bucket whose output you need — and a bare
 * declaration is an Effect, not a resolved handle, so
 * `Uploads.bucketName` reads as `undefined`. Pass the props as an
 * `Effect.gen` instead: inside it sibling resources resolve normally,
 * and the reference orders the deploy.
 *
 * **Example:** Threading a sibling resource's output into `env`
 * ```typescript
 * export const Uploads = Cloudflare.R2.Bucket("Uploads");
 *
 * export class Api extends Cloudflare.Container<Api>()(
 *   "Api",
 *   Effect.gen(function* () {
 *     const uploads = yield* Uploads;
 *     return {
 *       context: `${import.meta.dirname}/api`,
 *       env: { BUCKET_NAME: uploads.bucketName },
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Database Connections
 * An effectful (`main`) container runs your Effect program, so it
 * resolves a database capability the same way a Worker does — you never
 * name `DATABASE_URL`. The container has no bindings (it is a process,
 * not a Worker), so `Prisma.Connect` writes the connection's outputs
 * onto the deployment as environment variables and reads them back at
 * runtime; the capability owns both ends.
 *
 * **Example:** Binding a Prisma connection inside the container runtime
 * ```typescript
 * export default Api.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const db = yield* Prisma.Connect(Connection);
 *     const sql = yield* SQL.Postgres({ url: db.databaseUrl });
 *
 *     return Api.of({
 *       fetch: Effect.gen(function* () {
 *         const users = yield* sql`SELECT * FROM users`;
 *         return yield* HttpServerResponse.json(users);
 *       }),
 *     });
 *   }).pipe(Effect.provide(Prisma.ConnectBinding)),
 * );
 * ```
 *
 * An image you brought yourself knows nothing about alchemy, so there is
 * no capability to bind — name the variable and hand it the provider's
 * **pooled** connection string.
 *
 * **Example:** Passing a pooled database URL to an arbitrary image
 * ```typescript
 * export class Web extends Cloudflare.Container<Web>()(
 *   "Web",
 *   Effect.gen(function* () {
 *     const connection = yield* Connection;
 *     return {
 *       context: `${import.meta.dirname}/web`,
 *       env: { DATABASE_URL: connection.databaseUrl },
 *     };
 *   }),
 * ) {}
 * ```
 *
 * Either way, start it with `api.start({ enableInternet: true })` — without
 * outbound networking the container never reaches the database.
 * `Cloudflare.Hyperdrive.Connect` is the one that cannot work here: it
 * *is* a workerd binding, so no container process can resolve it.
 *
 * ### Stack-level wiring
 * The `.make()` `export default` is the side-effect that registers
 * the container's runtime. It must be reachable from your
 * `alchemy.run.ts` so the bundler emits the runtime entrypoint.
 * Provide it on the Stack's generator with `Effect.provide`.
 *
 * **Example:** Wiring SandboxLive into the Stack
 * ```typescript
 * // alchemy.run.ts
 * import SandboxLive from "./src/Sandbox.runtime.ts";
 *
 * export default Alchemy.Stack(
 *   "MyApp",
 *   { providers: Cloudflare.providers(), state: Cloudflare.state() },
 *   Effect.gen(function* () {
 *     const worker = yield* Worker;
 *     return { url: worker.url };
 *   }).pipe(Effect.provide(SandboxLive)),
 * );
 * ```
 *
 * ### Calling from a Durable Object
 * `yield* Sandbox` binds the container to the Durable Object and returns
 * its handle: every method declared on the container's shape, plus
 * `start`, `running`, `destroy`, `getTcpPort`, `exec` and the rest of the
 * native container API. Binding never starts the container. Because only
 * the class is imported, the runtime implementation in
 * `Sandbox.runtime.ts` is tree-shaken out of the DO's bundle.
 *
 * `start()` is idempotent: it starts the container unless it is already
 * running, and concurrent calls start it once. Call it at the top of each
 * operation. Its options apply only when that call actually starts the
 * container. RPC methods and ports wait until the container's port accepts
 * connections, but never start it: a stopped container fails with
 * `ContainerNotRunningError`.
 *
 * **Example:** Starting a container from a DO
 * ```typescript
 * export default class Agent extends Cloudflare.DurableObject<Agent>()(
 *   "Agents",
 *   Effect.gen(function* () {
 *     const sandbox = yield* Sandbox;
 *
 *     return Effect.gen(function* () {
 *       // An Effect is a lazy value: define "start" once, run it per call.
 *       const start = sandbox.start({ enableInternet: true });
 *       return {
 *         shell: (cmd: string) => start.pipe(Effect.andThen(sandbox.shell(cmd))),
 *       };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * A container's shape cannot declare a method the handle already has
 * (`start`, `exec`, `image`, `getTcpPort`, …); declaring one is a type
 * error, because the handle's method would shadow the RPC call.
 *
 * ### Using a Container from a Layer
 * A Layer can `yield*` a container like any other service. It runs in the
 * Durable Object that hosts it, and starts the container when an operation
 * needs it. Layers never stop a shared container; let it sleep through
 * `setInactivityTimeout`, or stop it from the Durable Object that owns it.
 *
 * **Example:** A service backed by a container
 * ```typescript
 * export const WriteFileLive = Layer.effect(
 *   WriteFile,
 *   Effect.gen(function* () {
 *     const devBox = yield* DevBox;
 *     const start = devBox.start({ enableInternet: true });
 *
 *     return ({ path, contents }) =>
 *       start.pipe(Effect.andThen(devBox.writeFile(path, contents)));
 *   }),
 * );
 * ```
 *
 * ### HTTP Requests to Container Ports
 * Use `getTcpPort` to get a `fetch` handle for a port inside the
 * container. Each request waits until the port accepts connections, then
 * is sent once.
 *
 * **Example:** Fetching from a container port
 * ```typescript
 * export default class Agent extends Cloudflare.DurableObject<Agent>()(
 *   "Agents",
 *   Effect.gen(function* () {
 *     const sandbox = yield* Sandbox;
 *
 *     return Effect.gen(function* () {
 *       const { fetch } = yield* sandbox.getTcpPort(3000);
 *
 *       return {
 *         health: () =>
 *           Effect.gen(function* () {
 *             yield* sandbox.start({ enableInternet: true });
 *             const response = yield* fetch(
 *               HttpClientRequest.get("http://container/health"),
 *             );
 *             return yield* response.text;
 *           }),
 *       };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * @resource
 * @product Containers
 * @category Workers & Compute
 */
export const Container: ResourceClassLike<ContainerApplication> &
  Pick<ResourceClass<ContainerApplication>, "ref"> & {
    <DOShape = unknown, const Id extends string = string, PropsReq = never>(
      id: Id,
      props: ImageContainerProps<PropsReq>,
    ): Container.Decl<Container<Id>, {}, Id, PropsReq, DOShape>;
    <Self>(): {
      <const Id extends string, PropsReq = never>(
        id: Id,
        props: ImageContainerProps<PropsReq>,
      ): Container.Decl<Self, {}, Id, PropsReq>;
    };
    <Self, Shape extends ContainerShape<Shape>>(): {
      <const Id extends string>(
        id: Id,
      ): Container.Decl<Self, Shape, Id, Container.Application<Self>>;
    };
  } = Object.assign(
  (...args: any[]) => {
    if (args.length === 0) {
      return (...args: any[]) => {
        if (args.length === 1) {
          const [id] = args as [string];
          const tag = ContainerPlatform()(id);
          // `yield* MyContainer` binds the container to the hosting Durable
          // Object and returns its handle. It never starts the container.
          // NOTE: no `~alchemy/Container/ClassName` marker here — an
          // effectful (`main`) container is not bindable on an async
          // Worker's `env` (its application is created by the `.make()`
          // Layer inside an Effect-native Durable Object host), so it must
          // not be picked up by bindWorkerAsyncBindings' container branch.
          return Object.assign(effectClass(makeContainerHandle(id, ContainerPlatform.bind(tag))), {
            "~alchemy/Id": id,
            make: (props: any, impl: any) => tag.make(props, impl),
            // yield* MyContainer.Application to get the ContainerApplication Resource Outputs
            Application: tag,
            of: (shape: any) => shape,
          });
        } else {
          return Container(...(args as [string, any]));
        }
      };
    } else {
      const [id, props] = args as [string, any];
      const resource = ContainerPlatform(id, props);
      return Object.assign(effectClass(makeContainerHandle(id, ContainerPlatform.bind(resource))), {
        "~alchemy/Id": id,
        // The Durable Object class name this container backs when bound on
        // an async Worker's `env` (see bindWorkerAsyncBindings). Defaults to
        // the binding name at bind time when no explicit `className` is set.
        // Effect-valued props cannot be read synchronously here, so carry
        // the unresolved lookup and let `bindContainerClass` await it.
        "~alchemy/Container/ClassName": Effect.isEffect(props)
          ? Effect.map(
              // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props are untyped; Effect-valued props are resolved by the engine
              props as Effect.Effect<{ className?: string } | undefined>,
              (resolved) => resolved?.className,
            )
          : (props as { className?: string })?.className,
        // yield* MyContainer.Application to get the ContainerApplication Resource Outputs
        Application: resource,
        of: (shape: any) => shape,
      });
    }
  },
  {
    Type: ContainerTypeId,
    // Read `ContainerPlatform` lazily: this module and ContainerPlatform.ts
    // import each other, so it may not be initialized at module load.
    ref: (id: string, options?: { stage?: string; stack?: string }) =>
      (ContainerPlatform as unknown as Pick<ResourceClass<ContainerApplication>, "ref">).ref(
        id,
        options,
      ),
  },
) as any;

export declare namespace Container {
  export interface Decl<
    Self = any,
    Shape = any,
    Id extends string = string,
    Req = never,
    DOShape = unknown,
  >
    extends Effect.Effect<Self, never, Providers | Req>, Rpc<Shape>, Named<Id> {
    new (): Container<Id> & Shape;
    /**
     * @internal phantom — the Durable Object class type backing this
     * container when it is bound on an async Worker's `env`. Drives
     * `InferEnv` (`env.NAME` becomes `DurableObjectNamespace<DOShape>`).
     */
    readonly "~alchemy/Container/Shape": DOShape;
    /**
     * @internal — the explicit `className` from props (`undefined` defaults
     * to the binding name at bind time). Doubles as the runtime marker that
     * identifies an async-bindable Container declaration in a Worker's `env`
     * (see `bindWorkerAsyncBindings`).
     */
    readonly "~alchemy/Container/ClassName": string | undefined | Effect.Effect<string | undefined>;
    /**
     * The underlying {@link ContainerApplication} resource declaration —
     * `yield*` it to get the application's Output attributes.
     */
    Application: Effect.Effect<ContainerApplication<Self>, never, Providers | Req>;
    make: <InitReq = never, WorkerReq = never, PropsReq = never>(
      props:
        | InputProps<EffectfulContainerProps>
        | Effect.Effect<InputProps<EffectfulContainerProps>, Config.ConfigError, PropsReq>,
      impl: Effect.Effect<Shape & WorkerShape<WorkerReq>, Config.ConfigError, InitReq>,
    ) => Layer.Layer<Application<Self>, never, Providers>;
    of(shape: Shape & WorkerShape): Shape;
  }
  export namespace Decl {
    export type Any = Decl<any, any, string, any, any>;
  }

  export interface Application<Self> {
    "~alchemy/Kind": "ContainerApplication";
    "~alchemy/Self": Self;
  }

  export type Instance<Shape = any> = Container & Shape;
}