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

import { Docker } from "@alchemy.run/docker/Docker";
import { isInlineDockerfile } from "@alchemy.run/docker/Dockerfile";
import { validateDockerfileBuild } from "@alchemy.run/docker/ImageSource";
import { AlchemyContext } from "alchemy/AlchemyContext";
import * as Bundle from "alchemy/Bundle/Bundle";
import { findCwdForBundle, getStableContextDir, resolveMainPath } from "alchemy/Bundle/TempRoot";
import * as Output from "alchemy/Output";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Stack } from "alchemy/Stack";
import { sha256Object } from "alchemy/Util/sha256";
import * as Effect from "effect/Effect";
import * as Path from "effect/Path";
import * as Redacted from "effect/Redacted";
import type * as rolldown from "rolldown";
import type { AnyContainerApplicationProps } from "./ContainerApplication.ts";

/**
 * Fold the runtime-context `env` map (populated by `Binding.Service`s and
 * `Config` injection — see `ContainerPlatform.set`) into the application's
 * `environmentVariables`.
 *
 * Unlike Cloudflare Workers, container `secrets` are *references to the
 * account Secrets Store by name* — they cannot carry an inline value — so
 * runtime-bound values (e.g. a minted API token) must travel as plain
 * `environmentVariables`. The value is the JSON-encoded payload produced by
 * `ContainerPlatform.set` (a `{_tag:"Redacted",value}` marker for secrets,
 * a JSON string otherwise), which `ContainerPlatform.get` parses back into
 * the original `Redacted`/plain value at runtime.
 *
 * `precreate` receives the raw, unevaluated props (the engine only resolves
 * Output expressions for the real `reconcile`/create), so env values that
 * reference other resources are still unresolved `Output`s there — skip them.
 * They are applied when reconcile runs against the resolved props.
 *
 * When `accountId` is provided it is injected as `ALCHEMY_CLOUDFLARE_ACCOUNT_ID`
 * (mirroring the Worker runtime) so the container bootstrap can build
 * `CloudflareEnvironment` for HTTP capability bindings (R2/KV/Queue `*Http`).
 *
 * `bindings` carries the resource's binding contract — the `{ env }` a
 * `Binding.Service` attaches with ``host.bind`${resource}`({ env })`` when the
 * container is the host (`Prisma.Connect`, and any other capability whose
 * runtime config travels as environment variables). Bindings are resolved by
 * the engine before `reconcile`, so they land here already evaluated. They are
 * applied FIRST, at the lowest precedence: an explicitly declared `env` or
 * `environmentVariables` entry always wins over a capability-injected one.
 */
export const makeContainerEnv = (
  props: AnyContainerApplicationProps,
  accountId: string,
  bindings: readonly {
    data?: { env?: Record<string, any> } | undefined;
  }[] = [],
) => {
  const env: Record<string, string | Redacted.Redacted<string>> = {};
  for (const binding of bindings) {
    for (const [name, value] of Object.entries(binding.data?.env ?? {})) {
      if (Output.isOutput(value) || value === undefined) {
        continue;
      }
      env[name] = value;
    }
  }
  for (const [name, value] of Object.entries(props.env ?? {})) {
    if (Output.isOutput(value) || value === undefined) {
      continue;
    }
    env[name] = value;
  }
  for (const value of props.environmentVariables ?? []) {
    env[value.name] = value.value;
  }
  if (!env.ALCHEMY_CLOUDFLARE_ACCOUNT_ID) {
    env.ALCHEMY_CLOUDFLARE_ACCOUNT_ID = accountId;
  }
  return env;
};

/**
 * Derive the physical name for a container application. Shared between the
 * live and local providers so they agree on the deterministic name.
 */
export const createContainerApplicationName = (id: string, name: string | undefined) =>
  Effect.suspend(() => {
    if (name) return Effect.succeed(name);
    return createPhysicalName({
      id,
      lowercase: true,
    });
  });

