sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ AutoScaling/ LaunchTemplate.ts

import type { Credentials } from "@distilled.cloud/aws/Credentials";
import * as ec2 from "@distilled.cloud/aws/ec2";
import { Region } from "@distilled.cloud/aws/Region";
import * as Bundle from "alchemy/Bundle/Bundle";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { Stack } from "alchemy/Stack";
import { Stage } from "alchemy/Stage";
import { createInternalTags, diffTags, hasTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Stream from "effect/Stream";
import type * as rolldown from "rolldown";
import {
  createEc2HostRuntimeContext,
  createEc2HostedSupport,
  type Ec2HostRuntimeContext,
  type InstanceMetadataOptions,
} from "../EC2/hosted.ts";
import type { SecurityGroupId } from "../EC2/SecurityGroup.ts";
import type { AccountID } from "../Environment.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import { AWSEnvironment } from "../index.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

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

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

export type LaunchTemplateId = `lt-${string}`;
export type LaunchTemplateName = string;
export type LaunchTemplateArn =
  `arn:aws:ec2:${RegionID}:${AccountID}:launch-template/${LaunchTemplateId}`;

export interface LaunchTemplateProps extends PlatformProps {
  /**
   * Launch template name. If omitted, a deterministic name is generated.
   */
  launchTemplateName?: string;
  /**
   * AMI ID to launch.
   */
  imageId: string;
  /**
   * EC2 instance type, such as `t3.micro`.
   */
  instanceType: string;
  /**
   * Security groups to attach to the primary network interface.
   */
  securityGroupIds?: Input<SecurityGroupId>[];
  /**
   * Optional EC2 key pair name for SSH access.
   */
  keyName?: string;
  /**
   * Optional IAM instance profile name to attach at launch.
   */
  instanceProfileName?: string;
  /**
   * User data script to provide at launch time.
   */
  userData?: string;
  /**
   * Whether to associate a public IPv4 address on launch.
   */
  associatePublicIpAddress?: boolean;
  /**
   * Instance Metadata Service (IMDS) options for launched instances, e.g.
   * requiring IMDSv2 and limiting the hop count. Changes publish a new
   * template version. Unset fields keep the AMI / account defaults.
   */
  metadataOptions?: InstanceMetadataOptions;
  /**
   * User-defined tags to apply to the launch template and launched instances.
   */
  tags?: Record<string, string>;
  /**
   * Module entrypoint for the bundled instance program.
   * When omitted, the launch template behaves as a low-level EC2 primitive.
   */
  main?: string;
  /**
   * Named export to load from `main`.
   * @default "default"
   */
  handler?: string;
  /**
   * Port exposed by the process, if any.
   * @default 3000
   */
  port?: number;
  /**
   * Additional environment variables for the hosted process.
   */
  env?: Record<string, any>;
  /**
   * Bundler configuration for the hosted process entrypoint.
   */
  build?: {
    input?: Partial<rolldown.InputOptions>;
    output?: Partial<rolldown.OutputOptions>;
  };
  /**
   * Additional managed policy ARNs for the managed instance role.
   * This can only be used when Alchemy manages the instance profile.
   */
  roleManagedPolicyArns?: string[];
}

export interface LaunchTemplate extends Resource<
  "AWS.AutoScaling.LaunchTemplate",
  LaunchTemplateProps,
  {
    /**
     * ID of the launch template (`lt-...`).
     */
    launchTemplateId: LaunchTemplateId;
    /**
     * ARN of the launch template.
     */
    launchTemplateArn: LaunchTemplateArn;
    /**
     * Name of the launch template.
     */
    launchTemplateName: LaunchTemplateName;
    /**
     * Version number launched by default.
     */
    defaultVersionNumber: number;
    /**
     * Most recently created version number.
     */
    latestVersionNumber: number;
    /**
     * Tags on the launch template.
     */
    tags: Record<string, string>;
    /**
     * ARN of the managed instance role, when Alchemy manages IAM.
     */
    roleArn?: string;
    /**
     * Name of the managed instance role, when Alchemy manages IAM.
     */
    roleName?: string;
    /**
     * Name of the inline policy on the managed instance role.
     */
    policyName?: string;
    /**
     * Name of the instance profile launched instances use; the managed one
     * when Alchemy manages IAM.
     */
    instanceProfileName?: string;
    /**
     * Whether Alchemy manages the instance profile/role for the hosted
     * program.
     */
    managedIam?: boolean;
    /**
     * systemd unit name running the hosted program on instances.
     */
    runtimeUnitName?: string;
    /**
     * S3 key prefix where the bundled program assets are staged.
     */
    assetPrefix?: string;
    /**
     * Bundled program code metadata.
     */
    code?: {
      /**
       * Content hash of the bundled entrypoint.
       */
      hash: string;
    };
  },
  {
    /**
     * Environment variables contributed by bindings to the hosted process.
     */
    env?: Record<string, any>;
    /**
     * IAM policy statements contributed by bindings to the instance role.
     */
    policyStatements?: PolicyStatement[];
  },
  Providers
> {}

export type LaunchTemplateServices = Credentials | Region;

export type LaunchTemplateShape = Main<LaunchTemplateServices>;

export type LaunchTemplateRuntimeContext = Ec2HostRuntimeContext;

/**
 * A launch template that preserves the `Host` authoring model used by
 * `AWS.EC2.Instance`, but packages that host configuration for use with an
 * Auto Scaling Group.
 * ### Creating a Launch Template
 * **Example:** Basic Launch Template
 * ```typescript
 * import { LaunchTemplate } from "@alchemy.run/aws/AutoScaling";
 *
 * const template = yield* LaunchTemplate("Template", {
 *   imageId: "ami-0abcdef1234567890",
 *   instanceType: "t3.micro",
 * });
 * ```
 *
 * **Example:** Launch a fleet from the template
 * ```typescript
 * import { AutoScalingGroup } from "@alchemy.run/aws/AutoScaling";
 *
 * const group = yield* AutoScalingGroup("Fleet", {
 *   launchTemplate: template,
 *   subnetIds: [subnet.subnetId],
 *   minSize: 1,
 *   maxSize: 3,
 * });
 * ```
 *
 * ### Hosting Processes
 * **Example:** Hosted HTTP Launch Template
 * ```typescript
 * const template = yield* Effect.gen(function* () {
 *   yield* Http.serve(HttpServerResponse.json({ ok: true }));
 *
 *   return {
 *     main: import.meta.url,
 *     imageId,
 *     instanceType: "t3.small",
 *     securityGroupIds: [securityGroup.groupId],
 *     port: 3000,
 *   };
 * }).pipe(
 *   Effect.provide(AWS.EC2.HttpServer),
 *   AWS.AutoScaling.LaunchTemplate("ApiTemplate"),
 * );
 * ```
 *
 * @resource
 */
export const LaunchTemplate: Platform<
  LaunchTemplate,
  LaunchTemplateServices,
  LaunchTemplateShape,
  LaunchTemplateRuntimeContext
> = Platform("AWS.AutoScaling.LaunchTemplate", {
  createRuntimeContext: createEc2HostRuntimeContext("AWS.AutoScaling.LaunchTemplate"),
});

export const LaunchTemplateProvider = () =>
  Provider.effect(
    LaunchTemplate,
    Effect.gen(function* () {
      const stack = yield* Stack;
      const stage = yield* Stage;
      const fs = yield* FileSystem.FileSystem;
      const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;

      const hosted = createEc2HostedSupport({
        stackName: stack.name,
        stage,
        fs,
        virtualEntryPlugin,
        resourceType: "AWS.AutoScaling.LaunchTemplate",
      });

      const toName = (id: string, props: { launchTemplateName?: string } = {}) =>
        props.launchTemplateName
          ? Effect.succeed(props.launchTemplateName)
          : createPhysicalName({ id, maxLength: 128, lowercase: true });

      const toArn = (launchTemplateId: LaunchTemplateId) =>
        AWSEnvironment.current.pipe(
          Effect.map(
            (env) =>
              `arn:aws:ec2:${env.region}:${env.accountId}:launch-template/${launchTemplateId}` as LaunchTemplateArn,
          ),
        );

      const describeById = (launchTemplateId: string) =>
        ec2
          .describeLaunchTemplates({
            LaunchTemplateIds: [launchTemplateId],
          } as any)
          .pipe(
            Effect.map((result) => result.LaunchTemplates?.[0]),
            Effect.catchIf(isLaunchTemplateNotFound, () => Effect.undefined),
          );

      const describeByName = (launchTemplateName: string) =>
        ec2
          .describeLaunchTemplates({
            LaunchTemplateNames: [launchTemplateName],
          } as any)
          .pipe(
            Effect.map((result) => result.LaunchTemplates?.[0]),
            Effect.catchIf(isLaunchTemplateNotFound, () => Effect.undefined),
          );

      const syncTemplateTags = Effect.fn(function* ({
        launchTemplateId,
        oldTags,
        newTags,
      }: {
        launchTemplateId: LaunchTemplateId;
        oldTags: Record<string, string>;
        newTags: Record<string, string>;
      }) {
        const { removed, upsert } = diffTags(oldTags, newTags);
        if (removed.length > 0) {
          yield* ec2.deleteTags({
            Resources: [launchTemplateId],
            Tags: removed.map((key) => ({ Key: key })),
          });
        }
        if (upsert.length > 0) {
          yield* ec2.createTags({
            Resources: [launchTemplateId],
            Tags: upsert,
          });
        }
      });

      const createVersion = Effect.fn(function* ({
        launchTemplateId,
        news,
        runtime,
      }: {
        launchTemplateId: LaunchTemplateId;
        news: LaunchTemplateProps;
        runtime: {
          userData?: string;
          instanceProfileName?: string;
          code?: {
            hash: string;
          };
        };
      }) {
        const created = yield* ec2.createLaunchTemplateVersion({
          LaunchTemplateId: launchTemplateId,
          VersionDescription: runtime.code?.hash ?? "alchemy-update",
          LaunchTemplateData: hosted.buildLaunchTemplateData(
            {
              imageId: news.imageId,
              instanceType: news.instanceType,
              keyName: news.keyName,
              securityGroupIds: news.securityGroupIds as string[] | undefined,
              associatePublicIpAddress: news.associatePublicIpAddress,
              metadataOptions: news.metadataOptions,
              tags: news.tags,
            },
            runtime,
          ),
        } as any);

        const versionNumber = created.LaunchTemplateVersion?.VersionNumber;
        if (versionNumber === undefined) {
          return yield* new LaunchTemplateUnexpectedResponse({
            message: `createLaunchTemplateVersion returned no version for '${launchTemplateId}'`,
          });
        }

        yield* ec2.modifyLaunchTemplate({
          LaunchTemplateId: launchTemplateId,
          DefaultVersion: String(versionNumber),
        } as any);

        return Number(versionNumber);
      });

      const toAttributes = Effect.fn(function* (
        template: ec2.LaunchTemplate,
        runtime: Partial<LaunchTemplate["Attributes"]> = {},
      ) {
        return {
          launchTemplateId: template.LaunchTemplateId as LaunchTemplateId,
          launchTemplateArn: yield* toArn(template.LaunchTemplateId as LaunchTemplateId),
          launchTemplateName: template.LaunchTemplateName!,
          defaultVersionNumber: Number(template.DefaultVersionNumber ?? 1),
          latestVersionNumber: Number(
            template.LatestVersionNumber ?? template.DefaultVersionNumber ?? 1,
          ),
          tags: toTagRecord(template.Tags),
          roleArn: runtime.roleArn,
          roleName: runtime.roleName,
          policyName: runtime.policyName,
          instanceProfileName: runtime.instanceProfileName,
          managedIam: runtime.managedIam,
          runtimeUnitName: runtime.runtimeUnitName,
          assetPrefix: runtime.assetPrefix,
          code: runtime.code,
        } satisfies LaunchTemplate["Attributes"];
      });

      return {
        stables: ["launchTemplateId", "launchTemplateArn", "launchTemplateName"],
        diff: Effect.fn(function* ({ id, olds, news: _news, output }) {
          if (!isResolved(_news)) return undefined;
          const news = _news as typeof olds;
          const oldName = yield* toName(id, olds ?? {});
          const newName = yield* toName(id, news ?? {});
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }

          if (!deepEqual(olds, news)) {
            return {
              action: "update",
              stables: ["launchTemplateId", "launchTemplateArn", "launchTemplateName"],
            } as const;
          }

          // The hosted bundle hash participates in planning: a change confined
          // to the runtime program (or its imports) leaves every prop equal,
          // so re-bundle and compare against the deployed hash. A mismatch
          // plans an in-place update, whose reconcile publishes a new template
          // version carrying the new bundle.
          if (news.main && output?.code?.hash) {
            const { hash } = yield* hosted.bundleProgram(id, news);
            if (hash !== output.code.hash) {
              return {
                action: "update",
                stables: ["launchTemplateId", "launchTemplateArn", "launchTemplateName"],
              } as const;
            }
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const template =
            (output?.launchTemplateId && (yield* describeById(output.launchTemplateId))) ??
            (yield* describeByName(yield* toName(id, olds ?? {})));

          return template
            ? yield* toAttributes(template, {
                roleArn: output?.roleArn,
                roleName: output?.roleName,
                policyName: output?.policyName,
                instanceProfileName: output?.instanceProfileName,
                managedIam: output?.managedIam,
                runtimeUnitName: output?.runtimeUnitName,
                assetPrefix: output?.assetPrefix,
                code: output?.code,
              })
            : undefined;
        }),
        list: () =>
          ec2.describeLaunchTemplates.pages({}).pipe(
            Stream.runCollect,
            Effect.flatMap((chunk) =>
              Effect.forEach(
                Array.from(chunk).flatMap((page) => page.LaunchTemplates ?? []),
                (template) => toAttributes(template),
              ),
            ),
          ),
        reconcile: Effect.fn(function* ({ id, news, output, bindings, session }) {
          const launchTemplateName = output?.launchTemplateName ?? (yield* toName(id, news));
          const desiredTags = {
            ...(yield* createInternalTags(id)),
            ...news.tags,
          };
          const runtime = yield* hosted.resolveHostedRuntime({
            id,
            news,
            bindings,
            output,
          });

          // Observe — fetch live cloud state. We try both lookup paths
          // (id from output, name from desired) so the reconciler
          // converges whether `output` is fresh, stale, or missing.
          let existing =
            (output?.launchTemplateId && (yield* describeById(output.launchTemplateId))) ||
            (yield* describeByName(launchTemplateName));

          // Ensure — create the launch template if missing. We must
          // verify alchemy ownership via tags here (since this resource
          // does not implement `read` adoption gating).
          if (!existing) {
            const created = yield* ec2.createLaunchTemplate({
              LaunchTemplateName: launchTemplateName,
              VersionDescription: runtime.code?.hash ?? "alchemy-create",
              TagSpecifications: [
                {
                  ResourceType: "launch-template",
                  Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                    Key,
                    Value,
                  })),
                },
              ],
              LaunchTemplateData: hosted.buildLaunchTemplateData(
                {
                  imageId: news.imageId,
                  instanceType: news.instanceType,
                  keyName: news.keyName,
                  securityGroupIds: news.securityGroupIds as string[] | undefined,
                  associatePublicIpAddress: news.associatePublicIpAddress,
                  metadataOptions: news.metadataOptions,
                  tags: desiredTags,
                },
                runtime,
              ),
            } as any);
            const template = created.LaunchTemplate;
            if (!template?.LaunchTemplateId || !template.LaunchTemplateName) {
              return yield* new LaunchTemplateUnexpectedResponse({
                message: `createLaunchTemplate returned no launch template for '${id}'`,
              });
            }
            yield* session.note(template.LaunchTemplateId);
            return yield* toAttributes(template as ec2.LaunchTemplate, runtime);
          }

          if (!hasTags(desiredTags, toTagRecord(existing.Tags))) {
            return yield* new LaunchTemplateConflict({
              message: `Launch template '${launchTemplateName}' already exists and is not managed by alchemy`,
            });
          }

          // Sync version — each reconcile creates a new version pinned as
          // the default. ASGs that reference `$Default` automatically
          // pick up the new version.
          yield* createVersion({
            launchTemplateId: existing.LaunchTemplateId as LaunchTemplateId,
            news,
            runtime,
          });

          // Sync tags — diff observed cloud tags against desired.
          yield* syncTemplateTags({
            launchTemplateId: existing.LaunchTemplateId as LaunchTemplateId,
            oldTags: toTagRecord(existing.Tags),
            newTags: desiredTags,
          });

          const refreshed = yield* describeById(existing.LaunchTemplateId!);
          if (!refreshed) {
            return yield* new LaunchTemplateUnexpectedResponse({
              message: `Launch template '${launchTemplateName}' was not readable after reconcile`,
            });
          }
          yield* session.note(refreshed.LaunchTemplateId!);
          return yield* toAttributes(refreshed, runtime);
        }),
        delete: Effect.fn(function* ({ output, session }) {
          yield* ec2
            .deleteLaunchTemplate({
              LaunchTemplateId: output.launchTemplateId,
            } as any)
            .pipe(Effect.catchIf(isLaunchTemplateNotFound, () => Effect.void));

          yield* hosted.cleanupHostedRuntime({ output, session });
        }),
      };
    }),
  );

const isLaunchTemplateNotFound = (error: unknown) => {
  const tag = (error as { _tag?: string })?._tag;
  return (
    tag === "InvalidLaunchTemplateNameNotFoundException" ||
    tag === "InvalidLaunchTemplateIdNotFoundException" ||
    tag === "InvalidLaunchTemplateId.Malformed" ||
    tag === "InvalidLaunchTemplateId.NotFound" ||
    // Live `describeLaunchTemplates` surfaces the dot-form codes, which the
    // ec2 SDK leaves untyped — a missing template on the read-before-create
    // probe otherwise fails the whole plan.
    tag === "InvalidLaunchTemplateName.NotFoundException" ||
    tag === "InvalidLaunchTemplateId.NotFoundException"
  );
};

const toTagRecord = (tags?: Array<{ Key?: string; Value?: string }>) =>
  Object.fromEntries(
    (tags ?? [])
      .filter((tag): tag is { Key: string; Value: string } =>
        Boolean(tag.Key && tag.Value !== undefined),
      )
      .map((tag) => [tag.Key, tag.Value]),
  );