sailfork / t3code-github / .repos/ alchemy-effect/ packages/ integration-tests/ test/ Docker/ Docker.test.ts

import { Docker, DockerLive, dockerLive } from "@alchemy.run/docker";
import type { RegistryCredentials } from "@alchemy.run/docker/Docker";
import { classifyDockerRegistryError } from "@alchemy.run/docker/RegistryError";
import { assert, expect, layer } from "@alchemy.run/test";
import * as NodeServices from "@effect/platform-node/NodeServices";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import { PlatformError, SystemError } from "effect/PlatformError";
import * as Redacted from "effect/Redacted";
import * as TestClock from "effect/testing/TestClock";
import { authenticatedRegistry, scopedBuildx } from "./Runtime.ts";

const describe = layer(
  Layer.provideMerge(DockerLive, Layer.merge(NodeServices.layer, FetchHttpClient.layer)),
);

// Which CLI the client runs: declared in code, overridable by DOCKER_BIN.
describe("Docker CLI binary", (it) => {
  const version = (layer: Layer.Layer<Docker, never, any>) =>
    Effect.gen(function* () {
      const docker = yield* Docker;
      return (yield* docker.run(["--version"])).stdout;
    }).pipe(Effect.provide(layer));

  it.effect(
    "runs the bin declared in code",
    () =>
      Effect.gen(function* () {
        const error = yield* version(dockerLive({ bin: "alchemy-test-no-such-cli" })).pipe(
          Effect.flip,
        );
        expect(String(error)).toContain("alchemy-test-no-such-cli");
        expect(yield* version(dockerLive({ bin: "docker" }))).toMatch(/^Docker version/);
      }).pipe(
        // Ignore any DOCKER_BIN in the host environment for this case.
        Effect.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({}))),
      ),
    { tags: ["provider:docker", "local"] },
  );

  it.effect(
    "lets DOCKER_BIN override the bin declared in code",
    () =>
      Effect.gen(function* () {
        const output = yield* version(dockerLive({ bin: "alchemy-test-no-such-cli" }));
        expect(output).toMatch(/^Docker version/);
      }).pipe(
        Effect.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({ DOCKER_BIN: "docker" }))),
      ),
    { tags: ["provider:docker", "local"] },
  );
});

describe("Docker.materialize", (it) => {
  it.effect(
    "materializes a Dockerfile in the target directory",
    () =>
      Effect.gen(function* () {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const docker = yield* Docker;
        const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-ctx-" });
        const ctx = path.join(root, "ctx");
        yield* docker.materialize({ context: ctx, dockerfile: "FROM scratch\n", files: [] });
        const dockerfile = path.join(ctx, "Dockerfile");
        expect(yield* fs.exists(dockerfile)).toBe(true);
        expect(yield* fs.readFileString(dockerfile)).toBe("FROM scratch\n");
      }),
    { tags: ["unit", "provider:docker", "local"] },
  );

  it.effect(
    "writes nested context files",
    () =>
      Effect.gen(function* () {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const docker = yield* Docker;
        const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-path-" });
        const ctx = path.join(root, "ctx");
        yield* docker.materialize({
          context: ctx,
          dockerfile: "FROM scratch\n",
          files: [{ path: "nested/hello.txt", content: "hi" }],
        });
        expect(yield* fs.readFileString(path.join(ctx, "nested", "hello.txt"))).toBe("hi");
      }),
    { tags: ["unit", "provider:docker", "local"] },
  );
});

