sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudFormation/ StackEventSource.ts

import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import {
  consumeBusEvents,
  type EventRecord,
  type EventRouteProps,
} from "../EventBridge/EventSource.ts";

/**
 * The `detail` payload CloudFormation delivers to EventBridge when a stack,
 * resource, drift detection, or StackSet changes status. CloudFormation uses
 * hyphenated keys; fields not shared by every event kind are optional (the
 * schema grows over time).
 */
export interface StackEventDetail {
  /** The ARN of the stack the event is about. */
  "stack-id"?: string;
  /** Resource events: the logical id of the resource within the stack. */
  "logical-resource-id"?: string;
  /** Resource events: the physical id of the resource. */
  "physical-resource-id"?: string;
  /** Resource events: the resource type, e.g. `AWS::SNS::Topic`. */
  "resource-type"?: string;
  /** Drift events: the drift detection run id. */
  "stack-drift-detection-id"?: string;
  /** The new status and reason. */
  "status-details"?: {
    /** The new status, e.g. `CREATE_COMPLETE`, `UPDATE_ROLLBACK_COMPLETE`. */
    status?: string;
    /** Human-readable reason accompanying the status, when present. */
    "status-reason"?: string;
    [key: string]: unknown;
  };
  /** Additional event fields (the schema grows over time). */
  [key: string]: unknown;
}

/** A CloudFormation EventBridge event delivered to the handler. */
export type StackEvent = EventRecord<StackEventDetail>;

/** Which CloudFormation status-change events to subscribe to. */
export type StackEventKind =
  | "stack"
  | "resource"
  | "drift-detection"
  | "stack-set"
  | "stack-set-operation"
  | "stack-set-stack-instance";

const DETAIL_TYPES: Record<StackEventKind, string> = {
  stack: "CloudFormation Stack Status Change",
  resource: "CloudFormation Resource Status Change",
  "drift-detection": "CloudFormation Drift Detection Status Change",
  "stack-set": "CloudFormation StackSet Status Change",
  "stack-set-operation": "CloudFormation StackSet Operation Status Change",
  "stack-set-stack-instance": "CloudFormation StackSet StackInstance Status Change",
};

export interface StackEventSourceProps extends EventRouteProps {
  /**
   * Logical id for the backing EventBridge rule.
   * @default "CloudFormationEvents"
   */
  id?: string;
  /**
   * Which status-change events to subscribe to.
   * @default all kinds
   */
  kinds?: readonly StackEventKind[];
  /**
   * Restrict to events about specific stacks (matched against the event's
   * `stack-id`, the stack ARN).
   */
  stackIds?: readonly string[];
}

/**
 * Event source connecting CloudFormation status changes to the hosting
 * compute. CloudFormation publishes every stack, resource, drift-detection,
 * and StackSet status change to the account's default EventBridge bus
 * (source `aws.cloudformation`); this subscribes the host Function to those
 * events so it can alert on failed deployments or chain post-deploy
 * automation.
 *
 * CloudFormation publishes to EventBridge automatically — no additional
 * resource is created besides the EventBridge rule targeting the host.
 * Provide the host-specific implementation layer
 * (e.g. `AWS.Lambda.EventSource`) on the Function effect.
 *
 * ### Consuming Stack Events
 * **Example:** Alert On Failed Stack Operations
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * export default AlertFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     yield* AWS.CloudFormation.consumeStackEvents(
 *       { kinds: ["stack"] },
 *       (events) =>
 *         Stream.runForEach(events, (event) =>
 *           event.detail["status-details"]?.status?.endsWith("_FAILED")
 *             ? Effect.log(`stack ${event.detail["stack-id"]} failed`)
 *             : Effect.void,
 *         ),
 *     );
 *     return {};
 *   }).pipe(Effect.provide(AWS.Lambda.EventSource)),
 * );
 * ```
 */
export const consumeStackEvents = <StreamReq = never, Req = never>(
  props: StackEventSourceProps,
  process: (events: Stream.Stream<StackEvent, never, StreamReq>) => Effect.Effect<void, never, Req>,
) =>
  consumeBusEvents(
    props.id ?? "CloudFormationEvents",
    {
      source: ["aws.cloudformation"],
      "detail-type": (props.kinds ?? (Object.keys(DETAIL_TYPES) as StackEventKind[])).map(
        (kind) => DETAIL_TYPES[kind],
      ),
      ...(props.stackIds !== undefined ? { detail: { "stack-id": [...props.stackIds] } } : {}),
    },
    { description: props.description, state: props.state },
    process,
  );