import { hashDockerBuildInputs, resolveDockerBuildPaths } from "@alchemy.run/docker/BuildHash";
import { Docker } from "@alchemy.run/docker/Docker";
import * as ecr from "@distilled.cloud/aws/ecr";
import { createPhysicalName } from "alchemy/PhysicalName";
import { createInternalTags, createTagsList, hasAlchemyTags } from "alchemy/Tags";
import { sha256Object } from "alchemy/Util/sha256";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Schema from "effect/Schema";
import { buildAndPushEcrImage } from "../ECR/Image.ts";
import { AWSEnvironment } from "../Environment.ts";
import { normalizePolicyDocument } from "../IAM/Policy.ts";
import type { FunctionImageConfig } from "./Function.ts";
export class FunctionImageInvalidProps extends Data.TaggedError("FunctionImageInvalidProps")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class FunctionImageNotReady extends Data.TaggedError("FunctionImageNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class FunctionImageOperationFailed extends Data.TaggedError("FunctionImageOperationFailed")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class FunctionImageUnexpectedResponse extends Data.TaggedError(
"FunctionImageUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
/** A Lambda container image built from a local Docker context. */
export interface FunctionDockerImageSource extends FunctionImageConfig {
uri?: never;
/** Docker build context directory. */
context: string;
/** Dockerfile path, relative to {@link context} unless absolute. */
dockerfile: string;
/**
* Docker build arguments (`--build-arg`).
*
* Build arguments are stored in deployment state and may be retained in
* image layers. Do not use them for secrets.
*/
buildArgs?: Record<string, string>;
}
/** An existing private ECR image, addressed by tag or immutable digest. */
export interface FunctionEcrImageSource extends FunctionImageConfig {
/**
* Full private ECR image URI, including a tag or digest.
*
* The repository must be in the same AWS Region as the Lambda function.
* Alchemy observes the current ECR digest on every plan, so repointing a
* tag updates the function even when the URI string itself is unchanged.
*/
uri: string;
context?: never;
dockerfile?: never;
buildArgs?: never;
}
/**
* Image input for an image-packaged Lambda function.
*
* Source values must be literal because Lambda's circular-dependency
* pre-create phase needs the deployable image before normal Output resolution.
*/
export type FunctionImageSource = FunctionDockerImageSource | FunctionEcrImageSource;
// Instruction overrides ride along on the source object; they are function
// configuration, not image identity, so they never enter the image hash.
const FunctionImageConfigFields = {
command: Schema.String.pipe(Schema.Array, Schema.optionalKey),
entryPoint: Schema.String.pipe(Schema.Array, Schema.optionalKey),
workingDirectory: Schema.optionalKey(Schema.String),
};
const FunctionDockerImageSourceSchema = Schema.Struct({
context: Schema.String,
dockerfile: Schema.String,
buildArgs: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
...FunctionImageConfigFields,
}) satisfies Schema.Schema<FunctionDockerImageSource>;
const FunctionEcrImageSourceSchema = Schema.Struct({
uri: Schema.String,
...FunctionImageConfigFields,
}) satisfies Schema.Schema<FunctionEcrImageSource>;
const FunctionImageSourceRecordSchema = Schema.Record(Schema.String, Schema.Unknown);
export interface ParsedFunctionImageUri {
uri: string;
registryId: string;
registryHost: string;
region: string;
repositoryName: string;
repositoryUri: string;
imageId: { imageTag: string } | { imageDigest: string };
}
/** Parse and validate a tagged or digest-pinned private ECR image URI. */
export const parseFunctionImageUri = Effect.fn("AWS.Lambda.parseImageUri")(function* (
id: string,
uri: string,
) {
const slash = uri.indexOf("/");
if (slash <= 0 || slash === uri.length - 1) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri must be a private ECR image URI including a tag or digest`,
});
}
const registryHost = uri.slice(0, slash);
const registry = /^(\d{12})\.dkr\.ecr(-fips)?\.([a-z0-9-]+)\.(.+)$/.exec(registryHost);
if (registry === null) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri must use a private ECR registry such as 123456789012.dkr.ecr.us-east-1.amazonaws.com/repository:tag`,
});
}
if (registry[2] !== undefined) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): Lambda container images do not support ECR FIPS endpoints`,
});
}
const reference = uri.slice(slash + 1);
const digestSeparator = reference.lastIndexOf("@");
const tagSeparator = reference.lastIndexOf(
":",
digestSeparator >= 0 ? digestSeparator : reference.length,
);
if (digestSeparator >= 0 && tagSeparator >= 0) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri must identify the image by either tag or digest, not both`,
});
}
const repositoryName = reference.slice(0, digestSeparator >= 0 ? digestSeparator : tagSeparator);
if (repositoryName.length === 0) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri has no ECR repository name`,
});
}
const resolveImageId = Effect.gen(function* () {
if (digestSeparator >= 0) {
const imageDigest = reference.slice(digestSeparator + 1);
if (!/^sha256:[0-9a-f]{64}$/.test(imageDigest)) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri digest must be sha256 followed by 64 lowercase hexadecimal characters`,
});
}
return { imageDigest } as const;
}
if (tagSeparator <= 0 || tagSeparator === reference.length - 1) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri must include an explicit ECR tag or digest`,
});
}
return { imageTag: reference.slice(tagSeparator + 1) } as const;
});
const imageId = yield* resolveImageId;
return {
uri,
registryId: registry[1],
registryHost,
region: registry[3],
repositoryName,
repositoryUri: `${registryHost}/${repositoryName}`,
imageId,
} satisfies ParsedFunctionImageUri;
});
export interface FunctionImageAttributes {
/** Image source kind used by the Function. */
source: "build" | "uri";
/** Stable identity hash for the requested URI and resolved image digest. */
hash: string;
/** Tag- or digest-based URI passed to Lambda. */
imageUri: string;
/** Digest-pinned URI resolved from ECR. */
resolvedImageUri: string;
/** Registry manifest digest. */
digest: string;
/** Backing ECR repository name. */
repositoryName: string;
/** Backing ECR repository URI. */
repositoryUri: string;
/** Whether the Function owns and may delete the backing repository. */
ownsRepository: boolean;
}
export interface ResolveFunctionImageOptions {
id: string;
source: FunctionImageSource;
architecture: "x86_64" | "arm64";
previousImage?: Omit<FunctionImageAttributes, "hash">;
session: { note: (message: string) => Effect.Effect<void> };
}
export interface FunctionImageIdentity {
source: "build" | "uri";
hash: string;
imageUri?: string;
resolvedImageUri?: string;
}
/**
* Increment when the Lambda image build behavior changes in a way that must
* invalidate already-pushed content-addressed images.
*/
const functionImageBuilderVersion = 2;
export const functionImagePlatform = (architecture: "x86_64" | "arm64") => {
if (architecture === "x86_64") {
return "linux/amd64";
}
if (architecture === "arm64") {
return "linux/arm64";
}
throw new Error(`Unsupported Lambda image architecture: ${architecture as string}`);
};
const hashDecodedFunctionImageBuild = Effect.fn(function* (
source: FunctionDockerImageSource,
architecture: "x86_64" | "arm64",
) {
const buildHash = yield* hashDockerBuildInputs(
{
...source,
platform: functionImagePlatform(architecture),
},
"effective",
);
return (yield* sha256Object({
builderVersion: functionImageBuilderVersion,
buildHash,
})).slice(0, 32);
});
/**
* Hash the Docker build context, Dockerfile, build args, target platform, and
* Lambda image-builder version without including absolute paths.
*/
export const hashFunctionImageBuild = Effect.fn(function* (
source: FunctionDockerImageSource,
architecture: "x86_64" | "arm64",
) {
const decoded = yield* Schema.decodeEffect(FunctionDockerImageSourceSchema)(source);
return yield* hashDecodedFunctionImageBuild(decoded, architecture);
});
export const decodeFunctionImageSource = Effect.fn("AWS.Lambda.decodeFunctionImageSource")(
function* (id: string, source: unknown) {
const record = yield* Schema.decodeUnknownEffect(FunctionImageSourceRecordSchema)(source).pipe(
Effect.mapError(
(error) =>
new FunctionImageInvalidProps({
message: `Function(${id}): image must be an object`,
cause: error,
}),
),
);
const hasUri = record.uri !== undefined;
const hasBuildSource =
record.context !== undefined ||
record.dockerfile !== undefined ||
record.buildArgs !== undefined;
if (hasUri && hasBuildSource) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image.uri cannot be combined with image.context, image.dockerfile, or image.buildArgs; declare exactly one image source`,
});
}
if (!hasUri && !hasBuildSource) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): image must declare either image.uri or both image.context and image.dockerfile`,
});
}
const decodeError = (error: unknown) =>
new Error(
`Function(${id}): image source values must be literal and valid before Lambda pre-create`,
{ cause: error },
);
if (hasUri) {
return yield* Schema.decodeUnknownEffect(FunctionEcrImageSourceSchema)(source).pipe(
Effect.map((decoded): FunctionEcrImageSource => decoded),
Effect.mapError(decodeError),
);
}
return yield* Schema.decodeUnknownEffect(FunctionDockerImageSourceSchema)(source).pipe(
Effect.map((decoded): FunctionDockerImageSource => decoded),
Effect.mapError(decodeError),
);
},
);
const isFunctionEcrImageSource = (source: FunctionImageSource): source is FunctionEcrImageSource =>
source.uri !== undefined;
/**
* Lambda-specific image resolver. It deliberately stays separate from the
* ECS/EKS image-source abstraction because Lambda deploys private ECR images
* directly and its managed local-build path owns a repository pull policy.
*/
export const makeFunctionImage = Effect.gen(function* () {
const docker = yield* Docker;
const createRepositoryName = (id: string) =>
createPhysicalName({
id: `${id}-image`,
maxLength: 256,
lowercase: true,
});
const desiredRepositoryPolicy = Effect.fn(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
return JSON.stringify({
Version: "2012-10-17",
Statement: [
{
Sid: "LambdaECRImageRetrievalPolicy",
Effect: "Allow",
Principal: { Service: "lambda.amazonaws.com" },
Action: ["ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer"],
Condition: {
StringLike: {
"aws:sourceArn": `arn:aws:lambda:${region}:${accountId}:function:*`,
},
},
},
],
});
});
const ensureRepository = Effect.fn(function* (id: string, repositoryName: string) {
let repository = yield* ecr.describeRepositories({ repositoryNames: [repositoryName] }).pipe(
Effect.map((response) => response.repositories?.[0]),
Effect.catchTag("RepositoryNotFoundException", () => Effect.undefined),
);
if (!repository?.repositoryArn || !repository.repositoryUri) {
const tags = yield* createInternalTags(id);
repository = yield* ecr
.createRepository({
repositoryName,
imageTagMutability: "IMMUTABLE",
imageScanningConfiguration: { scanOnPush: true },
tags: createTagsList(tags),
})
.pipe(
Effect.map((response) => response.repository),
Effect.catchTag("RepositoryAlreadyExistsException", () =>
ecr
.describeRepositories({ repositoryNames: [repositoryName] })
.pipe(Effect.map((response) => response.repositories?.[0])),
),
);
}
if (!repository?.repositoryArn || !repository.repositoryUri) {
return yield* Effect.die(
new Error(`Failed to create or read Lambda image repository '${repositoryName}'`),
);
}
const tags = yield* ecr.listTagsForResource({
resourceArn: repository.repositoryArn,
});
if (!(yield* hasAlchemyTags(id, tags.tags))) {
return yield* Effect.die(
new Error(
`Lambda image repository '${repositoryName}' exists but is not owned by Function(${id})`,
),
);
}
// Tags are content hashes, so changing what an existing tag references
// would violate the identity contract used by Lambda deployment state.
// Verify ownership before migrating repositories created by older versions.
if (repository.imageTagMutability !== "IMMUTABLE") {
yield* ecr.putImageTagMutability({
repositoryName,
imageTagMutability: "IMMUTABLE",
});
}
const desiredPolicy = yield* desiredRepositoryPolicy();
const observedPolicy = yield* ecr.getRepositoryPolicy({ repositoryName }).pipe(
Effect.map((response) => response.policyText),
Effect.catchTag("RepositoryPolicyNotFoundException", () => Effect.undefined),
);
if (
observedPolicy === undefined ||
normalizePolicyDocument(observedPolicy) !== normalizePolicyDocument(desiredPolicy)
) {
yield* ecr.setRepositoryPolicy({
repositoryName,
policyText: desiredPolicy,
});
}
return {
repositoryName,
repositoryUri: repository.repositoryUri,
};
});
const describeImage = Effect.fn(function* (repositoryName: string, imageTag: string) {
const response = yield* ecr
.describeImages({
repositoryName,
imageIds: [{ imageTag }],
})
.pipe(
Effect.catchTag(
["ImageNotFoundException", "RepositoryNotFoundException"],
() => Effect.undefined,
),
);
return response?.imageDetails?.[0];
});
const resolveExternalImage = Effect.fn("AWS.Lambda.resolveExternalImage")(function* (
id: string,
source: FunctionEcrImageSource,
previousImage?: Omit<FunctionImageAttributes, "hash">,
) {
const parsed = yield* parseFunctionImageUri(id, source.uri);
const { region } = yield* AWSEnvironment.current;
if (parsed.region !== region) {
return yield* new FunctionImageInvalidProps({
message: `Function(${id}): ECR image region '${parsed.region}' must match Lambda region '${region}'`,
});
}
const detail = yield* ecr
.describeImages({
registryId: parsed.registryId,
repositoryName: parsed.repositoryName,
imageIds: [parsed.imageId],
})
.pipe(
Effect.catchTag(["ImageNotFoundException", "RepositoryNotFoundException"], () =>
Effect.fail(
new FunctionImageOperationFailed({
message: `Function(${id}): ECR image '${source.uri}' does not exist or is not accessible`,
}),
),
),
Effect.map((response) => response.imageDetails?.[0]),
);
const digest = detail?.imageDigest;
if (digest === undefined) {
return yield* new FunctionImageUnexpectedResponse({
message: `Function(${id}): ECR image '${source.uri}' did not resolve to a registry digest`,
});
}
const hash = (yield* sha256Object({ uri: source.uri, digest })).slice(0, 32);
return {
source: "uri",
hash,
imageUri: source.uri,
resolvedImageUri: `${parsed.repositoryUri}@${digest}`,
digest,
repositoryName: parsed.repositoryName,
repositoryUri: parsed.repositoryUri,
ownsRepository:
previousImage?.ownsRepository === true &&
previousImage.repositoryUri === parsed.repositoryUri,
} satisfies FunctionImageAttributes;
});
const identity = Effect.fn(function* (
id: string,
source: FunctionImageSource,
architecture: "x86_64" | "arm64",
) {
const decoded = yield* decodeFunctionImageSource(id, source);
if (isFunctionEcrImageSource(decoded)) {
const external = yield* resolveExternalImage(id, decoded);
return {
source: external.source,
hash: external.hash,
imageUri: external.imageUri,
resolvedImageUri: external.resolvedImageUri,
} satisfies FunctionImageIdentity;
}
return {
source: "build",
hash: yield* hashDecodedFunctionImageBuild(decoded, architecture),
} satisfies FunctionImageIdentity;
});
const hash = Effect.fn(function* (
id: string,
source: FunctionImageSource,
architecture: "x86_64" | "arm64",
) {
return (yield* identity(id, source, architecture)).hash;
});
const resolve = Effect.fn(function* (options: ResolveFunctionImageOptions) {
const source = yield* decodeFunctionImageSource(options.id, options.source);
if (isFunctionEcrImageSource(source)) {
const image = yield* resolveExternalImage(options.id, source, options.previousImage);
yield* options.session.note(image.imageUri);
return image;
}
const imageTag = yield* hashDecodedFunctionImageBuild(source, options.architecture);
const repositoryName =
options.previousImage?.ownsRepository === true
? options.previousImage.repositoryName
: yield* createRepositoryName(options.id);
// Re-ensure even with persisted metadata: the repository or its Lambda
// pull policy may have drifted out-of-band.
const ensured = yield* ensureRepository(options.id, repositoryName);
const imageUri = `${ensured.repositoryUri}:${imageTag}`;
let detail = yield* describeImage(repositoryName, imageTag);
if (!detail?.imageDigest) {
const build = yield* resolveDockerBuildPaths(source);
yield* options.session.note(`Building Lambda image ${imageUri}...`);
const pushed = yield* buildAndPushEcrImage(docker, {
imageUri,
context: build.context,
dockerfile: build.dockerfile,
platform: functionImagePlatform(options.architecture),
buildArgs: source.buildArgs,
args: ["--provenance=false"],
}).pipe(
Effect.as(true),
Effect.catch((buildError) =>
// Two reconcilers can both observe a missing tag and build it. With
// immutable tags, the second push loses the race. Accept that failure
// only when ECR proves the desired content-addressed tag now exists.
describeImage(repositoryName, imageTag).pipe(
Effect.flatMap((image) =>
image?.imageDigest !== undefined ? Effect.succeed(false) : Effect.fail(buildError),
),
),
),
);
detail = yield* describeImage(repositoryName, imageTag).pipe(
Effect.filterOrFail(
(image) => image?.imageDigest !== undefined,
() =>
new FunctionImageNotReady({ message: `Image ${imageUri} not found in ECR after push` }),
),
Effect.retry({
schedule: Schedule.spaced("1 second"),
times: 8,
}),
);
yield* options.session.note(
pushed ? `Pushed ${imageUri}` : `Reused concurrently pushed ${imageUri}`,
);
}
const digest = detail?.imageDigest;
if (digest === undefined) {
return yield* new FunctionImageUnexpectedResponse({
message: `Image ${imageUri} has no registry digest after push`,
});
}
return {
source: "build",
hash: imageTag,
imageUri,
resolvedImageUri: `${ensured.repositoryUri}@${digest}`,
digest,
repositoryName,
repositoryUri: ensured.repositoryUri,
ownsRepository: true,
} satisfies FunctionImageAttributes;
});
const deleteRepository = (repositoryName: string) =>
ecr
.deleteRepository({ repositoryName, force: true })
.pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
const isReady = Effect.fn(function* (id: string, repositoryName: string, imageTag: string) {
const repository = yield* ecr.describeRepositories({ repositoryNames: [repositoryName] }).pipe(
Effect.map((response) => response.repositories?.[0]),
Effect.catchTag("RepositoryNotFoundException", () => Effect.undefined),
);
if (
repository?.repositoryArn === undefined ||
repository.repositoryUri === undefined ||
repository.imageTagMutability !== "IMMUTABLE"
) {
return false;
}
const [tags, observedPolicy, image] = yield* Effect.all(
[
ecr
.listTagsForResource({ resourceArn: repository.repositoryArn })
.pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.undefined)),
ecr.getRepositoryPolicy({ repositoryName }).pipe(
Effect.map((response) => response.policyText),
Effect.catchTag(
["RepositoryNotFoundException", "RepositoryPolicyNotFoundException"],
() => Effect.undefined,
),
),
describeImage(repositoryName, imageTag),
] as const,
{ concurrency: 3 },
);
if (tags === undefined || !(yield* hasAlchemyTags(id, tags.tags))) {
return false;
}
const desiredPolicy = yield* desiredRepositoryPolicy();
return (
observedPolicy !== undefined &&
normalizePolicyDocument(observedPolicy) === normalizePolicyDocument(desiredPolicy) &&
image?.imageDigest !== undefined
);
});
return { hash, identity, resolve, isReady, deleteRepository };
});
export interface FunctionImage extends Effect.Success<typeof makeFunctionImage> {}