alchemy 2.0.0-beta.82 → 2.0.0-beta.83

package/src/Cloudflare/Containers/DurableObjectApplication.ts

@@ -0,0 +1,382 @@
+import * as Containers from "@distilled.cloud/cloudflare/containers";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { isResolved } from "../../Diff.ts";
+import * as ProviderLayer from "../../Local/ProviderLayer.ts";
+import * as Namespace from "../../Namespace.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource, type ResourceBinding } from "../../Resource.ts";
+import { normalizeNulls } from "../../Util/stable.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { localAccountId } from "../LocalAccount.ts";
+import { generateLocalId, isLiveId } from "../LocalRuntime.ts";
+import type { Providers } from "../Providers.ts";
+import type { DurableObjectApplicationSettings } from "./ContainerApplication.ts";
+import { createContainerApplicationName } from "./ContainerBundle.ts";
+import {
+  ContainerConfigurationError,
+  durableObjectSettingsPatch,
+  mergeApplicationSettings,
+} from "./ContainerConfiguration.ts";
+
+export const DurableObjectApplicationTypeId = "Cloudflare.Containers.DurableObjectApplication";
+
+export interface DurableObjectApplicationProps {
+  /** The Durable Object class whose namespace the application serves. */
+  className: string;
+}
+
+/** What each bound Container contributes to its class's application. */
+export interface DurableObjectApplicationBinding {
+  /** The Durable Object namespace the application is attached to. */
+  durableObjects?: { namespaceId: string };
+  /** The bound Container and the application-wide settings it declares. */
+  container?: { id: string; settings: DurableObjectApplicationSettings };
+}
+
+/**
+ * INTERNAL — the one container application of a Durable Object class.
+ *
+ * Cloudflare allows exactly one container application per Durable Object
+ * namespace. Every `schedulingPolicy: "durable_object"` Container bound to a
+ * class declares this resource under the same logical id, so the engine
+ * registers it once; each Container then binds its application-wide settings
+ * onto it. The images themselves are Worker upload metadata, merged by the
+ * Worker.
+ *
+ * @internal
+ */
+export interface DurableObjectApplication extends Resource<
+  typeof DurableObjectApplicationTypeId,
+  DurableObjectApplicationProps,
+  {
+    /** The application id, which equals the Durable Object namespace id. Empty before creation. */
+    applicationId: string;
+    /** The generated application name. */
+    applicationName: string;
+    /** The Cloudflare account that owns the application. */
+    accountId: string;
+    /** The Durable Object class the application serves. */
+    className: string;
+    /** The Durable Object namespace attached to the application. */
+    durableObjects: { namespaceId: string } | undefined;
+    /** ISO-8601 creation time. Empty before creation. */
+    createdAt: string;
+    /** Application-wide container configuration (SSH and authorized keys). */
+    configuration: Containers.DurableObjectContainerConfiguration;
+    /** Application-wide logging. */
+    observability: Containers.ContainerApplicationObservability | undefined;
+    /** The merged settings last applied, used to reset settings a Container stops declaring. */
+    settings: DurableObjectApplicationSettings;
+  },
+  DurableObjectApplicationBinding,
+  Providers
+> {}
+
+export const DurableObjectApplication = Resource<DurableObjectApplication>(
+  DurableObjectApplicationTypeId,
+);
+
+/**
+ * Declare the container application of `className`, hosted by `worker`. Every
+ * Container bound to the class calls this; the engine dedupes the declaration
+ * by its fully qualified id, so all of them share one resource.
+ */
+export const declareDurableObjectApplication = (worker: { LogicalId: string }, className: string) =>
+  Namespace.push(
+    worker.LogicalId,
+    DurableObjectApplication(`${className}-Containers`, { className }),
+  );
+
+/**
+ * Right after a Worker upload creates a Durable Object namespace, the
+ * containers API can report the namespace missing for a few seconds before it
+ * sees it. Retry creates that attach to it, bounded at ~30s.
+ */
+export const retryNamespacePropagation = <A, E extends { readonly _tag: string }, R>(
+  effect: Effect.Effect<A, E, R>,
+) =>
+  effect.pipe(
+    Effect.tapError((error) =>
+      error._tag === "DurableObjectNamespaceNotFound"
+        ? Effect.logDebug("Cloudflare Container create: namespace not visible yet, retrying")
+        : Effect.void,
+    ),
+    Effect.retry({
+      while: (error) => error._tag === "DurableObjectNamespaceNotFound",
+      schedule: Schedule.spaced("2 seconds"),
+      times: 15,
+    }),
+  );
+
+/** Whether an application id names a created, live application (not a placeholder). */
+const isLiveApplication = (id: string | undefined): id is string => !!id && isLiveId(id);
+
+type Bindings = ReadonlyArray<ResourceBinding<DurableObjectApplicationBinding>>;
+
+/** The one namespace every bound Container attaches the application to. */
+const boundNamespace = (className: string, bindings: Bindings) => {
+  // A stale Worker namespace map can resolve a binding without an id; it
+  // does not request removing the live attachment.
+  const ids = [
+    ...new Set(
+      bindings.flatMap((b) =>
+        b.data.durableObjects?.namespaceId ? [b.data.durableObjects.namespaceId] : [],
+      ),
+    ),
+  ];
+  if (ids.length > 1) {
+    return Effect.fail(
+      new ContainerConfigurationError({
+        message: `The container application of Durable Object class '${className}' is bound to ${ids.length} namespaces (${ids.join(", ")}). A class has one namespace.`,
+      }),
+    );
+  }
+  return Effect.succeed(ids[0] === undefined ? undefined : { namespaceId: ids[0] });
+};
+
+const boundSettings = (className: string, bindings: Bindings) =>
+  mergeApplicationSettings(
+    className,
+    bindings.flatMap((b) => (b.data.container ? [b.data.container] : [])),
+  );
+
+/**
+ * Check the bound settings for conflicts at plan time. The namespace id in
+ * the same bindings resolves only after the Worker uploads, so check the
+ * settings contributions on their own once they are resolved.
+ */
+const planSettings = (className: string, newBindings: unknown) => {
+  const contributions = (Array.isArray(newBindings) ? newBindings : []).flatMap(
+    (binding: { data?: DurableObjectApplicationBinding }) =>
+      binding?.data?.container ? [binding.data.container] : [],
+  );
+  return isResolved(contributions)
+    ? Effect.asVoid(mergeApplicationSettings(className, contributions))
+    : Effect.void;
+};
+
+const placeholder = (
+  identity: Pick<
+    DurableObjectApplication["Attributes"],
+    "applicationId" | "applicationName" | "accountId" | "className" | "createdAt"
+  > &
+    Partial<DurableObjectApplication["Attributes"]>,
+): DurableObjectApplication["Attributes"] => ({
+  durableObjects: undefined,
+  configuration: {},
+  observability: undefined,
+  settings: {},
+  ...identity,
+});
+
+const toAttributes = (
+  application: Containers.GetContainerApplicationResponse,
+  className: string,
+  settings: DurableObjectApplicationSettings,
+): DurableObjectApplication["Attributes"] => ({
+  applicationId: application.id,
+  applicationName: application.name,
+  accountId: application.accountId,
+  className,
+  durableObjects: normalizeNulls(application.durableObjects) as { namespaceId: string } | undefined,
+  createdAt: application.createdAt,
+  configuration: normalizeNulls(
+    application.configuration,
+  ) as Containers.DurableObjectContainerConfiguration,
+  observability: normalizeNulls(application.observability ?? undefined),
+  settings,
+});
+
+export const LiveDurableObjectApplicationProvider = () =>
+  Provider.succeed(DurableObjectApplication, {
+    stables: ["accountId", "className"],
+    diff: Effect.fn(function* ({ news, output, newBindings }) {
+      if (!isResolved(news)) return undefined;
+      // Conflicting settings fail the plan, before anything is published.
+      yield* planSettings(news.className, newBindings);
+      if (!isResolved(newBindings)) return undefined;
+      const namespace = yield* boundNamespace(news.className, newBindings);
+      const deployed = output?.durableObjects?.namespaceId;
+      if (deployed !== undefined && namespace !== undefined && deployed !== namespace.namespaceId) {
+        return yield* new ContainerConfigurationError({
+          message: `The container application of Durable Object class '${news.className}' cannot move to another Durable Object namespace.`,
+        });
+      }
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      if (
+        output !== undefined &&
+        isLiveApplication(output.applicationId) &&
+        output.accountId !== accountId
+      ) {
+        return yield* new ContainerConfigurationError({
+          message: `The container application of Durable Object class '${news.className}' cannot move to another account in place.`,
+        });
+      }
+      // Precreate only reserves a name; reconcile creates the application
+      // once the Worker has created its namespace.
+      if (!isLiveApplication(output?.applicationId)) {
+        return { action: "update", stables: ["accountId", "className"] } as const;
+      }
+      return undefined;
+    }),
+    precreate: Effect.fn(function* ({ id, news, bindings }) {
+      // A new application is never diffed; fail conflicting settings here,
+      // before the Worker is uploaded.
+      yield* planSettings(news.className, bindings);
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      // The application needs the Worker's namespace id, which does not exist
+      // yet. Reserve the name so the Worker's upload can reference it.
+      return placeholder({
+        applicationId: "",
+        applicationName: yield* createContainerApplicationName(id, undefined),
+        accountId,
+        className: news.className,
+        createdAt: "",
+      });
+    }),
+    reconcile: Effect.fn(function* ({ id, news, bindings, output, session }) {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      const className = news.className;
+      // Prefer the deployed name: regenerating would target a different
+      // application if the generator's output for this id ever drifts.
+      const name =
+        output?.applicationName || (yield* createContainerApplicationName(id, undefined));
+      const durableObjects =
+        (yield* boundNamespace(className, bindings)) ??
+        (output?.durableObjects?.namespaceId ? output.durableObjects : undefined);
+      if (!durableObjects) {
+        return yield* new ContainerConfigurationError({
+          message: `The container application of Durable Object class '${className}' requires a resolved Durable Object namespace. Reconcile its Worker first.`,
+        });
+      }
+      const settings = yield* boundSettings(className, bindings);
+
+      // The application's id is the id of the namespace it serves.
+      const applicationId = durableObjects.namespaceId;
+      const getApplication = Containers.getContainerApplication({ accountId, applicationId });
+      const assertServesNamespace = (application: Containers.GetContainerApplicationResponse) =>
+        application.schedulingPolicy === "durable_object" &&
+        application.durableObjects?.namespaceId === applicationId
+          ? Effect.void
+          : Effect.fail(
+              new ContainerConfigurationError({
+                message: `The container application '${application.name}' of Durable Object namespace '${applicationId}' is not Durable Object-managed. Declare a new Durable Object class for Durable Object-managed Containers.`,
+              }),
+            );
+
+      // 1. Observe. The namespace belongs to this stack's Worker, so an
+      //    application already attached to it is this class's application.
+      let application = yield* getApplication.pipe(
+        Effect.catchTag("ContainerApplicationNotFound", () => Effect.succeed(undefined)),
+      );
+
+      // 2. Ensure
+      if (!application) {
+        yield* session.note(`Creating container application ${name}...`);
+        application = yield* retryNamespacePropagation(
+          Containers.createDurableObjectContainerApplication({
+            accountId,
+            name,
+            schedulingPolicy: "durable_object",
+            durableObjects,
+            configuration: {
+              ...(settings.ssh !== undefined ? { wranglerSsh: settings.ssh } : {}),
+              ...(settings.authorizedKeys !== undefined
+                ? { authorizedKeys: settings.authorizedKeys }
+                : {}),
+            },
+            observability: settings.observability,
+          }),
+        ).pipe(Effect.catchTag("DurableObjectAlreadyHasApplication", () => getApplication));
+      }
+      yield* assertServesNamespace(application);
+
+      // 3. Sync declared settings and reset settings no Container declares anymore.
+      const patch = durableObjectSettingsPatch(settings, output?.settings, application);
+      if (patch.configuration !== undefined || patch.observability !== undefined) {
+        application = yield* Containers.updateContainerApplication({
+          accountId,
+          applicationId,
+          ...patch,
+        });
+      }
+      return toAttributes(application, className, settings);
+    }),
+    delete: Effect.fn(function* ({ output }) {
+      if (!isLiveApplication(output.applicationId)) return;
+      yield* Containers.deleteContainerApplication({
+        accountId: output.accountId,
+        applicationId: output.applicationId,
+      }).pipe(Effect.catchTag("ContainerApplicationNotFound", () => Effect.void));
+    }),
+    read: Effect.fn(function* ({ id, olds, output }) {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      const className = olds?.className ?? output?.className ?? "";
+      if (output !== undefined && isLiveApplication(output.applicationId)) {
+        return yield* Containers.getContainerApplication({
+          accountId: output.accountId,
+          applicationId: output.applicationId,
+        }).pipe(
+          Effect.map((application) => toAttributes(application, className, output.settings)),
+          Effect.catchTag("ContainerApplicationNotFound", () => Effect.succeed(undefined)),
+        );
+      }
+      // Generated names identify this instance, so a match is ours.
+      const name =
+        output?.applicationName || (yield* createContainerApplicationName(id, undefined));
+      const found = yield* Containers.listContainerApplications({ accountId }).pipe(
+        Effect.map((apps) =>
+          apps.find((app) => app.name === name && app.schedulingPolicy === "durable_object"),
+        ),
+      );
+      return found === undefined
+        ? undefined
+        : toAttributes(found, className, output?.settings ?? {});
+    }),
+  });
+
+/**
+ * Local (dev) provider: `alchemy dev` runs every image through workerd and
+ * Docker, so the application is a placeholder carrying a `dev:` id.
+ */
+export const LocalDurableObjectApplicationProvider = () =>
+  Provider.succeed(DurableObjectApplication, {
+    stables: ["accountId", "className"],
+    diff: Effect.fn(function* ({ news, newBindings }) {
+      if (!isResolved(news)) return undefined;
+      yield* planSettings(news.className, newBindings);
+      return undefined;
+    }),
+    precreate: Effect.fn(function* ({ id, news, bindings }) {
+      yield* planSettings(news.className, bindings);
+      return placeholder({
+        applicationId: generateLocalId(),
+        applicationName: yield* createContainerApplicationName(id, undefined),
+        accountId: yield* localAccountId,
+        className: news.className,
+        createdAt: new Date().toISOString(),
+      });
+    }),
+    reconcile: Effect.fn(function* ({ id, news, bindings, output }) {
+      return placeholder({
+        applicationId: output?.applicationId || generateLocalId(),
+        applicationName: yield* createContainerApplicationName(id, undefined),
+        accountId: yield* localAccountId,
+        className: news.className,
+        createdAt: output?.createdAt || new Date().toISOString(),
+        durableObjects: yield* boundNamespace(news.className, bindings),
+        settings: yield* boundSettings(news.className, bindings),
+      });
+    }),
+    delete: () => Effect.void,
+    read: Effect.fn(function* ({ output }) {
+      return output;
+    }),
+  });
+
+export const DurableObjectApplicationProvider = () =>
+  ProviderLayer.dual(DurableObjectApplication, {
+    live: () => LiveDurableObjectApplicationProvider(),
+    local: () => LocalDurableObjectApplicationProvider(),
+  });

