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));
}),
};
}),
);