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

import * as imagebuilder from "@distilled.cloud/aws/imagebuilder";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } 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 Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  driftedFrom,
  imageBuilderArn,
  retryWhileDependedOn,
  syncImageBuilderTags,
  toTagRecord,
} from "./internal.ts";

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

export interface InfrastructureConfigurationProps {
  /**
   * Name of the infrastructure configuration. If omitted, a deterministic
   * physical name is generated. Changing the name replaces the
   * configuration.
   */
  infrastructureConfigurationName?: string;
  /**
   * Name of the IAM instance profile attached to build/test instances.
   * The profile's role needs at least `EC2InstanceProfileForImageBuilder`
   * and `AmazonSSMManagedInstanceCore`.
   */
  instanceProfileName: string;
  /**
   * EC2 instance types to use when building. Image Builder picks the
   * type with the most available capacity.
   */
  instanceTypes?: string[];
  /**
   * Security group IDs applied to build/test instances.
   */
  securityGroupIds?: string[];
  /**
   * Subnet in which to place build/test instances.
   */
  subnetId?: string;
  /**
   * Description of the configuration.
   */
  description?: string;
  /**
   * S3 logging configuration for build logs.
   */
  logging?: imagebuilder.Logging;
  /**
   * EC2 key pair for debugging build instances.
   */
  keyPair?: string;
  /**
   * Terminate the build instance when the build fails (set `false` to
   * keep it for debugging).
   * @default true
   */
  terminateInstanceOnFailure?: boolean;
  /**
   * SNS topic ARN notified of image build events.
   */
  snsTopicArn?: string;
  /**
   * Tags applied to the EC2 resources (instances, volumes) created
   * during builds.
   */
  resourceTags?: Record<string, string>;
  /**
   * Instance metadata service (IMDS) settings for build instances.
   */
  instanceMetadataOptions?: imagebuilder.InstanceMetadataOptions;
  /**
   * Placement settings (availability zone, tenancy, host) for build
   * instances.
   */
  placement?: imagebuilder.Placement;
  /**
   * User-defined tags for the configuration.
   */
  tags?: Record<string, string>;
}

export interface InfrastructureConfiguration extends Resource<
  "AWS.ImageBuilder.InfrastructureConfiguration",
  InfrastructureConfigurationProps,
  {
    /** The name of the infrastructure configuration. */
    infrastructureConfigurationName: string;
    /** The ARN of the infrastructure configuration. */
    infrastructureConfigurationArn: string;
    /** The instance profile builds run with. */
    instanceProfileName: string | undefined;
    /** When the infrastructure configuration was created. */
    dateCreated: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An EC2 Image Builder infrastructure configuration — the environment
 * (instance profile, instance types, network, logging) in which images are
 * built and tested.
 * ### Creating an Infrastructure Configuration
 * **Example:** Minimal Configuration
 * ```typescript
 * const role = yield* IAM.Role("BuilderRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [{
 *       Effect: "Allow",
 *       Principal: { Service: "ec2.amazonaws.com" },
 *       Action: ["sts:AssumeRole"],
 *     }],
 *   },
 *   managedPolicyArns: [
 *     "arn:aws:iam::aws:policy/EC2InstanceProfileForImageBuilder",
 *     "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore",
 *   ],
 * });
 * const profile = yield* IAM.InstanceProfile("BuilderProfile", {
 *   roleName: role.roleName,
 * });
 * const infra = yield* ImageBuilder.InfrastructureConfiguration("Infra", {
 *   instanceProfileName: profile.instanceProfileName,
 *   instanceTypes: ["t3.micro"],
 *   terminateInstanceOnFailure: true,
 * });
 * ```
 *
 * @resource
 */
export const InfrastructureConfiguration = Resource<InfrastructureConfiguration>(
  "AWS.ImageBuilder.InfrastructureConfiguration",
);

/**
 * A freshly created IAM instance profile takes a few seconds to become
 * visible to Image Builder, which rejects it with
 * `InvalidParameterValueException` ("The provided instance profile does not
 * exist") in the interim — retry through the propagation window (bounded).
 */
const retryThroughIamPropagation = <
  A,
  E extends { readonly _tag: string; readonly message?: string },
  R,
>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) =>
      e._tag === "InvalidParameterValueException" &&
      (e.message?.includes("instance profile does not exist") ?? false),
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
  });

