alchemy 2.0.0-beta.59 → 2.0.0-beta.60

package/src/Docker/Image.ts

@@ -0,0 +1,265 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Artifacts from "../Artifacts.ts";
+import { isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { Docker, dockerPhysicalName } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+import {
+  type ImageRegistry,
+  parseCreatedAt,
+  parseRepoDigest,
+  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. */
+  args?: Record<string, 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 for push. */
+  registry?: ImageRegistry;
+  /** Skip registry push even when `registry` is set. @default false */
+  skipPush?: boolean;
+  /** 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`.
+ *
+ * @resource
+ *
+ * @section 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" },
+ *   },
+ * });
+ * ```
+ *
+ * @section 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"),
+ *   },
+ * });
+ * ```
+ */
+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 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,
+          "cache-from": props.build.cacheFrom,
+          "cache-to": props.build.cacheTo,
+          args: props.build.options,
+        });
+
+        // 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),
+          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 ref =
+            output?.imageRef ??
+            (yield* dockerPhysicalName(id, olds, instanceId).pipe(
+              Effect.map((name) => `${name}:${olds.tag ?? "latest"}`),
+            ));
+          const image = yield* docker.image
+            .inspect(ref)
+            .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 }) {
+          if (!isResolved(news) || !output) return undefined;
+          const { image } = yield* buildAndInspectImage(id, news, instanceId);
+          if (output?.imageId !== image.Id) {
+            return { action: "update" };
+          }
+        }),
+        reconcile: Effect.fn(function* ({ id, instanceId, news, session }) {
+          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);
+            repoDigest = yield* docker.image
+              .push(ref, news.registry)
+              .pipe(
+                Effect.map((result) => parseRepoDigest(ref, result.stdout)),
+              );
+          }
+
+          return {
+            name,
+            imageRef: targetImageRef,
+            imageId: image.Id,
+            repoDigest,
+            tag,
+            builtAt: parseCreatedAt(image.Created),
+          };
+        }),
+        delete: Effect.fn(({ output }) =>
+          docker.image
+            .remove(output.imageRef)
+            .pipe(
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.void,
+              ),
+            ),
+        ),
+      });
+    }),
+  );

package/src/Docker/Network.ts

@@ -0,0 +1,178 @@
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import { Unowned } from "../AdoptPolicy.ts";
+import { isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import {
+  createInternalTags,
+  hasAlchemyTags,
+  stripInternalTags,
+} from "../Tags.ts";
+import { Docker, dockerPhysicalName } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface NetworkProps {
+  /**
+   * Docker network name.
+   *
+   * @default Generated from stack, stage, logical id, and instance id.
+   */
+  name?: string;
+  /** Network driver. @default "bridge" */
+  driver?: "bridge" | "host" | "none" | "overlay" | "macvlan" | (string & {});
+  /** Enable IPv6 on the network. @default false */
+  enableIPv6?: boolean;
+  /** Network labels. */
+  labels?: Record<string, string>;
+}
+
+export interface Network extends Resource<
+  "Docker.Network",
+  NetworkProps,
+  {
+    /** Docker network ID. */
+    id: string;
+    /** Docker network name. */
+    name: string;
+    /** Network driver. */
+    driver: string;
+    /** Whether IPv6 is enabled. */
+    enableIPv6: boolean;
+    /** Labels reported by Docker. */
+    labels: Record<string, string>;
+    /** Creation timestamp in milliseconds since epoch. */
+    createdAt: number;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * A Docker network managed through the active Docker context.
+ *
+ * Existing same-name networks are treated as foreign unless the engine is
+ * explicitly allowed to adopt them with `--adopt` or `adopt(true)`.
+ *
+ * @resource
+ *
+ * @section Creating Networks
+ * @example Basic bridge network
+ * ```typescript
+ * const network = yield* Docker.Network("app-network", {
+ *   name: "app-network",
+ * });
+ * ```
+ *
+ * @section Adoption
+ * @example Adopt a pre-existing network
+ * ```typescript
+ * const network = yield* Docker.Network("app-network", {
+ *   name: "shared-app-network",
+ * }).pipe(adopt(true));
+ * ```
+ */
+export const Network = Resource<Network>("Docker.Network");
+
+export const NetworkProvider = () =>
+  Provider.effect(
+    Network,
+    Effect.gen(function* () {
+      const docker = yield* Docker;
+
+      return Network.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+          const name = yield* dockerPhysicalName(id, olds, instanceId);
+          const info = yield* docker.network
+            .inspect(name)
+            .pipe(
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.undefined,
+              ),
+            );
+          if (!info) return undefined;
+          const attrs = toNetworkAttributes(info);
+          if (output) return attrs;
+          // Without prior state, only adopt a network that carries our branding;
+          // anything else is foreign and gated behind `--adopt`.
+          const owned = yield* hasAlchemyTags(id, info.Labels ?? undefined);
+          return owned ? attrs : Unowned(attrs);
+        }),
+        diff: Effect.fn(function* ({ id, output, instanceId, news }) {
+          if (!isResolved(news) || !output) return undefined;
+          const args = yield* makeNetworkArgs(id, news, instanceId);
+          if (
+            output.name !== args.name ||
+            output.driver !== args.driver ||
+            output.enableIPv6 !== args.ipv6 ||
+            // Compare only user labels; internal `alchemy::*` branding lives on
+            // the observed network but must not drive replacement.
+            !Equal.equals(stripInternalTags(output.labels), args.label ?? {})
+          ) {
+            return { action: "replace", deleteFirst: true };
+          }
+        }),
+        reconcile: Effect.fn(function* ({ output, id, instanceId, news }) {
+          if (output) {
+            const refreshed = yield* docker.network.inspect(output.id).pipe(
+              Effect.map(toNetworkAttributes),
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.undefined,
+              ),
+            );
+            if (refreshed) return refreshed;
+          }
+          const args = yield* makeNetworkArgs(id, news, instanceId);
+          const internalTags = yield* createInternalTags(id);
+          const { stdout: createdId } = yield* docker.network.create({
+            ...args,
+            label: { ...internalTags, ...args.label },
+          });
+          return toNetworkAttributes(yield* docker.network.inspect(createdId));
+        }),
+        delete: Effect.fn(({ output }) =>
+          docker.network
+            .remove(output.id)
+            .pipe(
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.void,
+              ),
+            ),
+        ),
+      });
+    }),
+  );
+
+const makeNetworkArgs = (
+  id: string,
+  props: NetworkProps | undefined,
+  instanceId: string,
+) =>
+  dockerPhysicalName(id, props, instanceId).pipe(
+    Effect.map(
+      (name): Parameters<Docker["Service"]["network"]["create"]>[0] => ({
+        name,
+        driver: props?.driver ?? "bridge",
+        ipv6: props?.enableIPv6 ?? false,
+        label: props?.labels ?? {},
+      }),
+    ),
+  );
+
+export const toNetworkAttributes = (
+  info: Docker.Network,
+): Network["Attributes"] => ({
+  id: info.Id,
+  name: info.Name,
+  driver: info.Driver,
+  enableIPv6: info.EnableIPv6,
+  labels: info.Labels ?? {},
+  createdAt: Date.parse(info.Created) || Date.now(),
+});