/**
 * Validate the image-source composition on container props. Exactly one
 * environment/source may be declared:
 *
 * - `main` + optional `image` (environment base) OR inline `dockerfile`
 *   (environment preamble) — never both, and never a `context`.
 * - `image` alone — a pre-built remote image, exclusive with `dockerfile`
 *   and `context`.
 * - `dockerfile` (string path against `context`, or inline content with no
 *   `context`) — the user-Dockerfile build. Only this source takes
 *   `build.args` / `build.secrets`.
 *
 * Invalid combinations are programmer errors, surfaced as plan-time defects
 * (`Effect.die`) rather than typed errors.
 */
export const validateContainerImageProps = (
  id: string,
  props: Pick<AnyContainerApplicationProps, "main" | "image" | "dockerfile" | "context" | "build">,
): Effect.Effect<void> =>
  validateImageSources(props).pipe(
    Effect.andThen(
      // An empty `main` declares no program, as in `validateImageSources`.
      validateDockerfileBuild(id, { ...props, main: props.main || undefined }),
    ),
  );

const validateImageSources = (
  props: Pick<AnyContainerApplicationProps, "main" | "image" | "dockerfile" | "context">,
): Effect.Effect<void> => {
  const df = props.dockerfile;
  const hasInline = df !== undefined && isInlineDockerfile(df);
  if (props.main) {
    if (props.image !== undefined && df !== undefined) {
      return Effect.die(
        new Error(
          "`image` and `dockerfile` are mutually exclusive with `main` — both pick the environment for the bundled program; declare one.",
        ),
      );
    }
    if (df !== undefined && !hasInline) {
      return Effect.die(
        new Error(
          "A `dockerfile` PATH cannot be combined with `main` on Cloudflare containers — use `Dockerfile.inline` content or `image` to pick the bundled program's environment.",
        ),
      );
    }
    if (props.context !== undefined) {
      return Effect.die(
        new Error(
          "`context` cannot be combined with `main` — the build context for a bundled program is generated by Alchemy.",
        ),
      );
    }
    return Effect.void;
  }
  if (props.image !== undefined && df !== undefined) {
    return Effect.die(
      new Error(
        "`image` (pre-built remote image) and `dockerfile` (build your own) are mutually exclusive — declare one.",
      ),
    );
  }
  if (props.image !== undefined && props.context !== undefined) {
    return Effect.die(
      new Error(
        "`image` (pre-built remote image) and `context` (Dockerfile build) are mutually exclusive — declare one.",
      ),
    );
  }
  if (hasInline && props.context !== undefined) {
    return Effect.die(
      new Error(
        "Inline `dockerfile` content cannot be combined with `context` — inline content has no build context; use a `dockerfile` PATH for context-relative builds.",
      ),
    );
  }
  return Effect.void;
};

/**
 * Resolve the environment preamble for a generated (Effect-native) container
 * Dockerfile from the props' `image` / inline `dockerfile` composition:
 *
 * - inline `dockerfile` content → used verbatim as the preamble (it carries
 *   its own `FROM` and any extra build steps),
 * - `image` → a synthesized `FROM <image>` line,
 * - neither → `undefined` (callers fall back to the runtime default base).
 */
export const containerEnvPreamble = (
  props: Pick<AnyContainerApplicationProps, "image" | "dockerfile">,
): Effect.Effect<string | undefined> => {
  const df = props.dockerfile;
  if (df !== undefined && isInlineDockerfile(df)) {
    const content = df.content;
    if (typeof content !== "string") {
      return Effect.die(
        new Error(
          "Inline `dockerfile` content is an unresolved Output at image-build time. " +
            "Outputs in `Dockerfile.inline` resolve during a normal deploy; this container is being built before its dependencies resolved (e.g. during precreate of a circular binding). Break the cycle or inline the resolved value.",
        ),
      );
    }
    return Effect.succeed(content.trimEnd());
  }
  const ref = props.image?.trim();
  if (ref) {
    if (/\s/.test(ref)) {
      // A registry reference never contains whitespace — catch Dockerfile
      // content early with an actionable message instead of producing a
      // broken build.
      return Effect.die(
        new Error(
          `\`image\` must be a plain image reference (e.g. "oven/bun:latest"), got: ${JSON.stringify(props.image)}. ` +
            "For inline Dockerfile content use `dockerfile: Dockerfile.inline`.",
        ),
      );
    }
    return Effect.succeed(`FROM ${ref}`);
  }
  return Effect.undefined;
};

