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

import type * as Containers from "@distilled.cloud/cloudflare/containers";
import { deepEqual } from "alchemy/Diff";
import * as Output from "alchemy/Output";
import { normalizeNulls } from "alchemy/Util/stable";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type {
  AnyContainerApplicationProps,
  ContainerApplication,
  DevContainerImage,
  DurableObjectApplicationSettings,
  DurableObjectContainerProps,
} from "./ContainerApplication.ts";
import type { DurableObjectApplication } from "./DurableObjectApplication.ts";

export class ContainerConfigurationError extends Data.TaggedError("ContainerConfigurationError")<{
  readonly message: string;
}> {}

export class ContainerImagePreparationError extends Data.TaggedError(
  "ContainerImagePreparationError",
)<{
  readonly image: string;
  readonly status: "pending" | "error";
  readonly message: string;
}> {}

/**
 * Two Containers bound to the same Durable Object class declare different
 * values for one application-wide setting. The class has one container
 * application, so the declarations must agree (or only one may declare it).
 */
export class ContainerApplicationSettingsConflict extends Data.TaggedError(
  "ContainerApplicationSettingsConflict",
)<{
  readonly className: string;
  readonly setting: keyof DurableObjectApplicationSettings;
  readonly containers: ReadonlyArray<string>;
  readonly message: string;
}> {}

/**
 * The Containers bound to one Durable Object class cannot be merged into the
 * class's single container entry: two images share a key, the class mixes a
 * fleet Container with Durable Object-managed ones, or it exceeds Cloudflare's
 * image limit.
 */
export class DurableObjectContainerConflict extends Data.TaggedError(
  "DurableObjectContainerConflict",
)<{
  readonly className: string;
  readonly message: string;
}> {}

/**
 * A Durable Object-managed Container was bound on an async Worker outside a
 * Durable Object binding, or a Durable Object binding lists a Container it
 * cannot attach. Durable Object-managed Containers attach to a class through
 * `Cloudflare.DurableObject(className, { containers })`.
 */
export class DurableObjectContainerBindingError extends Data.TaggedError(
  "DurableObjectContainerBindingError",
)<{
  readonly bindingName: string;
  readonly message: string;
}> {}

/**
 * An async `Cloudflare.DurableObject(className, { containers })` binding
 * attaches Containers to a class the same Worker implements as an
 * Effect-native Durable Object. Effect-native classes `yield*` their
 * Containers instead.
 */
export class DurableObjectContainersOnEffectNativeClass extends Data.TaggedError(
  "DurableObjectContainersOnEffectNativeClass",
)<{
  readonly className: string;
  readonly message: string;
}> {}

/**
 * Fail when an async binding's `containers` target a class the Worker
 * implements as an Effect-native Durable Object.
 */
export const assertBindingContainersOnAsyncClasses = (
  rows: ReadonlyArray<{ readonly className: string; readonly attachedBy?: "binding" }>,
  effectNativeClasses: Iterable<string>,
) => {
  const effectNative = new Set(effectNativeClasses);
  const row = rows.find((row) => row.attachedBy === "binding" && effectNative.has(row.className));
  return row === undefined
    ? Effect.void
    : Effect.fail(
        new DurableObjectContainersOnEffectNativeClass({
          className: row.className,
          message: `Durable Object class '${row.className}' is an Effect-native Durable Object, so it cannot take containers from Cloudflare.DurableObject("${row.className}", { containers }). Bind each Container inside the Durable Object with \`yield*\` instead, and remove the containers prop.`,
        }),
      );
};

/** Cloudflare's limits for the `images` map of a Durable Object class. */
const MAX_NAMED_IMAGES = 100;
const MAX_IMAGE_NAME_LENGTH = 128;

/**
 * Fleet-scheduled settings that have no meaning when the Durable Object picks
 * the image and instance size at `start()` time.
 */
const FLEET_ONLY_PROPS = [
  "name",
  "className",
  "main",
  "instanceType",
  "instances",
  "maxInstances",
  "vcpu",
  "memory",
  "memoryMib",
  "disk",
  "env",
  "environmentVariables",
  "secrets",
  "labels",
  "network",
  "command",
  "entrypoint",
  "dns",
  "ports",
  "checks",
  "constraints",
  "affinities",
  "rollout",
  "registryId",
  "sshPublicKeyIds",
] as const satisfies ReadonlyArray<keyof AnyContainerApplicationProps>;