export const InfrastructureConfigurationProvider = () =>
  Provider.effect(
    InfrastructureConfiguration,
    Effect.gen(function* () {
      const toName = (id: string, props: InfrastructureConfigurationProps) =>
        props.infrastructureConfigurationName
          ? Effect.succeed(props.infrastructureConfigurationName)
          : createPhysicalName({ id, maxLength: 126 });

      const toArn = (name: string) => imageBuilderArn("infrastructure-configuration", name);

      const getConfiguration = Effect.fn(function* (arn: string) {
        const response = yield* imagebuilder
          .getInfrastructureConfiguration({
            infrastructureConfigurationArn: arn,
          })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response?.infrastructureConfiguration;
      });

      const toAttrs = Effect.fn(function* (config: imagebuilder.InfrastructureConfiguration) {
        if (!config.arn || !config.name) {
          return yield* new InfrastructureConfigurationUnexpectedResponse({
            message: "Image Builder infrastructure configuration is missing its ARN or name",
          });
        }
        return {
          infrastructureConfigurationName: config.name,
          infrastructureConfigurationArn: config.arn,
          instanceProfileName: config.instanceProfileName,
          dateCreated: config.dateCreated,
        };
      });

      /**
       * Mutable aspects synced by a full-PUT update. Keys of both the
       * observed struct and the Props (they share names).
       */
      const mutableKeys = [
        "description",
        "instanceTypes",
        "instanceProfileName",
        "securityGroupIds",
        "subnetId",
        "logging",
        "keyPair",
        "terminateInstanceOnFailure",
        "snsTopicArn",
        "resourceTags",
        "instanceMetadataOptions",
        "placement",
      ] as const;

      return {
        stables: ["infrastructureConfigurationName", "infrastructureConfigurationArn"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          if ((yield* toName(id, olds)) !== (yield* toName(id, news))) {
            return { action: "replace" } as const;
          }
        }),

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

        reconcile: Effect.fn(function* ({ id, news, olds, 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?.infrastructureConfigurationName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // 1. Observe — the configuration ARN is deterministic from the
          //    name; cloud state is authoritative.
          const arn = output?.infrastructureConfigurationArn ?? (yield* toArn(name));
          let observed = yield* getConfiguration(arn);

          // 2. Ensure — create if missing; tolerate an AlreadyExists race
          //    by re-observing.
          if (observed === undefined) {
            const created = yield* retryThroughIamPropagation(
              imagebuilder.createInfrastructureConfiguration({
                name,
                description: news.description,
                instanceTypes: news.instanceTypes,
                instanceProfileName: news.instanceProfileName,
                securityGroupIds: news.securityGroupIds,
                subnetId: news.subnetId,
                logging: news.logging,
                keyPair: news.keyPair,
                terminateInstanceOnFailure: news.terminateInstanceOnFailure,
                snsTopicArn: news.snsTopicArn,
                resourceTags: news.resourceTags,
                instanceMetadataOptions: news.instanceMetadataOptions,
                placement: news.placement,
                tags: desiredTags,
                clientToken,
              }),
            ).pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.undefined));
            observed = yield* getConfiguration(created?.infrastructureConfigurationArn ?? arn);
            if (observed === undefined) {
              return yield* new InfrastructureConfigurationUnexpectedResponse({
                message: `created Image Builder infrastructure configuration '${name}' is not readable`,
              });
            }
          }

          // 3. Sync — compare OBSERVED cloud state against the desired
          //    props; a full-PUT update converges any drift (including
          //    props the user removed since the last deploy — `olds` is
          //    only a hint for removals).
          const drifted = mutableKeys.some(
            (key) =>
              driftedFrom(observed?.[key], news[key]) ||
              (news[key] === undefined && olds?.[key] !== undefined),
          );
          if (drifted && observed.arn) {
            yield* imagebuilder.updateInfrastructureConfiguration({
              infrastructureConfigurationArn: observed.arn,
              description: news.description,
              instanceTypes: news.instanceTypes,
              instanceProfileName: news.instanceProfileName,
              securityGroupIds: news.securityGroupIds,
              subnetId: news.subnetId,
              logging: news.logging,
              keyPair: news.keyPair,
              terminateInstanceOnFailure: news.terminateInstanceOnFailure,
              snsTopicArn: news.snsTopicArn,
              resourceTags: news.resourceTags,
              instanceMetadataOptions: news.instanceMetadataOptions,
              placement: news.placement,
              clientToken,
            });
            observed = (yield* getConfiguration(observed.arn)) ?? observed;
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          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.deleteInfrastructureConfiguration({
              infrastructureConfigurationArn: output.infrastructureConfigurationArn,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),

        list: () =>
          imagebuilder.listInfrastructureConfigurations.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.infrastructureConfigurationSummaryList ?? []).filter(
                  (
                    summary,
                  ): summary is imagebuilder.InfrastructureConfigurationSummary & {
                    arn: string;
                    name: string;
                  } => summary.arn !== undefined && summary.name !== undefined,
                ),
              ),
            ),
            Effect.map((summaries) =>
              summaries.map((summary) => ({
                infrastructureConfigurationName: summary.name,
                infrastructureConfigurationArn: summary.arn,
                instanceProfileName: summary.instanceProfileName,
                dateCreated: summary.dateCreated,
              })),
            ),
          ),
      };
    }),
  );