/**
 * Build the final Dockerfile used for a generated (Effect-native) container
 * image. Starts from the environment preamble (see
 * {@link containerEnvPreamble}) — or a runtime-appropriate default base —
 * then appends the statements that copy the bundled program and set the
 * entrypoint.
 */
export const buildFinalDockerfile = (
  envPreamble: string | undefined,
  runtime: "bun" | "node",
  external: string[] = [],
  autoInstallExternals = true,
): string => {
  const base = envPreamble ?? (runtime === "bun" ? "FROM oven/bun:1" : "FROM node:22-slim");
  const runtimeBin = runtime === "bun" ? "bun" : "node";
  const installCmd = runtime === "bun" ? "bun add" : "npm install";
  const installStep =
    autoInstallExternals && external.length > 0 ? `RUN ${installCmd} ${external.join(" ")}` : "";
  return [
    base,
    "",
    "WORKDIR /app",
    ...(installStep ? [installStep, ""] : []),
    // Linked copies don't depend on the layers below them, so the registry
    // exporter reuses cached base layers instead of downloading them first.
    "COPY --link index.mjs /app/index.mjs",
    // Copy any additional rolldown chunks (`chunk-XXX.js`,
    // `BunServices-YYY.js`, …). The glob matches zero or more files;
    // non-trivial bundles always emit at least one chunk, minimal
    // bundles emit none and the COPY no-ops.
    "COPY --link *.js /app/",
    "EXPOSE 3000",
    `ENTRYPOINT ["${runtimeBin}", "/app/index.mjs"]`,
    "",
  ].join("\n");
};

/**
 * Materialize resolved inline `dockerfile` content into a stable,
 * deterministic build-context directory (containing only the Dockerfile) so
 * both the live provider and the local dev runtime can `docker build` it.
 * Shared by the live and local providers so they agree on the path.
 */
export const materializeInlineDockerfileContext = Effect.fn(function* (
  id: string,
  content: string,
) {
  const { dotAlchemy } = yield* AlchemyContext;
  const docker = yield* Docker;
  const path = yield* Path.Path;
  const context = yield* getStableContextDir(dotAlchemy, dotAlchemy, `${id}-dockerfile`);
  yield* docker.materialize({ context, dockerfile: content, files: [] });
  return { context, dockerfile: path.join(context, "Dockerfile") };
});

/**
 * Bundle the container entrypoint program with rolldown. Returns every emitted
 * file (entry chunk plus shared chunks) so the full set can be materialized
 * into the Docker build context, along with a content hash of the bundle.
 *
 * Shared between the live provider (which builds + pushes a Cloudflare image)
 * and the local provider (which writes the context to disk for the runtime to
 * `docker build`).
 */