export const isDurableObjectContainer = (
  props: AnyContainerApplicationProps,
): props is DurableObjectContainerProps => props.schedulingPolicy === "durable_object";

const invalid = (message: string) => Effect.fail(new ContainerConfigurationError({ message }));

/** Validate a bounded preparation deadline before publishing any images. */
export const imagePreparationTimeoutMillis = (timeout: Duration.Input = "30 minutes") =>
  Effect.try({
    try: () => {
      const millis = Duration.toMillis(timeout);
      if (!Number.isFinite(millis) || millis <= 0) throw new Error("Invalid timeout");
      return millis;
    },
    catch: () =>
      new ContainerConfigurationError({
        message: "imagePreparationTimeout must be a finite, positive duration.",
      }),
  });

/**
 * Validate container props before publishing images or touching the hosting
 * Worker. Reject switches between fleet scheduling and Durable Object scheduling.
 */
export const validateContainerConfiguration = Effect.fn(function* (
  props: AnyContainerApplicationProps,
  deployedPolicy?: string,
) {
  const policy = props.schedulingPolicy ?? "default";
  if (
    deployedPolicy !== undefined &&
    (deployedPolicy === "durable_object") !== (policy === "durable_object")
  ) {
    return yield* invalid(
      "A container cannot switch between fleet and Durable Object scheduling in place. Declare a new container application and Durable Object class, then move traffic to the new namespace. Existing Durable Object storage is not transferred.",
    );
  }

  // `images` was removed: one Container is one image. Untyped or
  // Effect-produced props can still carry it.
  if ((props as { images?: unknown }).images !== undefined) {
    return yield* invalid(
      "Container property 'images' was removed. Declare one Cloudflare.Container per image with schedulingPolicy: 'durable_object' and bind each one to the Durable Object; the image key is the Container's id.",
    );
  }

  if (!isDurableObjectContainer(props)) return;

  yield* imagePreparationTimeoutMillis(props.imagePreparationTimeout);
  if (
    props.image !== undefined &&
    (props.context !== undefined || props.dockerfile !== undefined)
  ) {
    return yield* invalid(
      "A Durable Object-managed container declares one image source: `image`, or `context`/`dockerfile`.",
    );
  }

  // The union type already forbids these, but untyped or Effect-produced
  // props can still carry them.
  const loose: AnyContainerApplicationProps = props;
  const unsupported = FLEET_ONLY_PROPS.find((key) => loose[key] !== undefined);
  if (unsupported !== undefined) {
    return yield* invalid(
      `Container property '${unsupported}' is not supported with schedulingPolicy: 'durable_object'. The application is named and owned by the Durable Object class: attach the Container with Cloudflare.DurableObject(className, { containers }) on an async Worker, or yield it inside an Effect-native Durable Object. Pass per-instance settings to start().`,
    );
  }
});

/** Whether a Durable Object-managed Container declares an image to publish. */
export const hasImageSource = (props: DurableObjectContainerProps) =>
  props.image !== undefined || props.context !== undefined || props.dockerfile !== undefined;

/** Read the scheduling policy off a declared Container resource's props. */
export const isDurableObjectContainerResource = (container: ContainerApplication) => {
  const props = container.Props as { schedulingPolicy?: unknown } | undefined;
  return props?.schedulingPolicy === "durable_object";
};

/** The application-wide settings a Container contributes to its Durable Object class. */
export const containerApplicationSettings = (container: ContainerApplication) => {
  const props = container.Props as DurableObjectApplicationSettings | undefined;
  return {
    ssh: props?.ssh,
    authorizedKeys: props?.authorizedKeys,
    observability: props?.observability,
  };
};

const SETTING_KEYS = ["ssh", "authorizedKeys", "observability"] as const;

/**
 * Merge the application-wide settings every bound Container declares. A
 * setting declared by several Containers must have the same value.
 */
