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

package/lib/Volume.js

@@ -0,0 +1,133 @@
+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, dockerContextName, dockerPhysicalName } from "./Docker.js";
+/**
+ * A Docker volume managed through the active Docker context.
+ *
+ * Pre-existing same-name volumes are treated as foreign until the engine is
+ * allowed to adopt them with `--adopt` or `adopt(true)`.
+ *
+ *
+ * ### Creating Volumes
+ * **Example:** Basic volume
+ * ```typescript
+ * const data = yield* Docker.Volume("data", {
+ *   name: "app-data",
+ * });
+ * ```
+ *
+ * **Example:** PostgreSQL data volume
+ * ```typescript
+ * const data = yield* Docker.Volume("postgres-data");
+ * ```
+ *
+ * **Example:** Driver options and labels
+ * ```typescript
+ * const data = yield* Docker.Volume("db-data", {
+ *   driver: "local",
+ *   driverOpts: {
+ *     type: "nfs",
+ *     o: "addr=10.0.0.1,rw",
+ *     device: ":/path/to/dir",
+ *   },
+ *   labels: {
+ *     "com.example.usage": "database",
+ *   },
+ * });
+ * ```
+ *
+ * ### Docker Context
+ * **Example:** Create a volume in a named Docker context
+ * ```typescript
+ * const data = yield* Docker.Volume("data", {
+ *   name: "app-data",
+ *   context: "remote-build",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Volume
+ */
+export const Volume = Resource("Docker.Volume");
+export const VolumeProvider = () => Provider.effect(Volume, Effect.gen(function* () {
+    const docker = yield* Docker;
+    return Volume.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+            const context = dockerContextName(olds?.context);
+            const name = yield* dockerPhysicalName(id, olds, instanceId);
+            const info = yield* docker.volume
+                .inspect(name, context)
+                .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined));
+            if (!info)
+                return undefined;
+            const attrs = toVolumeAttributes(info);
+            if (output)
+                return attrs;
+            // Without prior state, only adopt a volume 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, instanceId, output, news, olds }) {
+            if (!isResolved(news))
+                return undefined;
+            if (dockerContextName(olds?.context) !== dockerContextName(news?.context)) {
+                return { action: "replace", deleteFirst: true };
+            }
+            const args = yield* makeVolumeArgs(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 ?? args.name;
+            if (output?.name !== desiredName ||
+                output?.driver !== args.driver ||
+                !Equal.equals(output?.driverOpts ?? {}, args.opt ?? {}) ||
+                // Compare only user labels; internal `alchemy::*` branding lives on
+                // the observed volume but must not drive replacement.
+                !Equal.equals(stripInternalTags(output?.labels), args.label ?? {})) {
+                return { action: "replace", deleteFirst: true };
+            }
+        }),
+        reconcile: Effect.fn(function* ({ id, instanceId, news, output }) {
+            const context = dockerContextName(news?.context);
+            const args = yield* makeVolumeArgs(id, news, instanceId);
+            // Prefer the deployed name: regenerating would target a different
+            // volume if the generator's output for this id ever drifts.
+            const name = news?.name ?? output?.name ?? args.name;
+            const internalTags = yield* createInternalTags(id);
+            const result = yield* docker.volume.create({
+                ...args,
+                name,
+                label: { ...internalTags, ...args.label },
+                context,
+            });
+            return toVolumeAttributes(yield* docker.volume.inspect(result.stdout, context));
+        }),
+        delete: Effect.fn(({ olds, output }) => docker.volume
+            .remove(output.name, dockerContextName(olds?.context))
+            .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.void))),
+    });
+}));
+// Every prop is optional, so `Docker.Volume("data")` arrives with no props.
+const makeVolumeArgs = (id, props, instanceId) => dockerPhysicalName(id, props, instanceId).pipe(Effect.map((name) => ({
+    name,
+    driver: props?.driver ?? "local",
+    opt: props?.driverOpts,
+    label: props?.labels,
+})));
+export const toVolumeAttributes = (info) => ({
+    id: info.Name,
+    name: info.Name,
+    driver: info.Driver,
+    driverOpts: info.Options ?? {},
+    labels: info.Labels ?? {},
+    mountpoint: info.Mountpoint,
+    createdAt: Date.parse(info.CreatedAt) || Date.now(),
+});
+//# sourceMappingURL=Volume.js.map