export const bundleContainerProgram = Effect.fn(function* ({
  main,
  runtime,
  handler = "default",
  isExternal = false,
  external = [],
  outdir,
  build,
}: {
  id: string;
  main: string;
  runtime: "bun" | "node";
  handler?: string | undefined;
  isExternal?: boolean;
  external?: string[];
  outdir?: string;
  build?: Bundle.BundleConfig;
}) {
  const stack = yield* Stack;
  const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;

  const realMain = yield* resolveMainPath(main);
  const cwd = yield* findCwdForBundle(realMain);

  const buildBundle = Effect.fn(function* (entry: string, plugins?: rolldown.RolldownPluginOption) {
    return yield* Bundle.build(
      {
        ...build?.input,
        input: entry,
        cwd,
        external: [
          "cloudflare:workers",
          "cloudflare:workflows",
          ...(runtime === "bun" ? ["bun", "bun:*"] : []),
          ...external,
          ...((build?.input?.external as string[] | undefined) ?? []),
        ],
        platform: "node",
        resolve: {
          conditionNames:
            runtime === "bun" ? [...Bundle.BUN_CONDITION_NAMES] : [...Bundle.NODE_CONDITION_NAMES],
          ...build?.input?.resolve,
        },
        plugins: [build?.input?.plugins, plugins],
        treeshake: true,
      },
      {
        ...build?.output,
        format: "esm",
        sourcemap: build?.output?.sourcemap ?? false,
        minify: build?.output?.minify ?? false,
        dir: outdir,
        entryFileNames: "index.mjs",
      },
      build,
    );
  });

  const bundleOutput = isExternal
    ? yield* buildBundle(realMain)
    : yield* buildBundle(
        realMain,
        virtualEntryPlugin(
          (importPath) => `
import { bootstrap } from ${JSON.stringify(
            runtime === "bun"
              ? "@alchemy.run/cloudflare/Bootstrap/ContainerBun"
              : "@alchemy.run/cloudflare/Bootstrap/ContainerNode",
          )};
import ${handler === "default" ? "entrypoint" : `{ ${handler} as entrypoint }`} from ${JSON.stringify(importPath)};

await bootstrap(entrypoint, ${JSON.stringify({
            stack: { name: stack.name, stage: stack.stage },
          })});
`,
        ),
      );

  // Rolldown can emit multiple chunk files (entry + shared chunks).
  // Return every file so downstream code can materialize all of them
  // into the Docker build context — dropping any of them produces a
  // `Cannot find module './chunk-XXX.js'` runtime crash inside the
  // container (with zero stdout, because it crashes before any user
  // code runs).
  const files = bundleOutput.files.map((f) => ({
    path: f.path,
    content: typeof f.content === "string" ? new TextEncoder().encode(f.content) : f.content,
  }));

  return { files, hash: bundleOutput.hash };
});

/**
 * Bundle an Effect-native container `main` and materialize it (plus the
 * generated Dockerfile) into a stable Docker build context directory, then
 * return the paths + content hash of that context.
 *
 * This is the local-dev image shape (`ContainerImage.Build`) that
 * `@alchemy.run/cloudflare-runtime/core` consumes: it `docker build`s the
 * `dockerfile` against the `context` directory. Shared between the local
 * provider (which serves this context to the runtime as the `dev` image) and
 * the live provider (which persists the same deterministic context path as
 * `dev` so a subsequent `alchemy dev` run has an image to build even though the
 * live deploy pushed to Cloudflare's registry instead).
 *
 * The context directory is deterministic for a given resource id, so live and
 * local agree on the path. Callers that want to skip re-bundling on an
 * unchanged resource should wrap this in {@link Artifacts.cached}.
 */
export const prepareContainerBuildContext = Effect.fn(function* (
  id: string,
  news: AnyContainerApplicationProps,
) {
  const { dotAlchemy } = yield* AlchemyContext;
  const docker = yield* Docker;
  const path = yield* Path.Path;

  const main = news.main;
  if (!main) {
    return yield* Effect.die(new Error("Container requires a `main` entrypoint."));
  }
  yield* validateContainerImageProps(id, news);
  const runtime = news.runtime ?? "bun";
  const context = yield* getStableContextDir(process.cwd(), dotAlchemy, `${id}-container`);
  const dockerfileContent = buildFinalDockerfile(
    yield* containerEnvPreamble(news),
    runtime,
    news.external,
    news.autoInstallExternals,
  );
  const [bundle] = yield* Effect.all(
    [
      bundleContainerProgram({
        id,
        main,
        runtime,
        handler: news.handler,
        isExternal: news.isExternal,
        external: news.external,
        outdir: context,
        build: news.build,
      }),
      docker.materialize({
        context,
        dockerfile: dockerfileContent,
        files: [],
      }),
    ],
    { concurrency: "unbounded" },
  );
  return {
    context,
    dockerfile: path.join(context, "Dockerfile"),
    hash: yield* sha256Object({
      bundle: bundle.hash,
      dockerfileContent,
    }),
  };
});