sailfork / t3code-github / .repos/ alchemy-effect/ packages/ docker/ src/ Image.ts

import * as Artifacts from "alchemy/Artifacts";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import type * as Redacted from "effect/Redacted";
import { Docker, dockerContextName, dockerPhysicalName } from "./Docker.ts";
import type { Providers } from "./Providers.ts";
import {
  type ImageRegistry,
  parseCreatedAt,
  publishedRepoDigest,
  repositoryFromImageRef,
  withRegistryHost,
} from "./Registry.ts";

export interface DockerBuildOptions {
  /**
   * Build context directory.
   *
   * @default Current working directory.
   */
  context?: string;
  /**
   * Dockerfile path, relative to the context unless absolute.
   *
   * @default "Dockerfile"
   */
  dockerfile?: string;
  /** Target platform, e.g. `"linux/amd64"`. */
  platform?: string;
  /**
   * Docker build arguments (`--build-arg`). Never pass secrets here: build
   * args are visible in the image history. Use {@link secrets} instead.
   */
  args?: Record<string, string>;
  /**
   * BuildKit secrets, keyed by id. Mount one in a `RUN` step with
   * `--mount=type=secret,id=<id>` and read it from `/run/secrets/<id>`, or
   * add `env=<NAME>` to expose it as an environment variable for that step.
   * A secret never enters the image, its build history, or `docker`'s argv.
   */
  secrets?: Record<string, Redacted.Redacted<string>>;
  /** Multi-stage build target. */
  target?: string;
  /** Cache sources passed as `--cache-from`. */
  cacheFrom?: string[];
  /** Cache destinations passed as `--cache-to`. */
  cacheTo?: string[];
  /** Additional Docker build options. */
  options?: string[];
}

export interface ImageProps {
  /**
   * Repository/name for the built image.
   *
   * @default Generated from stack, stage, logical id, and instance id.
   */
  name?: string;
  /** Image tag. @default "latest" */
  tag?: string;
  /**
   * Registry credentials. The image is pushed to this registry (unless
   * `skipPush`), and the build itself authenticates with them, so private
   * base images and `type=registry` caches hosted there resolve without a
   * host `docker login`. Credentials already in `DOCKER_AUTH_CONFIG` for
   * other registries are kept. Build-time authentication needs Buildx 0.26+
   * (Docker Desktop 4.44+) or the legacy builder; older Buildx plugins ignore
   * it, so a private base image there still needs `docker login`.
   */
  registry?: ImageRegistry;
  /** Skip registry push even when `registry` is set. @default false */
  skipPush?: boolean;
  /** Docker context name or context resource. */
  context?: Docker.ContextRef;
  /** Docker build configuration. */
  build: DockerBuildOptions;
}

export interface Image extends Resource<
  "Docker.Image",
  ImageProps,
  {
    /** Image repository/name without tag. */
    name: string;
    /** Final image reference. Includes registry host when pushed there. */
    imageRef: string;
    /** Local image id after build/tag. */
    imageId: string;
    /** Registry digest after push when available. */
    repoDigest?: string;
    /** Tag used for the local image. */
    tag: string;
    /** Build timestamp in milliseconds since epoch. */
    builtAt: number;
  },
  never,
  Providers
> {}

/**
 * Builds, tags, and optionally pushes Docker images through the active Docker
 * context.
 *
 * This resource uses the Docker CLI and whatever daemon or remote context the
 * CLI is configured to target. It is separate from `Cloudflare.Container`;
 * registry image references are the boundary between Docker-managed images and
 * cloud container platforms.
 *
 * `Image` always builds from a Dockerfile. To pull (and optionally re-tag and
 * push) an existing registry image, use `Docker.RemoteImage`.
 *
 *
 * ### Building Images
 * **Example:** Build from a Dockerfile
 * ```typescript
 * const image = yield* Docker.Image("app", {
 *   name: "my-app",
 *   tag: "latest",
 *   build: {
 *     context: "./app",
 *     dockerfile: "Dockerfile",
 *     args: { NODE_ENV: "production" },
 *   },
 * });
 * ```
 *
 * ### Build Secrets
 * **Example:** Install from a private npm registry
 * ```typescript
 * // Dockerfile:
 * //   RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
 * const image = yield* Docker.Image("app", {
 *   name: "my-app",
 *   build: {
 *     context: "./app",
 *     secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
 *   },
 * });
 * ```
 *
 * The secret is mounted only into the `RUN` step that asks for it; it never
 * lands in an image layer or the build history.
 *
 * ### Registry Push
 * **Example:** Push with Redacted credentials
 * ```typescript
 * const image = yield* Docker.Image("app", {
 *   name: "my-app",
 *   build: { context: "./app" },
 *   registry: {
 *     server: "ghcr.io",
 *     username: "octocat",
 *     password: Config.Redacted("GITHUB_TOKEN"),
 *   },
 * });
 * ```
 *
 * ### Private Base Images and Registry Caches
 * **Example:** Build FROM a private base image with a registry cache
 * ```typescript
 * // Dockerfile: FROM registry.example.com/base:v1
 * const image = yield* Docker.Image("app", {
 *   name: "registry.example.com/app",
 *   build: {
 *     context: "./app",
 *     cacheFrom: ["type=registry,ref=registry.example.com/app:buildcache"],
 *     cacheTo: ["type=registry,ref=registry.example.com/app:buildcache,mode=max"],
 *   },
 *   // Authenticates the base-image pull and cache import/export, then the push.
 *   registry: {
 *     server: "registry.example.com",
 *     username: "deploy",
 *     password: Config.Redacted("REGISTRY_PASSWORD"),
 *   },
 * });
 * ```
 *
 * ### Docker Context
 * **Example:** Build in a named Docker context
 * ```typescript
 * const image = yield* Docker.Image("app", {
 *   name: "my-app",
 *   context: "remote-build",
 *   build: { context: "./app" },
 * });
 * ```
 *
 * @resource
 * @product Image
 */