describe("Docker registry errors", (it) => {
  for (const [description, tag] of [
    [
      "ERROR: failed to build: failed to solve: failed to push registry.example/image:latest: unknown: blob unknown to registry",
      "DockerRegistryBlobUnknown",
    ],
    [
      "#7 ERROR: failed to push: unknown: blob unknown to registry\n------\nERROR: failed to build: failed to solve: failed to push registry.example/image:latest: unknown: blob unknown to registry\n\nView build details: docker-desktop://dashboard/build/builder/node/build-id\n",
      "DockerRegistryBlobUnknown",
    ],
    ["Command exited with code 1: blob unknown to registry", "DockerRegistryBlobUnknown"],
    [
      "ERROR: unexpected status from HEAD request to https://registry.example/v2/image/blobs/sha256:abc: 503 Service Unavailable",
      "DockerRegistryUnavailable",
    ],
    ["ERROR: failed to push: 502 Bad Gateway", "DockerRegistryUnavailable"],
    ["ERROR: unexpected status: 401 Unauthorized", "PlatformError"],
    ["ERROR: unexpected status: 403 Forbidden", "PlatformError"],
    ["ERROR: unexpected status: 400 Bad Request", "PlatformError"],
    ["ERROR: failed to solve: process exited with code 1", "PlatformError"],
    [
      "ERROR: unexpected status from HEAD request to https://registry.example/v2/500/blobs/sha256:abc: 403 Forbidden",
      "PlatformError",
    ],
    [
      'ERROR: failed to solve: process "/bin/sh -c echo 503 Service Unavailable && exit 1" did not complete successfully: exit code: 1',
      "PlatformError",
    ],
    ["#7 RUN echo 'blob unknown to registry'\nERROR: process exited with code 1", "PlatformError"],
    ["#7 RUN echo '503 Service Unavailable'\nERROR: process exited with code 1", "PlatformError"],
  ] as const) {
    it.effect(
      `classifies ${description}`,
      () =>
        Effect.sync(() => {
          const error = new PlatformError(
            new SystemError({
              _tag: "Unknown",
              module: "Docker",
              method: "buildx.build",
              description,
            }),
          );
          const classified = classifyDockerRegistryError(error);
          expect(classified._tag).toBe(tag);
          if (classified._tag === "PlatformError") {
            expect(classified).toBe(error);
          } else {
            expect(classified.cause).toBe(error);
            expect(classified.message).toBe(error.message);
          }
        }),
      { tags: ["unit", "provider:docker", "provider:docker:registry", "local"] },
    );
  }
});

const buildScratchImage = Effect.fn(function* (
  label: string,
  tag: string | [string, ...Array<string>],
  credentials: RegistryCredentials,
  platform?: string,
) {
  const fs = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-publish-" });
  yield* fs.writeFileString(
    path.join(root, "Dockerfile"),
    `FROM scratch\nLABEL alchemy.test=${label}\n`,
  );
  // A fresh service re-probes the Buildx plugin pinned by `scopedBuildx`.
  return yield* Effect.gen(function* () {
    const docker = yield* Docker;
    return yield* docker.image.build({ context: root, tag, platform }, undefined, credentials);
  }).pipe(Effect.provide(Layer.fresh(DockerLive)));
});

describe("Docker.image", (it) => {
  it.effect(
    "streams real pull output through deployment notes",
    () =>
      Effect.gen(function* () {
        const docker = yield* Docker;
        const notes: Array<{ message: string; kind?: string }> = [];
        const session = {
          note: (message: string, options?: { kind?: "status" | "output" }) =>
            Effect.sync(() => {
              notes.push({ message, kind: options?.kind });
            }),
        };
        yield* docker.image.pull("alpine:3.21", "linux/amd64", undefined, session);
        expect(notes.length).toBeGreaterThan(0);
        expect(notes.every((note) => note.kind === "output")).toBe(true);
        expect(notes.some((note) => note.message.includes("alpine:3.21"))).toBe(true);
      }),
    { tags: ["provider:docker", "local"], timeout: 120_000 },
  );
});

