sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ImageBuilder/ ImageRecipe.ts

import * as imagebuilder from "@distilled.cloud/aws/imagebuilder";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  deleteImageBuilderLogGroup,
  imageBuilderArn,
  immutableVersionKeysChanged,
  retryWhileDependedOn,
  syncImageBuilderTags,
  toTagRecord,
} from "./internal.ts";

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

/**
 * Image Builder image recipe versions are immutable — the deployed recipe
 * differs from the desired one but the semantic version was not bumped, so
 * the cloud state cannot be converged.
 */
export class ImageRecipeVersionImmutable extends Data.TaggedError(
  "AWS::ImageBuilder::ImageRecipeVersionImmutable",
)<{
  message: string;
}> {}

export interface RecipeComponentParameter {
  /** Name of the component parameter to set. */
  name: string;
  /** Value(s) to assign to the parameter. */
  value: string[];
}

export interface RecipeComponent {
  /**
   * Build-version ARN of the component to apply
   * (e.g. `component.componentBuildVersionArn`).
   */
  componentArn: string;
  /** Parameter overrides for parameterized components. */
  parameters?: RecipeComponentParameter[];
}

export interface ImageRecipeProps {
  /**
   * Name of the image recipe. If omitted, a deterministic physical name is
   * generated. Changing the name replaces the recipe.
   */
  imageRecipeName?: string;
  /**
   * Semantic version of the recipe (`major.minor.patch`). Recipes are
   * immutable — bump the version when changing any property. Changing the
   * version replaces the recipe.
   * @default "1.0.0"
   */
  semanticVersion?: string;
  /**
   * Base image of the recipe: an Image Builder image ARN (e.g. the
   * AWS-managed `arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x`),
   * an AMI ID, or an SSM parameter reference (`ssm:/path/to/parameter`).
   * Changing the parent image replaces the recipe.
   */
  parentImage: string;
  /**
   * Components applied to the image, in order. Changing the component list
   * replaces the recipe.
   */
  components: RecipeComponent[];
  /**
   * Description of the recipe. Changing it replaces the recipe.
   */
  description?: string;
  /**
   * Block device mappings for instances built from the recipe. Changing
   * them replaces the recipe.
   */
  blockDeviceMappings?: imagebuilder.InstanceBlockDeviceMapping[];
  /**
   * Working directory used during build and test workflows.
   * Changing it replaces the recipe.
   * @default "/tmp"
   */
  workingDirectory?: string;
  /**
   * Additional instance configuration (SSM agent removal, user data
   * override). Changing it replaces the recipe.
   */
  additionalInstanceConfiguration?: imagebuilder.AdditionalInstanceConfiguration;
  /**
   * Tags applied to output AMIs created from the recipe. Changing them
   * replaces the recipe.
   */
  amiTags?: Record<string, string>;
  /**
   * User-defined tags for the recipe.
   */
  tags?: Record<string, string>;
}

