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

main
ts 386 lines 14.1 KB
Raw
1 import * as dsql from "@distilled.cloud/aws/dsql";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as EStream from "effect/Stream";
11 import type { Providers } from "../Providers.ts";
12
13 export class StreamNotReady extends Data.TaggedError("StreamNotReady")<{
14 readonly message: string;
15 readonly cause?: unknown;
16 }> {}
17
18 export interface StreamProps {
19 /**
20 * Identifier of the DSQL cluster whose committed row-level changes the
21 * stream captures. The cluster must be in `ACTIVE` status when the stream
22 * is created (an `IDLE` cluster rejects `CreateStream` with a validation
23 * error). Changing the cluster replaces the stream.
24 */
25 clusterId: string;
26 /**
27 * ARN of the Amazon Kinesis data stream that receives the change records.
28 * Must be in the same account and region as the cluster. Configure the
29 * Kinesis stream with `maxRecordSizeInKiB: 10240` — CDC records can
30 * approach 10 MiB and an undersized stream becomes `IMPAIRED` with
31 * `KINESIS_OVERSIZE_RECORD`. Changing the target replaces the stream.
32 */
33 kinesisStreamArn: string;
34 /**
35 * ARN of the IAM role Aurora DSQL assumes to write records into the
36 * Kinesis stream. The role's trust policy must allow the
37 * `dsql.amazonaws.com` service principal and its permissions policy must
38 * grant `kinesis:PutRecord`, `kinesis:PutRecords`,
39 * `kinesis:DescribeStreamSummary` and `kinesis:ListShards` on the target
40 * stream. Changing the role replaces the stream.
41 */
42 roleArn: string;
43 /**
44 * Record ordering guarantee. Only `UNORDERED` is currently supported —
45 * consumers deduplicate and order by `source.ts_ns`.
46 * @default "UNORDERED"
47 */
48 ordering?: dsql.StreamOrdering;
49 /**
50 * Record serialization format.
51 * @default "JSON"
52 */
53 format?: dsql.StreamFormat;
54 /**
55 * User-defined tags for the stream.
56 */
57 tags?: Record<string, string>;
58 }
59
60 export interface Stream extends Resource<
61 "AWS.DSQL.Stream",
62 StreamProps,
63 {
64 /** Identifier of the source cluster. */
65 clusterId: string;
66 /** The unique stream identifier assigned by DSQL. */
67 streamId: string;
68 /** The ARN of the stream. */
69 streamArn: string;
70 /** The current status of the stream, e.g. `ACTIVE`. */
71 status: string;
72 /** Record ordering guarantee. */
73 ordering: string;
74 /** Record serialization format. */
75 format: string;
76 /** ARN of the target Kinesis data stream. */
77 kinesisStreamArn: string;
78 /** ARN of the IAM role DSQL assumes to write to Kinesis. */
79 roleArn: string;
80 },
81 never,
82 Providers
83 > {}
84
85 /**
86 * A change data capture (CDC) stream on an Aurora DSQL cluster — delivers
87 * committed row-level changes (Debezium-shaped JSON envelopes) to an Amazon
88 * Kinesis data stream.
89 *
90 * Creation is asynchronous (`CREATING` -> `ACTIVE`, typically one to three
91 * minutes); the provider waits for `ACTIVE` (bounded) before returning. A
92 * stream has no update operation — every property except tags replaces it.
93 *
94 * Functions consume the change records through the existing Kinesis event
95 * source on the **target** stream; DSQL itself never invokes compute
96 * directly.
97 *
98 * ### Creating a CDC Stream
99 * **Example:** Stream Cluster Changes into Kinesis
100 * ```typescript
101 * const cluster = yield* DSQL.Cluster("AppDb", {});
102 * const target = yield* Kinesis.Stream("Changes", {
103 * streamMode: "ON_DEMAND",
104 * maxRecordSizeInKiB: 10240,
105 * });
106 * const role = yield* IAM.Role("CdcRole", {
107 * assumeRolePolicyDocument: JSON.stringify({
108 * Version: "2012-10-17",
109 * Statement: [
110 * {
111 * Effect: "Allow",
112 * Principal: { Service: "dsql.amazonaws.com" },
113 * Action: "sts:AssumeRole",
114 * },
115 * ],
116 * }),
117 * inlinePolicies: {
118 * kinesis: JSON.stringify({
119 * Version: "2012-10-17",
120 * Statement: [
121 * {
122 * Effect: "Allow",
123 * Action: [
124 * "kinesis:PutRecord",
125 * "kinesis:PutRecords",
126 * "kinesis:DescribeStreamSummary",
127 * "kinesis:ListShards",
128 * ],
129 * Resource: target.streamArn,
130 * },
131 * ],
132 * }),
133 * },
134 * });
135 * const cdc = yield* DSQL.Stream("Cdc", {
136 * clusterId: cluster.clusterId,
137 * kinesisStreamArn: target.streamArn,
138 * roleArn: role.roleArn,
139 * });
140 * ```
141 *
142 * **Example:** Consume Change Records with a Function
143 * ```typescript
144 * // DSQL delivers into the Kinesis stream; consume it with the
145 * // Kinesis event source on the target stream.
146 * yield* Kinesis.consume(target, (records) =>
147 * Effect.forEach(records, (record) => handleChange(record)),
148 * );
149 * ```
150 *
151 * @resource
152 */
153 export const Stream = Resource<Stream>("AWS.DSQL.Stream");
154
155 const defaultOrdering = "UNORDERED";
156 const defaultFormat = "JSON";
157
158 export const StreamProvider = () =>
159 Provider.effect(
160 Stream,
161 Effect.gen(function* () {
162 const readStream = Effect.fn(function* (clusterIdentifier: string, streamIdentifier: string) {
163 return yield* dsql
164 .getStream({ clusterIdentifier, streamIdentifier })
165 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
166 });
167
168 // Bounded readiness wait — stream creation typically completes in one
169 // to three minutes; budget 5 min (60 x 5s). FAILED is terminal.
170 const waitForActive = Effect.fn(function* (
171 clusterIdentifier: string,
172 streamIdentifier: string,
173 ) {
174 const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(60)]);
175 return yield* readStream(clusterIdentifier, streamIdentifier).pipe(
176 Effect.flatMap((stream) => {
177 if (stream === undefined) {
178 return Effect.fail(
179 new StreamNotReady({ message: `DSQL stream '${streamIdentifier}' not found` }),
180 );
181 }
182 if (stream.status === "FAILED") {
183 return Effect.die(
184 `DSQL stream '${streamIdentifier}' failed to provision` +
185 (stream.statusReason ? ` (${stream.statusReason.error})` : ""),
186 );
187 }
188 if (stream.status !== "ACTIVE") {
189 return Effect.fail(
190 new StreamNotReady({
191 message: `DSQL stream '${streamIdentifier}' not active (status: ${stream.status})`,
192 }),
193 );
194 }
195 return Effect.succeed(stream);
196 }),
197 Effect.retry({ schedule: policy }),
198 );
199 });
200
201 const toAttrs = (stream: dsql.GetStreamOutput) => ({
202 clusterId: stream.clusterIdentifier,
203 streamId: stream.streamIdentifier,
204 streamArn: stream.arn,
205 status: stream.status,
206 ordering: stream.ordering,
207 format: stream.format,
208 kinesisStreamArn: stream.targetDefinition?.kinesis.streamArn ?? "",
209 roleArn: stream.targetDefinition?.kinesis.roleArn ?? "",
210 });
211
212 return {
213 stables: ["clusterId", "streamId", "streamArn"],
214
215 diff: Effect.fn(function* ({ olds, news }) {
216 if (!isResolved(news)) return undefined;
217 // There is no UpdateStream — everything except tags replaces.
218 if (
219 news.clusterId !== olds?.clusterId ||
220 news.kinesisStreamArn !== olds?.kinesisStreamArn ||
221 news.roleArn !== olds?.roleArn ||
222 (news.ordering ?? defaultOrdering) !== (olds?.ordering ?? defaultOrdering) ||
223 (news.format ?? defaultFormat) !== (olds?.format ?? defaultFormat)
224 ) {
225 return { action: "replace" } as const;
226 }
227 }),
228
229 read: Effect.fn(function* ({ id, output }) {
230 if (output?.streamId === undefined) return undefined;
231 const stream = yield* readStream(output.clusterId, output.streamId);
232 if (stream === undefined || stream.status === "DELETED") {
233 return undefined;
234 }
235 const tags = Object.fromEntries(
236 Object.entries(stream.tags ?? {}).filter(
237 (entry): entry is [string, string] => typeof entry[1] === "string",
238 ),
239 );
240 const attrs = toAttrs(stream);
241 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
242 }),
243
244 reconcile: Effect.fn(function* ({ id, news, output, session }) {
245 const props = news!;
246 const internalTags = yield* createInternalTags(id);
247 const desiredTags = { ...internalTags, ...props.tags };
248
249 // 1. Observe — cloud state is authoritative; output caches the id.
250 let observed =
251 output?.streamId === undefined
252 ? undefined
253 : yield* readStream(output.clusterId, output.streamId);
254
255 // 2. Ensure — create if missing. DSQL assigns the identifier.
256 let streamId = observed?.streamIdentifier ?? output?.streamId;
257 if (observed === undefined) {
258 const created = yield* dsql
259 .createStream({
260 clusterIdentifier: props.clusterId,
261 targetDefinition: {
262 kinesis: {
263 streamArn: props.kinesisStreamArn,
264 roleArn: props.roleArn,
265 },
266 },
267 ordering: props.ordering ?? defaultOrdering,
268 format: props.format ?? defaultFormat,
269 tags: desiredTags,
270 })
271 .pipe(
272 // Two transient races surface as typed errors here:
273 // - ConflictException while another cluster operation is in
274 // flight;
275 // - ValidationException "Aurora DSQL can't access the
276 // specified IAM role ..." while a freshly created service
277 // role propagates through IAM.
278 Effect.retry({
279 while: (e): boolean =>
280 e._tag === "ConflictException" ||
281 (e._tag === "ValidationException" && e.message.includes("IAM role")),
282 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(24)]),
283 }),
284 );
285 streamId = created.streamIdentifier;
286 }
287
288 // Wait for ACTIVE so consumers observe a delivering stream.
289 observed = yield* waitForActive(props.clusterId, streamId!);
290
291 // 3. Sync tags — diff against OBSERVED cloud tags.
292 const observedTags = Object.fromEntries(
293 Object.entries(observed.tags ?? {}).filter(
294 (entry): entry is [string, string] => typeof entry[1] === "string",
295 ),
296 );
297 const { upsert, removed } = diffTags(observedTags, desiredTags);
298 if (upsert.length > 0) {
299 yield* dsql.tagResource({
300 resourceArn: observed.arn,
301 tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
302 });
303 }
304 if (removed.length > 0) {
305 yield* dsql.untagResource({
306 resourceArn: observed.arn,
307 tagKeys: removed,
308 });
309 }
310
311 yield* session.note(streamId!);
312 return toAttrs(observed);
313 }),
314
315 delete: Effect.fn(function* ({ output }) {
316 yield* dsql
317 .deleteStream({
318 clusterIdentifier: output.clusterId,
319 streamIdentifier: output.streamId,
320 })
321 .pipe(
322 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
323 // A stream still CREATING rejects delete with a typed
324 // conflict; retry briefly until it settles.
325 Effect.retry({
326 while: (e): boolean => e._tag === "ConflictException",
327 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(24)]),
328 }),
329 );
330 // Wait until fully gone (bounded) so the parent cluster's delete
331 // does not trip over a stream still DELETING.
332 yield* readStream(output.clusterId, output.streamId).pipe(
333 Effect.flatMap((stream) =>
334 stream === undefined || stream.status === "DELETED"
335 ? Effect.void
336 : Effect.fail(
337 new StreamNotReady({
338 message: `DSQL stream '${output.streamId}' still ${stream.status}`,
339 }),
340 ),
341 ),
342 Effect.retry({
343 while: (e): boolean => e instanceof Error,
344 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
345 }),
346 // Best-effort — deletion continues server-side either way.
347 Effect.ignore,
348 );
349 }),
350
351 list: () =>
352 Effect.gen(function* () {
353 const clusters = yield* dsql.listClusters.items({}).pipe(
354 EStream.runCollect,
355 Effect.map((c) => Array.from(c)),
356 );
357 const nested = yield* Effect.forEach(
358 clusters,
359 (cluster) =>
360 dsql.listStreams.items({ clusterIdentifier: cluster.identifier }).pipe(
361 EStream.runCollect,
362 Effect.map((c) => Array.from(c)),
363 Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([])),
364 ),
365 { concurrency: 4 },
366 );
367 return yield* Effect.forEach(
368 nested.flat(),
369 (summary) =>
370 readStream(summary.clusterIdentifier, summary.streamIdentifier).pipe(
371 Effect.map((stream) =>
372 stream === undefined || stream.status === "DELETED"
373 ? undefined
374 : toAttrs(stream),
375 ),
376 ),
377 { concurrency: 4 },
378 ).pipe(
379 Effect.map((attrs) =>
380 attrs.filter((a): a is NonNullable<typeof a> => a !== undefined),
381 ),
382 );
383 }),
384 };
385 }),
386 );