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

import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import { consumeBusEvents, type EventRecord } from "../EventBridge/EventSource.ts";
import type { AutoScalingGroup } from "./AutoScalingGroup.ts";
import {
  LifecycleHook,
  normalizeTransition,
  type LifecycleActionResult,
  type LifecycleTransition,
} from "./LifecycleHook.ts";

/**
 * The `detail` payload EC2 Auto Scaling delivers to EventBridge when an instance
 * enters a lifecycle wait state.
 */
export interface LifecycleActionDetail {
  /**
   * Token identifying this specific lifecycle action; pass it to
   * `complete`/`heartbeat` on the {@link CompleteLifecycleAction} binding.
   */
  LifecycleActionToken: string;
  /**
   * Name of the Auto Scaling Group the instance belongs to.
   */
  AutoScalingGroupName: string;
  /**
   * Name of the lifecycle hook that paused the instance.
   */
  LifecycleHookName: string;
  /**
   * ID of the EC2 instance in the wait state.
   */
  EC2InstanceId: string;
  /**
   * The paused transition (e.g. `autoscaling:EC2_INSTANCE_LAUNCHING`).
   */
  LifecycleTransition: string;
  /**
   * Metadata configured on the hook via `notificationMetadata`.
   */
  NotificationMetadata?: string;
  /**
   * Where the instance is coming from (e.g. `EC2` or `WarmPool`).
   */
  Origin?: string;
  /**
   * Where the instance is headed (e.g. `AutoScalingGroup` or `WarmPool`).
   */
  Destination?: string;
}

/** A lifecycle-action EventBridge event delivered to the handler. */
export type LifecycleActionEvent = EventRecord<LifecycleActionDetail>;

export interface LifecycleHookEventSourceProps {
  /**
   * Logical id prefix for the backing hook + EventBridge rule. Defaults to the
   * Auto Scaling Group's logical id.
   */
  id?: string;
  /**
   * Physical name for the lifecycle hook. If omitted, a deterministic name is
   * generated.
   */
  lifecycleHookName?: string;
  /**
   * Instance state transition to pause on.
   */
  lifecycleTransition: LifecycleTransition;
  /**
   * Maximum time an instance stays paused before `defaultResult` applies,
   * e.g. `"5 minutes"` or `Duration.seconds(300)` (whole seconds on the
   * wire).
   * @default "1 hour"
   */
  heartbeatTimeout?: Duration.Input;
  /**
   * Action taken when the hook times out.
   * @default "ABANDON"
   */
  defaultResult?: LifecycleActionResult;
  /**
   * Metadata delivered with the lifecycle event.
   */
  notificationMetadata?: string;
}

const detailTypeFor = (transition: string): string =>
  transition === "autoscaling:EC2_INSTANCE_LAUNCHING"
    ? "EC2 Instance-launch Lifecycle Action"
    : "EC2 Instance-terminate Lifecycle Action";

/**
 * Pause an Auto Scaling instance transition and deliver the lifecycle event to
 * the host Function. Creates the backing {@link LifecycleHook} on `group` (so
 * instances actually pause) and subscribes the Function to the matching
 * `aws.autoscaling` EventBridge events. Pair with
 * {@link CompleteLifecycleAction} to signal `CONTINUE` / `ABANDON` from the
 * handler.
 *
 * The EventBridge pattern matches every lifecycle action of this transition in
 * the account; inspect `event.detail.AutoScalingGroupName` /
 * `event.detail.LifecycleHookName` in the handler if multiple groups share the
 * Function.
 *
 * ### Draining Instances
 * **Example:** Signal CONTINUE when an instance is about to terminate
 * ```typescript
 * const lifecycle = yield* CompleteLifecycleAction(group);
 * yield* consumeLifecycleActions(
 *   group,
 *   { lifecycleTransition: "TERMINATING", heartbeatTimeout: "300 seconds" },
 *   (events) =>
 *     Stream.runForEach(events, (event) =>
 *       lifecycle
 *         .complete({
 *           LifecycleHookName: event.detail.LifecycleHookName,
 *           LifecycleActionToken: event.detail.LifecycleActionToken,
 *           LifecycleActionResult: "CONTINUE",
 *         })
 *         .pipe(Effect.orDie),
 *     ),
 * );
 * ```
 *
 * **Example:** Register the event source inside a Lambda Function
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 * import {
 *   CompleteLifecycleAction,
 *   CompleteLifecycleActionHttp,
 *   consumeLifecycleActions,
 * } from "@alchemy.run/aws/AutoScaling";
 *
 * export class DrainFunction extends AWS.Lambda.Function<AWS.Lambda.Function>()(
 *   "DrainFunction",
 * ) {}
 *
 * export default DrainFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const lifecycle = yield* CompleteLifecycleAction(group);
 *
 *     // creates the LifecycleHook on the group and subscribes this Function
 *     // to the matching EventBridge lifecycle events
 *     yield* consumeLifecycleActions(
 *       group,
 *       { lifecycleTransition: "TERMINATING" },
 *       (events) =>
 *         Stream.runForEach(events, (event) =>
 *           lifecycle
 *             .complete({
 *               LifecycleHookName: event.detail.LifecycleHookName,
 *               LifecycleActionToken: event.detail.LifecycleActionToken,
 *               LifecycleActionResult: "CONTINUE",
 *             })
 *             .pipe(Effect.orDie),
 *         ),
 *     );
 *
 *     return {};
 *   }).pipe(
 *     Effect.provide(
 *       Layer.mergeAll(AWS.Lambda.EventSource, CompleteLifecycleActionHttp),
 *     ),
 *   ),
 * );
 * ```
 */
export const consumeLifecycleActions = <StreamReq = never, Req = never>(
  group: AutoScalingGroup,
  props: LifecycleHookEventSourceProps,
  process: (
    events: Stream.Stream<LifecycleActionEvent, never, StreamReq>,
  ) => Effect.Effect<void, never, Req>,
) =>
  Effect.gen(function* () {
    const transition = normalizeTransition(props.lifecycleTransition);
    const idPrefix = props.id ?? group.LogicalId;

    // Create the hook so instances actually pause and emit lifecycle events.
    const hook = yield* LifecycleHook(`${idPrefix}-LifecycleHook`, {
      autoScalingGroup: group,
      lifecycleHookName: props.lifecycleHookName,
      lifecycleTransition: props.lifecycleTransition,
      heartbeatTimeout: props.heartbeatTimeout,
      defaultResult: props.defaultResult,
      notificationMetadata: props.notificationMetadata,
    });

    // Subscribe the host Function to the matching lifecycle events. The pattern
    // uses only literal `source` + `detail-type` so it round-trips through both
    // the deploy-time rule and the runtime matcher (Output values cannot appear
    // in the pattern — they don't resolve inside the deployed bundle).
    yield* consumeBusEvents(
      `${idPrefix}-LifecycleEvents`,
      {
        source: ["aws.autoscaling"],
        "detail-type": [detailTypeFor(transition)],
      },
      process,
    );

    return hook;
  });