package/src/Cloudflare/Containers/LocalContainerProvider.ts

@@ -4,7 +4,7 @@ import * as Path from "effect/Path";
 import * as Redacted from "effect/Redacted";
 import * as Artifacts from "../../Artifacts.ts";
 import { hashDirectory } from "../../Command/Memo.ts";
-import { deepEqual, isResolved } from "../../Diff.ts";
+import { isResolved } from "../../Diff.ts";
 import { isInlineDockerfile } from "../../Docker/Dockerfile.ts";
 import * as RpcProvider from "../../Local/RpcProvider.ts";
 import type { ResourceBinding } from "../../Resource.ts";
@@ -16,7 +16,6 @@ import type {
   AnyContainerApplicationProps,
   ContainerApplication,
   DevContainerImage,
-  DurableObjectContainerProps,
 } from "./ContainerApplication.ts";
 import {
   createContainerApplicationName,
@@ -26,9 +25,9 @@ import {
   validateContainerImageProps,
 } from "./ContainerBundle.ts";
 import {
-  isDurableObjectContainer,
   durableObjectPlaceholder,
-  namedImageHash,
+  hasImageSource,
+  isDurableObjectContainer,
   validateContainerConfiguration,
 } from "./ContainerConfiguration.ts";
 import { ContainerPlatform } from "./ContainerPlatform.ts";
@@ -151,7 +150,6 @@ export const LocalContainerProvider = () =>
         const news = input as AnyContainerApplicationProps;
         const picked = {
           schedulingPolicy: news.schedulingPolicy,
-          images: news.images,
           main: news.main,
           image: news.image,
           dockerfile: news.dockerfile,
@@ -176,27 +174,6 @@ export const LocalContainerProvider = () =>
         return picked as AnyContainerApplicationProps;
       };
 
-      /**
-       * Prepare every named image of a Durable Object-managed container.
-       * Each image is cached under its own `${id}-${name}` artifact key.
-       */
-      const prepareNamedImages = Effect.fn(function* (
-        id: string,
-        props: DurableObjectContainerProps,
-      ) {
-        const devImages: Record<string, DevContainerImage> = {};
-        const hashes: Record<string, string> = {};
-        for (const [name, source] of Object.entries(props.images ?? {})) {
-          const image = yield* prepareImage(`${id}-${name}`, source);
-          devImages[name] = image.dev;
-          hashes[name] = image.hash;
-        }
-        return {
-          devImages,
-          hash: yield* namedImageHash(hashes),
-        };
-      });
-
       const placeholderConfiguration = (
         props: AnyContainerApplicationProps,
         env: Record<string, string | Redacted.Redacted<string>>,
@@ -238,19 +215,22 @@ export const LocalContainerProvider = () =>
         yield* validateContainerConfiguration(news, output?.schedulingPolicy);
         const accountId = yield* localAccountId;
         if (isDurableObjectContainer(news)) {
-          // workerd resolves each image by its declared name, so locally the
-          // runtime image reference is just the name.
-          const imageNames = Object.keys(news.images ?? {});
+          const attributes = durableObjectPlaceholder({
+            applicationId: output?.applicationId ?? generateLocalId(),
+            applicationName: yield* createContainerApplicationName(id, undefined),
+            accountId,
+            createdAt: output?.createdAt ?? new Date().toISOString(),
+            observability: news.observability,
+          });
+          if (!hasImageSource(news)) return attributes;
+          const { dev, hash } = yield* prepareImage(id, news);
           return {
-            ...durableObjectPlaceholder({
-              applicationId: output?.applicationId ?? generateLocalId(),
-              applicationName: yield* createContainerApplicationName(id, news.name),
-              accountId,
-              createdAt: output?.createdAt ?? new Date().toISOString(),
-              observability: news.observability,
-            }),
-            images: Object.fromEntries(imageNames.map((name) => [name, name])),
-            ...(yield* prepareNamedImages(id, news)),
+            ...attributes,
+            // workerd resolves each image by its key in the class's image
+            // map, so locally the image reference is the Container's id.
+            image: id,
+            dev,
+            hash: { image: hash },
           } satisfies ContainerApplication["Attributes"];
         }
         const env = makeContainerEnv(news, accountId, bindings);
@@ -290,16 +270,8 @@ export const LocalContainerProvider = () =>
           // disabled this check for every effectful container.
           const imageInputs = resolvedImageInputs(news);
           if (imageInputs !== undefined) {
-            if (isDurableObjectContainer(imageInputs)) {
-              const artifacts = yield* Artifacts.Artifacts;
-              for (const name of Object.keys(imageInputs.images ?? {})) {
-                yield* artifacts.delete(`container-image:${id}-${name}`);
-              }
-              const prepared = yield* prepareNamedImages(id, imageInputs);
-              const changed =
-                output.devImages === undefined ||
-                !deepEqual(prepared.hash.images, output.hash?.images);
-              return changed ? { action: "update" } : undefined;
+            if (isDurableObjectContainer(imageInputs) && !hasImageSource(imageInputs)) {
+              return output.image !== undefined ? { action: "update" } : undefined;
             }
             // Recompute fresh on every plan. `prepareImage` is memoized so
             // a plan's diff→precreate→reconcile chain bundles once — but

package/src/Cloudflare/Containers/index.ts

@@ -15,9 +15,19 @@ export type {
   ReservedContainerKey,
 } from "./ContainerClient.ts";
 export {
+  ContainerApplicationSettingsConflict,
   ContainerConfigurationError,
   ContainerImagePreparationError,
+  DurableObjectContainerBindingError,
+  DurableObjectContainerConflict,
+  DurableObjectContainersOnEffectNativeClass,
 } from "./ContainerConfiguration.ts";
 export { ContainerPlatform } from "./ContainerPlatform.ts";
 export * from "./ContainerProvider.ts";
+export {
+  DurableObjectApplication,
+  DurableObjectApplicationProvider,
+  type DurableObjectApplicationBinding,
+  type DurableObjectApplicationProps,
+} from "./DurableObjectApplication.ts";
 export * from "./LocalContainerProvider.ts";

package/src/Cloudflare/Providers.ts

@@ -196,6 +196,7 @@ export const providers = () =>
       Configuration.Configuration,
       Connectivity.DirectoryService,
       Containers.ContainerPlatform,
+      Containers.DurableObjectApplication,
       ContentScanning.ContentScanning,
       ContentScanning.Expression,
       CustomCertificates.CustomCertificate,
@@ -450,6 +451,7 @@ export const providers = () =>
         Configuration.ConfigurationProvider(),
         Connectivity.DirectoryServiceProvider(),
         Containers.ContainerProvider(),
+        Containers.DurableObjectApplicationProvider(),
         ContentScanning.ContentScanningProvider(),
         ContentScanning.ExpressionProvider(),
         CustomCertificates.CustomCertificateProvider(),

package/src/Cloudflare/Workers/DurableObject.ts

@@ -61,6 +61,8 @@ export interface DurableObjectLike<Shape = any> {
   scriptName?: Input<string>;
   /** @internal phantom */
   transferredFrom?: DurableObjectTransferSource | DurableObjectTransferSource[];
+  /** @internal Durable Object-managed Containers attached to the class. */
+  containers?: ReadonlyArray<Container.Decl.Any>;
   /** @internal phantom */
   Shape?: Shape;
 }
@@ -264,6 +266,30 @@ export interface DurableObjectProps {
   // namespaceId?: string | undefined;
 }
 
+/**
+ * Props of an async Worker's Durable Object binding,
+ * `Cloudflare.DurableObject(className, props)` in `env`.
+ */
+export interface DurableObjectBindingProps extends DurableObjectProps {
+  /**
+   * Durable Object-managed Containers (`schedulingPolicy: "durable_object"`)
+   * this class starts. Each adds its image to the class's container
+   * application under the Container's id, read at runtime from
+   * `ctx.container.images`. A Container may be listed by several classes.
+   *
+   * Only for a plain (async) Durable Object class the Worker hosts.
+   * Effect-native Durable Objects `yield*` their Containers instead; listing
+   * Containers for one fails with `DurableObjectContainersOnEffectNativeClass`.
+   *
+   * ```typescript
+   * env: {
+   *   AGENT: Cloudflare.DurableObject("Agent", { containers: [Node, Python] }),
+   * }
+   * ```
+   */
+  containers?: ReadonlyArray<Container.Decl.Any> | undefined;
+}
+
 export interface DurableObjectClass extends Effect.Effect<DurableObject, never, DurableObject> {
   <Self, Shape>(): {
     <Name extends string>(
@@ -310,7 +336,7 @@ export interface DurableObjectClass extends Effect.Effect<DurableObject, never,
       new (_: never): Shape;
     };
   };
-  <Shape>(name: string, props?: DurableObjectProps): DurableObjectLike<Shape>;
+  <Shape>(name: string, props?: DurableObjectBindingProps): DurableObjectLike<Shape>;
   <Shape, InitReq = never>(
     name: string,
     impl: Effect.Effect<Shape, never, DurableObjectServices | InitReq>,
@@ -1076,6 +1102,55 @@ export class DurableObjectScope extends Context.Service<DurableObjectScope, Dura
  * });
  * ```
  *
+ * ### Native Containers in an Async Worker
+ * A plain Durable Object class can start Durable Object-managed Containers
+ * (`schedulingPolicy: "durable_object"`). List them in its binding's
+ * `containers`: each adds its image to the class's container application,
+ * keyed by the Container's id in `ctx.container.images`. A Container may be
+ * shared by several classes.
+ *
+ * **Example:** Two classes, one shared image
+ * ```typescript
+ * 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] }),
+ *   },
+ * });
+ * ```
+ *
+ * **Example:** Starting a Container's image from the class
+ * ```typescript
+ * // src/worker.ts
+ * 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();
+ *   }
+ * }
+ * ```
+ *
  * ### Moving a Class Between Workers
  * A Durable Object class can move from one Worker to another with its
  * data intact. The move is always **declared** — a class that disappears
@@ -1357,6 +1432,7 @@ export const DurableObject: DurableObjectClass = taggedFunction(
         className: (args[1] as DurableObjectProps)?.className || namespace,
         scriptName: (args[1] as DurableObjectProps)?.scriptName,
         transferredFrom: (args[1] as DurableObjectProps)?.transferredFrom,
+        containers: (args[1] as DurableObjectBindingProps)?.containers,
       };
     } else if (Effect.isEffect(propsOrImpl)) {
       // inline Effect DO