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

main
ts 2,281 lines 92.6 KB
Raw
1 import * as cloudwatch from "@distilled.cloud/aws/cloudwatch";
2 import type * as DynamoDB from "@distilled.cloud/aws/dynamodb";
3 import type { TimeToLiveSpecification } from "@distilled.cloud/aws/dynamodb";
4 import * as dynamodb from "@distilled.cloud/aws/dynamodb";
5 import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
6 import { havePropsChanged, isResolved } from "alchemy/Diff";
7 import type { Input } from "alchemy/Input";
8 import { createPhysicalName } from "alchemy/PhysicalName";
9 import * as Provider from "alchemy/Provider";
10 import { Resource } from "alchemy/Resource";
11 import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
12 import { toWireDays } from "alchemy/Util/Duration";
13 import type * as lambda from "aws-lambda";
14 import * as Data from "effect/Data";
15 import type * as Duration from "effect/Duration";
16 import * as Effect from "effect/Effect";
17 import * as Schedule from "effect/Schedule";
18 import * as Stream from "effect/Stream";
19 import type { AccountID } from "../Environment.ts";
20 import type { Providers } from "../Providers.ts";
21 import type { RegionID } from "../Region.ts";
22
23 export class TableUnexpectedResponse extends Data.TaggedError("TableUnexpectedResponse")<{
24 readonly message: string;
25 readonly cause?: unknown;
26 }> {}
27
28 export type TableName = string;
29
30 export type TableArn = `arn:aws:dynamodb:${RegionID}:${AccountID}:table/${TableName}`;
31
32 export type TableRecord<Data> = Omit<lambda.DynamoDBRecord, "dynamodb"> & {
33 dynamodb: Omit<lambda.StreamRecord, "NewImage" | "OldImage"> & {
34 NewImage?: Data;
35 OldImage?: Data;
36 };
37 };
38
39 export type TableEvent<Data> = Omit<lambda.DynamoDBStreamEvent, "Records"> & {
40 Records: TableRecord<Data>[];
41 };
42
43 export type ScalarAttributeType = "S" | "N" | "B";
44
45 export interface PointInTimeRecoverySpecification {
46 /**
47 * Whether point-in-time recovery (continuous backups) is enabled for the
48 * table.
49 */
50 pointInTimeRecoveryEnabled: boolean;
51 /**
52 * How far back the table can be restored, e.g. `"7 days"` or
53 * `Duration.days(7)`. Rounded to whole days on the wire (1–35 days).
54 * @default 35 days
55 */
56 recoveryPeriod?: Duration.Input;
57 }
58
59 export interface KinesisStreamingDestination {
60 /**
61 * ARN of the destination Kinesis Data Stream. The stream must be ACTIVE
62 * when the destination is enabled (deploy the `AWS.Kinesis.Stream`
63 * resource in the same stack and pass `stream.streamArn`).
64 */
65 streamArn: string;
66 /**
67 * Precision of the approximate creation timestamp stamped on records
68 * delivered to the Kinesis stream. Changing this on an ACTIVE destination
69 * updates it in place, but the UPDATING→ACTIVE transition can take several
70 * minutes.
71 * @default "MILLISECOND"
72 */
73 approximateCreationDateTimePrecision?: DynamoDB.ApproximateCreationDateTimePrecision;
74 }
75
76 /**
77 * One or more attribute names forming an index key. DynamoDB's wire format
78 * flattens both key segments into a single ordered `KeySchema` list, but
79 * semantically a key is two ordered segments — this type captures one of
80 * them. Order is significant: partition attributes are hashed together in
81 * declaration order, and sort attributes are queried left-to-right.
82 */
83 export type IndexKey = string | string[];
84
85 export interface LocalSecondaryIndexProps {
86 /**
87 * Name of the index, unique within the table.
88 */
89 indexName: string;
90 /**
91 * Sort key attribute name. An LSI always shares the table's partition
92 * key, so only the sort key is declared; multi-attribute keys are not
93 * supported on LSIs.
94 */
95 sortKey: string;
96 /**
97 * Attributes projected from the table into the index.
98 */
99 projection: DynamoDB.Projection;
100 }
101
102 export interface GlobalSecondaryIndexProps {
103 /**
104 * Name of the index, unique within the table.
105 */
106 indexName: string;
107 /**
108 * Partition key attribute name(s). Up to four attributes may be listed;
109 * they are hashed together in declaration order and every one must be
110 * specified with an equality condition when querying the index.
111 */
112 partitionKey: IndexKey;
113 /**
114 * Optional sort key attribute name(s). Up to four attributes may be
115 * listed; items sort by each attribute in declaration order and queries
116 * narrow them left-to-right (no gaps, inequality last).
117 */
118 sortKey?: IndexKey;
119 /**
120 * Attributes projected from the table into the index.
121 */
122 projection: DynamoDB.Projection;
123 provisionedThroughput?: DynamoDB.ProvisionedThroughput;
124 onDemandThroughput?: DynamoDB.OnDemandThroughput;
125 warmThroughput?: DynamoDB.WarmThroughput;
126 }
127
128 export type TableProps = {
129 /**
130 * Name of the table. If omitted, Alchemy generates a deterministic physical
131 * name from the stack, stage, and logical ID, suffixed with the instance ID
132 * so replacements can create the successor table before deleting the old one.
133 *
134 * Changing this property replaces the table. If the name is hard-coded,
135 * replacement-triggering changes (key schema, attribute types, LSIs, GSI
136 * key changes) delete the old table first and then recreate it under the
137 * same name, since DynamoDB table names are unique per account/region.
138 */
139 tableName?: string;
140 /**
141 * Partition key attribute name for the table.
142 *
143 * Base-table primary keys are always a single partition attribute plus an
144 * optional single sort attribute — DynamoDB supports multi-attribute keys
145 * only on global secondary indexes (see `globalSecondaryIndexes`).
146 */
147 partitionKey: string;
148 /**
149 * Optional sort key attribute name for the table.
150 */
151 sortKey?: string;
152 /**
153 * Attribute definitions used by the primary key and any secondary indexes.
154 */
155 attributes: Record<string, ScalarAttributeType>;
156 /**
157 * Local secondary indexes, created with the table. An LSI always shares
158 * the table's partition key and declares a single sort key. Changing this
159 * property replaces the table.
160 */
161 localSecondaryIndexes?: LocalSecondaryIndexProps[];
162 /**
163 * Global secondary indexes. GSIs support multi-attribute keys: up to four
164 * partition attributes (hashed together as the composite partition key)
165 * and up to four sort attributes (sorted and queried left-to-right).
166 * Attribute order is significant — reordering defines a different index
167 * and replaces the table. Every key attribute must appear in `attributes`.
168 */
169 globalSecondaryIndexes?: GlobalSecondaryIndexProps[];
170 billingMode?: DynamoDB.BillingMode;
171 deletionProtectionEnabled?: boolean;
172 onDemandThroughput?: DynamoDB.OnDemandThroughput;
173 /**
174 * Enables point-in-time recovery (continuous backups) and optionally sets
175 * the recovery window via `recoveryPeriod` (a `Duration.Input`, rounded to
176 * whole days on the wire).
177 */
178 pointInTimeRecoverySpecification?: PointInTimeRecoverySpecification;
179 provisionedThroughput?: DynamoDB.ProvisionedThroughput;
180 sseSpecification?: DynamoDB.SSESpecification;
181 tags?: Record<string, string>;
182 timeToLiveSpecification?: DynamoDB.TimeToLiveSpecification;
183 warmThroughput?: DynamoDB.WarmThroughput;
184 tableClass?: DynamoDB.TableClass;
185 /**
186 * Resource-based IAM policy document (JSON string) attached to the table.
187 * Grants cross-account or scoped-principal access to the table and its
188 * indexes. Removing the property deletes the policy.
189 */
190 resourcePolicy?: string;
191 /**
192 * Streams change data capture records to the given Kinesis Data Stream.
193 * Changing the stream disables the old destination before enabling the
194 * new one; removing the property disables streaming.
195 */
196 kinesisStreamingDestination?: KinesisStreamingDestination;
197 /**
198 * Enables CloudWatch Contributor Insights (table-level rule) for the
199 * table, surfacing the most-accessed and most-throttled keys.
200 * @default false
201 */
202 contributorInsightsEnabled?: boolean;
203 };
204
205 export type TableBinding = {
206 streamSpecification?: DynamoDB.StreamSpecification;
207 };
208
209 export interface Table extends Resource<
210 "AWS.DynamoDB.Table",
211 TableProps,
212 {
213 /** The unique ID AWS assigns to the table. */
214 tableId: string;
215 /** The physical name of the table. */
216 tableName: TableName;
217 /** The ARN of the table. */
218 tableArn: TableArn;
219 /** The AWS region the table lives in. */
220 region: RegionID;
221 /** The partition (hash) key attribute name. */
222 partitionKey: string;
223 /** The sort (range) key attribute name, if defined. */
224 sortKey: string | undefined;
225 /** ARN of the most recent DynamoDB stream (when streams are enabled). */
226 latestStreamArn: string | undefined;
227 /** The current stream configuration (when streams are enabled). */
228 streamSpecification: DynamoDB.StreamSpecification | undefined;
229 /** Descriptions of the table's local secondary indexes. */
230 localSecondaryIndexes: DynamoDB.LocalSecondaryIndexDescription[] | undefined;
231 /** Descriptions of the table's global secondary indexes. */
232 globalSecondaryIndexes: DynamoDB.GlobalSecondaryIndexDescription[] | undefined;
233 /** The point-in-time recovery status of the table. */
234 pointInTimeRecoveryDescription: DynamoDB.PointInTimeRecoveryDescription | undefined;
235 /** The tags attached to the table. */
236 tags: Record<string, string> | undefined;
237 /**
238 * Billing mode, as observed on the table. Lets `alchemy drift` detect
239 * out-of-band changes.
240 */
241 billingMode?: DynamoDB.BillingMode;
242 /**
243 * Table-level provisioned capacity (PROVISIONED tables only), as
244 * observed. Lets `alchemy drift` detect out-of-band changes.
245 */
246 provisionedThroughput?: {
247 ReadCapacityUnits?: number;
248 WriteCapacityUnits?: number;
249 };
250 /**
251 * Table-level on-demand maximums, observed when `onDemandThroughput` is
252 * set. Lets `alchemy drift` detect out-of-band changes.
253 */
254 onDemandThroughput?: DynamoDB.OnDemandThroughput;
255 /**
256 * Whether deletion protection is enabled, as observed. Lets
257 * `alchemy drift` detect out-of-band changes.
258 */
259 deletionProtectionEnabled?: boolean;
260 /**
261 * KMS server-side encryption, as observed (`undefined` when the table
262 * uses the default AWS owned key). Lets `alchemy drift` detect
263 * out-of-band changes.
264 */
265 sseDescription?: {
266 sseType?: string;
267 kmsMasterKeyArn?: string;
268 };
269 /**
270 * Table class, as observed. Lets `alchemy drift` detect out-of-band
271 * changes.
272 */
273 tableClass?: DynamoDB.TableClass;
274 /**
275 * Time-to-live attribute when TTL is enabled, as observed. Lets
276 * `alchemy drift` detect out-of-band changes.
277 */
278 timeToLiveAttributeName?: string;
279 /**
280 * Resource-based policy document attached to the table (canonical JSON),
281 * as observed. Lets `alchemy drift` detect out-of-band changes.
282 */
283 resourcePolicy?: string;
284 /**
285 * Active Kinesis streaming destinations, as observed. Lets
286 * `alchemy drift` detect out-of-band changes.
287 */
288 kinesisStreamingDestinations?: {
289 streamArn: string;
290 approximateCreationDateTimePrecision: string;
291 }[];
292 /**
293 * Whether Contributor Insights is enabled, as observed. Lets
294 * `alchemy drift` detect out-of-band changes.
295 */
296 contributorInsightsEnabled?: boolean;
297 },
298 TableBinding,
299 Providers
300 > {}
301
302 /**
303 * An Amazon DynamoDB table with optional indexes, PITR, TTL, and stream-aware
304 * binding support.
305 *
306 * `Table` owns the lifecycle of the physical table while the binding contract
307 * allows runtime-specific integrations such as Lambda table event sources to
308 * request stream configuration without forcing a circular input prop.
309 * ### Creating Tables
310 * **Example:** Basic Table
311 * ```typescript
312 * import * as DynamoDB from "@alchemy.run/aws/DynamoDB";
313 *
314 * const table = yield* DynamoDB.Table("UsersTable", {
315 * partitionKey: "pk",
316 * attributes: {
317 * pk: "S",
318 * },
319 * });
320 * ```
321 *
322 * **Example:** Table with Sort Key and TTL
323 * ```typescript
324 * const table = yield* DynamoDB.Table("SessionsTable", {
325 * partitionKey: "userId",
326 * sortKey: "sessionId",
327 * attributes: {
328 * userId: "S",
329 * sessionId: "S",
330 * expiresAt: "N",
331 * },
332 * timeToLiveSpecification: {
333 * Enabled: true,
334 * AttributeName: "expiresAt",
335 * },
336 * });
337 * ```
338 *
339 * **Example:** Table with Global Secondary Index
340 * ```typescript
341 * const table = yield* DynamoDB.Table("OrdersTable", {
342 * partitionKey: "pk",
343 * sortKey: "sk",
344 * attributes: {
345 * pk: "S",
346 * sk: "S",
347 * gsi1pk: "S",
348 * gsi1sk: "S",
349 * },
350 * globalSecondaryIndexes: [{
351 * indexName: "GSI1",
352 * partitionKey: "gsi1pk",
353 * sortKey: "gsi1sk",
354 * projection: { ProjectionType: "ALL" },
355 * }],
356 * });
357 * ```
358 *
359 * **Example:** Multi-Attribute GSI Keys
360 * GSI partition and sort keys may be composed of up to four attributes each,
361 * indexing natural domain attributes directly instead of synthetic
362 * concatenated keys. Partition attributes are hashed together (queries must
363 * specify all of them with equality); sort attributes are queried
364 * left-to-right in declaration order.
365 * ```typescript
366 * const matches = yield* DynamoDB.Table("TournamentMatches", {
367 * partitionKey: "matchId",
368 * attributes: {
369 * matchId: "S",
370 * tournamentId: "S",
371 * region: "S",
372 * round: "S",
373 * },
374 * globalSecondaryIndexes: [{
375 * indexName: "TournamentRegionIndex",
376 * partitionKey: ["tournamentId", "region"],
377 * sortKey: ["round", "matchId"],
378 * projection: { ProjectionType: "ALL" },
379 * }],
380 * });
381 *
382 * // init
383 * const query = yield* AWS.DynamoDB.Query(matches);
384 *
385 * // runtime: query with every partition attribute, then narrow the sort
386 * // attributes left-to-right
387 * const response = yield* query({
388 * IndexName: "TournamentRegionIndex",
389 * KeyConditionExpression:
390 * "tournamentId = :t AND #r = :r AND round = :round",
391 * ExpressionAttributeNames: { "#r": "region" },
392 * ExpressionAttributeValues: {
393 * ":t": { S: "WINTER2024" },
394 * ":r": { S: "NA-EAST" },
395 * ":round": { S: "SEMIFINALS" },
396 * },
397 * });
398 * ```
399 *
400 * ### Runtime Operations
401 * Bind DynamoDB operations in the init phase and use them in runtime
402 * handlers. Bindings inject the table name and grant scoped IAM
403 * permissions automatically.
404 *
405 * **Example:** Read and write items
406 * ```typescript
407 * // init
408 * const getItem = yield* AWS.DynamoDB.GetItem(table);
409 * const putItem = yield* AWS.DynamoDB.PutItem(table);
410 *
411 * return {
412 * fetch: Effect.gen(function* () {
413 * // runtime
414 * yield* putItem({
415 * Item: { pk: { S: "user#123" }, name: { S: "Alice" } },
416 * });
417 * const result = yield* getItem({
418 * Key: { pk: { S: "user#123" } },
419 * });
420 * return yield* HttpServerResponse.json(result.Item);
421 * }),
422 * };
423 * ```
424 *
425 * **Example:** Read and write items from a Cloudflare Worker
426 *
427 * The `*Http` layers also run on a Cloudflare Worker. Alchemy creates an
428 * IAM user, access key, and least-privilege role for the Worker, binds the
429 * key onto it, and signs each request with the assumed role in the table's
430 * region. The Stack needs both provider sets:
431 * `Layer.mergeAll(Cloudflare.providers(), AWS.providers())`.
432 * ```typescript
433 * export default class Api extends Cloudflare.Worker<Api>()(
434 * "Api",
435 * { main: import.meta.url },
436 * Effect.gen(function* () {
437 * const table = yield* AWS.DynamoDB.Table("Links", {
438 * partitionKey: "id",
439 * attributes: { id: "S" },
440 * });
441 * const getItem = yield* AWS.DynamoDB.GetItem(table);
442 * const putItem = yield* AWS.DynamoDB.PutItem(table);
443 * return {
444 * fetch: Effect.gen(function* () {
445 * yield* putItem({ Item: { id: { S: "a" }, url: { S: "https://alchemy.run" } } });
446 * const { Item } = yield* getItem({ Key: { id: { S: "a" } } });
447 * return yield* HttpServerResponse.json(Item);
448 * }).pipe(Effect.orDie),
449 * };
450 * }).pipe(
451 * Effect.provide(
452 * Layer.mergeAll(AWS.DynamoDB.GetItemHttp, AWS.DynamoDB.PutItemHttp),
453 * ),
454 * ),
455 * ) {}
456 * ```
457 *
458 * ### Table Features
459 * **Example:** Resource Policy
460 * ```typescript
461 * const table = yield* DynamoDB.Table("SharedTable", {
462 * partitionKey: "pk",
463 * attributes: { pk: "S" },
464 * resourcePolicy: JSON.stringify({
465 * Version: "2012-10-17",
466 * Statement: [{
467 * Effect: "Allow",
468 * Principal: { AWS: "arn:aws:iam::111122223333:root" },
469 * Action: ["dynamodb:GetItem", "dynamodb:Query"],
470 * Resource: "*",
471 * }],
472 * }),
473 * });
474 * ```
475 *
476 * **Example:** Kinesis Streaming Destination
477 * ```typescript
478 * import * as Kinesis from "@alchemy.run/aws/Kinesis";
479 *
480 * const stream = yield* Kinesis.Stream("CdcStream", {});
481 * const table = yield* DynamoDB.Table("CdcTable", {
482 * partitionKey: "pk",
483 * attributes: { pk: "S" },
484 * kinesisStreamingDestination: {
485 * streamArn: stream.streamArn,
486 * approximateCreationDateTimePrecision: "MICROSECOND",
487 * },
488 * });
489 * ```
490 *
491 * **Example:** Contributor Insights
492 * ```typescript
493 * const table = yield* DynamoDB.Table("HotKeyTable", {
494 * partitionKey: "pk",
495 * attributes: { pk: "S" },
496 * contributorInsightsEnabled: true,
497 * });
498 * ```
499 *
500 * ### DynamoDB Streams
501 * Process change data capture events from a DynamoDB table using a
502 * Lambda event source mapping. The stream is enabled automatically
503 * through the binding contract.
504 *
505 * **Example:** Process table changes
506 * ```typescript
507 * // init
508 * yield* DynamoDB.consumeTableChanges(
509 * table,
510 * { streamViewType: "NEW_AND_OLD_IMAGES" },
511 * Effect.fn(function* (event) {
512 * for (const record of event.Records) {
513 * yield* Effect.log(`${record.eventName}: ${JSON.stringify(record.dynamodb)}`);
514 * }
515 * }),
516 * );
517 * ```
518 *
519 * @resource
520 */
521 export const Table = Resource<Table>("AWS.DynamoDB.Table");
522
523 export const TableProvider = () =>
524 Provider.effect(
525 Table,
526 Effect.gen(function* () {
527 const createTableName = (id: string, props: Input.ResolveProps<TableProps>) =>
528 Effect.gen(function* () {
529 return (
530 props.tableName ??
531 (yield* createPhysicalName({
532 id,
533 // see: https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TableDescription.html#DDB-Type-TableDescription-TableName
534 maxLength: 255,
535 }))
536 );
537 });
538
539 const toKeySchema = (props: Input.ResolveProps<TableProps>) => [
540 {
541 AttributeName: props.partitionKey,
542 KeyType: "HASH" as const,
543 },
544 ...(props.sortKey
545 ? [
546 {
547 AttributeName: props.sortKey,
548 KeyType: "RANGE" as const,
549 },
550 ]
551 : []),
552 ];
553
554 const toKeyAttributeNames = (key: IndexKey | undefined) =>
555 key === undefined ? [] : typeof key === "string" ? [key] : key;
556
557 // AWS's wire format flattens an index key into one ordered KeySchema
558 // list and validates that all HASH elements precede all RANGE
559 // elements; deriving the list from the two typed segments makes the
560 // invalid orderings unrepresentable in props.
561 const toIndexKeySchema = (
562 partitionKey: IndexKey,
563 sortKey: IndexKey | undefined,
564 ): DynamoDB.KeySchemaElement[] => [
565 ...toKeyAttributeNames(partitionKey).map((name) => ({
566 AttributeName: name,
567 KeyType: "HASH" as const,
568 })),
569 ...toKeyAttributeNames(sortKey).map((name) => ({
570 AttributeName: name,
571 KeyType: "RANGE" as const,
572 })),
573 ];
574
575 // Pre-typed-props state may persist index props in the legacy wire
576 // shape ({ IndexName, KeySchema, ... }). Tolerate it when converting
577 // `olds` so upgrading alchemy never plans a spurious table
578 // replacement over a shape-only difference.
579 const isLegacyWireIndex = (index: unknown): index is DynamoDB.GlobalSecondaryIndex =>
580 typeof index === "object" && index !== null && "KeySchema" in index;
581
582 const toWireGlobalSecondaryIndex = (
583 index: GlobalSecondaryIndexProps,
584 ): DynamoDB.GlobalSecondaryIndex =>
585 isLegacyWireIndex(index)
586 ? index
587 : {
588 IndexName: index.indexName,
589 KeySchema: toIndexKeySchema(index.partitionKey, index.sortKey),
590 Projection: index.projection,
591 ProvisionedThroughput: index.provisionedThroughput,
592 OnDemandThroughput: index.onDemandThroughput,
593 WarmThroughput: index.warmThroughput,
594 };
595
596 const toWireLocalSecondaryIndex = (
597 tablePartitionKey: string,
598 index: LocalSecondaryIndexProps,
599 ): DynamoDB.LocalSecondaryIndex =>
600 isLegacyWireIndex(index)
601 ? index
602 : {
603 IndexName: index.indexName,
604 KeySchema: toIndexKeySchema(tablePartitionKey, index.sortKey),
605 Projection: index.projection,
606 };
607
608 const toWireGlobalSecondaryIndexes = (
609 indexes: readonly GlobalSecondaryIndexProps[] | undefined,
610 ) =>
611 indexes === undefined || indexes.length === 0
612 ? undefined
613 : indexes.map(toWireGlobalSecondaryIndex);
614
615 const toWireLocalSecondaryIndexes = (
616 tablePartitionKey: string,
617 indexes: readonly LocalSecondaryIndexProps[] | undefined,
618 ) =>
619 indexes === undefined || indexes.length === 0
620 ? undefined
621 : indexes.map((index) => toWireLocalSecondaryIndex(tablePartitionKey, index));
622
623 const toAttributeDefinitions = (attrs: Record<string, ScalarAttributeType>) =>
624 Object.entries(attrs)
625 .map(([name, type]) => ({
626 AttributeName: name,
627 AttributeType: type,
628 }))
629 .sort((a, b) => a.AttributeName.localeCompare(b.AttributeName));
630
631 const adoptExistingTable = (tableName: string) =>
632 // The engine has cleared us via `read` (foreign-tagged tables are
633 // surfaced as `Unowned`). On a race between read and create, just
634 // describe the existing table and continue.
635 dynamodb.describeTable({ TableName: tableName }).pipe(Effect.map((r) => r.Table!));
636
637 const createTags = Effect.fn(function* (id: string, tags?: Record<string, string>) {
638 return {
639 ...(yield* createInternalTags(id)),
640 ...tags,
641 };
642 });
643
644 const normalizeStreamSpecification = (
645 streamSpecification: DynamoDB.StreamSpecification | undefined,
646 ) =>
647 streamSpecification?.StreamEnabled === true
648 ? ({
649 StreamEnabled: true,
650 StreamViewType: streamSpecification.StreamViewType,
651 } satisfies DynamoDB.StreamSpecification)
652 : undefined;
653
654 const resolveStreamSpecification = (
655 bindings: ReadonlyArray<TableBinding | { data?: TableBinding }>,
656 ) =>
657 Effect.gen(function* () {
658 const requested = bindings
659 .flatMap((binding) =>
660 (binding as { data?: TableBinding }).data?.streamSpecification?.StreamEnabled === true
661 ? [
662 normalizeStreamSpecification(
663 (binding as { data?: TableBinding }).data?.streamSpecification,
664 ),
665 ]
666 : (binding as TableBinding).streamSpecification?.StreamEnabled === true
667 ? [normalizeStreamSpecification((binding as TableBinding).streamSpecification)]
668 : [],
669 )
670 .filter((spec) => spec !== undefined);
671
672 if (requested.length === 0) {
673 return undefined;
674 }
675
676 const [first, ...rest] = requested;
677 if (!first?.StreamViewType) {
678 return yield* new MissingStreamViewType();
679 }
680
681 for (const spec of rest) {
682 if (spec.StreamViewType !== first.StreamViewType) {
683 return yield* new ConflictingStreamViewTypes({
684 requested: requested.map((item) => item.StreamViewType),
685 });
686 }
687 }
688
689 return first;
690 });
691
692 const isRetryableControlPlaneError = (error: { _tag?: string }) =>
693 error._tag === "InternalServerError" ||
694 error._tag === "LimitExceededException" ||
695 error._tag === "ResourceInUseException" ||
696 error._tag === "ResourceNotFoundException" ||
697 // Throttling: DynamoDB's control-plane API limits are low and the
698 // blanket SDK retry (10 attempts) is easily exhausted when the whole
699 // suite hammers create/update/describe concurrently. Give it the
700 // provider's much larger budget too.
701 error._tag === "ThrottlingException" ||
702 error._tag === "ProvisionedThroughputExceededException" ||
703 error._tag === "RequestLimitExceeded";
704
705 const waitForControlPlaneConvergence = Schedule.max([
706 Schedule.fixed("1 second"),
707 Schedule.recurs(120),
708 ]);
709
710 const waitForTableActivationConvergence = Schedule.max([
711 Schedule.fixed("10 seconds"),
712 Schedule.recurs(180),
713 ]);
714
715 const waitForGlobalSecondaryIndexesConvergence = Schedule.max([
716 Schedule.fixed("10 seconds"),
717 Schedule.recurs(180),
718 ]);
719
720 const waitForDeletionConvergence = Schedule.max([
721 Schedule.fixed("1 second"),
722 Schedule.recurs(90),
723 ]);
724
725 const formatPollingElapsed = (elapsedSeconds: number) => `${elapsedSeconds}s elapsed`;
726
727 const formatGlobalSecondaryIndexStatuses = (
728 indexes: readonly DynamoDB.GlobalSecondaryIndexDescription[] | undefined,
729 ) =>
730 JSON.stringify(
731 (indexes ?? []).map((index) => ({
732 name: index.IndexName,
733 status: index.IndexStatus,
734 backfilling: index.Backfilling,
735 })),
736 );
737
738 const updateTimeToLive = (
739 tableName: string,
740 timeToLiveSpecification: TimeToLiveSpecification,
741 ) =>
742 dynamodb
743 .updateTimeToLive({
744 TableName: tableName,
745 TimeToLiveSpecification: timeToLiveSpecification!,
746 })
747 .pipe(
748 Effect.retry({
749 while: isRetryableControlPlaneError,
750 schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(30)]),
751 }),
752 );
753
754 const updateContinuousBackups = (
755 tableName: string,
756 pointInTimeRecoverySpecification: DynamoDB.PointInTimeRecoverySpecification,
757 ) =>
758 dynamodb
759 .updateContinuousBackups({
760 TableName: tableName,
761 PointInTimeRecoverySpecification: pointInTimeRecoverySpecification,
762 })
763 .pipe(
764 Effect.retry({
765 while: (e) =>
766 e._tag === "ContinuousBackupsUnavailableException" ||
767 isRetryableControlPlaneError(e),
768 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
769 }),
770 );
771
772 // Resource policies are compared as canonicalized JSON so formatting
773 // differences between what the user wrote and what AWS stores don't
774 // cause phantom putResourcePolicy calls on every reconcile.
775 const canonicalPolicyDocument = (policy: string | undefined) => {
776 if (policy === undefined) return undefined;
777 try {
778 return JSON.stringify(JSON.parse(policy));
779 } catch {
780 return policy;
781 }
782 };
783
784 const readTableResourcePolicy = (tableArn: string) =>
785 dynamodb.getResourcePolicy({ ResourceArn: tableArn }).pipe(
786 Effect.map((response) => response.Policy),
787 Effect.catchTag("PolicyNotFoundException", () => Effect.undefined),
788 Effect.retry({
789 while: isRetryableControlPlaneError,
790 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
791 }),
792 );
793
794 const putTableResourcePolicy = (tableArn: string, policy: string) =>
795 dynamodb.putResourcePolicy({ ResourceArn: tableArn, Policy: policy }).pipe(
796 Effect.retry({
797 while: isRetryableControlPlaneError,
798 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
799 }),
800 );
801
802 const deleteTableResourcePolicy = (tableArn: string) =>
803 dynamodb.deleteResourcePolicy({ ResourceArn: tableArn }).pipe(
804 Effect.catchTag("PolicyNotFoundException", () => Effect.void),
805 Effect.retry({
806 while: isRetryableControlPlaneError,
807 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
808 }),
809 );
810
811 const isKinesisDestinationTransitioning = (
812 destination: DynamoDB.KinesisDataStreamDestination,
813 ) =>
814 destination.DestinationStatus === "ENABLING" ||
815 destination.DestinationStatus === "DISABLING" ||
816 destination.DestinationStatus === "UPDATING";
817
818 // Kinesis streaming destinations transition ENABLING→ACTIVE and
819 // DISABLING→DISABLED within seconds, but a precision change
820 // (UPDATING→ACTIVE) takes multiple minutes; poll bounded to 8 minutes.
821 const waitForKinesisDestinationsConvergence = Schedule.max([
822 Schedule.fixed("5 seconds"),
823 Schedule.recurs(96),
824 ]);
825
826 const waitForKinesisDestinationsSettled = (
827 session: {
828 note: (message: string) => Effect.Effect<void, never, never>;
829 },
830 tableName: string,
831 ) => {
832 let elapsedSeconds = 0;
833 return Effect.gen(function* () {
834 const response = yield* dynamodb.describeKinesisStreamingDestination({
835 TableName: tableName,
836 });
837 const destinations = response.KinesisDataStreamDestinations ?? [];
838 if (destinations.some(isKinesisDestinationTransitioning)) {
839 return yield* new KinesisDestinationNotSettled();
840 }
841 return destinations;
842 }).pipe(
843 Effect.retry({
844 while: (error) =>
845 error._tag === "KinesisDestinationNotSettled" || isRetryableControlPlaneError(error),
846 schedule: waitForKinesisDestinationsConvergence.pipe(
847 Schedule.tap(({ attempt }) => {
848 elapsedSeconds = (attempt + 1) * 5;
849 return session.note(
850 `DynamoDB Table provider: waiting for Kinesis streaming destinations on ${tableName} to settle (${formatPollingElapsed(elapsedSeconds)})`,
851 );
852 }),
853 ),
854 }),
855 );
856 };
857
858 const disableKinesisDestination = (tableName: string, streamArn: string) =>
859 dynamodb
860 .disableKinesisStreamingDestination({
861 TableName: tableName,
862 StreamArn: streamArn,
863 })
864 .pipe(
865 Effect.retry({
866 while: isRetryableControlPlaneError,
867 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
868 }),
869 );
870
871 const enableKinesisDestination = (
872 tableName: string,
873 destination: KinesisStreamingDestination,
874 ) =>
875 dynamodb
876 .enableKinesisStreamingDestination({
877 TableName: tableName,
878 StreamArn: destination.streamArn,
879 EnableKinesisStreamingConfiguration:
880 destination.approximateCreationDateTimePrecision !== undefined
881 ? {
882 ApproximateCreationDateTimePrecision:
883 destination.approximateCreationDateTimePrecision,
884 }
885 : undefined,
886 })
887 .pipe(
888 Effect.retry({
889 while: isRetryableControlPlaneError,
890 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
891 }),
892 );
893
894 const updateKinesisDestinationPrecision = (
895 tableName: string,
896 destination: KinesisStreamingDestination,
897 ) =>
898 dynamodb
899 .updateKinesisStreamingDestination({
900 TableName: tableName,
901 StreamArn: destination.streamArn,
902 UpdateKinesisStreamingConfiguration: {
903 ApproximateCreationDateTimePrecision:
904 destination.approximateCreationDateTimePrecision,
905 },
906 })
907 .pipe(
908 Effect.retry({
909 while: isRetryableControlPlaneError,
910 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
911 }),
912 );
913
914 // Contributor Insights transitions ENABLING→ENABLED / DISABLING→DISABLED
915 // within seconds, but UpdateContributorInsights rejects a DISABLE while
916 // the status is still ENABLING — wait for a settled status before
917 // diffing observed against desired.
918 const waitForContributorInsightsSettled = (
919 session: {
920 note: (message: string) => Effect.Effect<void, never, never>;
921 },
922 tableName: string,
923 ) =>
924 Effect.gen(function* () {
925 const response = yield* dynamodb.describeContributorInsights({
926 TableName: tableName,
927 });
928 const status = response.ContributorInsightsStatus ?? "DISABLED";
929 if (status === "ENABLING" || status === "DISABLING") {
930 return yield* new ContributorInsightsNotSettled();
931 }
932 return status;
933 }).pipe(
934 Effect.retry({
935 while: (error) =>
936 error._tag === "ContributorInsightsNotSettled" || isRetryableControlPlaneError(error),
937 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(45)]).pipe(
938 Schedule.tap(({ attempt }) =>
939 session.note(
940 `DynamoDB Table provider: waiting for Contributor Insights on ${tableName} to settle (${formatPollingElapsed((attempt + 1) * 2)})`,
941 ),
942 ),
943 ),
944 }),
945 );
946
947 // Enabling Contributor Insights makes DynamoDB create CloudWatch rules
948 // named `DynamoDBContributorInsights-{PKC|PKT}-<tableName>-<timestamp>`
949 // in the customer's account. Those rules can ONLY be removed by
950 // DynamoDB's own asynchronous cleanup, which runs when an
951 // UpdateContributorInsights DISABLE completes — CloudWatch's
952 // DeleteInsightRules/PutInsightRule reject them with AccessDenied even
953 // for account admins, and deleting the table aborts the cleanup and
954 // strands the rules forever (recoverable only via AWS support). The
955 // delete lifecycle therefore observes the rules and holds off
956 // deleteTable until DynamoDB's cleanup has actually removed them.
957 const listContributorInsightsRules = (tableName: string) =>
958 cloudwatch.describeInsightRules.pages({}).pipe(
959 Stream.runFold(
960 () => [] as string[],
961 (acc, page) => [
962 ...acc,
963 ...(page.InsightRules ?? [])
964 .map((rule) => rule.Name)
965 .filter(
966 (name): name is string =>
967 name !== undefined &&
968 name.startsWith("DynamoDBContributorInsights-") &&
969 name.includes(`-${tableName}-`),
970 ),
971 ],
972 ),
973 );
974
975 const waitForContributorInsightsRulesDeleted = (
976 session: {
977 note: (message: string) => Effect.Effect<void, never, never>;
978 },
979 tableName: string,
980 ) =>
981 Effect.gen(function* () {
982 const remaining = yield* listContributorInsightsRules(tableName);
983 if (remaining.length > 0) {
984 return yield* new ContributorInsightsNotSettled();
985 }
986 }).pipe(
987 Effect.retry({
988 while: (error) =>
989 error._tag === "ContributorInsightsNotSettled" || isRetryableControlPlaneError(error),
990 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(20)]).pipe(
991 Schedule.tap(({ attempt }) =>
992 session.note(
993 `DynamoDB Table provider: waiting for Contributor Insights rules of ${tableName} to be cleaned up (${formatPollingElapsed((attempt + 1) * 2)})`,
994 ),
995 ),
996 ),
997 }),
998 // Rules from a PREVIOUS enable session whose cleanup was already
999 // aborted (e.g. by an out-of-band table deletion) can never be
1000 // removed by anyone but AWS support — don't wedge the delete on
1001 // them; surface a note and move on.
1002 Effect.catchTag("ContributorInsightsNotSettled", () =>
1003 session.note(
1004 `DynamoDB Table provider: Contributor Insights rules for ${tableName} were not cleaned up by DynamoDB; they may be stranded from an earlier enable session (deletable only via AWS support)`,
1005 ),
1006 ),
1007 );
1008
1009 const updateTableContributorInsights = (tableName: string, enabled: boolean) =>
1010 dynamodb
1011 .updateContributorInsights({
1012 TableName: tableName,
1013 ContributorInsightsAction: enabled ? "ENABLE" : "DISABLE",
1014 })
1015 .pipe(
1016 Effect.retry({
1017 while: isRetryableControlPlaneError,
1018 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
1019 }),
1020 );
1021
1022 const waitForTableActive = (
1023 session: {
1024 note: (message: string) => Effect.Effect<void, never, never>;
1025 },
1026 tableName: string,
1027 ) => {
1028 let elapsedSeconds = 0;
1029 let progressMessage = `DynamoDB Table provider: waiting for table ${tableName} to become ACTIVE`;
1030
1031 return Effect.gen(function* () {
1032 const response = yield* dynamodb.describeTable({
1033 TableName: tableName,
1034 });
1035 if (response.Table?.TableStatus !== "ACTIVE") {
1036 progressMessage = `DynamoDB Table provider: table ${tableName} not active yet (status=${response.Table?.TableStatus ?? "undefined"} gsiStatuses=${formatGlobalSecondaryIndexStatuses(response.Table?.GlobalSecondaryIndexes)})`;
1037 return yield* new TableNotActive();
1038 }
1039 yield* session.note(
1040 `DynamoDB Table provider: table ${tableName} is ACTIVE (${formatPollingElapsed(elapsedSeconds)})`,
1041 );
1042 return response.Table;
1043 }).pipe(
1044 Effect.retry({
1045 while: (error) =>
1046 error._tag === "TableNotActive" || isRetryableControlPlaneError(error),
1047 schedule: waitForTableActivationConvergence.pipe(
1048 Schedule.tap(({ attempt }) => {
1049 elapsedSeconds = attempt * 10;
1050 return session.note(`${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`);
1051 }),
1052 ),
1053 }),
1054 );
1055 };
1056
1057 const waitForGlobalSecondaryIndexesStable = (
1058 session: {
1059 note: (message: string) => Effect.Effect<void, never, never>;
1060 },
1061 tableName: string,
1062 expectedIndexNames: readonly string[],
1063 ) => {
1064 let elapsedSeconds = 0;
1065 let progressMessage = `DynamoDB Table provider: waiting for GSIs on ${tableName} to stabilize`;
1066
1067 return Effect.gen(function* () {
1068 const response = yield* dynamodb.describeTable({
1069 TableName: tableName,
1070 });
1071 const table = response.Table;
1072 const actualIndexNames = [...(table?.GlobalSecondaryIndexes ?? [])]
1073 .map((index) => index.IndexName!)
1074 .sort();
1075 const expected = [...expectedIndexNames].sort();
1076 const allActive = (table?.GlobalSecondaryIndexes ?? []).every(
1077 (index) => index.IndexStatus === "ACTIVE",
1078 );
1079
1080 if (JSON.stringify(actualIndexNames) !== JSON.stringify(expected) || !allActive) {
1081 progressMessage = `DynamoDB Table provider: GSIs for ${tableName} not stable yet (expected=${JSON.stringify(expected)} actual=${JSON.stringify(actualIndexNames)} statuses=${JSON.stringify((table?.GlobalSecondaryIndexes ?? []).map((index) => ({ name: index.IndexName, status: index.IndexStatus })))} tableStatus=${table?.TableStatus ?? "undefined"})`;
1082 return yield* new TableIndexesNotStable();
1083 }
1084
1085 yield* session.note(
1086 `DynamoDB Table provider: GSIs for ${tableName} stabilized (${JSON.stringify(actualIndexNames)}) (${formatPollingElapsed(elapsedSeconds)})`,
1087 );
1088 return table;
1089 }).pipe(
1090 Effect.retry({
1091 while: (error) =>
1092 error._tag === "TableIndexesNotStable" || isRetryableControlPlaneError(error),
1093 schedule: waitForGlobalSecondaryIndexesConvergence.pipe(
1094 Schedule.tap(({ attempt }) => {
1095 elapsedSeconds = attempt * 10;
1096 return session.note(`${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`);
1097 }),
1098 ),
1099 }),
1100 );
1101 };
1102
1103 const waitForTableDeleted = (
1104 session: {
1105 note: (message: string) => Effect.Effect<void, never, never>;
1106 },
1107 tableName: string,
1108 ) => {
1109 let elapsedSeconds = 0;
1110 let progressMessage = `DynamoDB Table provider: waiting for deletion of ${tableName}`;
1111
1112 return Effect.gen(function* () {
1113 const response = yield* dynamodb.describeTable({
1114 TableName: tableName,
1115 });
1116 progressMessage = `DynamoDB Table provider: table ${tableName} still deleting (status=${response.Table?.TableStatus ?? "undefined"})`;
1117 return yield* new TableStillDeleting();
1118 }).pipe(
1119 Effect.catchTag("ResourceNotFoundException", () =>
1120 session.note(
1121 `DynamoDB Table provider: table ${tableName} deletion confirmed (${formatPollingElapsed(elapsedSeconds)})`,
1122 ),
1123 ),
1124 Effect.retry({
1125 while: (error) =>
1126 error._tag === "TableStillDeleting" || isRetryableControlPlaneError(error),
1127 schedule: waitForDeletionConvergence.pipe(
1128 Schedule.tap(({ attempt }) => {
1129 elapsedSeconds = attempt;
1130 return session.note(`${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`);
1131 }),
1132 ),
1133 }),
1134 );
1135 };
1136
1137 const deleteGlobalSecondaryIndexes = (
1138 session: {
1139 note: (message: string) => Effect.Effect<void, never, never>;
1140 },
1141 tableName: string,
1142 ) =>
1143 Effect.gen(function* () {
1144 const response = yield* dynamodb
1145 .describeTable({
1146 TableName: tableName,
1147 })
1148 .pipe(
1149 Effect.retry({
1150 while: isRetryableControlPlaneError,
1151 schedule: waitForControlPlaneConvergence,
1152 }),
1153 Effect.catchTag("ResourceNotFoundException", () =>
1154 Effect.succeed({ Table: undefined }),
1155 ),
1156 );
1157
1158 const indexNames = [...(response.Table?.GlobalSecondaryIndexes ?? [])]
1159 .map((index) => index.IndexName!)
1160 .sort();
1161
1162 if (indexNames.length === 0) {
1163 yield* session.note(
1164 `DynamoDB Table provider: no GSIs remain on ${tableName}; retrying table deletion`,
1165 );
1166 return;
1167 }
1168
1169 yield* session.note(
1170 `DynamoDB Table provider: deleting GSIs before deleting table ${tableName} (${indexNames.join(", ")})`,
1171 );
1172
1173 yield* waitForGlobalSecondaryIndexesStable(session, tableName, indexNames);
1174
1175 const remainingIndexNames = [...indexNames];
1176 for (const indexName of indexNames) {
1177 let elapsedSeconds = 0;
1178 let progressMessage = `DynamoDB Table provider: waiting to delete GSI ${indexName} from ${tableName}`;
1179
1180 yield* session.note(
1181 `DynamoDB Table provider: deleting GSI ${indexName} from ${tableName}`,
1182 );
1183
1184 yield* dynamodb
1185 .updateTable({
1186 TableName: tableName,
1187 GlobalSecondaryIndexUpdates: [
1188 {
1189 Delete: {
1190 IndexName: indexName,
1191 },
1192 },
1193 ],
1194 })
1195 .pipe(
1196 Effect.timeout(1000),
1197 Effect.tap(() =>
1198 session.note(
1199 `DynamoDB Table provider: delete accepted for GSI ${indexName} on ${tableName} (${formatPollingElapsed(elapsedSeconds)})`,
1200 ),
1201 ),
1202 Effect.retry({
1203 while: (error) => {
1204 if (error._tag === "ResourceInUseException") {
1205 progressMessage = `DynamoDB Table provider: delete for GSI ${indexName} on ${tableName} is blocked while the table or indexes are still transitioning`;
1206 return true;
1207 }
1208 if (error._tag === "TimeoutError") {
1209 progressMessage = `DynamoDB Table provider: delete for GSI ${indexName} on ${tableName} timed out`;
1210 return true;
1211 }
1212 if (
1213 error._tag === "InternalServerError" ||
1214 error._tag === "LimitExceededException"
1215 ) {
1216 progressMessage = `DynamoDB Table provider: delete for GSI ${indexName} on ${tableName} hit ${error._tag}`;
1217 return true;
1218 }
1219 return false;
1220 },
1221 schedule: waitForGlobalSecondaryIndexesConvergence.pipe(
1222 Schedule.tap(({ attempt }) => {
1223 elapsedSeconds = attempt * 10;
1224 return session.note(
1225 `${progressMessage} (${formatPollingElapsed(elapsedSeconds)})`,
1226 );
1227 }),
1228 ),
1229 }),
1230 );
1231
1232 remainingIndexNames.splice(remainingIndexNames.indexOf(indexName), 1);
1233
1234 yield* waitForGlobalSecondaryIndexesStable(session, tableName, remainingIndexNames);
1235 }
1236 });
1237
1238 // For read, we want `ResourceNotFoundException` to propagate immediately
1239 // (the table doesn't exist — this is the cold-start adoption "no
1240 // resource" signal). Only retry on transient control-plane errors.
1241 const isRetryableReadError = (error: { _tag?: string }) =>
1242 error._tag === "InternalServerError" ||
1243 error._tag === "LimitExceededException" ||
1244 // See `isRetryableControlPlaneError`: read-path describes throttle too
1245 // under full-suite concurrency, so ride them out generously.
1246 error._tag === "ThrottlingException" ||
1247 error._tag === "ProvisionedThroughputExceededException" ||
1248 error._tag === "RequestLimitExceeded";
1249
1250 const readTableState = (tableName: string) =>
1251 Effect.gen(function* () {
1252 const response = yield* dynamodb
1253 .describeTable({
1254 TableName: tableName,
1255 })
1256 .pipe(
1257 Effect.retry({
1258 while: isRetryableReadError,
1259 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
1260 }),
1261 );
1262 const table = response.Table;
1263 if (!table?.TableArn) {
1264 return yield* new TableUnexpectedResponse({ message: `Table ${tableName} not found` });
1265 }
1266
1267 const [tagsResult, continuousBackupsResult, ttlResult] = yield* Effect.all([
1268 dynamodb
1269 .listTagsOfResource({
1270 ResourceArn: table.TableArn,
1271 })
1272 .pipe(
1273 Effect.retry({
1274 while: isRetryableReadError,
1275 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
1276 }),
1277 ),
1278 dynamodb
1279 .describeContinuousBackups({
1280 TableName: tableName,
1281 })
1282 .pipe(
1283 Effect.retry({
1284 while: (e) => e._tag === "InternalServerError",
1285 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
1286 }),
1287 Effect.catchTag("TableNotFoundException", () =>
1288 Effect.succeed({ ContinuousBackupsDescription: undefined }),
1289 ),
1290 ),
1291 dynamodb
1292 .describeTimeToLive({
1293 TableName: tableName,
1294 })
1295 .pipe(
1296 Effect.retry({
1297 while: isRetryableReadError,
1298 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(30)]),
1299 }),
1300 Effect.catchTag("ResourceNotFoundException", () =>
1301 Effect.succeed({ TimeToLiveDescription: undefined }),
1302 ),
1303 ),
1304 ]);
1305
1306 return {
1307 table,
1308 tags: Object.fromEntries(
1309 (tagsResult.Tags ?? []).map((tag) => [tag.Key!, tag.Value!]),
1310 ) as Record<string, string>,
1311 pointInTimeRecoveryDescription:
1312 continuousBackupsResult.ContinuousBackupsDescription?.PointInTimeRecoveryDescription,
1313 timeToLiveDescription: ttlResult.TimeToLiveDescription,
1314 };
1315 }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
1316
1317 const toAttrs = (state: {
1318 table: DynamoDB.TableDescription;
1319 tags: Record<string, string>;
1320 pointInTimeRecoveryDescription: DynamoDB.PointInTimeRecoveryDescription | undefined;
1321 }) => ({
1322 tableId: state.table.TableId!,
1323 tableName: state.table.TableName!,
1324 tableArn: state.table.TableArn! as TableArn,
1325 region: state.table.TableArn!.split(":")[3] as RegionID,
1326 partitionKey:
1327 state.table.KeySchema?.find((key) => key.KeyType === "HASH")?.AttributeName ?? "",
1328 sortKey: state.table.KeySchema?.find((key) => key.KeyType === "RANGE")?.AttributeName,
1329 latestStreamArn: state.table.LatestStreamArn,
1330 streamSpecification: state.table.StreamSpecification,
1331 // Index descriptions carry item counts, sizes and status that change
1332 // on their own; keep only the configuration so drift stays quiet.
1333 localSecondaryIndexes: state.table.LocalSecondaryIndexes?.map((index) => ({
1334 IndexName: index.IndexName,
1335 IndexArn: index.IndexArn,
1336 KeySchema: index.KeySchema,
1337 Projection: index.Projection,
1338 })),
1339 globalSecondaryIndexes: state.table.GlobalSecondaryIndexes?.map((index) => ({
1340 IndexName: index.IndexName,
1341 IndexArn: index.IndexArn,
1342 KeySchema: index.KeySchema,
1343 Projection: index.Projection,
1344 ProvisionedThroughput: normalizeProvisioned(index.ProvisionedThroughput),
1345 OnDemandThroughput: normalizeOnDemand(index.OnDemandThroughput),
1346 })),
1347 // The restorable window moves every second; only the setting is state.
1348 pointInTimeRecoveryDescription: state.pointInTimeRecoveryDescription && {
1349 PointInTimeRecoveryStatus: state.pointInTimeRecoveryDescription.PointInTimeRecoveryStatus,
1350 RecoveryPeriodInDays: state.pointInTimeRecoveryDescription.RecoveryPeriodInDays,
1351 },
1352 tags: state.tags,
1353 });
1354
1355 // DynamoDB omits `BillingModeSummary` for tables that have always been
1356 // PROVISIONED — fall back to the observed throughput (on-demand tables
1357 // report 0 read capacity).
1358 const observedBillingModeOf = (table: DynamoDB.TableDescription): DynamoDB.BillingMode =>
1359 table.BillingModeSummary?.BillingMode ??
1360 ((table.ProvisionedThroughput?.ReadCapacityUnits ?? 0) > 0
1361 ? "PROVISIONED"
1362 : "PAY_PER_REQUEST");
1363
1364 // Encrypted with a KMS key (AWS managed or customer managed) rather
1365 // than the default AWS owned key.
1366 const isKmsEncrypted = (sse: DynamoDB.SSEDescription | undefined) =>
1367 sse?.Status === "ENABLED" || sse?.Status === "ENABLING" || sse?.Status === "UPDATING";
1368
1369 /**
1370 * The table configuration `alchemy drift` compares: every setting
1371 * reconcile converges, as observed. `read` and `reconcile` share it so
1372 * a converged table reads unchanged. Transitional statuses
1373 * (ENABLING, UPDATING) count as their target so a just-applied change
1374 * is not reported as drift.
1375 */
1376 const observeTableConfiguration = Effect.fn(function* (
1377 state: {
1378 table: DynamoDB.TableDescription;
1379 timeToLiveDescription: DynamoDB.TimeToLiveDescription | undefined;
1380 },
1381 props: { onDemandThroughput?: DynamoDB.OnDemandThroughput } | undefined,
1382 ) {
1383 const { table } = state;
1384 const [policy, destinations, insights] = yield* Effect.all(
1385 [
1386 readTableResourcePolicy(table.TableArn!),
1387 dynamodb.describeKinesisStreamingDestination({ TableName: table.TableName! }).pipe(
1388 Effect.map((response) => response.KinesisDataStreamDestinations ?? []),
1389 Effect.retry({
1390 while: isRetryableControlPlaneError,
1391 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
1392 }),
1393 ),
1394 dynamodb.describeContributorInsights({ TableName: table.TableName! }).pipe(
1395 Effect.map((response) => response.ContributorInsightsStatus ?? "DISABLED"),
1396 Effect.retry({
1397 while: isRetryableControlPlaneError,
1398 schedule: Schedule.max([Schedule.exponential(250), Schedule.recurs(15)]),
1399 }),
1400 ),
1401 ],
1402 { concurrency: "unbounded" },
1403 );
1404 const billingMode = observedBillingModeOf(table);
1405 const sse = table.SSEDescription;
1406 const ttl = state.timeToLiveDescription;
1407 const kinesisStreamingDestinations = destinations
1408 .filter(
1409 (destination) =>
1410 destination.StreamArn !== undefined &&
1411 (destination.DestinationStatus === "ACTIVE" ||
1412 destination.DestinationStatus === "ENABLING" ||
1413 destination.DestinationStatus === "UPDATING"),
1414 )
1415 .map((destination) => ({
1416 streamArn: destination.StreamArn!,
1417 approximateCreationDateTimePrecision:
1418 destination.ApproximateCreationDateTimePrecision ?? "MILLISECOND",
1419 }))
1420 .sort((a, b) => a.streamArn.localeCompare(b.streamArn));
1421 return {
1422 billingMode,
1423 provisionedThroughput:
1424 billingMode === "PROVISIONED"
1425 ? normalizeProvisioned(table.ProvisionedThroughput)
1426 : undefined,
1427 onDemandThroughput:
1428 props?.onDemandThroughput === undefined
1429 ? undefined
1430 : normalizeOnDemand(table.OnDemandThroughput),
1431 deletionProtectionEnabled: table.DeletionProtectionEnabled ?? false,
1432 sseDescription: isKmsEncrypted(sse)
1433 ? { sseType: sse?.SSEType, kmsMasterKeyArn: sse?.KMSMasterKeyArn }
1434 : undefined,
1435 tableClass: table.TableClassSummary?.TableClass ?? "STANDARD",
1436 timeToLiveAttributeName:
1437 ttl?.TimeToLiveStatus === "ENABLED" || ttl?.TimeToLiveStatus === "ENABLING"
1438 ? ttl.AttributeName
1439 : undefined,
1440 resourcePolicy: canonicalPolicyDocument(policy),
1441 kinesisStreamingDestinations:
1442 kinesisStreamingDestinations.length > 0 ? kinesisStreamingDestinations : undefined,
1443 contributorInsightsEnabled: insights === "ENABLED" || insights === "ENABLING",
1444 } satisfies Partial<Table["Attributes"]>;
1445 });
1446
1447 const indexesByName = <T extends { IndexName?: string }>(indexes: readonly T[] | undefined) =>
1448 Object.fromEntries((indexes ?? []).map((index) => [index.IndexName!, index])) as Record<
1449 string,
1450 T
1451 >;
1452
1453 // KeySchema order is significant with multi-attribute keys: partition
1454 // attributes are hashed together in declaration order and sort key
1455 // attributes are queried left-to-right. Only the HASH/RANGE grouping is
1456 // normalized (DescribeTable reports all HASH elements before all RANGE
1457 // elements regardless of how the request interleaved them); the relative
1458 // order within each group must be preserved — reordering attributes
1459 // defines a different index.
1460 const normalizeKeySchema = (keySchema: readonly DynamoDB.KeySchemaElement[] | undefined) => {
1461 const elements = (keySchema ?? []).map((element) => ({
1462 AttributeName: element.AttributeName,
1463 KeyType: element.KeyType,
1464 }));
1465 return [
1466 ...elements.filter((element) => element.KeyType === "HASH"),
1467 ...elements.filter((element) => element.KeyType === "RANGE"),
1468 ];
1469 };
1470
1471 const normalizeProjection = (projection: DynamoDB.Projection | undefined) => ({
1472 ...projection,
1473 NonKeyAttributes: [...(projection?.NonKeyAttributes ?? [])].sort(),
1474 });
1475
1476 const isSameGsiDefinition = (
1477 left: DynamoDB.GlobalSecondaryIndex,
1478 right: DynamoDB.GlobalSecondaryIndex,
1479 ) =>
1480 JSON.stringify(normalizeKeySchema(left.KeySchema)) ===
1481 JSON.stringify(normalizeKeySchema(right.KeySchema)) &&
1482 JSON.stringify(normalizeProjection(left.Projection)) ===
1483 JSON.stringify(normalizeProjection(right.Projection));
1484
1485 // The describe response includes server-side bookkeeping fields
1486 // (`NumberOfDecreasesToday`, `LastIncreaseDateTime`, etc.) that the
1487 // request shape doesn't. For PAY_PER_REQUEST tables it also reports
1488 // a zero-throughput object. Normalize both sides to the user-settable
1489 // fields so we don't fire a phantom UpdateGlobalSecondaryIndex with
1490 // `ProvisionedThroughput: undefined` (which AWS rejects with
1491 // ValidationException).
1492 const normalizeProvisioned = (
1493 pt: { ReadCapacityUnits?: number; WriteCapacityUnits?: number } | undefined,
1494 ) => {
1495 if (!pt || ((pt.ReadCapacityUnits ?? 0) === 0 && (pt.WriteCapacityUnits ?? 0) === 0)) {
1496 return undefined;
1497 }
1498 return {
1499 ReadCapacityUnits: pt.ReadCapacityUnits,
1500 WriteCapacityUnits: pt.WriteCapacityUnits,
1501 };
1502 };
1503
1504 const normalizeOnDemand = (
1505 od:
1506 | {
1507 MaxReadRequestUnits?: number;
1508 MaxWriteRequestUnits?: number;
1509 }
1510 | undefined,
1511 ) => {
1512 if (!od || ((od.MaxReadRequestUnits ?? -1) < 0 && (od.MaxWriteRequestUnits ?? -1) < 0)) {
1513 return undefined;
1514 }
1515 return {
1516 MaxReadRequestUnits: od.MaxReadRequestUnits,
1517 MaxWriteRequestUnits: od.MaxWriteRequestUnits,
1518 };
1519 };
1520
1521 const normalizeWarm = (
1522 wt: { ReadUnitsPerSecond?: number; WriteUnitsPerSecond?: number } | undefined,
1523 ) => {
1524 if (!wt || ((wt.ReadUnitsPerSecond ?? 0) === 0 && (wt.WriteUnitsPerSecond ?? 0) === 0)) {
1525 return undefined;
1526 }
1527 return {
1528 ReadUnitsPerSecond: wt.ReadUnitsPerSecond,
1529 WriteUnitsPerSecond: wt.WriteUnitsPerSecond,
1530 };
1531 };
1532
1533 const diffGlobalSecondaryIndexes = (
1534 olds: readonly DynamoDB.GlobalSecondaryIndex[] | undefined,
1535 news: readonly DynamoDB.GlobalSecondaryIndex[] | undefined,
1536 ) => {
1537 const oldByName = indexesByName(olds);
1538 const newByName = indexesByName(news);
1539 const updates: DynamoDB.GlobalSecondaryIndexUpdate[] = [];
1540 let requiresReplacement = false;
1541
1542 for (const [indexName, oldIndex] of Object.entries(oldByName)) {
1543 const newIndex = newByName[indexName];
1544 if (!newIndex) {
1545 updates.push({
1546 Delete: {
1547 IndexName: indexName,
1548 },
1549 });
1550 continue;
1551 }
1552
1553 if (!isSameGsiDefinition(oldIndex, newIndex)) {
1554 requiresReplacement = true;
1555 continue;
1556 }
1557
1558 // Only emit an Update when the user has explicitly set a
1559 // throughput value AND it differs from observed. Cloud-side
1560 // defaults (AWS auto-assigns ProvisionedThroughput/WarmThroughput
1561 // values for PAY_PER_REQUEST tables) should not trigger phantom
1562 // updates against an undefined desired value.
1563 const provDiff =
1564 newIndex.ProvisionedThroughput !== undefined &&
1565 JSON.stringify(normalizeProvisioned(oldIndex.ProvisionedThroughput)) !==
1566 JSON.stringify(normalizeProvisioned(newIndex.ProvisionedThroughput));
1567 const odDiff =
1568 newIndex.OnDemandThroughput !== undefined &&
1569 JSON.stringify(normalizeOnDemand(oldIndex.OnDemandThroughput)) !==
1570 JSON.stringify(normalizeOnDemand(newIndex.OnDemandThroughput));
1571 const wtDiff =
1572 newIndex.WarmThroughput !== undefined &&
1573 JSON.stringify(normalizeWarm(oldIndex.WarmThroughput)) !==
1574 JSON.stringify(normalizeWarm(newIndex.WarmThroughput));
1575 if (provDiff || odDiff || wtDiff) {
1576 updates.push({
1577 Update: {
1578 IndexName: indexName,
1579 ProvisionedThroughput: newIndex.ProvisionedThroughput,
1580 OnDemandThroughput: newIndex.OnDemandThroughput,
1581 WarmThroughput: newIndex.WarmThroughput,
1582 },
1583 });
1584 }
1585 }
1586
1587 for (const [indexName, newIndex] of Object.entries(newByName)) {
1588 if (!oldByName[indexName]) {
1589 updates.push({
1590 Create: {
1591 IndexName: indexName,
1592 KeySchema: newIndex.KeySchema,
1593 Projection: newIndex.Projection,
1594 ProvisionedThroughput: newIndex.ProvisionedThroughput,
1595 OnDemandThroughput: newIndex.OnDemandThroughput,
1596 WarmThroughput: newIndex.WarmThroughput,
1597 },
1598 });
1599 }
1600 }
1601
1602 return {
1603 updates,
1604 requiresReplacement,
1605 };
1606 };
1607
1608 return Table.Provider.of({
1609 stables: ["tableName", "tableId", "tableArn", "region"],
1610 // Enumerate every table in the ambient account/region. `listTables`
1611 // returns only names, so each is hydrated to the full Attributes shape
1612 // via the same multi-API read helper (`readTableState`) `read` uses.
1613 list: () =>
1614 Effect.gen(function* () {
1615 const names = yield* dynamodb.listTables.items({}).pipe(
1616 Stream.runCollect,
1617 Effect.map((chunk) => Array.from(chunk)),
1618 );
1619 const states = yield* Effect.forEach(
1620 names,
1621 (tableName) =>
1622 readTableState(tableName).pipe(
1623 // Hydrating every table fires four describe calls each.
1624 // Across a busy account this trips DynamoDB's read throttle,
1625 // and a table that isn't ACTIVE yet (a peer mid-create)
1626 // transiently rejects the continuous-backups/TTL describes
1627 // with ValidationException. Both are transient — retry to
1628 // converge so a table that *is* ours still hydrates fully.
1629 Effect.retry({
1630 while: (e) =>
1631 e._tag === "ThrottlingException" || e._tag === "ValidationException",
1632 schedule: Schedule.max([
1633 Schedule.exponential(250).pipe(Schedule.jittered),
1634 Schedule.recurs(12),
1635 ]),
1636 }),
1637 // Last resort: if a foreign table never settles within the
1638 // retry budget (e.g. a peer is still mid-create/delete when
1639 // we give up), skip it rather than failing the whole
1640 // enumeration. Our own table is ACTIVE by the time list()
1641 // runs, so it always hydrates via the retry above.
1642 //
1643 // `AccessDeniedException` is the same case seen from the
1644 // other side: enumerating an account walks tables we do not
1645 // own, and one can deny the tag read outright (a restrictive
1646 // resource policy live; a peer test's table under the local
1647 // emulator). A table we cannot read is not ours to return.
1648 // `TableNotFoundException` completes the set: a peer can
1649 // delete a table between `listTables` and our describes, and
1650 // that is what DynamoDB raises for a table that vanished.
1651 Effect.catchTag(
1652 [
1653 "ValidationException",
1654 "AccessDeniedException",
1655 "TableNotFoundException",
1656 "ResourceNotFoundException",
1657 ],
1658 () => Effect.undefined,
1659 ),
1660 ),
1661 { concurrency: 8 },
1662 );
1663 return states.filter((state) => state !== undefined).map((state) => toAttrs(state));
1664 }),
1665 read: Effect.fn(function* ({ id, olds, output, previous }) {
1666 const tableName =
1667 output?.tableName ?? (olds ? yield* createTableName(id, olds) : undefined);
1668 if (!tableName) return undefined;
1669 const state = yield* readTableState(tableName).pipe(
1670 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
1671 );
1672 if (!state) return undefined;
1673 const attrs = {
1674 ...toAttrs(state),
1675 ...(yield* observeTableConfiguration(state, olds)),
1676 };
1677 return (yield* hasAlchemyTags(id, state.tags as any))
1678 ? attrs
1679 : unownedUnlessPrevious(attrs, previous, "tableName");
1680 }),
1681 diff: Effect.fn(function* ({ news, olds }) {
1682 if (!isResolved(news)) return undefined;
1683 // Renaming the table always replaces. The successor's name cannot
1684 // collide with the predecessor's, so the default
1685 // create-before-delete replacement flow applies.
1686 if (news.tableName !== olds.tableName) {
1687 return { action: "replace" } as const;
1688 }
1689 // For every other replacement trigger the physical name stays the
1690 // same. Engine-generated names embed the instance id, which is
1691 // re-minted on replacement, so the successor gets a fresh name and
1692 // create-before-delete works. A hard-coded `tableName` cannot
1693 // change — DynamoDB table names are unique per account/region, so
1694 // the successor's createTable would collide with the still-live
1695 // predecessor and mis-adopt it. Delete the old generation first in
1696 // that case; `delete` waits until the name is fully released.
1697 const replace =
1698 news.tableName !== undefined
1699 ? ({ action: "replace", deleteFirst: true } as const)
1700 : ({ action: "replace" } as const);
1701 if (olds.partitionKey !== news.partitionKey || olds.sortKey !== news.sortKey) {
1702 return replace;
1703 }
1704 for (const [name, type] of Object.entries(olds.attributes ?? {})) {
1705 if (news.attributes[name] !== type) {
1706 return replace;
1707 }
1708 }
1709 // Compare secondary indexes in the wire shape so legacy state
1710 // (persisted before the typed index props) diffs cleanly against
1711 // the new prop shape.
1712 if (
1713 havePropsChanged(
1714 {
1715 localSecondaryIndexes:
1716 toWireLocalSecondaryIndexes(olds.partitionKey, olds.localSecondaryIndexes) ?? [],
1717 },
1718 {
1719 localSecondaryIndexes:
1720 toWireLocalSecondaryIndexes(news.partitionKey, news.localSecondaryIndexes) ?? [],
1721 },
1722 )
1723 ) {
1724 return replace;
1725 }
1726 const { requiresReplacement } = diffGlobalSecondaryIndexes(
1727 toWireGlobalSecondaryIndexes(olds.globalSecondaryIndexes),
1728 toWireGlobalSecondaryIndexes(news.globalSecondaryIndexes),
1729 );
1730 if (requiresReplacement) {
1731 return replace;
1732 }
1733 // ImportSourceSpecification (importTable) is out of scope — see
1734 // processes/AWS/catalog/serverless-data.md (import/export are
1735 // long-running jobs, deferred as effectful functions).
1736 }),
1737
1738 reconcile: Effect.fn(function* ({ id, output, news, session, bindings }) {
1739 const tableName = output?.tableName ?? (yield* createTableName(id, news));
1740 const desiredTags = yield* createTags(id, news.tags);
1741 const desiredStreamSpecification = yield* resolveStreamSpecification(bindings);
1742
1743 // Observe cloud state. `output` is treated as a cache for the table
1744 // name; the table's actual existence and configuration are fetched
1745 // fresh so the reconciler converges regardless of drift, adoption,
1746 // or a partially-completed prior run.
1747 let state = yield* readTableState(tableName);
1748
1749 if (state === undefined) {
1750 yield* session.note(
1751 `Table ${tableName}: creating with stream specification ${JSON.stringify(desiredStreamSpecification)}`,
1752 );
1753 yield* dynamodb
1754 .createTable({
1755 TableName: tableName,
1756 TableClass: news.tableClass,
1757 KeySchema: toKeySchema(news),
1758 AttributeDefinitions: toAttributeDefinitions(news.attributes),
1759 LocalSecondaryIndexes: toWireLocalSecondaryIndexes(
1760 news.partitionKey,
1761 news.localSecondaryIndexes,
1762 ),
1763 GlobalSecondaryIndexes: toWireGlobalSecondaryIndexes(news.globalSecondaryIndexes),
1764 BillingMode: news.billingMode ?? "PAY_PER_REQUEST",
1765 SSESpecification: news.sseSpecification,
1766 StreamSpecification: desiredStreamSpecification,
1767 WarmThroughput: news.warmThroughput,
1768 DeletionProtectionEnabled: news.deletionProtectionEnabled,
1769 OnDemandThroughput: news.onDemandThroughput,
1770 ProvisionedThroughput: news.provisionedThroughput,
1771 Tags: createTagsList(desiredTags),
1772 })
1773 .pipe(
1774 Effect.retry({
1775 while: (e) =>
1776 e._tag === "LimitExceededException" || e._tag === "InternalServerError",
1777 schedule: Schedule.exponential(100),
1778 }),
1779 // A peer reconciler created the table between our observe and
1780 // create; describe it and continue with the sync path.
1781 Effect.catchTag("ResourceInUseException", () => adoptExistingTable(tableName)),
1782 );
1783
1784 yield* waitForTableActive(session, tableName);
1785
1786 if ((news.globalSecondaryIndexes?.length ?? 0) > 0) {
1787 yield* waitForGlobalSecondaryIndexesStable(
1788 session,
1789 tableName,
1790 news.globalSecondaryIndexes?.map((index) => index.indexName) ?? [],
1791 );
1792 }
1793
1794 state = yield* readTableState(tableName);
1795 if (!state) {
1796 return yield* new TableUnexpectedResponse({
1797 message: `Failed to read created table ${tableName}`,
1798 });
1799 }
1800 }
1801
1802 // Sync stream specification — observed ↔ desired.
1803 //
1804 // SQL of stream changes: changing the StreamViewType requires a
1805 // disable→enable sequence; AWS rejects an in-place view-type change.
1806 const currentStreamSpecification = normalizeStreamSpecification(
1807 state.table.StreamSpecification,
1808 );
1809 const streamViewTypeChanged =
1810 currentStreamSpecification?.StreamEnabled === true &&
1811 desiredStreamSpecification?.StreamEnabled === true &&
1812 currentStreamSpecification.StreamViewType !== desiredStreamSpecification.StreamViewType;
1813
1814 if (streamViewTypeChanged) {
1815 yield* dynamodb.updateTable({
1816 TableName: tableName,
1817 StreamSpecification: { StreamEnabled: false },
1818 });
1819 yield* waitForTableActive(session, tableName);
1820 }
1821
1822 if (
1823 havePropsChanged(
1824 { streamSpecification: currentStreamSpecification },
1825 { streamSpecification: desiredStreamSpecification },
1826 )
1827 ) {
1828 yield* session.note(`Table ${tableName}: updating stream configuration`);
1829 yield* dynamodb.updateTable({
1830 TableName: tableName,
1831 StreamSpecification: desiredStreamSpecification ?? {
1832 StreamEnabled: false,
1833 },
1834 });
1835 yield* waitForTableActive(session, tableName);
1836 }
1837
1838 // Sync GSIs — diff observed cloud state against desired and apply
1839 // each delta serially. AWS only accepts one GSI change per
1840 // updateTable call. The diff function only reads fields shared
1841 // between `GlobalSecondaryIndex` and `GlobalSecondaryIndexDescription`
1842 // (IndexName, KeySchema, Projection, throughputs), so the cast is safe.
1843 const { updates: globalSecondaryIndexUpdates } = diffGlobalSecondaryIndexes(
1844 state.table.GlobalSecondaryIndexes as
1845 | readonly DynamoDB.GlobalSecondaryIndex[]
1846 | undefined,
1847 toWireGlobalSecondaryIndexes(news.globalSecondaryIndexes),
1848 );
1849
1850 for (const globalSecondaryIndexUpdate of globalSecondaryIndexUpdates) {
1851 const action = globalSecondaryIndexUpdate.Create
1852 ? `create ${globalSecondaryIndexUpdate.Create.IndexName}`
1853 : globalSecondaryIndexUpdate.Update
1854 ? `update ${globalSecondaryIndexUpdate.Update.IndexName}`
1855 : `delete ${globalSecondaryIndexUpdate.Delete!.IndexName}`;
1856 yield* session.note(`Table ${tableName}: applying GSI update (${action})`);
1857 yield* dynamodb.updateTable({
1858 TableName: tableName,
1859 AttributeDefinitions: toAttributeDefinitions(news.attributes),
1860 GlobalSecondaryIndexUpdates: [globalSecondaryIndexUpdate],
1861 });
1862 yield* waitForTableActive(session, tableName);
1863 }
1864
1865 if (globalSecondaryIndexUpdates.length > 0) {
1866 const expectedNames =
1867 news.globalSecondaryIndexes?.map((index) => index.indexName) ?? [];
1868 yield* session.note(
1869 `Table ${tableName}: waiting for GSIs to stabilize (${expectedNames.join(", ") || "none"})`,
1870 );
1871 yield* waitForGlobalSecondaryIndexesStable(session, tableName, expectedNames);
1872 yield* session.note(`Table ${tableName}: GSIs stabilized`);
1873 }
1874
1875 // Sync base attributes — observed ↔ desired.
1876 const desiredBillingMode = news.billingMode ?? "PAY_PER_REQUEST";
1877 // An unchanged PROVISIONED table must not trigger a spurious
1878 // `updateTable` (which DynamoDB rejects with "provisioned throughput
1879 // will not change").
1880 const observedBillingMode = observedBillingModeOf(state.table);
1881 const observedProvisionedThroughput = state.table.ProvisionedThroughput
1882 ? {
1883 ReadCapacityUnits: state.table.ProvisionedThroughput.ReadCapacityUnits,
1884 WriteCapacityUnits: state.table.ProvisionedThroughput.WriteCapacityUnits,
1885 }
1886 : undefined;
1887 const baseChanged = havePropsChanged(
1888 {
1889 billingMode: observedBillingMode,
1890 provisionedThroughput:
1891 desiredBillingMode === "PROVISIONED" ? observedProvisionedThroughput : undefined,
1892 },
1893 {
1894 billingMode: desiredBillingMode,
1895 provisionedThroughput:
1896 desiredBillingMode === "PROVISIONED" ? news.provisionedThroughput : undefined,
1897 },
1898 );
1899
1900 // DynamoDB rejects a table-class or deletion-protection change
1901 // combined with any other update, and treats either field in the
1902 // request as a change, so each is synced on its own.
1903 const desiredDeletionProtection = news.deletionProtectionEnabled ?? false;
1904 if ((state.table.DeletionProtectionEnabled ?? false) !== desiredDeletionProtection) {
1905 yield* session.note(
1906 `Table ${tableName}: ${desiredDeletionProtection ? "enabling" : "disabling"} deletion protection`,
1907 );
1908 yield* dynamodb.updateTable({
1909 TableName: tableName,
1910 DeletionProtectionEnabled: desiredDeletionProtection,
1911 });
1912 yield* waitForTableActive(session, tableName);
1913 }
1914
1915 // Omitting the prop means STANDARD, so a class changed out-of-band
1916 // converges back.
1917 const desiredTableClass = news.tableClass ?? "STANDARD";
1918 if ((state.table.TableClassSummary?.TableClass ?? "STANDARD") !== desiredTableClass) {
1919 yield* session.note(`Table ${tableName}: updating table class to ${desiredTableClass}`);
1920 yield* dynamodb.updateTable({
1921 TableName: tableName,
1922 TableClass: desiredTableClass,
1923 });
1924 yield* waitForTableActive(session, tableName);
1925 }
1926
1927 if (baseChanged) {
1928 yield* dynamodb.updateTable({
1929 TableName: tableName,
1930 AttributeDefinitions: toAttributeDefinitions(news.attributes),
1931 BillingMode: desiredBillingMode,
1932 WarmThroughput: news.warmThroughput,
1933 OnDemandThroughput: news.onDemandThroughput,
1934 ProvisionedThroughput: news.provisionedThroughput,
1935 });
1936 yield* waitForTableActive(session, tableName);
1937 }
1938
1939 // Sync table-level on-demand maximums when declared.
1940 if (
1941 news.onDemandThroughput !== undefined &&
1942 JSON.stringify(normalizeOnDemand(state.table.OnDemandThroughput)) !==
1943 JSON.stringify(normalizeOnDemand(news.onDemandThroughput))
1944 ) {
1945 yield* session.note(`Table ${tableName}: updating on-demand throughput`);
1946 yield* dynamodb.updateTable({
1947 TableName: tableName,
1948 OnDemandThroughput: news.onDemandThroughput,
1949 });
1950 yield* waitForTableActive(session, tableName);
1951 }
1952
1953 // Sync server-side encryption. Omitting `sseSpecification` (or
1954 // `Enabled: false`) means the default AWS owned key. A key given as
1955 // an alias can't be matched against the observed key ARN, so only
1956 // the encryption type is compared for it.
1957 const desiredKms = news.sseSpecification?.Enabled === true;
1958 const desiredKey = news.sseSpecification?.KMSMasterKeyId;
1959 const observedKey = state.table.SSEDescription?.KMSMasterKeyArn;
1960 const observedKms = isKmsEncrypted(state.table.SSEDescription);
1961 const keyMatches =
1962 desiredKey === undefined ||
1963 desiredKey.startsWith("alias/") ||
1964 observedKey === desiredKey ||
1965 observedKey?.endsWith(`:key/${desiredKey}`) === true;
1966 if (desiredKms !== observedKms || (desiredKms && !keyMatches)) {
1967 yield* session.note(`Table ${tableName}: updating server-side encryption`);
1968 yield* dynamodb.updateTable({
1969 TableName: tableName,
1970 SSESpecification: desiredKms ? news.sseSpecification : { Enabled: false },
1971 });
1972 yield* waitForTableActive(session, tableName);
1973 }
1974
1975 // Sync TTL — observed ↔ desired.
1976 //
1977 // updateTimeToLive rejects calls that would not change anything
1978 // (e.g. enabling TTL on the same attribute name), so we have to
1979 // diff against the current TimeToLiveDescription before calling.
1980 const currentTtl = state.timeToLiveDescription;
1981 const currentTtlEnabled =
1982 currentTtl?.TimeToLiveStatus === "ENABLED" ||
1983 currentTtl?.TimeToLiveStatus === "ENABLING";
1984 const currentTtlAttribute = currentTtl?.AttributeName;
1985 const desiredTtl = news.timeToLiveSpecification;
1986 const desiredTtlEnabled = desiredTtl?.Enabled === true;
1987 const desiredTtlAttribute = desiredTtl?.AttributeName;
1988
1989 if (
1990 desiredTtlEnabled !== currentTtlEnabled ||
1991 (desiredTtlEnabled && desiredTtlAttribute !== currentTtlAttribute)
1992 ) {
1993 if (desiredTtlEnabled) {
1994 if (currentTtlEnabled && currentTtlAttribute !== desiredTtlAttribute) {
1995 // AWS only allows one TTL attribute. We must disable first
1996 // before re-enabling on a different attribute.
1997 yield* updateTimeToLive(tableName, {
1998 AttributeName: currentTtlAttribute!,
1999 Enabled: false,
2000 });
2001 }
2002 yield* updateTimeToLive(tableName, {
2003 AttributeName: desiredTtlAttribute!,
2004 Enabled: true,
2005 });
2006 } else if (currentTtlEnabled && currentTtlAttribute) {
2007 yield* updateTimeToLive(tableName, {
2008 AttributeName: currentTtlAttribute,
2009 Enabled: false,
2010 });
2011 }
2012 }
2013
2014 // Sync PITR — observed ↔ desired.
2015 const currentPitrEnabled =
2016 state.pointInTimeRecoveryDescription?.PointInTimeRecoveryStatus === "ENABLED";
2017 const desiredPitrEnabled =
2018 news.pointInTimeRecoverySpecification?.pointInTimeRecoveryEnabled ?? false;
2019 const currentPitrPeriod = state.pointInTimeRecoveryDescription?.RecoveryPeriodInDays;
2020 const desiredPitrPeriod = toWireDays(
2021 news.pointInTimeRecoverySpecification?.recoveryPeriod,
2022 );
2023 if (
2024 currentPitrEnabled !== desiredPitrEnabled ||
2025 (desiredPitrEnabled && currentPitrPeriod !== desiredPitrPeriod)
2026 ) {
2027 yield* updateContinuousBackups(tableName, {
2028 PointInTimeRecoveryEnabled: desiredPitrEnabled,
2029 RecoveryPeriodInDays: desiredPitrPeriod,
2030 });
2031 }
2032
2033 // Sync resource policy — observed ↔ desired. The observed policy is
2034 // read fresh from the cloud (never olds/output) so adoption and
2035 // out-of-band drift converge.
2036 const observedPolicy = yield* readTableResourcePolicy(state.table.TableArn!);
2037 if (
2038 canonicalPolicyDocument(observedPolicy) !== canonicalPolicyDocument(news.resourcePolicy)
2039 ) {
2040 if (news.resourcePolicy !== undefined) {
2041 yield* session.note(`Table ${tableName}: putting resource policy`);
2042 yield* putTableResourcePolicy(state.table.TableArn!, news.resourcePolicy);
2043 } else {
2044 yield* session.note(`Table ${tableName}: deleting resource policy`);
2045 yield* deleteTableResourcePolicy(state.table.TableArn!);
2046 }
2047 }
2048
2049 // Sync Kinesis streaming destination — observe the table's actual
2050 // destinations, wait out any in-flight transition (enable/disable
2051 // reject while another change is in progress), disable whatever is
2052 // ACTIVE but not desired, then enable/update the desired
2053 // destination and wait for it to reach ACTIVE.
2054 const desiredKinesisDestination = news.kinesisStreamingDestination;
2055 let kinesisDestinations = yield* waitForKinesisDestinationsSettled(session, tableName);
2056 for (const destination of kinesisDestinations) {
2057 if (destination.DestinationStatus !== "ACTIVE") continue;
2058 if (destination.StreamArn === desiredKinesisDestination?.streamArn) {
2059 continue;
2060 }
2061 yield* session.note(
2062 `Table ${tableName}: disabling Kinesis streaming destination ${destination.StreamArn}`,
2063 );
2064 yield* disableKinesisDestination(tableName, destination.StreamArn!);
2065 kinesisDestinations = yield* waitForKinesisDestinationsSettled(session, tableName);
2066 }
2067 if (desiredKinesisDestination !== undefined) {
2068 const activeDestination = kinesisDestinations.find(
2069 (destination) =>
2070 destination.StreamArn === desiredKinesisDestination.streamArn &&
2071 destination.DestinationStatus === "ACTIVE",
2072 );
2073 if (activeDestination === undefined) {
2074 yield* session.note(
2075 `Table ${tableName}: enabling Kinesis streaming destination ${desiredKinesisDestination.streamArn}`,
2076 );
2077 yield* enableKinesisDestination(tableName, desiredKinesisDestination);
2078 kinesisDestinations = yield* waitForKinesisDestinationsSettled(session, tableName);
2079 } else if (
2080 desiredKinesisDestination.approximateCreationDateTimePrecision !== undefined &&
2081 (activeDestination.ApproximateCreationDateTimePrecision ?? "MILLISECOND") !==
2082 desiredKinesisDestination.approximateCreationDateTimePrecision
2083 ) {
2084 yield* session.note(
2085 `Table ${tableName}: updating Kinesis streaming destination precision to ${desiredKinesisDestination.approximateCreationDateTimePrecision}`,
2086 );
2087 yield* updateKinesisDestinationPrecision(tableName, desiredKinesisDestination);
2088 kinesisDestinations = yield* waitForKinesisDestinationsSettled(session, tableName);
2089 }
2090 const settledDestination = kinesisDestinations.find(
2091 (destination) => destination.StreamArn === desiredKinesisDestination.streamArn,
2092 );
2093 if (settledDestination?.DestinationStatus !== "ACTIVE") {
2094 return yield* new KinesisStreamingDestinationFailed({
2095 tableName,
2096 streamArn: desiredKinesisDestination.streamArn,
2097 status: settledDestination?.DestinationStatus,
2098 description: settledDestination?.DestinationStatusDescription,
2099 });
2100 }
2101 }
2102
2103 // Sync Contributor Insights — observed ↔ desired.
2104 const desiredInsightsEnabled = news.contributorInsightsEnabled ?? false;
2105 const observedInsightsStatus = yield* waitForContributorInsightsSettled(
2106 session,
2107 tableName,
2108 );
2109 const observedInsightsEnabled = observedInsightsStatus === "ENABLED";
2110 if (observedInsightsEnabled !== desiredInsightsEnabled) {
2111 yield* session.note(
2112 `Table ${tableName}: ${desiredInsightsEnabled ? "enabling" : "disabling"} Contributor Insights`,
2113 );
2114 yield* updateTableContributorInsights(tableName, desiredInsightsEnabled);
2115 if (!desiredInsightsEnabled) {
2116 // Wait for the DISABLE to settle so DynamoDB's rule cleanup
2117 // (which fires on the DISABLING→DISABLED transition) runs
2118 // while the table still exists — a deleteTable racing this
2119 // window strands the CloudWatch rules forever.
2120 yield* waitForContributorInsightsSettled(session, tableName);
2121 }
2122 }
2123
2124 // Sync tags — diff observed cloud tags against desired.
2125 //
2126 // Adoption may bring us a table that already has its own tag set;
2127 // diffing against `state.tags` (fetched fresh) lets the reconciler
2128 // converge ownership without fighting whatever was there before.
2129 const { removed, upsert } = diffTags(state.tags, desiredTags);
2130 if (removed.length > 0) {
2131 yield* dynamodb.untagResource({
2132 ResourceArn: state.table.TableArn!,
2133 TagKeys: removed,
2134 });
2135 }
2136 if (upsert.length > 0) {
2137 yield* dynamodb.tagResource({
2138 ResourceArn: state.table.TableArn!,
2139 Tags: upsert,
2140 });
2141 }
2142
2143 // Re-read final state after all sync steps so the returned
2144 // attributes reflect the post-reconcile cloud state.
2145 const final = yield* readTableState(tableName);
2146 if (!final) {
2147 return yield* new TableUnexpectedResponse({
2148 message: `Failed to read reconciled table ${tableName}`,
2149 });
2150 }
2151
2152 yield* session.note(final.table.TableArn!);
2153
2154 return {
2155 ...toAttrs(final),
2156 ...(yield* observeTableConfiguration(final, news)),
2157 tags: desiredTags,
2158 };
2159 }),
2160
2161 delete: Effect.fn(function* ({ output, session }) {
2162 // Contributor Insights must be fully torn down BEFORE the table is
2163 // deleted: DynamoDB removes its CloudWatch insight rules only when
2164 // a DISABLE completes while the table exists. Deleting the table
2165 // while insights are ENABLED (or mid-transition) aborts that
2166 // cleanup and strands the rules — CloudWatch rejects direct
2167 // deletion of DynamoDB-managed rules with AccessDenied, so only
2168 // AWS support can remove them afterwards.
2169 //
2170 // Observe existence first: `waitForContributorInsightsSettled`
2171 // retries `ResourceNotFoundException` as a control-plane blip (its
2172 // reconcile-side callers run right after the table was created),
2173 // so a table that is already gone would otherwise spin through the
2174 // full ~90s settle budget before this delete can notice.
2175 const tableExists = yield* dynamodb.describeTable({ TableName: output.tableName }).pipe(
2176 Effect.as(true),
2177 Effect.catchTag("ResourceNotFoundException", () => Effect.succeed(false)),
2178 );
2179 if (tableExists) {
2180 yield* Effect.gen(function* () {
2181 const insightsStatus = yield* waitForContributorInsightsSettled(
2182 session,
2183 output.tableName,
2184 );
2185 if (insightsStatus !== "DISABLED") {
2186 yield* session.note(
2187 `Table ${output.tableName}: disabling Contributor Insights before delete`,
2188 );
2189 yield* updateTableContributorInsights(output.tableName, false);
2190 yield* waitForContributorInsightsSettled(session, output.tableName);
2191 }
2192 yield* waitForContributorInsightsRulesDeleted(session, output.tableName);
2193 }).pipe(
2194 // Table vanished mid-teardown — nothing left to tear down.
2195 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
2196 );
2197 }
2198
2199 let deleteAttempt = 0;
2200
2201 while (true) {
2202 deleteAttempt += 1;
2203 yield* session.note(`Table ${output.tableName}: deleting (attempt ${deleteAttempt})`);
2204
2205 const deleteResult = yield* dynamodb
2206 .deleteTable({
2207 TableName: output.tableName,
2208 })
2209 .pipe(
2210 Effect.timeout(1000),
2211 Effect.as("accepted" as const),
2212 Effect.catchTags({
2213 ResourceNotFoundException: () => Effect.succeed("already-deleted" as const),
2214 ResourceInUseException: () => Effect.succeed("delete-gsis-first" as const),
2215 }),
2216 Effect.retry({
2217 while: (error) =>
2218 error._tag === "InternalServerError" || error._tag === "TimeoutError",
2219 schedule: waitForDeletionConvergence.pipe(
2220 Schedule.tap(({ attempt }) =>
2221 session.note(
2222 `DynamoDB Table provider: deleteTable transient failure for ${output.tableName} on attempt ${deleteAttempt} (${formatPollingElapsed(attempt)})`,
2223 ),
2224 ),
2225 ),
2226 }),
2227 );
2228
2229 if (deleteResult === "accepted") {
2230 yield* session.note(
2231 `DynamoDB Table provider: deleteTable accepted for ${output.tableName}`,
2232 );
2233 break;
2234 }
2235
2236 if (deleteResult === "already-deleted") {
2237 yield* session.note(
2238 `DynamoDB Table provider: table ${output.tableName} already deleted`,
2239 );
2240 return;
2241 }
2242
2243 yield* session.note(
2244 `DynamoDB Table provider: deleteTable blocked for ${output.tableName}; deleting GSIs first`,
2245 );
2246 yield* deleteGlobalSecondaryIndexes(session, output.tableName);
2247 yield* waitForGlobalSecondaryIndexesStable(session, output.tableName, []);
2248 yield* waitForTableActive(session, output.tableName);
2249 }
2250
2251 yield* session.note(`Table ${output.tableName}: waiting for deletion`);
2252 yield* waitForTableDeleted(session, output.tableName);
2253 }),
2254 });
2255 }),
2256 );
2257
2258 class TableNotActive extends Data.TaggedError("TableNotActive") {}
2259
2260 class TableIndexesNotStable extends Data.TaggedError("TableIndexesNotStable") {}
2261
2262 class TableStillDeleting extends Data.TaggedError("TableStillDeleting") {}
2263
2264 class MissingStreamViewType extends Data.TaggedError("MissingStreamViewType") {}
2265
2266 class KinesisDestinationNotSettled extends Data.TaggedError("KinesisDestinationNotSettled") {}
2267
2268 class ContributorInsightsNotSettled extends Data.TaggedError("ContributorInsightsNotSettled") {}
2269
2270 class KinesisStreamingDestinationFailed extends Data.TaggedError(
2271 "KinesisStreamingDestinationFailed",
2272 )<{
2273 tableName: string;
2274 streamArn: string;
2275 status: string | undefined;
2276 description: string | undefined;
2277 }> {}
2278
2279 class ConflictingStreamViewTypes extends Data.TaggedError("ConflictingStreamViewTypes")<{
2280 requested: readonly (DynamoDB.StreamViewType | undefined)[];
2281 }> {}