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

import * as Containers from "@distilled.cloud/cloudflare/containers";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import * as Namespace from "alchemy/Namespace";
import * as Provider from "alchemy/Provider";
import { Resource, type ResourceBinding } from "alchemy/Resource";
import { normalizeNulls } from "alchemy/Util/stable";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
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({
      // Cloudflare also refuses creates for a moment ("can't create
      // application at this time"); the same request succeeds when retried.
      while: (error) =>
        error._tag === "DurableObjectNamespaceNotFound" ||
        error._tag === "ContainerApplicationCreateUnavailable",
      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) {
        // An existing Worker gaining this class publishes its old output
        // first, which has no namespace for it yet. The application stays a
        // placeholder until the Worker's upload binds the namespace, when
        // the run reconciles it again; if that never comes, the next
        // deploy's diff plans the create.
        if (!isLiveApplication(output?.applicationId)) {
          return placeholder({
            applicationId: "",
            applicationName: name,
            accountId,
            className,
            createdAt: "",
          });
        }
        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.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.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(),
  });