package/src/Docker/Providers.ts

@@ -0,0 +1,37 @@
+import * as Layer from "effect/Layer";
+import * as Provider from "../Provider.ts";
+import { Container, ContainerProvider } from "./Container.ts";
+import { DockerLive } from "./Docker.ts";
+import { Image, ImageProvider } from "./Image.ts";
+import { Network, NetworkProvider } from "./Network.ts";
+import { RemoteImage, RemoteImageProvider } from "./RemoteImage.ts";
+import { Volume, VolumeProvider } from "./Volume.ts";
+
+export class Providers extends Provider.ProviderCollection<Providers>()(
+  "Docker",
+) {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
+
+/**
+ * Registers all Docker resource providers.
+ *
+ * Docker providers use the active Docker CLI context and are intentionally
+ * separate from `Cloudflare.Container`.
+ */
+export const providers = () =>
+  Layer.effect(
+    Providers,
+    Provider.collection([Container, Image, Network, RemoteImage, Volume]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ContainerProvider(),
+        ImageProvider(),
+        NetworkProvider(),
+        RemoteImageProvider(),
+        VolumeProvider(),
+      ),
+    ),
+    Layer.provideMerge(DockerLive),
+  );

package/src/Docker/Registry.ts

@@ -0,0 +1,63 @@
+import type * as Redacted from "effect/Redacted";
+
+export interface ImageRegistry {
+  /** Registry host, e.g. `ghcr.io`. */
+  server: string;
+  /** Registry username. */
+  username: string;
+  /** Registry password. Use `Redacted.make(...)` or `Config.redacted(...)`. */
+  password: Redacted.Redacted<string>;
+}
+
+/** Strips the tag and digest from an image reference, leaving the repository. */
+export const repositoryFromImageRef = (imageRef: string): string => {
+  const withoutDigest = imageRef.includes("@")
+    ? imageRef.slice(0, imageRef.indexOf("@"))
+    : imageRef;
+  const tagSeparator = withoutDigest.lastIndexOf(":");
+  const pathSeparator = withoutDigest.lastIndexOf("/");
+  return tagSeparator > pathSeparator
+    ? withoutDigest.slice(0, tagSeparator)
+    : withoutDigest;
+};
+
+/**
+ * Prefixes an image reference with the registry host unless the reference
+ * already carries a registry prefix (a dotted host, a host:port, or `localhost`).
+ */
+export const withRegistryHost = (
+  imageRef: string,
+  registry: { server: string },
+): string => {
+  const registryHost = registry.server.replace(/\/$/, "");
+  const firstSegment = imageRef.split("/")[0];
+  const hasRegistryPrefix =
+    imageRef.includes("/") &&
+    (firstSegment.includes(".") ||
+      firstSegment.includes(":") ||
+      firstSegment === "localhost");
+  return hasRegistryPrefix ? imageRef : `${registryHost}/${imageRef}`;
+};
+
+/** Extracts the `repository@sha256:...` digest from `docker push` output. */
+export const parseRepoDigest = (
+  imageRef: string,
+  output: string,
+): string | undefined => {
+  const match = /digest:\s+([a-z0-9]+:[a-f0-9]{64})/i.exec(output);
+  if (!match) return undefined;
+  return `${repositoryFromImageRef(imageRef)}@${match[1]}`;
+};
+
+/**
+ * Parses an image's RFC 3339 `Created` timestamp into epoch milliseconds.
+ *
+ * Docker only reports `Created` when the image config carries a creation time:
+ * API >= 1.44 omits it, older APIs backfill the year-1 zero value
+ * (`0001-01-01T00:00:00Z`), and 25.0.0–25.0.3 returned an empty string. In any
+ * of those cases there is no real build time, so we fall back to the wall clock.
+ */
+export const parseCreatedAt = (created: string | undefined): number => {
+  const parsed = created ? Date.parse(created) : Number.NaN;
+  return Number.isNaN(parsed) || parsed <= 0 ? Date.now() : parsed;
+};