package/lib/Volume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Volume.js","sourceRoot":"","sources":["../src/Volume.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./Container.ts";
+export * from "./Context.ts";
+export * from "./Docker.ts";
+export * as Dockerfile from "./Dockerfile.ts";
+export * from "./Image.ts";
+export * from "./Network.ts";
+export * from "./Providers.ts";
+export type { ImageRegistry } from "./Registry.ts";
+export { DockerRegistryBlobUnknown, DockerRegistryUnavailable, type DockerImagePublicationError, } from "./RegistryError.ts";
+export * from "./RemoteImage.ts";
+export * from "./Service.ts";
+export * from "./Swarm.ts";
+export * from "./Volume.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAC9C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,KAAK,2BAA2B,GACjC,MAAM,oBAAoB,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/lib/index.js

@@ -0,0 +1,13 @@
+export * from "./Container.js";
+export * from "./Context.js";
+export * from "./Docker.js";
+export * as Dockerfile from "./Dockerfile.js";
+export * from "./Image.js";
+export * from "./Network.js";
+export * from "./Providers.js";
+export { DockerRegistryBlobUnknown, DockerRegistryUnavailable, } from "./RegistryError.js";
+export * from "./RemoteImage.js";
+export * from "./Service.js";
+export * from "./Swarm.js";
+export * from "./Volume.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAC9C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAE/B,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAE1B,MAAM,oBAAoB,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@alchemy.run/docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0-beta.84",
+  "description": "Docker images, containers, networks, volumes and registries for Alchemy, and the image builds container platforms share.",
+  "keywords": [
+    "alchemy",
+    "containers",
+    "docker",
+    "effect",
+    "infrastructure-as-code"
+  ],
+  "homepage": "https://alchemy.run",
+  "bugs": {
+    "url": "https://github.com/alchemy-run/alchemy/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Sam Goodwin <sam@alchemy.run>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alchemy-run/alchemy.git",
+    "directory": "packages/docker"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./Bootstrap": {
+      "types": "./src/Bootstrap.ts",
+      "bun": "./src/Bootstrap.ts",
+      "default": "./src/Bootstrap.ts"
+    },
+    "./*": {
+      "types": "./lib/*.d.ts",
+      "bun": "./src/*.ts",
+      "default": "./lib/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "rolldown": "1.2.13"
+  },
+  "devDependencies": {
+    "@effect/platform-bun": "^4.0.5",
+    "@types/bun": "1.4.3",
+    "@types/node": "26.6.5",
+    "alchemy": "2.0.0-beta.84",
+    "effect": "^4.0.5",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@effect/platform-bun": "^4.0.5",
+    "alchemy": "2.0.0-beta.84",
+    "effect": "^4.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@effect/platform-bun": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "pnpm -r --filter \"{.}...\" run build:package",
+    "build:package": "node scripts/build.ts"
+  }
 }

package/src/Bootstrap.ts

@@ -0,0 +1,51 @@
+/**
+ * Process bootstrap for `Docker.Service` (a bun process serving the
+ * bundled program). The generated entry imports this module and the user's
+ * `main`, nothing else — see `alchemy/Runtime/Bootstrap` for why.
+ */
+import { BunServices } from "@effect/platform-bun";
+import { BunHttpServer } from "alchemy/Http";
+import { reifyBoundConfigProvider } from "alchemy/Runtime";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "alchemy/Runtime/Bootstrap";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Bun HTTP server bound to `PORT`, so the returned
+ * `{ fetch }` handler is actually served and `host.run` loops stay alive.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    BunServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(BunHttpServer()),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Docker service", program);
+};

package/src/BuildHash.ts

