sailfork / t3code-github / .repos/ alchemy-effect/ packages/ docker/ src/ BuildHash.ts

/**
 * 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 Data from "effect/Data";
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 class BuildHashInvalidProps extends Data.TaggedError("BuildHashInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

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* new BuildHashInvalidProps({
      message: `Docker build context does not exist: ${context}`,
    });
  }
  if (!(yield* fs.exists(dockerfile))) {
    return yield* new BuildHashInvalidProps({
      message: `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);
});