@alchemy.run/docker 0.0.0 → 2.0.0-beta.85

package/src/Dockerfile.ts

@@ -0,0 +1,81 @@
+/**
+ * Inline Dockerfile content for container platforms.
+ *
+ * Container platform props accept `dockerfile: string | { content: Input<string> }`:
+ * a plain string is always a **path** (relative to `context`); an object with a
+ * `content` key is **inline Dockerfile content**. `Dockerfile.inline` is the
+ * ergonomic way to produce the latter — a tagged template whose interpolations
+ * ride the normal {@link Output} machinery, so referencing another resource's
+ * attributes (e.g. an {@link ECR.Image}'s `imageUri`) creates a real dependency
+ * edge and re-resolves on change.
+ *
+ * The returned value is a plain JSON-serializable object (no symbols or
+ * brands) so it round-trips through persisted state unchanged; the structural
+ * `content` key is the discriminant.
+ *
+ * @example Base plus system packages, still bundling your Effect program
+ * ```typescript
+ * import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
+ *
+ * const worker = yield* AWS.ECS.Task(
+ *   "Transcoder",
+ *   {
+ *     cluster,
+ *     main: import.meta.url,
+ *     dockerfile: Dockerfile.inline`
+ *       FROM oven/bun:1
+ *       RUN apt-get update && apt-get install -y ffmpeg
+ *     `,
+ *   },
+ *   impl,
+ * );
+ * ```
+ *
+ * @example Deriving from another resource's image (dependency edge for free)
+ * ```typescript
+ * const base = yield* AWS.ECR.Image("MlBase", { context: "./ml-base" });
+ *
+ * const trainer = yield* AWS.ECS.Task(
+ *   "Trainer",
+ *   {
+ *     cluster,
+ *     main: import.meta.url,
+ *     dockerfile: Dockerfile.inline`
+ *       FROM ${base.imageUri}
+ *       RUN pip install -r /opt/requirements.txt
+ *     `,
+ *   },
+ *   impl,
+ * );
+ * ```
+ */
+import type { Input } from "alchemy/Input";
+import * as Output from "alchemy/Output";
+
+/**
+ * Inline Dockerfile content. A plain, state-serializable object; the
+ * structural `content` key distinguishes it from a path string wherever
+ * `dockerfile` props accept `string | InlineDockerfile`.
+ *
+ * Never interpolate secrets: anything in Dockerfile content is baked into
+ * image layers. `Input<string>` excludes `Redacted` values at the type level.
+ */
+export interface InlineDockerfile {
+  readonly content: Input<string>;
+}
+
+/** Structural guard for {@link InlineDockerfile} vs a path string. */
+export const isInlineDockerfile = (value: unknown): value is InlineDockerfile =>
+  typeof value === "object" && value !== null && "content" in value;
+
+/**
+ * Tagged template producing {@link InlineDockerfile}. Interpolations may be
+ * plain strings or `Output<string>`s (resolved at deploy time via
+ * `Output.interpolate`); with no interpolations the content is a plain string.
+ */
+export const inline = (
+  template: TemplateStringsArray,
+  ...args: Array<Input<string>>
+): InlineDockerfile => ({
+  content: args.length === 0 ? template.raw.join("") : Output.interpolate(template, ...args),
+});

package/src/HealthcheckCommand.ts

@@ -0,0 +1,35 @@
+/**
+ * Renders a healthcheck `cmd` as the single string Docker's `--health-cmd`
+ * flag takes. The flag always runs its value through the container's shell, so
+ * the Docker API's exec form has to be flattened:
+ *
+ * - `"cmd"`: used as is.
+ * - `["CMD-SHELL", "cmd"]`: the shell command, without the marker.
+ * - `["CMD", "pg_isready", "-U", "app"]`: the arguments, each quoted so it
+ *   reaches the program as one argument.
+ * - `["NONE"]`: no command (the caller disables the healthcheck).
+ * - any other array: joined with spaces and run in the shell, as before, so
+ *   `["curl -f localhost || exit 1"]` keeps working.
+ */
+export const healthcheckCommand = (cmd: string[] | string): string | undefined => {
+  if (typeof cmd === "string") return cmd;
+  const [head, ...rest] = cmd;
+  switch (head) {
+    case "NONE":
+      return undefined;
+    case "CMD-SHELL":
+      return rest.join(" ");
+    case "CMD":
+      return rest.map(shellQuote).join(" ");
+    default:
+      return cmd.join(" ");
+  }
+};
+
+/** True when `cmd` is Docker's `["NONE"]` form, which disables the healthcheck. */
+export const isHealthcheckDisabled = (cmd: string[] | string): boolean =>
+  Array.isArray(cmd) && cmd[0] === "NONE";
+
+/** Single-quotes an argument unless it is made only of shell-safe characters. */
+const shellQuote = (arg: string): string =>
+  /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;

package/src/Image.ts

@@ -0,0 +1,322 @@
+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)),
+        ),
+      });
+    }),
+  );