@@ -0,0 +1,255 @@
+/**
+ * INTERNAL — deterministic identity for a Docker build: context + Dockerfile
+ * + platform + build args, with Docker's own semantics (`.dockerignore`
+ * pattern matching, symlink targets, permission bits, empty directories).
+ * Cloud-agnostic — consumed by `AWS.ECR.Image` and `AWS.Lambda.Function`
+ * image packaging; NOT exported from the Docker barrel.
+ */
+
+import * as crypto from "node:crypto";
+import {
+  type IgnoreRules,
+  listFileSystemDirectory,
+  normalizeRelativePath,
+  parseIgnoreRules,
+  walkIgnoring,
+} from "alchemy/Util/Ignore";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Stream from "effect/Stream";
+
+export interface DockerBuildSource {
+  context: string;
+  dockerfile: string;
+  platform: string;
+  buildArgs?: Record<string, string>;
+}
+
+export type DockerBuildHashMode = "all" | "effective";
+
+interface DockerIgnore {
+  content: string;
+  path?: string;
+  rules: IgnoreRules;
+}
+
+/**
+ * Resolve and validate a Docker build context and Dockerfile.
+ *
+ * Dockerfile paths are relative to the build context unless absolute.
+ */
+export const resolveDockerBuildPaths = Effect.fn(function* (
+  source: Pick<DockerBuildSource, "context" | "dockerfile">,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const context = path.resolve(source.context);
+  const dockerfile = path.isAbsolute(source.dockerfile)
+    ? source.dockerfile
+    : path.resolve(context, source.dockerfile);
+
+  if (!(yield* fs.exists(context))) {
+    return yield* Effect.fail(new Error(`Docker build context does not exist: ${context}`));
+  }
+  if (!(yield* fs.exists(dockerfile))) {
+    return yield* Effect.fail(new Error(`Dockerfile does not exist: ${dockerfile}`));
+  }
+
+  return { context, dockerfile };
+});
+
+const resolveDockerIgnore = Effect.fn(function* ({
+  context,
+  dockerfile,
+}: {
+  context: string;
+  dockerfile: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dockerfileIgnore = `${dockerfile}.dockerignore`;
+  const contextIgnore = path.join(context, ".dockerignore");
+  const ignoreFile = (yield* fs.exists(dockerfileIgnore))
+    ? dockerfileIgnore
+    : (yield* fs.exists(contextIgnore))
+      ? contextIgnore
+      : undefined;
+
+  if (ignoreFile === undefined) {
+    return undefined;
+  }
+
+  const content = yield* fs.readFileString(ignoreFile);
+  const relativePath = normalizeRelativePath(path.relative(context, ignoreFile));
+  return {
+    content,
+    path:
+      relativePath === ".." || relativePath.startsWith("../") || path.isAbsolute(relativePath)
+        ? undefined
+        : relativePath,
+    rules: parseIgnoreRules(content, "dockerignore"),
+  } satisfies DockerIgnore;
+});
+
+interface DockerBuildContextSelection {
+  /** Absolute build-context directory. */
+  readonly context: string;
+  /** Absolute Dockerfile path. */
+  readonly dockerfile: string;
+  /** Dockerfile path relative to the context, if it is inside the context. */
+  readonly dockerfilePath: string | undefined;
+  /** Return whether an entry must be sent to the Docker builder. */
+  readonly includes: (relativePath: string) => boolean;
+}
+
+/**
+ * Select the effective files sent for a Docker build.
+ *
+ * Dockerfile-specific ignore files take precedence over `.dockerignore`.
+ * The Dockerfile and selected ignore file stay in the upload even when an
+ * ignore rule matches them, as Docker clients must send both to the builder.
+ */
+export const selectDockerBuildContext = Effect.fn(function* (
+  source: Pick<DockerBuildSource, "context" | "dockerfile">,
+) {
+  const path = yield* Path.Path;
+  const { context, dockerfile } = yield* resolveDockerBuildPaths(source);
+  const dockerignore = yield* resolveDockerIgnore({ context, dockerfile });
+  const relativeDockerfile = normalizeRelativePath(path.relative(context, dockerfile));
+  const dockerfilePath =
+    relativeDockerfile === ".." ||
+    relativeDockerfile.startsWith("../") ||
+    path.isAbsolute(relativeDockerfile)
+      ? undefined
+      : relativeDockerfile;
+
+  return {
+    context,
+    dockerfile,
+    dockerfilePath,
+    includes: (relativePath: string) => {
+      const normalized = normalizeRelativePath(relativePath);
+      if (normalized === dockerfilePath || normalized === dockerignore?.path) {
+        return true;
+      }
+      return dockerignore === undefined || !dockerignore.rules.ignores(normalized);
+    },
+  } satisfies DockerBuildContextSelection;
+});
+
+/**
+ * Hash a Docker build context together with the Dockerfile, platform, and
+ * build arguments. In `effective` mode, the selected `.dockerignore` is
+ * applied exactly once before files are hashed. Absolute paths do not
+ * participate.
+ */
+export const hashDockerBuildInputs = Effect.fn(function* (
+  source: DockerBuildSource,
+  mode: DockerBuildHashMode,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const { context, dockerfile } = yield* resolveDockerBuildPaths(source);
+  const dockerignore =
+    mode === "effective" ? yield* resolveDockerIgnore({ context, dockerfile }) : undefined;
+  const hasher = yield* Effect.sync(() => crypto.createHash("sha256"));
+
+  yield* Effect.sync(() =>
+    hasher.update(
+      JSON.stringify({
+        platform: source.platform,
+        buildArgs: Object.entries(source.buildArgs ?? {}).sort(([a], [b]) =>
+          a < b ? -1 : a > b ? 1 : 0,
+        ),
+        dockerignore:
+          dockerignore === undefined
+            ? undefined
+            : {
+                content: dockerignore.content,
+                path: dockerignore.path,
+              },
+      }),
+    ),
+  );
+
+  const dockerfileContent = yield* fs.readFile(dockerfile);
+  yield* Effect.sync(() => {
+    hasher.update("Dockerfile\0");
+    hasher.update(dockerfileContent);
+  });
+
+  const forcedPaths = [
+    dockerignore?.path,
+    normalizeRelativePath(path.relative(context, dockerfile)),
+  ].filter(
+    (entry): entry is string =>
+      entry !== undefined && entry !== ".." && !entry.startsWith("../") && !path.isAbsolute(entry),
+  );
+  // Walk one level at a time so an excluded directory is discarded before
+  // its contents are read; entries come back sorted, preserving hash order.
+  const entries = yield* walkIgnoring({
+    list: yield* listFileSystemDirectory(context),
+    rules: dockerignore?.rules,
+    force: forcedPaths,
+  });
+
+  for (const { path: entry } of entries) {
+    // The ignore file and Dockerfile contents are hashed above; excluded
+    // entries were only walked so re-included descendants could be found.
+    if (
+      dockerignore !== undefined &&
+      (entry === dockerignore.path || dockerignore.rules.ignores(entry))
+    ) {
+      continue;
+    }
+
+    const fullPath = path.join(context, entry);
+    const hashedEntry = entry;
+    // FileSystem.stat follows symbolic links, so probe the link itself first.
+    // Docker preserves the link in the build context; hashing the target file
+    // would miss retargets between files with identical contents and metadata.
+    const link = yield* Effect.result(fs.readLink(fullPath));
+    if (Result.isSuccess(link)) {
+      yield* Effect.sync(() =>
+        hasher.update(
+          `${JSON.stringify({
+            path: hashedEntry,
+            type: "SymbolicLink",
+            target: link.success,
+          })}\0`,
+        ),
+      );
+      continue;
+    }
+
+    const info = yield* fs.stat(fullPath);
+
+    // Docker COPY preserves entry types and permission bits, including empty
+    // directories. Include that metadata before any file bytes so changes such
+    // as making a Lambda bootstrap executable invalidate the image tag.
+    yield* Effect.sync(() =>
+      hasher.update(
+        `${JSON.stringify({
+          path: hashedEntry,
+          type: info.type,
+          mode: info.mode & 0o7777,
+          size: info.type === "File" ? String(info.size) : undefined,
+        })}\0`,
+      ),
+    );
+
+    if (info.type === "File") {
+      yield* fs.stream(fullPath).pipe(
+        Stream.runForEach((chunk) =>
+          Effect.sync(() => {
+            hasher.update(chunk);
+          }),
+        ),
+      );
+    }
+  }
+
+  return (yield* Effect.sync(() => hasher.digest("hex"))).slice(0, 32);
+});