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

package/src/Network.ts

@@ -0,0 +1,169 @@
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { createInternalTags, hasAlchemyTags, stripInternalTags } from "alchemy/Tags";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import { Docker, dockerEngineContextName, 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>;
+  /**
+   * The engine the network is created on: a Docker context name, a
+   * `Docker.Context` resource, or a `Docker.Swarm` — overlay networks
+   * require a swarm manager, and passing the swarm orders the network after
+   * the swarm is initialized.
+   */
+  context?: Docker.EngineRef;
+}
+
+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)`.
+ *
+ *
+ * ### Creating Networks
+ * **Example:** Basic bridge network
+ * ```typescript
+ * const network = yield* Docker.Network("app-network", {
+ *   name: "app-network",
+ * });
+ * ```
+ *
+ * ### Adoption
+ * **Example:** Adopt a pre-existing network
+ * ```typescript
+ * const network = yield* Docker.Network("app-network", {
+ *   name: "shared-app-network",
+ * }).pipe(adopt(true));
+ * ```
+ *
+ * @resource
+ * @product Network
+ */
+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 context = dockerEngineContextName(olds?.context);
+          const name = yield* dockerPhysicalName(id, olds, instanceId);
+          const info = yield* docker.network
+            .inspect(name, context)
+            .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, olds }) {
+          if (!isResolved(news) || !output) return undefined;
+          if (dockerEngineContextName(olds?.context) !== dockerEngineContextName(news?.context)) {
+            return { action: "replace", deleteFirst: true };
+          }
+          const args = yield* makeNetworkArgs(id, news, instanceId);
+          // Auto-generated names are engine-owned: the deployed name stays
+          // authoritative even if the generator would name this id differently
+          // today. Only an explicit user-provided name can force a replace.
+          const desiredName = news?.name ?? output.name;
+          if (
+            output.name !== desiredName ||
+            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 }) {
+          const context = dockerEngineContextName(news?.context);
+          if (output) {
+            const refreshed = yield* docker.network.inspect(output.id, context).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 },
+            context,
+          });
+          return toNetworkAttributes(yield* docker.network.inspect(createdId, context));
+        }),
+        delete: Effect.fn(({ olds, output }) =>
+          docker.network
+            .remove(output.id, dockerEngineContextName(olds?.context))
+            .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/Providers.ts

@@ -0,0 +1,46 @@
+import * as Provider from "alchemy/Provider";
+import * as Layer from "effect/Layer";
+import { Container, ContainerProvider } from "./Container.ts";
+import { Context, ContextProvider } from "./Context.ts";
+import { type DockerOptions, dockerLive } from "./Docker.ts";
+import { Image, ImageProvider } from "./Image.ts";
+import { Network, NetworkProvider } from "./Network.ts";
+import { RemoteImage, RemoteImageProvider } from "./RemoteImage.ts";
+import { Service, ServiceProvider } from "./Service.ts";
+import { Swarm, SwarmProvider } from "./Swarm.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`. Pass `bin` to run a Docker-compatible
+ * CLI such as Podman; the `DOCKER_BIN` environment variable overrides it.
+ *
+ * ```typescript
+ * providers: Docker.providers({ bin: "podman" }),
+ * ```
+ */
+export const providers = (options: DockerOptions = {}) =>
+  Layer.effect(
+    Providers,
+    Provider.collection([Container, Image, Network, RemoteImage, Volume, Context, Service, Swarm]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ContainerProvider(),
+        ImageProvider(),
+        NetworkProvider(),
+        RemoteImageProvider(),
+        VolumeProvider(),
+        ContextProvider(),
+        ServiceProvider(),
+        SwarmProvider(),
+      ),
+    ),
+    Layer.provideMerge(dockerLive(options)),
+  );

package/src/Registry.ts