export const mergeApplicationSettings = (
  className: string,
  contributions: ReadonlyArray<{
    readonly id: string;
    readonly settings: DurableObjectApplicationSettings | undefined;
  }>,
) =>
  Effect.gen(function* () {
    const merged: DurableObjectApplicationSettings = {};
    for (const setting of SETTING_KEYS) {
      const declared = contributions.flatMap(({ id, settings }) => {
        const value = normalizeNulls(settings?.[setting]);
        return value === undefined ? [] : [{ id, value }];
      });
      const [first] = declared;
      if (first === undefined) continue;
      const conflicting = declared.find(({ value }) => !deepEqual(value, first.value));
      if (conflicting !== undefined) {
        return yield* new ContainerApplicationSettingsConflict({
          className,
          setting,
          containers: declared.map(({ id }) => id),
          message: `Containers '${first.id}' and '${conflicting.id}' declare different '${setting}' for Durable Object class '${className}'. A class has one container application, so its Containers must agree on application-wide settings; declare '${setting}' on one Container or give them the same value.`,
        });
      }
      Object.assign(merged, { [setting]: first.value });
    }
    return merged;
  });

/**
 * One row of a Worker's `containers` binding data: the container a Durable
 * Object class is backed by.
 */
export interface WorkerContainerRow {
  readonly className: string;
  /** Set when an async `Cloudflare.DurableObject(name, { containers })` binding contributed the row. */
  readonly attachedBy?: "binding";
  /** Application name, set for a Durable Object-managed class. */
  readonly name?: string;
  /** Prepared images keyed by Container id (Durable Object-managed). */
  readonly images?: Record<string, string>;
  /** Local image sources keyed by Container id (Durable Object-managed). */
  readonly devImages?: Record<string, DevContainerImage>;
  /** The fleet container's local image. */
  readonly dev: DevContainerImage | undefined;
  readonly hash: string | undefined;
}

const isDurableObjectRow = (row: Pick<WorkerContainerRow, "name" | "images" | "devImages">) =>
  row.name !== undefined || row.images !== undefined || row.devImages !== undefined;

const mergeImageMaps = <V>(
  className: string,
  label: string,
  maps: ReadonlyArray<Record<string, V> | undefined>,
) =>
  Effect.gen(function* () {
    if (maps.every((map) => map === undefined)) return undefined;
    const merged: Record<string, V> = {};
    for (const map of maps) {
      for (const [key, value] of Object.entries(map ?? {})) {
        if (key in merged && !deepEqual(merged[key], value)) {
          return yield* new DurableObjectContainerConflict({
            className,
            message: `Two Containers bound to Durable Object class '${className}' publish different ${label} under the key '${key}'. The image key is the Container's id, so give each Container a distinct id.`,
          });
        }
        merged[key] = value;
      }
    }
    return merged;
  });

/**
 * Merge a Worker's `containers` rows into one entry per Durable Object class.
 * A Durable Object-managed class unions the images of every bound Container;
 * a fleet class is backed by exactly one Container.
 */
export const mergeWorkerContainers = <
  Row extends Partial<WorkerContainerRow> & { className: string },
>(
  rows: ReadonlyArray<Row>,
) =>
  Effect.gen(function* () {
    const byClass = new Map<string, Row[]>();
    for (const row of rows) {
      const existing = byClass.get(row.className);
      if (existing) existing.push(row);
      else byClass.set(row.className, [row]);
    }
    const merged: Row[] = [];
    for (const [className, classRows] of byClass) {
      const [first, ...rest] = classRows as [Row, ...Row[]];
      const managed = classRows.filter(isDurableObjectRow);
      if (managed.length === 0) {
        // Fleet: rows for the same Container collapse; distinct ones conflict.
        if (rest.some((row) => !deepEqual(row, first))) {
          return yield* new DurableObjectContainerConflict({
            className,
            message: `Durable Object class '${className}' is bound to more than one fleet Container. Only Durable Object-managed Containers (schedulingPolicy: 'durable_object') can share a class.`,
          });
        }
        merged.push(first);
        continue;
      }
      if (managed.length !== classRows.length) {
        return yield* new DurableObjectContainerConflict({
          className,
          message: `Durable Object class '${className}' mixes a fleet Container with Durable Object-managed Containers. Every Container bound to one class must use schedulingPolicy: 'durable_object'.`,
        });
      }
      const names = [
        ...new Set(managed.flatMap((row) => (row.name === undefined ? [] : [row.name]))),
      ];
      if (names.length > 1) {
        return yield* new DurableObjectContainerConflict({
          className,
          message: `Durable Object class '${className}' resolves to more than one container application (${names.join(", ")}).`,
        });
      }
      const images = yield* mergeImageMaps(
        className,
        "images",
        managed.map((row) => row.images),
      );
      const devImages = yield* mergeImageMaps(
        className,
        "local images",
        managed.map((row) => row.devImages),
      );
      const keys = Object.keys(images ?? devImages ?? {});
      if (keys.length > MAX_NAMED_IMAGES) {
        return yield* new DurableObjectContainerConflict({
          className,
          message: `Durable Object class '${className}' is bound to ${keys.length} container images; Cloudflare allows at most ${MAX_NAMED_IMAGES}.`,
        });
      }
      const badKey = keys.find((key) => key.length === 0 || key.length > MAX_IMAGE_NAME_LENGTH);
      if (badKey !== undefined) {
        return yield* new DurableObjectContainerConflict({
          className,
          message: `Container id '${badKey}' is used as an image key and must contain between 1 and ${MAX_IMAGE_NAME_LENGTH} characters.`,
        });
      }
      const hashes = managed.flatMap((row) => (row.hash === undefined ? [] : [row.hash])).sort();
      merged.push({
        ...first,
        name: names[0],
        images,
        devImages,
        dev: undefined,
        hash: hashes.length === 0 ? undefined : hashes.join(","),
      });
    }
    return merged;
  });