describe("Docker.image publication", (it) => {
  for (const [name, version, platform] of [
    ["exports straight to the registry on Buildx >= 0.26", "v0.26.1", "linux/amd64"],
    ["builds with --load then pushes on Buildx < 0.26", "v0.25.0", "linux/amd64"],
    ["builds then pushes without a Buildx plugin", undefined, undefined],
  ] as const) {
    it.effect(
      name,
      () =>
        Effect.gen(function* () {
          const fs = yield* FileSystem.FileSystem;
          const path = yield* Path.Path;
          const docker = yield* Docker;
          const registry = yield* authenticatedRegistry();
          const tags: [string, string] = [
            `${registry.host}/app:1`,
            `${registry.host}/app:buildcache`,
          ];
          yield* Effect.addFinalizer(() => docker.image.remove(tags, true).pipe(Effect.ignore));
          const { config } = yield* scopedBuildx(version);

          yield* buildScratchImage(version ?? "legacy", tags, registry.credentials, platform);

          expect(yield* registry.hasManifest("app", "1")).toBe(true);
          expect(yield* registry.hasManifest("app", "buildcache")).toBe(true);
          // Credentials ride per-invocation env/temp config, never the CLI's own.
          const cliConfig = path.join(config, "config.json");
          if (yield* fs.exists(cliConfig)) {
            expect(yield* fs.readFileString(cliConfig)).not.toContain(registry.host);
          }
        }).pipe(
          // Registry readiness and the Buildx download retry on real time.
          TestClock.withLive,
        ),
      { tags: ["provider:docker", "local"], exclusive: true, timeout: 180_000 },
    );
  }

  for (const [name, auth] of [
    ["invalid JSON", '{"auths":{"source.invalid":{"auth":"AUTH_SECRET_SENTINEL"}},'],
    ["invalid base64", '{"auths":{"source.invalid":{"auth":"AUTH_SECRET_SENTINEL!"}}}'],
    [
      "missing credential separator",
      '{"auths":{"source.invalid":{"auth":"QVVUSF9TRUNSRVRfU0VOVElORUw="}}}',
    ],
  ]) {
    it.effect(
      `rejects ${name} DOCKER_AUTH_CONFIG without exposing registry credentials`,
      () =>
        Effect.gen(function* () {
          const registry = yield* authenticatedRegistry();
          yield* scopedBuildx("v0.26.1");

          const result = yield* buildScratchImage(
            "invalid-auth",
            `${registry.host}/invalid-auth:1`,
            {
              ...registry.credentials,
              password: Redacted.make("DESTINATION_SECRET_SENTINEL"),
            },
          ).pipe(
            Effect.flip,
            Effect.provide(
              ConfigProvider.layer(ConfigProvider.fromUnknown({ DOCKER_AUTH_CONFIG: auth })),
            ),
          );
          assert(result._tag === "PlatformError");
          expect(result.reason._tag).toBe("InvalidData");
          expect(result.reason.description).toContain("DOCKER_AUTH_CONFIG");
          const serialized = yield* Effect.sync(() => JSON.stringify(result));
          expect(serialized).not.toContain("AUTH_SECRET_SENTINEL");
          expect(serialized).not.toContain("QVVUSF9TRUNSRVRfU0VOVElORUw=");
          expect(serialized).not.toContain("DESTINATION_SECRET_SENTINEL");
          // Rejected before anything was built or published.
          expect(yield* registry.hasManifest("invalid-auth", "1")).toBe(false);
        }).pipe(
          // Registry readiness and the Buildx download retry on real time.
          TestClock.withLive,
        ),
      { tags: ["provider:docker", "local"], exclusive: true, timeout: 180_000 },
    );
  }
});

// How a failing `docker` command is reported, against the real CLI.
describe("Docker.run failure output", (it) => {
  it.effect(
    "says so when a failing command wrote nothing",
    () =>
      Effect.gen(function* () {
        const docker = yield* Docker;
        const error = yield* docker
          .run(["run", "--rm", "alpine:3.19", "sh", "-c", "exit 3"])
          .pipe(Effect.flip);
        expect(error.reason._tag).toBe("Unknown");
        expect(error.reason.description).toContain("exited with code 3");
        expect(error.reason.description).toContain("wrote no output");
      }),
    { tags: ["provider:docker", "local"], timeout: 60_000 },
  );

  it.effect(
    "keeps stdout and stderr from a failing command",
    () =>
      Effect.gen(function* () {
        const docker = yield* Docker;
        const error = yield* docker
          .run([
            "run",
            "--rm",
            "alpine:3.19",
            "sh",
            "-c",
            "echo step-log-on-stdout; echo reason-on-stderr >&2; exit 1",
          ])
          .pipe(Effect.flip);
        expect(error.reason.description).toContain("step-log-on-stdout");
        expect(error.reason.description).toContain("reason-on-stderr");
        // The reason (stderr) comes first.
        expect(error.reason.description!.indexOf("reason-on-stderr")).toBeLessThan(
          error.reason.description!.indexOf("step-log-on-stdout"),
        );
      }),
    { tags: ["provider:docker", "local"], timeout: 60_000 },
  );

  it.effect(
    "still classifies a daemon NotFound from stderr",
    () =>
      Effect.gen(function* () {
        const docker = yield* Docker;
        const error = yield* docker
          .run(["image", "inspect", "alchemy-test-no-such-image:missing"])
          .pipe(Effect.flip);
        expect(error.reason._tag).toBe("NotFound");
      }),
    { tags: ["provider:docker", "local"] },
  );
});

