sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ECR/ Image.ts

import { hashDockerBuildInputs, resolveDockerBuildPaths } from "@alchemy.run/docker/BuildHash";
import { Docker } from "@alchemy.run/docker/Docker";
import * as ecr from "@distilled.cloud/aws/ecr";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export class ImageUnexpectedResponse extends Data.TaggedError("ImageUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * Docker login credentials for the account's private ECR registry, in the
 * shape `Docker.image.push` expects. The password is the decoded ECR bearer
 * token — a credential — so it is carried as `Redacted` and only unwrapped
 * inside `docker push`'s ephemeral auth config.
 */
export interface EcrRegistryCredentials {
  username: string;
  password: Redacted.Redacted<string>;
  server: string;
}

/**
 * Resolves Docker login credentials for the account's private ECR registry
 * by decoding `ecr.getAuthorizationToken`.
 */
export const getEcrRegistryCredentials = Effect.gen(function* () {
  const auth = yield* ecr.getAuthorizationToken({});
  const authData = auth.authorizationData?.[0];
  const token = authData?.authorizationToken;
  const proxyEndpoint = authData?.proxyEndpoint;
  if (!token || !proxyEndpoint) {
    return yield* Effect.die(new Error("Failed to get ECR authorization token"));
  }
  const password = yield* Effect.sync(() => {
    const raw = Redacted.isRedacted(token) ? Redacted.value(token) : token;
    const decoded = Buffer.from(raw, "base64").toString("utf8");
    const [, secret] = decoded.split(":", 2);
    return Redacted.make(secret);
  });
  return {
    username: "AWS",
    password,
    server: proxyEndpoint.replace(/^https?:\/\//, ""),
  } satisfies EcrRegistryCredentials;
});

/**
 * Builds a Docker image from a local context and pushes it to the account's
 * private ECR registry. Shared by the `ECR.Image` provider and the
 * `ECS.Task` runtime resource (which materializes a generated Dockerfile
 * into its bundle context before delegating here).
 */
export const buildAndPushEcrImage = Effect.fn(function* (
  docker: Docker["Service"],
  options: {
    /** Full image reference to build and push, e.g. `<repositoryUri>:<tag>`. */
    imageUri: string;
    /** Docker build context directory. */
    context: string;
    /** Absolute path to the Dockerfile. Defaults to `Dockerfile` in `context`. */
    dockerfile?: string;
    /** Target platform, e.g. `"linux/amd64"`. */
    platform?: string;
    /** Docker build arguments. */
    buildArgs?: Record<string, string>;
    /** Additional arguments appended to `docker image build`. */
    args?: string[];
  },
) {
  const credentials = yield* getEcrRegistryCredentials;
  yield* docker.image.build({
    tag: options.imageUri,
    context: options.context,
    file: options.dockerfile,
    platform: options.platform,
    "build-arg": options.buildArgs,
    args: options.args,
  });
  // Pushes are idempotent; transient registry-transport failures (Docker
  // Desktop's embedded proxy timing out under load, ECR 503s, credential
  // helper contention) resolve on a bounded re-attempt.
  yield* docker.image.push(options.imageUri, credentials).pipe(
    Effect.retry({
      while: (): boolean => true,
      schedule: Schedule.exponential("2 seconds"),
      times: 3,
    }),
  );
  return options.imageUri;
});

export interface ImageProps {
  /**
   * URI of the target ECR repository, e.g. `repository.repositoryUri` from an
   * `ECR.Repository`. When omitted, the Image auto-creates (and owns) a
   * repository whose name is derived from the logical id; the owned
   * repository is force-deleted when the Image is destroyed.
   */
  repositoryUri?: string;
  /**
   * Docker build context directory. The files Docker receives from the
   * context (after `.dockerignore`), plus the Dockerfile, platform, and build
   * args, participate in the content hash that identifies the image. Ignored
   * files are never read and never change the tag. An existing image with the
   * same hash is reused; missing images are rebuilt and pushed to the desired
   * repository.
   */
  context: string;
  /**
   * Path to the Dockerfile, relative to `context` unless absolute.
   * @default "Dockerfile"
   */
  dockerfile?: string;
  /**
   * Target platform for the image build. Fargate defaults to X86_64, so the
   * default pins `linux/amd64` — without it an image built on an ARM64 host
   * (e.g. Apple Silicon) is rejected at task start.
   * @default "linux/amd64"
   */
  platform?: string;
  /**
   * Docker build arguments (`--build-arg`).
   */
  buildArgs?: Record<string, string>;
}

export interface Image extends Resource<
  "AWS.ECR.Image",
  ImageProps,
  {
    /** Full image reference, `<repositoryUri>:<imageTag>`. */
    imageUri: string;
    /** Registry manifest digest, e.g. `sha256:...`. */
    digest: string;
    /** URI of the repository the image was pushed to. */
    repositoryUri: string;
    /** Name of the repository the image was pushed to. */
    repositoryName: string;
    /** Content-hash tag the image was pushed under. */
    imageTag: string;
    /** Whether this Image auto-created (and owns) the backing repository. */
    ownsRepository: boolean;
  },
  never,
  Providers
> {}

/**
 * A Docker image built from a local context and pushed to a private Amazon
 * ECR repository.
 *
 * The image is identified by a content hash over the build context,
 * Dockerfile, platform, and build args. An existing image with that hash is
 * reused; a missing image is rebuilt and pushed. A content change produces a
 * new tag on the same resource, so replacement is never needed.
 *
 * ### Building Images
 * **Example:** Push to an ECR Repository
 * ```typescript
 * const repository = yield* AWS.ECR.Repository("AppRepository", {});
 * const image = yield* AWS.ECR.Image("AppImage", {
 *   repositoryUri: repository.repositoryUri,
 *   context: "./app",
 * });
 * ```
 *
 * **Example:** Auto-created Repository
 * ```typescript
 * const image = yield* AWS.ECR.Image("AppImage", {
 *   context: "./app",
 * });
 * ```
 *
 * ### Moving an Unchanged Build Context
 * **Example:** Relocate identical build inputs without rebuilding
 * ```diff
 * const image = yield* AWS.ECR.Image("AppImage", {
 *   repositoryUri: repository.repositoryUri,
 * -  context: "./app",
 * +  context: "./relocated-app",
 * });
 * ```
 *
 * Absolute paths are not part of the image's identity. With identical build
 * inputs and the same repository setting, this plans a no-op. Content,
 * Dockerfile, platform, build-argument, and repository changes still update
 * the image. A deleted image or auto-created repository is recreated on deploy.
 *
 * ### Ignoring Files with `.dockerignore`
 * **Example:** Build from the repository root
 * ```typescript
 * // .dockerignore next to the context keeps node_modules/ and target/ out
 * const image = yield* AWS.ECR.Image("ServiceImage", {
 *   repositoryUri: repository.repositoryUri,
 *   context: "..",
 *   dockerfile: "docker/service.Dockerfile",
 * });
 * ```
 *
 * The content hash covers only the files Docker receives, so ignored trees
 * are never read and a local `bun install` or `cargo build` does not change
 * the tag. A `<Dockerfile>.dockerignore` takes precedence over the context's
 * `.dockerignore`, as in Docker.
 *
 * ### Build Configuration
 * **Example:** Custom Dockerfile, Platform, and Build Args
 * ```typescript
 * const image = yield* AWS.ECR.Image("WorkerImage", {
 *   repositoryUri: repository.repositoryUri,
 *   context: "./worker",
 *   dockerfile: "Dockerfile.worker",
 *   platform: "linux/arm64",
 *   buildArgs: { NODE_ENV: "production" },
 * });
 * ```
 *
 * ### Consuming the Image
 * **Example:** Reference from a Task Definition
 * ```typescript
 * const task = yield* AWS.ECS.Task("ApiTask", {
 *   main: import.meta.url,
 *   sidecars: [{ name: "proxy", image: image.imageUri, essential: false }],
 * });
 * ```
 *
 * @resource
 */
export const Image = Resource<Image>("AWS.ECR.Image");

/** Derives the repository name from a repository URI (`<registry>/<name>`). */
const repositoryNameFromUri = (repositoryUri: string) =>
  repositoryUri.split("/").slice(1).join("/");

export const ImageProvider = () =>
  Provider.effect(
    Image,
    Effect.gen(function* () {
      const docker = yield* Docker;

      const toOwnedRepositoryName = (id: string) =>
        createPhysicalName({
          id,
          maxLength: 256,
          lowercase: true,
        });

      // Content hash over everything that affects the built image: the
      // Dockerfile, the context files `.dockerignore` keeps (relative path + bytes),
      // the target platform, and the build args. Absolute paths deliberately
      // do NOT participate, so relocating an identical context (e.g. a temp
      // dir) produces the same tag.
      const hashBuildInputs = (props: ImageProps) =>
        hashDockerBuildInputs(
          {
            context: props.context,
            dockerfile: props.dockerfile ?? "Dockerfile",
            platform: props.platform ?? "linux/amd64",
            buildArgs: props.buildArgs,
          },
          "effective",
        );

      // Observe the pushed image in ECR. Missing repository or tag → undefined.
      const describeImage = Effect.fn(function* (repositoryName: string, imageTag: string) {
        const described = yield* ecr
          .describeImages({
            repositoryName,
            imageIds: [{ imageTag }],
          })
          .pipe(
            Effect.catchTag(
              ["ImageNotFoundException", "RepositoryNotFoundException"],
              () => Effect.undefined,
            ),
          );
        return described?.imageDetails?.[0];
      });

      // Ensure the auto-created repository exists. Idempotent: tolerates
      // `RepositoryAlreadyExistsException` as a race / re-run and re-describes.
      const ensureOwnedRepository = Effect.fn(function* (id: string, repositoryName: string) {
        const internalTags = yield* createInternalTags(id);
        const created = yield* ecr
          .createRepository({
            repositoryName,
            imageTagMutability: "MUTABLE",
            tags: Object.entries(internalTags).map(([Key, Value]) => ({
              Key,
              Value,
            })),
          })
          .pipe(
            Effect.catchTag("RepositoryAlreadyExistsException", () =>
              ecr
                .describeRepositories({ repositoryNames: [repositoryName] })
                .pipe(Effect.map((res) => ({ repository: res.repositories?.[0] }))),
            ),
          );
        const repositoryUri = created.repository?.repositoryUri;
        if (!repositoryUri) {
          return yield* new ImageUnexpectedResponse({
            message: `Failed to create or read ECR repository '${repositoryName}'`,
          });
        }
        return repositoryUri;
      });

      return {
        read: Effect.fn(function* ({ output }) {
          // The content hash cannot be recovered without running a build, so
          // a lost-state read has nothing to look up.
          if (!output) return undefined;
          const detail = yield* describeImage(output.repositoryName, output.imageTag);
          if (!detail?.imageDigest) return undefined;
          return { ...output, digest: detail.imageDigest };
        }),
        // Content changes don't change Props (the context path stays the
        // same while the files under it change), so surface them here: hash
        // the build inputs and request an update when the hash drifts from
        // the pushed tag. Replacement is never needed — a new hash is just a
        // new tag + digest on the same resource.
        diff: Effect.fn(function* ({ news, output, olds }) {
          if (!isResolved(news) || !output) return undefined;
          const hash = yield* hashBuildInputs(news);
          if (hash !== output.imageTag || olds.repositoryUri !== news.repositoryUri) {
            return { action: "update" } as const;
          }
          const image = yield* describeImage(output.repositoryName, hash);
          if (!image?.imageDigest) return { action: "update" } as const;
          // Build paths may move without changing an existing image.
          return { action: "noop" } as const;
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // Resolve the target repository: user-supplied URI, or an
          // auto-created repository owned by this Image.
          const resolveRepository = Effect.gen(function* () {
            if (news.repositoryUri) {
              return {
                repositoryName: repositoryNameFromUri(news.repositoryUri),
                repositoryUri: news.repositoryUri,
                ownsRepository: false,
              };
            }
            const repositoryName = output?.ownsRepository
              ? output.repositoryName
              : yield* toOwnedRepositoryName(id);
            const repositoryUri = yield* ensureOwnedRepository(id, repositoryName);
            return { repositoryName, repositoryUri, ownsRepository: true };
          });
          const { repositoryName, repositoryUri, ownsRepository } = yield* resolveRepository;

          const { context, dockerfile } = yield* resolveDockerBuildPaths({
            context: news.context,
            dockerfile: news.dockerfile ?? "Dockerfile",
          });
          const imageTag = yield* hashBuildInputs(news);
          const imageUri = `${repositoryUri}:${imageTag}`;

          // Observe — if this exact content hash is already pushed, there is
          // nothing to build (crash-safe: a re-run after a mid-reconcile
          // failure converges without a rebuild).
          const observed = yield* describeImage(repositoryName, imageTag);
          if (observed?.imageDigest) {
            yield* session.note(imageUri);
            return {
              imageUri,
              digest: observed.imageDigest,
              repositoryUri,
              repositoryName,
              imageTag,
              ownsRepository,
            };
          }

          yield* session.note(`building ${imageUri}`);
          yield* buildAndPushEcrImage(docker, {
            imageUri,
            context,
            dockerfile,
            platform: news.platform ?? "linux/amd64",
            buildArgs: news.buildArgs,
            // Engines using the containerd image store attach provenance
            // attestations by default, turning the pushed tag into an OCI
            // image index — which Lambda (a valid consumer of these images)
            // rejects. Disable: single-manifest pushes work everywhere.
            args: ["--provenance=false"],
          });

          const pushed = yield* describeImage(repositoryName, imageTag);
          if (!pushed?.imageDigest) {
            return yield* new ImageUnexpectedResponse({
              message: `Image ${imageUri} not found in ECR after push`,
            });
          }
          yield* session.note(imageUri);
          return {
            imageUri,
            digest: pushed.imageDigest,
            repositoryUri,
            repositoryName,
            imageTag,
            ownsRepository,
          };
        }),
        // Enumerate every tagged image across every repository in the
        // account/region. Repository ownership is recorded per-instance in
        // state and cannot be recovered from enumeration, so listed items are
        // conservatively marked `ownsRepository: false` — orphan deletion
        // removes the tag but leaves the repository (ECR.Repository's own
        // list()/delete() covers repositories).
        list: () =>
          Effect.gen(function* () {
            const repositories = yield* ecr.describeRepositories.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.repositories ?? [])),
            );
            const nested = yield* Effect.forEach(
              repositories.filter(
                (
                  r,
                ): r is ecr.Repository & {
                  repositoryName: string;
                  repositoryUri: string;
                } => r.repositoryName != null && r.repositoryUri != null,
              ),
              (repository) =>
                ecr.describeImages.pages({ repositoryName: repository.repositoryName }).pipe(
                  Stream.runCollect,
                  Effect.map((chunk) =>
                    Array.from(chunk).flatMap((page) => page.imageDetails ?? []),
                  ),
                  Effect.map((details) =>
                    details.flatMap((detail) =>
                      detail.imageDigest === undefined
                        ? []
                        : (detail.imageTags ?? []).map((imageTag) => ({
                            imageUri: `${repository.repositoryUri}:${imageTag}`,
                            digest: detail.imageDigest!,
                            repositoryUri: repository.repositoryUri,
                            repositoryName: repository.repositoryName,
                            imageTag,
                            ownsRepository: false,
                          })),
                    ),
                  ),
                  // Repository deleted between the list and the describe.
                  Effect.catchTag("RepositoryNotFoundException", () => Effect.succeed([])),
                ),
              { concurrency: 10 },
            );
            return nested.flat();
          }),
        delete: Effect.fn(function* ({ output }) {
          if (output.ownsRepository) {
            yield* ecr
              .deleteRepository({
                repositoryName: output.repositoryName,
                force: true,
              })
              .pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
            return;
          }
          // Foreign repository: delete only our tag. `batchDeleteImage`
          // reports a missing image via its `failures` array (not an error),
          // so this is naturally idempotent.
          yield* ecr
            .batchDeleteImage({
              repositoryName: output.repositoryName,
              imageIds: [{ imageTag: output.imageTag }],
            })
            .pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
        }),
      };
    }),
  );