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

package/src/Docker.ts

@@ -85,6 +85,42 @@ export class Docker extends Context.Service<
         network?: string | undefined;
         /** Linux capabilities to add. */
         "cap-add"?: Array<string> | undefined;
+        /** Linux capabilities to drop. */
+        "cap-drop"?: Array<string> | undefined;
+        /** Hard memory limit in Docker's byte-suffix format. */
+        memory?: string | undefined;
+        /** Combined memory-and-swap limit in Docker's byte-suffix format. */
+        "memory-swap"?: string | undefined;
+        /** Soft memory reservation for memory contention. */
+        "memory-reservation"?: string | undefined;
+        /** CPU quota, in cores. */
+        cpus?: number | undefined;
+        /** Per-container process and thread limit. */
+        "pids-limit"?: number | undefined;
+        /** Mount the root filesystem read-only. */
+        "read-only"?: boolean | undefined;
+        /** Security options such as `no-new-privileges` and seccomp/AppArmor profiles. */
+        "security-opt"?: Array<string> | undefined;
+        /** Per-container user namespace; "host" disables daemon user remapping. */
+        userns?: string | undefined;
+        /** Supplemental Linux groups. */
+        "group-add"?: Array<string> | undefined;
+        /** Per-process soft/hard resource limits. */
+        ulimit?: Array<string> | undefined;
+        /** Docker log driver. */
+        "log-driver"?: string | undefined;
+        /** Driver-specific Docker logging options. */
+        "log-opt"?: Array<string> | undefined;
+        /** Kernel OOM score adjustment. */
+        "oom-score-adj"?: number | undefined;
+        /** Signal used on container stop. */
+        "stop-signal"?: string | undefined;
+        /** Run Docker's tiny init process. */
+        init?: boolean | undefined;
+        /** Runtime UID/GID or named user. */
+        user?: string | undefined;
+        /** Docker tmpfs mount expressions (target[:options]). */
+        tmpfs?: Array<string> | undefined;
         /** Host devices in Docker's `host:container[:permissions]` form. */
         device?: Array<string> | undefined;
         command: Array<string> | undefined;
@@ -130,6 +166,12 @@ export class Docker extends Context.Service<
           platform?: string;
           target?: string;
           "build-arg"?: Record<string, string>;
+          /**
+           * BuildKit secrets, keyed by id (`RUN --mount=type=secret,id=<id>`).
+           * Values reach `docker` through its environment, never its argv,
+           * and are not written to the image.
+           */
+          secrets?: Record<string, string | Redacted.Redacted<string>>;
           "cache-from"?: Array<string>;
           "cache-to"?: Array<string>;
           args?: Array<string>;
@@ -327,10 +369,12 @@ export class Docker extends Context.Service<
         context?: string;
         replicas?: number;
         "endpoint-mode"?: "vip" | "dnsrr";
+        /** Networks to detach, by name or id; applied before `network-add`. */
+        "network-rm"?: string[];
+        "network-add"?: string[];
         "constraint-add"?: string[];
         "constraint-rm"?: string[];
         "replicas-max-per-node"?: number;
-        "placement-pref"?: string[];
         "update-parallelism"?: number;
         "update-delay"?: string;
         "update-monitor"?: string;
@@ -356,13 +400,23 @@ export class Docker extends Context.Service<
         "health-start-period"?: string;
         "stop-grace-period"?: string;
         "mount-add"?: string[];
+        /** Mount targets to remove. */
+        "mount-rm"?: string[];
         "secret-add"?: string[];
+        /** Secret names to remove; applied before `secret-add`. */
+        "secret-rm"?: string[];
         "config-add"?: string[];
+        /** Config names to remove; applied before `config-add`. */
+        "config-rm"?: string[];
         "read-only"?: boolean;
         "publish-add"?: string[];
+        /** Published ports to remove, as `target=<port>,protocol=<p>,mode=<m>`. */
+        "publish-rm"?: string[];
         "label-add"?: Record<string, string>;
         "label-rm"?: string[];
         "env-add"?: Record<string, string>;
+        /** Environment variable names to remove. */
+        "env-rm"?: string[];
         args?: string;
       }) => Effect.Effect<CommandOutput, PlatformError>;
       /** Inspects a service. */