describe("Docker.image", (it) => {
  it.effect(
    "builds a minimal image with content Dockerfile",
    () =>
      Effect.gen(function* () {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const docker = yield* Docker;
        const tag = "alchemy-docker-test:minimal";
        yield* Effect.addFinalizer(() =>
          docker.image.remove(tag, true).pipe(
            Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
            Effect.ignore,
          ),
        );
        const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-build-" });
        const ctx = path.join(root, "ctx");
        yield* docker.materialize({
          context: ctx,
          dockerfile: [
            "FROM alpine:3.19",
            "RUN echo ok > /tmp/ok.txt",
            'CMD ["cat", "/tmp/ok.txt"]',
            "",
          ].join("\n"),
          files: [],
        });
        yield* docker.image.build({ tag, context: ctx });
        const inspect = yield* docker.image.inspect(tag);
        expect(inspect.Id.length).toBeGreaterThan(0);
      }),
    { tags: ["unit", "provider:docker", "local"] },
  );

  it.effect(
    "passes --platform and --build-arg",
    () =>
      Effect.gen(function* () {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const docker = yield* Docker;
        const tag = "alchemy-docker-test:args";
        yield* Effect.addFinalizer(() =>
          docker.image.remove(tag, true).pipe(
            Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
            Effect.ignore,
          ),
        );
        const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-build-" });
        const ctx = path.join(root, "ctx");
        yield* docker.materialize({
          context: ctx,
          dockerfile: [
            "FROM alpine:3.19",
            "ARG FOO=default",
            'RUN echo "$FOO" > /out.txt',
            "",
          ].join("\n"),
          files: [],
        });
        yield* docker.image.build({
          tag,
          context: ctx,
          platform: "linux/amd64",
          "build-arg": { FOO: "from-arg" },
        });
        const out = yield* docker.run(["run", "--rm", tag, "cat", "/out.txt"]);
        expect(out.stdout.trim()).toBe("from-arg");
      }),
    { tags: ["unit", "provider:docker", "local"] },
  );

  it.effect(
    "passes --secret through the environment and keeps it out of the image",
    () =>
      Effect.gen(function* () {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const docker = yield* Docker;
        const tag = "alchemy-docker-test:secret";
        const value = "alchemy-build-secret-value";
        yield* Effect.addFinalizer(() =>
          docker.image.remove(tag, true).pipe(
            Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
            Effect.ignore,
          ),
        );
        const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-build-" });
        const ctx = path.join(root, "ctx");
        yield* docker.materialize({
          context: ctx,
          dockerfile: [
            "FROM alpine:3.19",
            // `PATH` as an id proves the value does not ride in a variable of
            // that name: shadowing it would break `docker` itself.
            "RUN --mount=type=secret,id=PATH,required=true " +
              "wc -c < /run/secrets/PATH > /length.txt",
            "",
          ].join("\n"),
          files: [],
        });
        yield* docker.image.build({
          tag,
          context: ctx,
          secrets: { PATH: Redacted.make(value) },
        });
        const out = yield* docker.run(["run", "--rm", tag, "cat", "/length.txt"]);
        expect(out.stdout.trim()).toBe(String(value.length));
        const history = yield* docker.run(["image", "history", "--no-trunc", tag]);
        expect(history.stdout).not.toContain(value);
      }),
    { tags: ["unit", "provider:docker", "local"] },
  );

  it.effect(
    "respects multi-stage --target",
    () =>
      Effect.gen(function* () {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const docker = yield* Docker;
        const tag = "alchemy-docker-test:target";
        yield* Effect.addFinalizer(() =>
          docker.image.remove(tag, true).pipe(
            Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
            Effect.ignore,
          ),
        );
        const root = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-build-" });
        const ctx = path.join(root, "ctx");
        yield* docker.materialize({
          context: ctx,
          dockerfile: [
            "FROM alpine:3.19 AS base",
            "RUN echo base > /stage.txt",
            "",
            "FROM alpine:3.19 AS secondary",
            "RUN echo secondary > /stage.txt",
            "",
          ].join("\n"),
          files: [],
        });
        yield* docker.image.build({ tag, context: ctx, target: "secondary" });
        const out = yield* docker.run(["run", "--rm", tag, "cat", "/stage.txt"]);
        expect(out.stdout.trim()).toBe("secondary");
      }),
    { tags: ["unit", "provider:docker", "local"] },
  );
});