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

main
ts 590 lines 21.5 KB
Raw
1 import * as keyspaces from "@distilled.cloud/aws/keyspaces";
2 import * as keyspacesstreams from "@distilled.cloud/aws/keyspacesstreams";
3 import { Unowned } from "alchemy/AdoptPolicy";
4 import { isResolved } from "alchemy/Diff";
5 import { createPhysicalName } from "alchemy/PhysicalName";
6 import * as Provider from "alchemy/Provider";
7 import { Resource } from "alchemy/Resource";
8 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
9 import { toWireSeconds } from "alchemy/Util/Duration";
10 import * as Data from "effect/Data";
11 import type * as Duration from "effect/Duration";
12 import * as Effect from "effect/Effect";
13 import * as Schedule from "effect/Schedule";
14 import * as Stream from "effect/Stream";
15 import type { Providers } from "../Providers.ts";
16
17 export class KeyspacesTableNotReady extends Data.TaggedError("KeyspacesTableNotReady")<{
18 readonly message: string;
19 readonly cause?: unknown;
20 }> {}
21
22 /**
23 * A Cassandra column definition. `type` is a CQL data type such as `text`,
24 * `int`, `uuid`, `timestamp`, `blob`, or a collection like `list<text>`.
25 */
26 export interface KeyspacesColumn {
27 /** Column name. */
28 name: string;
29 /** CQL data type, e.g. `text`, `int`, `uuid`. */
30 type: string;
31 }
32
33 /**
34 * A clustering key column and its sort order.
35 */
36 export interface KeyspacesClusteringKey {
37 /** Name of a column also present in `columns`. */
38 name: string;
39 /**
40 * Sort order for the clustering key.
41 * @default "ASC"
42 */
43 orderBy?: "ASC" | "DESC";
44 }
45
46 /**
47 * Read/write throughput mode for a table.
48 */
49 export interface KeyspacesCapacity {
50 /**
51 * Billing mode.
52 * @default "PAY_PER_REQUEST"
53 */
54 throughputMode: "PAY_PER_REQUEST" | "PROVISIONED";
55 /** Provisioned read capacity units (only for `PROVISIONED`). */
56 readCapacityUnits?: number;
57 /** Provisioned write capacity units (only for `PROVISIONED`). */
58 writeCapacityUnits?: number;
59 }
60
61 /**
62 * Change data capture (CDC) stream configuration for a table.
63 */
64 export interface KeyspacesCdcSpecification {
65 /**
66 * Whether CDC is enabled on the table.
67 */
68 status: "ENABLED" | "DISABLED";
69 /**
70 * What data is written to the table's stream for each changed row.
71 * @default "NEW_AND_OLD_IMAGES"
72 */
73 viewType?: "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY" | "NEW_AND_OLD_IMAGES";
74 }
75
76 export interface TableProps {
77 /**
78 * Name of the parent keyspace. Changing it replaces the table.
79 */
80 keyspaceName: string;
81 /**
82 * Name of the table. Must be 1-48 characters of `[a-zA-Z0-9_]`. If omitted a
83 * deterministic physical name is generated. Changing the name replaces the
84 * table.
85 */
86 tableName?: string;
87 /**
88 * All columns in the table, including those used as partition and clustering
89 * keys. Adding new columns is applied in place; removing or retyping columns
90 * replaces the table.
91 */
92 columns: KeyspacesColumn[];
93 /**
94 * Names of the columns forming the partition key (at least one). Changing
95 * the partition key replaces the table.
96 */
97 partitionKeys: string[];
98 /**
99 * Columns forming the clustering (sort) key. Changing them replaces the
100 * table.
101 */
102 clusteringKeys?: KeyspacesClusteringKey[];
103 /**
104 * Names of static columns (shared across all rows of a partition).
105 */
106 staticColumns?: string[];
107 /**
108 * Read/write throughput mode.
109 * @default { throughputMode: "PAY_PER_REQUEST" }
110 */
111 capacity?: KeyspacesCapacity;
112 /**
113 * Enables point-in-time recovery (continuous backups).
114 * @default false
115 */
116 pointInTimeRecovery?: boolean;
117 /**
118 * Enables row-level TTL on the table. Required before per-row TTLs can be
119 * set. Enabling TTL cannot be undone without replacing the table.
120 * @default false
121 */
122 ttlEnabled?: boolean;
123 /**
124 * Default TTL applied to all rows, e.g. `"1 day"` or `Duration.hours(12)`.
125 * The API stores whole seconds. Requires `ttlEnabled`.
126 */
127 defaultTimeToLive?: Duration.Input;
128 /**
129 * Change data capture (CDC) stream configuration. Enabling CDC creates a
130 * stream that captures row-level changes for 24 hours; consume it with the
131 * `TableStreams` binding or the `keyspacesstreams` data-plane API.
132 */
133 cdcSpecification?: KeyspacesCdcSpecification;
134 /**
135 * User-defined tags for the table.
136 */
137 tags?: Record<string, string>;
138 }
139
140 export interface Table extends Resource<
141 "AWS.Keyspaces.Table",
142 TableProps,
143 {
144 /**
145 * Name of the keyspace containing the table.
146 */
147 keyspaceName: string;
148 /**
149 * The table's physical name.
150 */
151 tableName: string;
152 /**
153 * ARN of the table.
154 */
155 tableArn: string;
156 /**
157 * Lifecycle status of the table (e.g. `CREATING`, `ACTIVE`).
158 */
159 status: string;
160 /**
161 * ARN of the most recent CDC stream, when `cdcSpecification` is enabled.
162 */
163 latestStreamArn: string | undefined;
164 },
165 never,
166 Providers
167 > {}
168
169 /**
170 * An Amazon Keyspaces (for Apache Cassandra) table.
171 *
172 * Tables are serverless and provisioned asynchronously (`CREATING` ->
173 * `ACTIVE`), usually within a minute; the provider waits for `ACTIVE`
174 * (bounded) before returning. Schema mutations (adding columns, changing
175 * capacity/TTL/PITR) are applied in place; changing keys replaces the table.
176 * ### Creating a Table
177 * **Example:** Simple Key-Value Table
178 * ```typescript
179 * const table = yield* Table("Sessions", {
180 * keyspaceName: keyspace.keyspaceName,
181 * columns: [
182 * { name: "id", type: "uuid" },
183 * { name: "data", type: "text" },
184 * ],
185 * partitionKeys: ["id"],
186 * });
187 * ```
188 *
189 * **Example:** Table with a Clustering Key and TTL
190 * ```typescript
191 * const table = yield* Table("Events", {
192 * keyspaceName: keyspace.keyspaceName,
193 * columns: [
194 * { name: "device", type: "text" },
195 * { name: "ts", type: "timestamp" },
196 * { name: "payload", type: "blob" },
197 * ],
198 * partitionKeys: ["device"],
199 * clusteringKeys: [{ name: "ts", orderBy: "DESC" }],
200 * ttlEnabled: true,
201 * defaultTimeToLive: "1 day",
202 * });
203 * ```
204 *
205 * ### Change Data Capture
206 * **Example:** CDC-Enabled Table
207 * ```typescript
208 * const table = yield* Table("Orders", {
209 * keyspaceName: keyspace.keyspaceName,
210 * columns: [
211 * { name: "id", type: "uuid" },
212 * { name: "total", type: "int" },
213 * ],
214 * partitionKeys: ["id"],
215 * cdcSpecification: {
216 * status: "ENABLED",
217 * viewType: "NEW_AND_OLD_IMAGES",
218 * },
219 * });
220 * // table.latestStreamArn → consume via the TableStreams binding
221 * ```
222 *
223 * @resource
224 */
225 export const Table = Resource<Table>("AWS.Keyspaces.Table");
226
227 const toTagRecord = (tags: keyspaces.Tag[] | undefined): Record<string, string> =>
228 Object.fromEntries((tags ?? []).map((t) => [t.key, t.value]));
229
230 const buildSchema = (props: TableProps): keyspaces.SchemaDefinition => ({
231 allColumns: props.columns.map((c) => ({ name: c.name, type: c.type })),
232 partitionKeys: props.partitionKeys.map((name) => ({ name })),
233 clusteringKeys: props.clusteringKeys?.map((c) => ({
234 name: c.name,
235 orderBy: c.orderBy ?? "ASC",
236 })),
237 staticColumns: props.staticColumns?.map((name) => ({ name })),
238 });
239
240 const activeStatuses = new Set(["ACTIVE"]);
241
242 export const TableProvider = () =>
243 Provider.effect(
244 Table,
245 Effect.gen(function* () {
246 const toName = (id: string, props: Partial<TableProps>) =>
247 props.tableName
248 ? Effect.succeed(props.tableName)
249 : createPhysicalName({ id, maxLength: 48 }).pipe(
250 Effect.map((n) => n.replaceAll("-", "_")),
251 );
252
253 const readTable = Effect.fn(function* (keyspaceName: string, tableName: string) {
254 return yield* keyspaces
255 .getTable({ keyspaceName, tableName })
256 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
257 });
258
259 const readTags = Effect.fn(function* (arn: string) {
260 const tags = yield* keyspaces.listTagsForResource.items({ resourceArn: arn }).pipe(
261 Stream.runCollect,
262 Effect.map((c) => Array.from(c)),
263 Effect.orElseSucceed(() => []),
264 );
265 return toTagRecord(tags);
266 });
267
268 // Resolve the most recent CDC stream's ARN (streams are labeled with
269 // their creation timestamp; the lexicographically greatest label is the
270 // latest). Only meaningful while CDC is (or was recently) enabled.
271 const readLatestStreamArn = Effect.fn(function* (keyspaceName: string, tableName: string) {
272 const response = yield* keyspacesstreams
273 .listStreams({ keyspaceName, tableName })
274 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
275 const sorted = [...(response?.streams ?? [])].sort((a, b) =>
276 b.streamLabel.localeCompare(a.streamLabel),
277 );
278 return sorted[0]?.streamArn;
279 });
280
281 const isCdcEnabled = (table: keyspaces.GetTableResponse) => {
282 const status = table.cdcSpecification?.status;
283 return status === "ENABLED" || status === "ENABLING";
284 };
285
286 // A freshly-enabled stream can lag ListStreams visibility briefly;
287 // poll (bounded ~60s) and fall back to undefined rather than failing
288 // the reconcile.
289 const waitForStreamArn = Effect.fn(function* (keyspaceName: string, tableName: string) {
290 return yield* readLatestStreamArn(keyspaceName, tableName).pipe(
291 Effect.flatMap((arn) =>
292 arn !== undefined
293 ? Effect.succeed<string | undefined>(arn)
294 : Effect.fail(
295 new KeyspacesTableNotReady({
296 message: `CDC stream for '${keyspaceName}.${tableName}' not yet visible`,
297 }),
298 ),
299 ),
300 Effect.retry({
301 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
302 }),
303 Effect.orElseSucceed(() => undefined),
304 );
305 });
306
307 // Bounded readiness wait; Keyspaces tables typically reach ACTIVE within
308 // a minute. Budget ~5 min (60 * 5s). When `requiredColumns` is provided
309 // the wait also blocks until those columns are visible in the schema —
310 // AddColumn updates return before the table transitions out of ACTIVE and
311 // the new columns propagate to GetTable with a short lag.
312 const waitForActive = Effect.fn(function* (
313 keyspaceName: string,
314 tableName: string,
315 requiredColumns?: readonly string[],
316 ) {
317 const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(60)]);
318 return yield* readTable(keyspaceName, tableName).pipe(
319 Effect.flatMap((table) => {
320 if (table === undefined) {
321 return Effect.fail(
322 new KeyspacesTableNotReady({ message: `Keyspaces table '${tableName}' not found` }),
323 );
324 }
325 if (!activeStatuses.has(table.status ?? "")) {
326 return Effect.fail(
327 new KeyspacesTableNotReady({
328 message: `Keyspaces table '${tableName}' not active (status: ${table.status})`,
329 }),
330 );
331 }
332 if (requiredColumns !== undefined) {
333 const present = new Set(
334 (table.schemaDefinition?.allColumns ?? []).map((c) => c.name),
335 );
336 const missing = requiredColumns.filter((c) => !present.has(c));
337 if (missing.length > 0) {
338 return Effect.fail(
339 new KeyspacesTableNotReady({
340 message: `Keyspaces table '${tableName}' missing columns: ${missing.join(", ")}`,
341 }),
342 );
343 }
344 }
345 return Effect.succeed(table);
346 }),
347 Effect.retry({ schedule: policy }),
348 );
349 });
350
351 const toCapacity = (
352 capacity: KeyspacesCapacity | undefined,
353 ): keyspaces.CapacitySpecification | undefined =>
354 capacity === undefined
355 ? undefined
356 : {
357 throughputMode: capacity.throughputMode,
358 readCapacityUnits: capacity.readCapacityUnits,
359 writeCapacityUnits: capacity.writeCapacityUnits,
360 };
361
362 return {
363 stables: ["keyspaceName", "tableName", "tableArn"],
364
365 diff: Effect.fn(function* ({ id, olds, news }) {
366 if (!isResolved(news)) return undefined;
367 const oldProps = olds as TableProps | undefined;
368 if (oldProps === undefined) return undefined;
369 if (news.keyspaceName !== oldProps.keyspaceName) {
370 return { action: "replace" } as const;
371 }
372 if ((yield* toName(id, oldProps)) !== (yield* toName(id, news))) {
373 return { action: "replace" } as const;
374 }
375 // Keys and column removals/retypes require a replacement; pure
376 // column additions are handled in reconcile via UpdateTable.
377 const newCols = new Map(news.columns.map((c) => [c.name, c.type]));
378 const removedOrRetyped = oldProps.columns.some((c) => newCols.get(c.name) !== c.type);
379 const keysChanged =
380 JSON.stringify([...news.partitionKeys].sort()) !==
381 JSON.stringify([...oldProps.partitionKeys].sort()) ||
382 JSON.stringify(
383 (news.clusteringKeys ?? []).map((c) => `${c.name}:${c.orderBy ?? "ASC"}`).sort(),
384 ) !==
385 JSON.stringify(
386 (oldProps.clusteringKeys ?? [])
387 .map((c) => `${c.name}:${c.orderBy ?? "ASC"}`)
388 .sort(),
389 ) ||
390 JSON.stringify([...(news.staticColumns ?? [])].sort()) !==
391 JSON.stringify([...(oldProps.staticColumns ?? [])].sort());
392 if (removedOrRetyped || keysChanged) {
393 return { action: "replace" } as const;
394 }
395 }),
396
397 read: Effect.fn(function* ({ id, olds, output }) {
398 const props = (olds ?? {}) as Partial<TableProps>;
399 const keyspaceName = output?.keyspaceName ?? props.keyspaceName;
400 if (keyspaceName === undefined) return undefined;
401 const tableName = output?.tableName ?? (yield* toName(id, props));
402 const found = yield* readTable(keyspaceName, tableName);
403 if (found === undefined || found.status === "DELETING") {
404 return undefined;
405 }
406 const attrs = {
407 keyspaceName: found.keyspaceName,
408 tableName: found.tableName,
409 tableArn: found.resourceArn,
410 status: found.status ?? "ACTIVE",
411 latestStreamArn: isCdcEnabled(found)
412 ? yield* readLatestStreamArn(found.keyspaceName, found.tableName)
413 : undefined,
414 };
415 const tags = yield* readTags(found.resourceArn);
416 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
417 }),
418
419 reconcile: Effect.fn(function* ({ id, news, output, session }) {
420 const props = news as TableProps;
421 const keyspaceName = props.keyspaceName;
422 const tableName = output?.tableName ?? (yield* toName(id, props));
423 // The Keyspaces API expects the default TTL in whole seconds.
424 const desiredTtlSeconds = toWireSeconds(props.defaultTimeToLive);
425 const internalTags = yield* createInternalTags(id);
426 const desiredTags = { ...internalTags, ...props.tags };
427
428 // 1. Observe — cloud state is authoritative.
429 let observed = yield* readTable(keyspaceName, tableName);
430
431 // 2. Ensure — create if missing; tolerate the AlreadyExists race.
432 if (observed === undefined) {
433 yield* keyspaces
434 .createTable({
435 keyspaceName,
436 tableName,
437 schemaDefinition: buildSchema(props),
438 capacitySpecification: toCapacity(props.capacity),
439 pointInTimeRecovery: props.pointInTimeRecovery ? { status: "ENABLED" } : undefined,
440 ttl: props.ttlEnabled ? { status: "ENABLED" } : undefined,
441 defaultTimeToLive: desiredTtlSeconds,
442 cdcSpecification:
443 props.cdcSpecification?.status === "ENABLED"
444 ? {
445 status: "ENABLED",
446 viewType: props.cdcSpecification.viewType ?? "NEW_AND_OLD_IMAGES",
447 }
448 : undefined,
449 tags: Object.entries(desiredTags).map(([key, value]) => ({
450 key,
451 value,
452 })),
453 })
454 .pipe(Effect.catchTag("ConflictException", () => Effect.void));
455 }
456
457 observed = yield* waitForActive(keyspaceName, tableName);
458
459 // 3. Sync mutable aspects against observed state.
460 const update: keyspaces.UpdateTableRequest = {
461 keyspaceName,
462 tableName,
463 };
464 let needsUpdate = false;
465
466 const observedCols = new Set(
467 (observed.schemaDefinition?.allColumns ?? []).map((c) => c.name),
468 );
469 const addColumns = props.columns.filter((c) => !observedCols.has(c.name));
470 if (addColumns.length > 0) {
471 update.addColumns = addColumns.map((c) => ({
472 name: c.name,
473 type: c.type,
474 }));
475 needsUpdate = true;
476 }
477
478 const desiredCapacity = toCapacity(props.capacity);
479 if (
480 desiredCapacity !== undefined &&
481 (desiredCapacity.throughputMode !== observed.capacitySpecification?.throughputMode ||
482 (desiredCapacity.throughputMode === "PROVISIONED" &&
483 (desiredCapacity.readCapacityUnits !==
484 observed.capacitySpecification?.readCapacityUnits ||
485 desiredCapacity.writeCapacityUnits !==
486 observed.capacitySpecification?.writeCapacityUnits)))
487 ) {
488 update.capacitySpecification = desiredCapacity;
489 needsUpdate = true;
490 }
491
492 const desiredPitr = props.pointInTimeRecovery ? "ENABLED" : "DISABLED";
493 if (desiredPitr !== (observed.pointInTimeRecovery?.status ?? "DISABLED")) {
494 update.pointInTimeRecovery = { status: desiredPitr };
495 needsUpdate = true;
496 }
497
498 if (props.ttlEnabled && observed.ttl?.status !== "ENABLED") {
499 update.ttl = { status: "ENABLED" };
500 needsUpdate = true;
501 }
502 if (desiredTtlSeconds !== undefined && desiredTtlSeconds !== observed.defaultTimeToLive) {
503 update.defaultTimeToLive = desiredTtlSeconds;
504 needsUpdate = true;
505 }
506
507 const desiredCdcEnabled = props.cdcSpecification?.status === "ENABLED";
508 if (desiredCdcEnabled !== isCdcEnabled(observed)) {
509 update.cdcSpecification = desiredCdcEnabled
510 ? {
511 status: "ENABLED",
512 viewType: props.cdcSpecification?.viewType ?? "NEW_AND_OLD_IMAGES",
513 }
514 : { status: "DISABLED" };
515 needsUpdate = true;
516 }
517
518 if (needsUpdate) {
519 yield* keyspaces.updateTable(update);
520 observed = yield* waitForActive(
521 keyspaceName,
522 tableName,
523 props.columns.map((c) => c.name),
524 );
525 }
526
527 // 3b. Sync tags — diff against OBSERVED cloud tags.
528 const observedTags = yield* readTags(observed.resourceArn);
529 const { upsert, removed } = diffTags(observedTags, desiredTags);
530 if (upsert.length > 0) {
531 yield* keyspaces.tagResource({
532 resourceArn: observed.resourceArn,
533 tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
534 });
535 }
536 if (removed.length > 0) {
537 yield* keyspaces.untagResource({
538 resourceArn: observed.resourceArn,
539 tags: removed.map((key) => ({ key, value: "" })),
540 });
541 }
542
543 yield* session.note(`${keyspaceName}.${tableName}`);
544 return {
545 keyspaceName: observed.keyspaceName,
546 tableName: observed.tableName,
547 tableArn: observed.resourceArn,
548 status: observed.status ?? "ACTIVE",
549 latestStreamArn: isCdcEnabled(observed)
550 ? yield* waitForStreamArn(observed.keyspaceName, observed.tableName)
551 : undefined,
552 };
553 }),
554
555 delete: Effect.fn(function* ({ output }) {
556 const { keyspaceName, tableName } = output;
557 yield* keyspaces.deleteTable({ keyspaceName, tableName }).pipe(
558 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
559 // A table still CREATING/UPDATING rejects delete with
560 // ConflictException; retry until it settles.
561 Effect.retry({
562 while: (e) => e._tag === "ConflictException",
563 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(24)]),
564 }),
565 );
566 // Wait (bounded) until the table is gone so the parent keyspace can
567 // be deleted without a ConflictException.
568 yield* readTable(keyspaceName, tableName).pipe(
569 Effect.flatMap((t) =>
570 t === undefined
571 ? Effect.void
572 : Effect.fail(
573 new KeyspacesTableNotReady({ message: `Table '${tableName}' still deleting` }),
574 ),
575 ),
576 // Point-in-time-recovery tables take minutes to finish deleting.
577 Effect.retry({
578 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
579 }),
580 Effect.ignore,
581 );
582 }),
583
584 // Table is keyed by a parent keyspace and cannot be enumerated
585 // account-wide without iterating every keyspace; treated as a
586 // sub-resource per the factory list() convention.
587 list: () => Effect.succeed([]),
588 };
589 }),
590 );