export interface ImageRecipe extends Resource<
  "AWS.ImageBuilder.ImageRecipe",
  ImageRecipeProps,
  {
    /** The name of the image recipe. */
    imageRecipeName: string;
    /** The ARN of the image recipe. */
    imageRecipeArn: string;
    /** The semantic version of the recipe. */
    semanticVersion: string;
    /** The OS platform of the recipe (`Linux` / `Windows`). */
    platform: string | undefined;
    /** The base image the recipe builds on. */
    parentImage: string | undefined;
    /** When the recipe was created. */
    dateCreated: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An EC2 Image Builder image recipe — the blueprint that combines a parent
 * image with an ordered list of components to produce a new AMI.
 *
 * Recipes are immutable versions: every property except `tags` replaces the
 * recipe. Bump `semanticVersion` when changing the definition.
 * ### Creating an Image Recipe
 * **Example:** Recipe from an AWS-Managed Parent Image
 * ```typescript
 * const recipe = yield* ImageBuilder.ImageRecipe("Recipe", {
 *   parentImage: "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x",
 *   semanticVersion: "1.0.0",
 *   components: [{ componentArn: component.componentBuildVersionArn }],
 * });
 * ```
 *
 * ### Using in a Pipeline
 * **Example:** Wire into an Image Pipeline
 * ```typescript
 * const pipeline = yield* ImageBuilder.ImagePipeline("Pipeline", {
 *   imageRecipeArn: recipe.imageRecipeArn,
 *   infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
 * });
 * ```
 *
 * @resource
 */
export const ImageRecipe = Resource<ImageRecipe>("AWS.ImageBuilder.ImageRecipe");

export const ImageRecipeProvider = () =>
  Provider.effect(
    ImageRecipe,
    Effect.gen(function* () {
      const toName = (id: string, props: ImageRecipeProps) =>
        props.imageRecipeName
          ? Effect.succeed(props.imageRecipeName)
          : createPhysicalName({ id, maxLength: 126 });

      const toVersion = (props: ImageRecipeProps) => props.semanticVersion ?? "1.0.0";

      const toArn = (name: string, version: string) =>
        imageBuilderArn("image-recipe", `${name}/${version}`);

      const getRecipe = Effect.fn(function* (arn: string) {
        const response = yield* imagebuilder
          .getImageRecipe({ imageRecipeArn: arn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response?.imageRecipe;
      });

      const toAttrs = Effect.fn(function* (recipe: imagebuilder.ImageRecipe) {
        if (!recipe.arn || !recipe.name || !recipe.version) {
          return yield* new ImageRecipeUnexpectedResponse({
            message: "Image Builder image recipe is missing its ARN, name, or version",
          });
        }
        return {
          imageRecipeName: recipe.name,
          imageRecipeArn: recipe.arn,
          semanticVersion: recipe.version,
          platform: recipe.platform,
          parentImage: recipe.parentImage,
          dateCreated: recipe.dateCreated,
        };
      });

      return {
        stables: ["imageRecipeName", "semanticVersion"],

        // Recipes are immutable — any changed property except tags
        // replaces. Individual keys may still hold unresolved Outputs at
        // plan time (e.g. the ARN of a component being replaced in the
        // same deploy); compare per key so a resolved change (like a
        // semanticVersion bump) still plans a replacement, and let the
        // reconcile immutability guard catch drift hidden behind an
        // unresolved key.
        diff: Effect.fn(function* ({ olds, news }) {
          const immutableKeys = [
            "imageRecipeName",
            "semanticVersion",
            "parentImage",
            "components",
            "description",
            "blockDeviceMappings",
            "workingDirectory",
            "additionalInstanceConfiguration",
            "amiTags",
          ] as const;
          if (immutableVersionKeysChanged(olds, news, immutableKeys)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const arn =
            output?.imageRecipeArn ?? (yield* toArn(yield* toName(id, olds), toVersion(olds)));
          const recipe = yield* getRecipe(arn);
          if (recipe === undefined) return undefined;
          const attrs = yield* toAttrs(recipe);
          const tags = toTagRecord(recipe.tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // One idempotency token per reconcile — retries within this run
          // are deduplicated by the API.
          const clientToken = yield* Effect.sync(() => crypto.randomUUID());
          const name = output?.imageRecipeName ?? (yield* toName(id, news));
          const version = output?.semanticVersion ?? toVersion(news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // 1. Observe — the recipe ARN is deterministic from name+version.
          const arn = output?.imageRecipeArn ?? (yield* toArn(name, version));
          let observed = yield* getRecipe(arn);

          // Immutability guard — the version already exists in the cloud
          // with a different definition (e.g. a component was replaced
          // without bumping the recipe version). It cannot be converged in
          // place; the user must bump `semanticVersion`.
          if (observed !== undefined) {
            const observedComponents = (observed.components ?? []).map(
              (component) => component.componentArn,
            );
            const desiredComponents = news.components.map((component) => component.componentArn);
            if (
              !deepEqual(observedComponents, desiredComponents) ||
              observed.parentImage !== news.parentImage
            ) {
              return yield* new ImageRecipeVersionImmutable({
                message: `Image Builder recipe '${name}' version '${version}' already exists with a different definition — bump semanticVersion to publish the change`,
              });
            }
          }

          // 2. Ensure — recipes are immutable; missing is the only create
          //    path.
          if (observed === undefined) {
            const created = yield* imagebuilder.createImageRecipe({
              name,
              semanticVersion: version,
              parentImage: news.parentImage,
              components: news.components,
              description: news.description,
              blockDeviceMappings: news.blockDeviceMappings,
              workingDirectory: news.workingDirectory,
              additionalInstanceConfiguration: news.additionalInstanceConfiguration,
              amiTags: news.amiTags,
              tags: desiredTags,
              clientToken,
            });
            if (!created.imageRecipeArn) {
              return yield* new ImageRecipeUnexpectedResponse({
                message: "CreateImageRecipe returned no imageRecipeArn",
              });
            }
            observed = yield* getRecipe(created.imageRecipeArn);
            if (observed === undefined) {
              return yield* new ImageRecipeUnexpectedResponse({
                message: `created Image Builder recipe '${name}' is not readable`,
              });
            }
          }

          // 3. Sync — tags are the only mutable aspect.
          if (observed.arn) {
            yield* syncImageBuilderTags(observed.arn, desiredTags);
          }

          // 4. Return fresh attributes.
          yield* session.note(name);
          return yield* toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileDependedOn(
            imagebuilder.deleteImageRecipe({
              imageRecipeArn: output.imageRecipeArn,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));

          // Do not discard state until Image Builder confirms the owned
          // version is gone. The auto-created recipe log group is shared by
          // every version with the same name, so delete it only when no live
          // same-name recipe remains (including a replacement version).
          for (let attempt = 0; attempt < 30; attempt++) {
            if ((yield* getRecipe(output.imageRecipeArn)) === undefined) break;
            if (attempt === 29) {
              return yield* Effect.die(
                new Error(
                  `Image Builder recipe ${output.imageRecipeArn} remained observable 30 seconds after delete`,
                ),
              );
            }
            yield* Effect.sleep("1 second");
          }

          const summaries = yield* imagebuilder.listImageRecipes.pages({ owner: "Self" }).pipe(
            Stream.runCollect,
            Effect.map((pages) =>
              Array.from(pages).flatMap((page) => page.imageRecipeSummaryList ?? []),
            ),
          );
          const sameName = summaries.filter(
            (summary) => summary.name === output.imageRecipeName && summary.arn !== undefined,
          );
          const liveSameName = yield* Effect.forEach(
            sameName,
            (summary) => getRecipe(summary.arn!),
            { concurrency: 4 },
          );
          if (liveSameName.every((recipe) => recipe === undefined)) {
            yield* deleteImageBuilderLogGroup(`/aws/imagebuilder/${output.imageRecipeName}`);
          }
        }),

        list: () =>
          imagebuilder.listImageRecipes.pages({ owner: "Self" }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.imageRecipeSummaryList ?? []).filter(
                  (
                    summary,
                  ): summary is imagebuilder.ImageRecipeSummary & {
                    arn: string;
                  } => summary.arn !== undefined,
                ),
              ),
            ),
            Effect.flatMap(
              Effect.forEach(
                (summary) =>
                  getRecipe(summary.arn).pipe(
                    Effect.flatMap((recipe) =>
                      recipe === undefined ? Effect.undefined : toAttrs(recipe),
                    ),
                  ),
                { concurrency: 4 },
              ),
            ),
            Effect.map((items) => items.filter((item) => item !== undefined)),
          ),
      };
    }),
  );