export const Image = Resource<Image>("Docker.Image");

export const ImageProvider = () =>
  Provider.effect(
    Image,
    Effect.gen(function* () {
      const fs = yield* FileSystem.FileSystem;
      const path = yield* Path.Path;
      const docker = yield* Docker;

      const buildAndInspectImage = Effect.fn(function* (
        id: string,
        props: ImageProps,
        instanceId: string,
      ) {
        const name = yield* dockerPhysicalName(id, props, instanceId);
        const engineContext = dockerContextName(props.context);
        const tag = props.tag ?? "latest";
        const ref = `${name}:${tag}`;

        const paths = yield* resolveBuildPaths(props.build);
        yield* docker.image.build({
          tag: ref,
          context: paths.context,
          file: paths.dockerfile,
          platform: props.build.platform,
          target: props.build.target,
          "build-arg": props.build.args,
          secrets: props.build.secrets,
          "cache-from": props.build.cacheFrom,
          "cache-to": props.build.cacheTo,
          args: props.build.options,
          engineContext,
          // Base images and registry caches may live in the same registry;
          // the push itself stays in `reconcile`.
          credentials: props.registry,
        });

        // Read the freshly built image's id and creation time straight from
        // Docker rather than synthesizing a wall-clock timestamp.
        return {
          name,
          tag,
          image: yield* docker.image.inspect(ref, engineContext),
          ref,
        };
      }, Artifacts.cached("build"));

      const resolveBuildPaths = Effect.fn(function* (build: DockerBuildOptions) {
        const cwd = yield* Effect.sync(() => process.cwd());
        const context = path.resolve(build.context ?? cwd);
        const dockerfile = build.dockerfile
          ? path.isAbsolute(build.dockerfile)
            ? build.dockerfile
            : path.resolve(context, build.dockerfile)
          : path.resolve(context, "Dockerfile");
        if (!(yield* fs.exists(context))) {
          return yield* Effect.die(`Docker build context does not exist: ${context}`);
        }
        if (!(yield* fs.exists(dockerfile))) {
          return yield* Effect.die(`Dockerfile does not exist: ${dockerfile}`);
        }
        return { context, dockerfile };
      });

      return Image.Provider.of({
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
          const context = dockerContextName(olds.context);
          const ref =
            output?.imageRef ??
            (yield* dockerPhysicalName(id, olds, instanceId).pipe(
              Effect.map((name) => `${name}:${olds.tag ?? "latest"}`),
            ));
          const image = yield* docker.image
            .inspect(ref, context)
            .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined));
          if (!image) return undefined;
          return {
            name: output?.name ?? repositoryFromImageRef(ref),
            imageRef: ref,
            imageId: image.Id,
            repoDigest: output?.repoDigest,
            tag: output?.tag ?? olds.tag ?? "latest",
            builtAt: output?.builtAt ?? parseCreatedAt(image.Created),
          };
        }),
        diff: Effect.fn(function* ({ id, instanceId, news, output, olds }) {
          if (!isResolved(news) || !output) return undefined;
          if (dockerContextName(olds.context) !== dockerContextName(news.context)) {
            return { action: "update" };
          }
          const { image } = yield* buildAndInspectImage(id, news, instanceId);
          if (output?.imageId !== image.Id) {
            return { action: "update" };
          }
        }),
        reconcile: Effect.fn(function* ({ id, instanceId, news, session }) {
          const context = dockerContextName(news.context);
          const { name, tag, image, ref } = yield* buildAndInspectImage(id, news, instanceId);

          let repoDigest: string | undefined;
          let targetImageRef: string = ref;
          if (news.registry && !news.skipPush) {
            yield* session.note(`Pushing image to registry "${news.registry.server}"`);
            targetImageRef = withRegistryHost(ref, news.registry);
            const pushed = yield* docker.image.push(ref, news.registry, undefined, context);
            const published = yield* docker.image.inspect(ref, context);
            repoDigest = publishedRepoDigest(ref, pushed, published.RepoDigests, targetImageRef);
          }

          return {
            name,
            imageRef: targetImageRef,
            imageId: image.Id,
            repoDigest,
            tag,
            builtAt: parseCreatedAt(image.Created),
          };
        }),
        delete: Effect.fn(({ olds, output }) =>
          docker.image
            .remove(output.imageRef, undefined, dockerContextName(olds.context))
            .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.void)),
        ),
      });
    }),
  );