/**
 * The `containers` entry a fleet Container contributes to the Durable Object
 * class it backs.
 */
export const workerContainerBinding = (className: string, application: ContainerApplication) => ({
  className,
  dev: application.dev,
  hash: application.hash.pipe(Output.map((hash) => hash?.image)),
});

/**
 * The `containers` entry a Durable Object-managed Container contributes to
 * its class: the class's application name plus this Container's one image,
 * keyed by the Container's id. The Worker merges every entry of the class.
 */
export const durableObjectContainerBinding = (
  className: string,
  application: DurableObjectApplication,
  container: ContainerApplication,
) => {
  const key = container.LogicalId;
  return {
    className,
    name: application.applicationName,
    images: container.image.pipe(
      Output.map((image): Record<string, string> => (image === undefined ? {} : { [key]: image })),
    ),
    devImages: container.dev.pipe(
      Output.map((dev): Record<string, DevContainerImage> =>
        dev === undefined ? {} : { [key]: dev },
      ),
    ),
    dev: undefined,
    hash: container.hash.pipe(Output.map((hash) => hash?.image)),
  };
};

/**
 * Converge declared settings and reset settings removed from a prior declaration.
 * Omitted settings on new or adopted applications remain unmanaged.
 */
export const durableObjectSettingsPatch = (
  desired: DurableObjectApplicationSettings,
  previous: DurableObjectApplicationSettings | undefined,
  observed: Pick<Containers.GetContainerApplicationResponse, "configuration" | "observability">,
): Pick<Containers.UpdateContainerApplicationRequest, "configuration" | "observability"> => {
  const configuration: Containers.DurableObjectContainerConfiguration = {
    // Cloudflare names the SSH setting after the CLI that connects to it.
    ...(desired.ssh !== undefined
      ? { wranglerSsh: desired.ssh }
      : previous?.ssh !== undefined
        ? { wranglerSsh: { enabled: false } }
        : {}),
    ...(desired.authorizedKeys !== undefined
      ? { authorizedKeys: desired.authorizedKeys }
      : previous?.authorizedKeys !== undefined
        ? { authorizedKeys: [] }
        : {}),
  };
  const observability =
    desired.observability ??
    (previous?.observability !== undefined ? { logs: { enabled: false } } : undefined);
  const configurationChanged = Object.entries(configuration).some(
    ([key, value]) =>
      !deepEqual(
        value,
        normalizeNulls(observed.configuration?.[key as keyof typeof configuration]),
      ),
  );
  return {
    ...(configurationChanged ? { configuration } : {}),
    ...(observability !== undefined &&
    !deepEqual(observability, normalizeNulls(observed.observability))
      ? { observability }
      : {}),
  };
};

/** Common attributes before a Durable Object-managed application exists remotely. */
export const durableObjectPlaceholder = (
  identity: Pick<
    ContainerApplication["Attributes"],
    "applicationId" | "applicationName" | "accountId" | "createdAt" | "observability"
  >,
): ContainerApplication["Attributes"] => ({
  ...identity,
  schedulingPolicy: "durable_object",
  instances: undefined,
  maxInstances: undefined,
  constraints: undefined,
  affinities: undefined,
  configuration: {},
  durableObjects: undefined,
  version: undefined,
  dev: undefined,
});