The best way to control Claude Code, Codex and more from any computer or phone

main
ts 127 lines 4.46 KB
Raw
1 import type * as Effect from "effect/Effect";
2 import type * as Stream from "effect/Stream";
3 import {
4 consumeBusEvents,
5 type EventRecord,
6 type EventRouteProps,
7 } from "../EventBridge/EventSource.ts";
8
9 /**
10 * The `detail` payload CloudFormation delivers to EventBridge when a stack,
11 * resource, drift detection, or StackSet changes status. CloudFormation uses
12 * hyphenated keys; fields not shared by every event kind are optional (the
13 * schema grows over time).
14 */
15 export interface StackEventDetail {
16 /** The ARN of the stack the event is about. */
17 "stack-id"?: string;
18 /** Resource events: the logical id of the resource within the stack. */
19 "logical-resource-id"?: string;
20 /** Resource events: the physical id of the resource. */
21 "physical-resource-id"?: string;
22 /** Resource events: the resource type, e.g. `AWS::SNS::Topic`. */
23 "resource-type"?: string;
24 /** Drift events: the drift detection run id. */
25 "stack-drift-detection-id"?: string;
26 /** The new status and reason. */
27 "status-details"?: {
28 /** The new status, e.g. `CREATE_COMPLETE`, `UPDATE_ROLLBACK_COMPLETE`. */
29 status?: string;
30 /** Human-readable reason accompanying the status, when present. */
31 "status-reason"?: string;
32 [key: string]: unknown;
33 };
34 /** Additional event fields (the schema grows over time). */
35 [key: string]: unknown;
36 }
37
38 /** A CloudFormation EventBridge event delivered to the handler. */
39 export type StackEvent = EventRecord<StackEventDetail>;
40
41 /** Which CloudFormation status-change events to subscribe to. */
42 export type StackEventKind =
43 | "stack"
44 | "resource"
45 | "drift-detection"
46 | "stack-set"
47 | "stack-set-operation"
48 | "stack-set-stack-instance";
49
50 const DETAIL_TYPES: Record<StackEventKind, string> = {
51 stack: "CloudFormation Stack Status Change",
52 resource: "CloudFormation Resource Status Change",
53 "drift-detection": "CloudFormation Drift Detection Status Change",
54 "stack-set": "CloudFormation StackSet Status Change",
55 "stack-set-operation": "CloudFormation StackSet Operation Status Change",
56 "stack-set-stack-instance": "CloudFormation StackSet StackInstance Status Change",
57 };
58
59 export interface StackEventSourceProps extends EventRouteProps {
60 /**
61 * Logical id for the backing EventBridge rule.
62 * @default "CloudFormationEvents"
63 */
64 id?: string;
65 /**
66 * Which status-change events to subscribe to.
67 * @default all kinds
68 */
69 kinds?: readonly StackEventKind[];
70 /**
71 * Restrict to events about specific stacks (matched against the event's
72 * `stack-id`, the stack ARN).
73 */
74 stackIds?: readonly string[];
75 }
76
77 /**
78 * Event source connecting CloudFormation status changes to the hosting
79 * compute. CloudFormation publishes every stack, resource, drift-detection,
80 * and StackSet status change to the account's default EventBridge bus
81 * (source `aws.cloudformation`); this subscribes the host Function to those
82 * events so it can alert on failed deployments or chain post-deploy
83 * automation.
84 *
85 * CloudFormation publishes to EventBridge automatically — no additional
86 * resource is created besides the EventBridge rule targeting the host.
87 * Provide the host-specific implementation layer
88 * (e.g. `AWS.Lambda.EventSource`) on the Function effect.
89 *
90 * ### Consuming Stack Events
91 * **Example:** Alert On Failed Stack Operations
92 * ```typescript
93 * import * as AWS from "@alchemy.run/aws";
94 *
95 * export default AlertFunction.make(
96 * { main: import.meta.url },
97 * Effect.gen(function* () {
98 * yield* AWS.CloudFormation.consumeStackEvents(
99 * { kinds: ["stack"] },
100 * (events) =>
101 * Stream.runForEach(events, (event) =>
102 * event.detail["status-details"]?.status?.endsWith("_FAILED")
103 * ? Effect.log(`stack ${event.detail["stack-id"]} failed`)
104 * : Effect.void,
105 * ),
106 * );
107 * return {};
108 * }).pipe(Effect.provide(AWS.Lambda.EventSource)),
109 * );
110 * ```
111 */
112 export const consumeStackEvents = <StreamReq = never, Req = never>(
113 props: StackEventSourceProps,
114 process: (events: Stream.Stream<StackEvent, never, StreamReq>) => Effect.Effect<void, never, Req>,
115 ) =>
116 consumeBusEvents(
117 props.id ?? "CloudFormationEvents",
118 {
119 source: ["aws.cloudformation"],
120 "detail-type": (props.kinds ?? (Object.keys(DETAIL_TYPES) as StackEventKind[])).map(
121 (kind) => DETAIL_TYPES[kind],
122 ),
123 ...(props.stackIds !== undefined ? { detail: { "stack-id": [...props.stackIds] } } : {}),
124 },
125 { description: props.description, state: props.state },
126 process,
127 );