1import * as notifications from "@distilled.cloud/aws/notifications";
2import * as Effect from "effect/Effect";
3import * as Option from "effect/Option";
4import * as Schedule from "effect/Schedule";
5import * as Stream from "effect/Stream";
6import { isResolved } from "../../Diff.ts";
7import * as Provider from "../../Provider.ts";
8import { Resource } from "../../Resource.ts";
9import type { Providers } from "../Providers.ts";
10import { pinNotificationsRegion } from "./internal.ts";
11
12export interface NotificationHubProps {
13 /**
14 * The AWS region to enable as a notification hub (where User
15 * Notifications stores and replicates notification events), e.g.
16 * `us-west-2`. Changing the region replaces the hub.
17 */
18 region: string;
19}
20
21export interface NotificationHub extends Resource<
22 "AWS.Notifications.NotificationHub",
23 NotificationHubProps,
24 {
25 /** The region registered as a notification hub. */
26 notificationHubRegion: string;
27 /** Hub status: `ACTIVE`, `REGISTERING`, `DEREGISTERING` or `INACTIVE`. */
28 status: string;
29 },
30 never,
31 Providers
32> {}
33
34/**
35 * An AWS User Notifications **notification hub** — a regional enablement
36 * that stores and replicates notification events. An account can register
37 * at most 3 hubs, and at least one ACTIVE hub must exist for notification
38 * configurations to deliver events.
39 *
40 * Registration is a true upsert keyed by region (re-registering an existing
41 * hub region is a no-op), so the hub behaves like a per-region singleton.
42 *
43 * **AWS refuses to deregister the last ACTIVE hub in the account**
44 * (`ConflictException`). Destroying a stack containing the account's only
45 * hub therefore fails — keep a baseline hub registered outside the stack,
46 * or register a second hub first.
47 *
48 * ### Registering a Notification Hub
49 * **Example:** Enable a region as a notification hub
50 * ```typescript
51 * import * as Notifications from "alchemy/AWS/Notifications";
52 *
53 * const hub = yield* Notifications.NotificationHub("Hub", {
54 * region: "us-east-2",
55 * });
56 * ```
57 *
58 * @resource
59 */
60export const NotificationHub = Resource<NotificationHub>(
61 "AWS.Notifications.NotificationHub",
62);
63
64/**
65 * Poll until the hub reaches a terminal status (bounded and fail-open —
66 * registration is typically ACTIVE immediately).
67 *
68 * Explicitly typed so `Effect.repeat`'s conditional return type doesn't
69 * survive into declaration emit and widen the provider layer.
70 */
71const untilActive = <A, E, R>(
72 self: Effect.Effect<A, E, R>,
73 status: (a: A) => string | undefined,
74): Effect.Effect<A, E, R> =>
75 Effect.repeat(self, {
76 schedule: Schedule.fixed("2 seconds"),
77 until: (a) => status(a) !== "REGISTERING",
78 times: 20,
79 });
80
81export const NotificationHubProvider = () =>
82 Provider.effect(
83 NotificationHub,
84 Effect.gen(function* () {
85 const findByRegion = Effect.fn(function* (region: string) {
86 return yield* pinNotificationsRegion(
87 notifications.listNotificationHubs.items({}).pipe(
88 Stream.filter((hub) => hub.notificationHubRegion === region),
89 Stream.runHead,
90 Effect.map(Option.getOrUndefined),
91 ),
92 );
93 });
94
95 const toAttrs = (hub: {
96 notificationHubRegion: string;
97 statusSummary: { status: string };
98 }) => ({
99 notificationHubRegion: hub.notificationHubRegion,
100 status: hub.statusSummary.status,
101 });
102
103 return NotificationHub.Provider.of({
104 stables: ["notificationHubRegion"],
105
106 list: () =>
107 pinNotificationsRegion(
108 notifications.listNotificationHubs.items({}).pipe(
109 Stream.runCollect,
110 Effect.map((chunk) => Array.from(chunk).map(toAttrs)),
111 ),
112 ),
113
114 read: Effect.fn(function* ({ olds, output }) {
115 const region = output?.notificationHubRegion ?? olds?.region;
116 if (region === undefined) return undefined;
117 const found = yield* findByRegion(region);
118 // Hubs are not taggable — identity is the region itself.
119 return found ? toAttrs(found) : undefined;
120 }),
121
122 diff: Effect.fn(function* ({ news, olds }) {
123 if (!isResolved(news)) return undefined;
124 if (news.region !== olds.region) {
125 return { action: "replace" } as const;
126 }
127 return undefined;
128 }),
129
130 reconcile: Effect.fn(function* ({ news, session }) {
131 // OBSERVE — the hub is keyed by region; registration is an
132 // idempotent upsert so a concurrent create is harmless.
133 let live = yield* findByRegion(news.region);
134
135 // ENSURE — register when missing (or not yet ACTIVE; re-register
136 // of an existing region is a no-op returning current state).
137 if (live === undefined) {
138 const registered = yield* pinNotificationsRegion(
139 notifications.registerNotificationHub({
140 notificationHubRegion: news.region,
141 }),
142 );
143 live = registered;
144 }
145
146 // Wait for activation (bounded, fail-open — usually immediate).
147 if (live.statusSummary.status === "REGISTERING") {
148 const settled = yield* untilActive(
149 findByRegion(news.region),
150 (hub) => hub?.statusSummary.status,
151 );
152 live = settled ?? live;
153 }
154
155 yield* session.note(news.region);
156 return toAttrs(live);
157 }),
158
159 delete: Effect.fn(function* ({ output }) {
160 // Idempotent for an already-gone hub. A ConflictException
161 // ("Cannot deregister last ACTIVE notification hub") is a genuine
162 // account constraint and propagates.
163 yield* pinNotificationsRegion(
164 notifications
165 .deregisterNotificationHub({
166 notificationHubRegion: output.notificationHubRegion,
167 })
168 .pipe(
169 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
170 ),
171 );
172 }),
173 });
174 }),
175 );