@@ -423,6 +477,8 @@ export declare namespace Docker {
       Image: string;
       Cmd: string[] | null;
       Env: string[] | null;
+      User?: string;
+      StopSignal?: string;
       Labels: Record<string, string> | null;
       StopTimeout?: number;
       Healthcheck?: {
@@ -442,12 +498,28 @@ export declare namespace Docker {
       AutoRemove: boolean;
       NetworkMode?: string;
       CapAdd?: string[] | null;
+      CapDrop?: string[] | null;
+      Memory?: number;
+      MemorySwap?: number;
+      MemoryReservation?: number;
+      NanoCpus?: number;
+      PidsLimit?: number;
+      ReadonlyRootfs?: boolean;
+      SecurityOpt?: string[] | null;
+      UsernsMode?: string;
+      GroupAdd?: string[] | null;
+      Ulimits?: Array<{ Name: string; Soft: number; Hard: number }> | null;
+      LogConfig?: { Type: string; Config: Record<string, string> | null };
+      OomScoreAdj?: number;
+      Init?: boolean | null;
+      Tmpfs?: Record<string, string> | null;
       Devices?: Array<{
         PathOnHost: string;
         PathInContainer: string;
         CgroupPermissions: string;
       }> | null;
     };
+    AppArmorProfile?: string;
     NetworkSettings: {
       Networks: Record<string, { NetworkID: string; Aliases: string[] | null }> | null;
       Ports?: Record<string, Array<{ HostIp: string; HostPort: string }> | null> | null;
@@ -832,17 +904,21 @@ const makeDocker = (options: DockerOptions) =>
       },
       image: {
         build: Effect.fn("Docker.image.build")(function* (
-          { context: buildContext, engineContext, args, credentials, ...options },
+          { context: buildContext, engineContext, args, credentials, secrets, ...options },
           session,
           registry,
         ) {
           const tap = outputTap(session);
-          const buildArgs = [buildContext, ...formatArgs(options), ...(args ?? [])];
+          const secret = buildSecrets(secrets);
+          const buildArgs = [buildContext, ...formatArgs(options), ...secret.args, ...(args ?? [])];
           const engine = formatArgs({ context: engineContext });
           if (registry === undefined) {
             return yield* run(
               [...engine, "image", "build", ...buildArgs],
-              credentials ? yield* registryEnvironment(credentials) : undefined,
+              {
+                ...(credentials ? yield* registryEnvironment(credentials) : undefined),
+                ...secret.env,
+              },
               tap,
             );
           }
@@ -853,7 +929,7 @@ const makeDocker = (options: DockerOptions) =>
             const env = yield* registryEnvironment(registry);
             return yield* run(
               [...engine, "buildx", "build", "--push", ...buildArgs],
-              env,
+              { ...env, ...secret.env },
               tap,
             ).pipe(Effect.mapError(classifyDockerRegistryError));
           }
@@ -869,7 +945,7 @@ const makeDocker = (options: DockerOptions) =>
               ...(mode === "load" ? ["buildx", "build", "--load"] : ["image", "build"]),
               ...buildArgs,
             ],
-            undefined,
+            secret.env,
             tap,
           );
           const [tag, ...tags] =
@@ -1048,6 +1124,22 @@ const systemError = (input: {
     }),
   );
 
+/**
+ * `--secret id=<id>,env=<var>` per secret, with each value under a generated
+ * variable name: an id is the Dockerfile author's choice and may collide with
+ * the environment Docker itself reads (`PATH`, `DOCKER_HOST`).
+ */
+const buildSecrets = (secrets: Record<string, string | Redacted.Redacted<string>> | undefined) => {
+  const args: Array<string> = [];
+  const env: Record<string, string> = {};
+  Object.entries(secrets ?? {}).forEach(([id, value], index) => {
+    const variable = `ALCHEMY_BUILD_SECRET_${index}`;
+    args.push("--secret", `id=${id},env=${variable}`);
+    env[variable] = Redacted.isRedacted(value) ? Redacted.value(value) : value;
+  });
+  return { args, env };
+};
+
 /** Formats a set of options into a list of command-line arguments. */
 const formatArgs = (
   options: Record<
@@ -1057,7 +1149,9 @@ const formatArgs = (
 ) => {
   const args: Array<string> = [];
   for (const [key, value] of Object.entries(options)) {
-    if (!value) continue;
+    // `0` is meaningful (`--replicas 0`, `--update-parallelism 0`), so only
+    // absent, `false` and empty values are omitted.
+    if (value === undefined || value === false || value === "") continue;
     const prefix = key.length > 1 ? `--${key}` : `-${key}`;
     if (value === true) {
       args.push(prefix);

package/src/Image.ts

@@ -5,6 +5,7 @@ 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 {
@@ -30,8 +31,18 @@ export interface DockerBuildOptions {
   dockerfile?: string;
   /** Target platform, e.g. `"linux/amd64"`. */
   platform?: string;
-  /** Docker build arguments. */
+  /**
+   * 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`. */
@@ -117,6 +128,23 @@ export interface Image extends Resource<
  * });
  * ```
  *
+ * ### 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
@@ -192,6 +220,7 @@ export const ImageProvider = () =>
           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,

package/src/ImageSource.ts

@@ -3,9 +3,11 @@ import * as Bundle from "alchemy/Bundle/Bundle";
 import { findCwdForBundle, getStableContextDir, resolveMainPath } from "alchemy/Bundle/TempRoot";
 import { hashDirectory } from "alchemy/Command/Memo";
 import { sha256Object } from "alchemy/Util/sha256";
+import * as Data from "effect/Data";
 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 * as Schedule from "effect/Schedule";
 import type * as rolldown from "rolldown";
 import { Docker, type RegistryCredentials } from "./Docker.ts";
@@ -82,11 +84,41 @@ export interface BundledImageSource {
   build?: Bundle.BundleConfig;
 }
 
+/**
+ * Build arguments and BuildKit secrets for an image built from the user's
+ * own Dockerfile (`context` / `dockerfile`).
+ */
+export interface DockerfileBuild {
+  /**
+   * Docker build arguments (`--build-arg`), read by `ARG` instructions.
+   * They are part of the image's content hash, so changing one rebuilds the
+   * image. 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 are left out of the image's content hash, so rotating one does
+   * not rebuild the image.
+   */
+  secrets?: Record<string, Redacted.Redacted<string>>;
+}
+
+/** The `build` prop of a source built from the user's own Dockerfile. */
+export interface DockerfileBuildOptions {
+  /** Build arguments and BuildKit secrets for the Dockerfile build. */
+  build?: DockerfileBuild;
+}
+
 /**
  * Build the image from the user's own Dockerfile and build context — no
  * Effect program is bundled.
  */
-export interface DockerfileImageSource {
+export interface DockerfileImageSource extends DockerfileBuildOptions {
   /**
    * Docker build context directory. Optional when {@link dockerfile} is
    * inline content (which builds with an empty context).
@@ -123,7 +155,8 @@ export type ImageSourceProps = BundledImageSource | DockerfileImageSource | Regi
 export interface ImageSourceLike {
   main?: string;
   handler?: string;
-  build?: BundledImageSource["build"];
+  /** Bundler config for `main`; Docker build args and secrets for `context`. */
+  build?: Bundle.BundleConfig & DockerfileBuild;
   context?: string;
   dockerfile?: string | InlineDockerfile;
   image?: string;
@@ -146,9 +179,41 @@ export const imageSourceKind = (source: ImageSourceLike): ImageSourceKind | unde
         ? "context"
         : undefined;
 
+/**
+ * `build.args` or `build.secrets` set on an image that is not built from the
+ * user's own Dockerfile: a `main` program or a pre-built `image`.
+ */
+export class DockerfileBuildConflict extends Data.TaggedError("DockerfileBuildConflict")<{
+  readonly id: string;
+  readonly source: "main" | "image";
+}> {
+  override get message() {
+    return `'${this.id}': 'build.args' and 'build.secrets' apply to an image built from your own Dockerfile ('context' / 'dockerfile'), not to '${this.source}'`;
+  }
+}
+
+/**
+ * Dies with {@link DockerfileBuildConflict} when `build.args` or
+ * `build.secrets` are set alongside `main` or `image`.
+ */
+export const validateDockerfileBuild = (
+  id: string,
+  source: { main?: string; image?: string; build?: DockerfileBuild },
+): Effect.Effect<void> =>
+  (source.main !== undefined || source.image !== undefined) &&
+  (source.build?.args !== undefined || source.build?.secrets !== undefined)
+    ? Effect.die(
+        new DockerfileBuildConflict({
+          id,
+          source: source.main !== undefined ? "main" : "image",
+        }),
+      )
+    : Effect.void;
+
 /**
  * Validate environment-source exclusivity. Dies (plan-time defect) on
- * `image`+`dockerfile`, `image`+`context`, or inline-`dockerfile`+`context`.
+ * `image`+`dockerfile`, `image`+`context`, inline-`dockerfile`+`context`, or
+ * build args/secrets without a Dockerfile build.
  */
 export const validateImageSource = (id: string, source: ImageSourceLike): Effect.Effect<void> => {
   if (source.image !== undefined && source.dockerfile !== undefined) {
@@ -176,7 +241,7 @@ export const validateImageSource = (id: string, source: ImageSourceLike): Effect
       ),
     );
   }
-  return Effect.void;
+  return validateDockerfileBuild(id, source);
 };
 
 /**
@@ -287,6 +352,8 @@ export const computeStaticSourceHash = Effect.fn(function* (
       return (yield* sha256Object({
         dockerfile: source.dockerfile.content,
         platform: platform ?? "linux/amd64",
+        // Absent when unset, so existing hashes hold. Secrets are excluded.
+        buildArgs: source.build?.args,
       })).slice(0, 16);
     }
     const fs = yield* FileSystem.FileSystem;
@@ -300,6 +367,7 @@ export const computeStaticSourceHash = Effect.fn(function* (
       contextHash,
       dockerfile: dockerfileContent,
       platform: platform ?? "linux/amd64",
+      buildArgs: source.build?.args,
     })).slice(0, 16);
   }
   return undefined;
@@ -460,7 +528,7 @@ export const makeContainerImageSource = Effect.gen(function* () {
       envFrom !== undefined
         ? `FROM ${envFrom}`
         : source.dockerfile !== undefined && isInlineDockerfile(source.dockerfile)
-          ? String(source.dockerfile.content).trimEnd()
+          ? (source.dockerfile.content as string).trimEnd()
           : `FROM ${source.image ?? "oven/bun:1"}`;
     const lines = [
       preamble,
@@ -514,6 +582,7 @@ export const makeContainerImageSource = Effect.gen(function* () {
       context: string;
       dockerfile?: string;
       platform?: string;
+      build?: DockerfileBuild;
     },
   ) {
     const credentials = yield* target.credentials;
@@ -522,6 +591,8 @@ export const makeContainerImageSource = Effect.gen(function* () {
       context: options.context,
       file: options.dockerfile,
       platform: options.platform,
+      "build-arg": options.build?.args,
+      secrets: options.build?.secrets,
     });
     yield* push(options.imageUri, credentials, options.platform);
     return options.imageUri;
@@ -676,6 +747,7 @@ export const makeContainerImageSource = Effect.gen(function* () {
         imageUri,
         context: contextDir,
         platform,
+        build: source.build,
       });
       yield* session.note(`Pushed ${imageUri}`);
       return { imageUri, repositoryUri, codeHash };
@@ -698,6 +770,7 @@ export const makeContainerImageSource = Effect.gen(function* () {
       context,
       dockerfile,
       platform,
+      build: source.build,
     });
     yield* session.note(`Pushed ${imageUri}`);
     return { imageUri, repositoryUri, codeHash };

package/src/RemoteImage.ts

@@ -140,7 +140,7 @@ export const RemoteImageProvider = () =>
       const inspectImage = (ref: string, context: string | undefined) =>
         docker.image
           .inspect(ref, context)
-          .pipe(Effect.catchIf(isMissingImageError, () => Effect.succeed(undefined)));
+          .pipe(Effect.catchIf(isMissingImageError, () => Effect.undefined));
 
       return RemoteImage.Provider.of({
         list: () => Effect.succeed([]),