sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Lambda/ FunctionImage.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 { 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> {}