@@ -0,0 +1,91 @@
+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]}`;
+};
+
+/**
+ * Picks the `repository@digest` that inspect reports for this image.
+ *
+ * A fallback when push output has no `digest:` line. Podman pushes report the
+ * published digest through `--digestfile` instead, because Podman can list a
+ * pulled image's source digest under the pushed name here.
+ */
+export const repoDigestFromInspect = (
+  imageRef: string,
+  repoDigests: ReadonlyArray<string> | null | undefined,
+): string | undefined => {
+  const repository = repositoryFromImageRef(imageRef);
+  for (const digest of repoDigests ?? []) {
+    const at = digest.lastIndexOf("@");
+    if (at > 0 && digest.slice(0, at) === repository) return digest;
+  }
+  return undefined;
+};
+
+/**
+ * Digest from push output when the engine prints one, otherwise the matching
+ * `RepoDigests` entry. `registryRef` is the host-qualified name when it
+ * differs from the local reference that was pushed.
+ */
+export const publishedRepoDigest = (
+  imageRef: string,
+  output: { stdout: string; stderr: string },
+  repoDigests: ReadonlyArray<string> | null | undefined,
+  registryRef?: string,
+): string | undefined => {
+  const text = `${output.stdout}\n${output.stderr}`;
+  return (
+    parseRepoDigest(imageRef, text) ??
+    (registryRef === undefined ? undefined : repoDigestFromInspect(registryRef, repoDigests)) ??
+    repoDigestFromInspect(imageRef, repoDigests)
+  );
+};
+
+/**
+ * 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;
+};

package/src/RegistryError.ts

@@ -0,0 +1,48 @@
+import * as Data from "effect/Data";
+import type { PlatformError } from "effect/PlatformError";
+
+export class DockerRegistryBlobUnknown extends Data.TaggedError("DockerRegistryBlobUnknown")<{
+  readonly cause: PlatformError;
+}> {
+  override get message() {
+    return this.cause.message;
+  }
+}
+
+export class DockerRegistryUnavailable extends Data.TaggedError("DockerRegistryUnavailable")<{
+  readonly cause: PlatformError;
+}> {
+  override get message() {
+    return this.cause.message;
+  }
+}
+
+export type DockerImagePublicationError =
+  | PlatformError
+  | DockerRegistryBlobUnknown
+  | DockerRegistryUnavailable;
+
+export const classifyDockerRegistryError = (error: PlatformError): DockerImagePublicationError => {
+  // Build logs can contain arbitrary Dockerfile output before the final error.
+  const message =
+    error.reason.description
+      ?.split("\n")
+      .map((line) => line.trim())
+      .filter(
+        (line) =>
+          line.length > 0 &&
+          !line.startsWith("View build details: docker-desktop://dashboard/build/"),
+      )
+      .at(-1) ?? "";
+  if (/(?:^|:\s*)(?:unknown:\s*)?blob unknown to registry$/i.test(message)) {
+    return new DockerRegistryBlobUnknown({ cause: error });
+  }
+  if (
+    /(?:unexpected (?:http )?status(?:[^\n]*:\s*|\s+)5\d\d(?:\s|$)|(?:^|:\s*)(?:500 internal server error|502 bad gateway|503 service unavailable|504 gateway timeout)$)/i.test(
+      message,
+    )
+  ) {
+    return new DockerRegistryUnavailable({ cause: error });
+  }
+  return error;
+};

package/src/RemoteImage.ts

@@ -0,0 +1,255 @@
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import type { PlatformError } from "effect/PlatformError";
+import { Docker, dockerContextName } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+import {
+  type ImageRegistry,
+  parseCreatedAt,
+  publishedRepoDigest,
+  repositoryFromImageRef,
+  withRegistryHost,
+} from "./Registry.ts";
+
+export interface RemoteImageProps {
+  /** Docker image name to use as the source, without tag. */
+  name: string;
+  /** Docker source image tag. @default "latest" */
+  tag?: string;
+  /** Pull for this platform when the source is not already local or alwaysPull is enabled. */
+  platform?: string;
+  /**
+   * Always pull the source image, even when that reference exists locally.
+   *
+   * @default true
+   */
+  alwaysPull?: boolean;
+  /**
+   * Re-tag the pulled image under this repository/name. When omitted the pulled
+   * `name` is kept.
+   */
+  targetName?: string;
+  /**
+   * Tag applied to the re-tagged image.
+   *
+   * @default The pulled `tag`.
+   */
+  targetTag?: string;
+  /** Registry credentials. When set, the (re-tagged) image is pushed. */
+  registry?: ImageRegistry;
+  /**
+   * Skip registry push even when `registry` is set.
+   *
+   * @default false
+   */
+  skipPush?: boolean;
+  /** Docker context name or context resource. */
+  context?: Docker.ContextRef;
+}
+
+export interface RemoteImage extends Resource<
+  "Docker.RemoteImage",
+  RemoteImageProps,
+  {
+    /** Final image reference. Includes the registry host when pushed there. */
+    imageRef: string;
+    /** Local image id after reuse or pull. */
+    imageId: string;
+    /** Source image id used for the last reconcile, preserved across refresh. */
+    sourceImageId?: string;
+    /** Pull timestamp in milliseconds since epoch. */
+    createdAt: number;
+    /** Final image repository/name. */
+    name: string;
+    /** Final image tag. */
+    tag: string;
+    /** Registry digest after push when available. */
+    repoDigest?: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * Makes a source Docker image available through the active Docker context,
+ * optionally re-tagging it and pushing it to a registry.
+ *
+ * The image is available to other Docker resources by `imageRef`. Use
+ * `alwaysPull: false` reuses the source tag when it exists in the configured
+ * Docker daemon, pulling only when it is missing. Set `targetName`/`targetTag`
+ * to re-tag the source image, and `registry` to push it (mirroring it from a
+ * source registry into your own, for example).
+ *
+ *
+ * ### Pulling Images
+ * **Example:** Pull nginx
+ * ```typescript
+ * const nginx = yield* Docker.RemoteImage("nginx", {
+ *   name: "nginx",
+ *   tag: "alpine",
+ * });
+ * ```
+ *
+ * **Example:** Reuse an existing daemon tag
+ * ```typescript
+ * const postgres = yield* Docker.RemoteImage("postgres", {
+ *   name: "postgres",
+ *   tag: "18-alpine",
+ *   alwaysPull: false,
+ * });
+ * ```
+ *
+ * ### Re-tagging and Pushing
+ * **Example:** Mirror a public image into your registry
+ * ```typescript
+ * const mirrored = yield* Docker.RemoteImage("nginx-mirror", {
+ *   name: "nginx",
+ *   tag: "alpine",
+ *   targetName: "acme/nginx",
+ *   targetTag: "alpine",
+ *   registry: {
+ *     server: "ghcr.io",
+ *     username: "octocat",
+ *     password: Config.Redacted("GITHUB_TOKEN"),
+ *   },
+ * });
+ * ```
+ *
+ * ### Docker Context
+ * **Example:** Pull through a named Docker context
+ * ```typescript
+ * const nginx = yield* Docker.RemoteImage("nginx", {
+ *   name: "nginx",
+ *   tag: "alpine",
+ *   context: "remote-build",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Image
+ */
+export const RemoteImage = Resource<RemoteImage>("Docker.RemoteImage");
+
+export const RemoteImageProvider = () =>
+  Provider.effect(
+    RemoteImage,
+    Effect.gen(function* () {
+      const docker = yield* Docker;
+      const inspectImage = (ref: string, context: string | undefined) =>
+        docker.image
+          .inspect(ref, context)
+          .pipe(Effect.catchIf(isMissingImageError, () => Effect.succeed(undefined)));
+
+      return RemoteImage.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds, output }) {
+          const context = dockerContextName(olds.context);
+          const ref = output?.imageRef ?? targetImageRef(olds);
+          return yield* inspectImage(ref, context).pipe(
+            Effect.map((image) =>
+              image
+                ? {
+                    imageRef: ref,
+                    imageId: image.Id,
+                    createdAt: output?.createdAt ?? parseCreatedAt(image.Created),
+                    sourceImageId: output?.sourceImageId ?? output?.imageId ?? image.Id,
+                    name: output?.name ?? repositoryFromImageRef(ref),
+                    tag: output?.tag ?? targetTag(olds),
+                    repoDigest: output?.repoDigest,
+                  }
+                : undefined,
+            ),
+          );
+        }),
+        diff: Effect.fn(function* ({ output, news, olds }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            dockerContextName(olds.context) !== dockerContextName(news.context) ||
+            !output ||
+            news.alwaysPull !== false ||
+            output.imageRef !== targetImageRef(news)
+          ) {
+            return { action: "update" };
+          }
+          const source = yield* inspectImage(remoteImageRef(news), dockerContextName(news.context));
+          const target = yield* inspectImage(targetImageRef(news), dockerContextName(news.context));
+          if (
+            !source ||
+            !target ||
+            source.Id !== (output.sourceImageId ?? output.imageId) ||
+            source.Id !== target.Id
+          ) {
+            return { action: "update" };
+          }
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          const context = dockerContextName(news.context);
+          const sourceRef = remoteImageRef(news);
+          let source: Docker.Image | undefined;
+          if (news.alwaysPull === false) {
+            source = yield* inspectImage(sourceRef, context);
+            if (source) {
+              yield* session.note(`Reusing local Docker image: ${sourceRef}`);
+            }
+          }
+          if (!source) {
+            yield* session.note(`Pulling Docker image: ${sourceRef}`);
+            yield* docker.image.pull(sourceRef, news.platform, context);
+            source = yield* docker.image.inspect(sourceRef, context);
+          }
+
+          const finalRef = targetImageRef(news);
+          if (finalRef !== sourceRef || (news.registry && !news.skipPush)) {
+            yield* session.note(`Tagging Docker image: ${source.Id} -> ${finalRef}`);
+            yield* docker.image.tag(source.Id, finalRef, context);
+          }
+
+          let pushed: { stdout: string; stderr: string } | undefined;
+          if (news.registry && !news.skipPush) {
+            yield* session.note(`Pushing image to registry "${news.registry.server}"`);
+            pushed = yield* docker.image.push(finalRef, news.registry, undefined, context);
+          }
+
+          const inspected = yield* docker.image.inspect(finalRef, context);
+          const repoDigest =
+            pushed === undefined
+              ? undefined
+              : publishedRepoDigest(finalRef, pushed, inspected.RepoDigests);
+          return {
+            imageRef: finalRef,
+            imageId: inspected.Id,
+            sourceImageId: source.Id,
+            createdAt: parseCreatedAt(inspected.Created),
+            name: repositoryFromImageRef(finalRef),
+            tag: targetTag(news),
+            repoDigest,
+          };
+        }),
+        delete: Effect.fn(function* () {
+          // Remote images are not removed on destroy because tags may be shared by
+          // unrelated local stacks or developer workflows.
+        }),
+      });
+    }),
+  );
+
+/** The reference the image is pulled from. */
+const remoteImageRef = (props: RemoteImageProps): string =>
+  `${props.name}:${props.tag ?? "latest"}`;
+
+const isMissingImageError = (error: PlatformError): boolean =>
+  error.reason._tag === "NotFound" &&
+  /no such image|image not known|image not found/i.test(error.reason.description ?? "");
+
+const targetTag = (props: RemoteImageProps): string => props.targetTag ?? props.tag ?? "latest";
+
+/**
+ * The final reference after re-tagging and registry-host prefixing. Equals the
+ * pulled reference when no re-tag/registry is configured.
+ */
+const targetImageRef = (props: RemoteImageProps): string => {
+  const local = `${props.targetName ?? props.name}:${targetTag(props)}`;
+  return props.registry && !props.skipPush ? withRegistryHost(local, props.registry) : local;
+};