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

main
ts 379 lines 14.3 KB
Raw
1 import {
2 diffMigrations,
3 migrationsAttrs,
4 migrationsInputOf,
5 stampedOf,
6 type MigrationsInput,
7 } from "@alchemy.run/sql/Migrations";
8 import * as dsql from "@distilled.cloud/aws/dsql";
9 import { Unowned } from "alchemy/AdoptPolicy";
10 import { isResolved } from "alchemy/Diff";
11 import * as Provider from "alchemy/Provider";
12 import { Resource } from "alchemy/Resource";
13 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
14 import * as Data from "effect/Data";
15 import * as Effect from "effect/Effect";
16 import * as Schedule from "effect/Schedule";
17 import * as Stream from "effect/Stream";
18 import { AWSEnvironment } from "../Environment.ts";
19 import type { Providers } from "../Providers.ts";
20 import { runDsqlMigrations } from "./Migrations.ts";
21 import { validateDsqlMigrations } from "./MigrationSql.ts";
22
23 export class DSQLClusterNotReady extends Data.TaggedError("DSQLClusterNotReady")<{
24 readonly message: string;
25 readonly cause?: unknown;
26 }> {}
27
28 export interface ClusterProps {
29 /**
30 * SQL migrations directory, `{ dir, table? }`, or a Drizzle.Schema output.
31 * Applied as admin using the deploy identity (requires dsql:DbConnectAdmin
32 * and the optional `pg` peer). Files are checked before cluster mutation.
33 * DDL runs one statement at a time; completed statements survive retries.
34 * CREATE INDEX is adapted to ASYNC and awaited. Explicit transaction
35 * control and serial columns are rejected. Use UUIDs or bigint identity
36 * columns with an explicit CACHE. Applied migration files are immutable.
37 */
38 migrations?: MigrationsInput;
39 /**
40 * Enables deletion protection. While enabled the cluster cannot be deleted;
41 * the provider automatically disables it during delete so `stack.destroy()`
42 * always succeeds.
43 * @default false
44 */
45 deletionProtectionEnabled?: boolean;
46 /**
47 * ARN of a customer-managed KMS key used to encrypt the cluster at rest.
48 * Changing the key replaces the cluster.
49 * @default an AWS-owned key
50 */
51 kmsEncryptionKey?: string;
52 /**
53 * User-defined tags for the cluster.
54 */
55 tags?: Record<string, string>;
56 }
57
58 export interface Cluster extends Resource<
59 "AWS.DSQL.Cluster",
60 ClusterProps,
61 {
62 /** Directory used by the current migration configuration. */
63 migrationsDir: string | undefined;
64 /** Applied-migrations bookkeeping table. */
65 migrationsTable: string | undefined;
66 /** SHA256 hashes used to detect migration file changes during plan. */
67 migrationsHashes: Record<string, string>;
68 /** The unique cluster identifier assigned by DSQL. */
69 clusterId: string;
70 /** The ARN of the cluster. */
71 clusterArn: string;
72 /** The current status of the cluster, e.g. `ACTIVE`. */
73 status: string;
74 /**
75 * The public cluster endpoint hostname, e.g.
76 * `<clusterId>.dsql.<region>.on.aws`. Connect with a Postgres wire client
77 * using an IAM-generated auth token as the password.
78 */
79 endpoint: string;
80 /** Whether deletion protection is enabled on the cluster. */
81 deletionProtectionEnabled: boolean;
82 },
83 never,
84 Providers
85 > {}
86
87 /**
88 * An Amazon Aurora DSQL cluster — a serverless, distributed SQL database with
89 * active-active high availability and Postgres wire compatibility.
90 *
91 * Clusters are pay-per-use with no provisioned capacity, so they have
92 * excellent test economics. Create is asynchronous (`CREATING` -> `ACTIVE`),
93 * usually completing in under a minute; the provider waits for `ACTIVE`
94 * (bounded) before returning.
95 * ### Creating a Cluster
96 * **Example:** Basic Cluster
97 * ```typescript
98 * const cluster = yield* Cluster("AppDb", {});
99 * // connect to cluster.endpoint on port 5432 as user "admin"
100 * ```
101 *
102 * **Example:** Cluster with Deletion Protection
103 * ```typescript
104 * const cluster = yield* Cluster("AppDb", {
105 * deletionProtectionEnabled: true,
106 * });
107 * ```
108 *
109 * **Example:** Cluster with a Customer-Managed KMS Key
110 * ```typescript
111 * const cluster = yield* Cluster("AppDb", {
112 * kmsEncryptionKey: key.keyArn,
113 * });
114 * ```
115 *
116 * ### Applying SQL migrations
117 * **Example:** Drizzle-generated PostgreSQL migrations
118 * ```typescript
119 * const schema = yield* Drizzle.Schema("Schema", {
120 * schema: "./src/schema.ts",
121 * dialect: "postgres",
122 * });
123 * const cluster = yield* Cluster("Database", { migrations: schema.out });
124 * ```
125 *
126 * **Example:** Hand-written SQL migrations
127 * ```typescript
128 * const cluster = yield* Cluster("Database", { migrations: "./migrations" });
129 * ```
130 *
131 * ### Recovering an interrupted migration <!-- api-prose -->
132 * DSQL cannot roll back a whole migration. Alchemy records completed statements
133 * in `<migrationsTable>__progress` and serializes deploys with
134 * `__alchemy_dsql_migration_lock`. Server-rejected statements can be retried;
135 * a running index job is resumed on the next deploy. After a disconnect with
136 * an uncertain outcome, inspect the indicated statement and database first.
137 * With all migrators stopped, set the progress row to `ready`, advancing
138 * `next_statement` only if that statement committed (it is zero-based), then
139 * remove a stale lock row if one remains. Never clear progress blindly.
140 *
141 * Automatic conversion of a different tool's existing history is refused
142 * because DSQL cannot atomically combine the table DDL and history copy.
143 * Convert that history explicitly before adopting an already-migrated database.
144 *
145 * @resource
146 */
147 export const Cluster = Resource<Cluster>("AWS.DSQL.Cluster");
148
149 const activeStatuses = new Set(["ACTIVE", "IDLE"]);
150
151 export const ClusterProvider = () =>
152 Provider.effect(
153 Cluster,
154 Effect.gen(function* () {
155 const endpointFor = (identifier: string, region: string) =>
156 `${identifier}.dsql.${region}.on.aws`;
157
158 const readCluster = Effect.fn(function* (identifier: string) {
159 return yield* dsql
160 .getCluster({ identifier })
161 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
162 });
163
164 const readTags = Effect.fn(function* (arn: string) {
165 const response = yield* dsql
166 .listTagsForResource({ resourceArn: arn })
167 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
168 return Object.fromEntries(
169 Object.entries(response?.tags ?? {}).filter(
170 (entry): entry is [string, string] => typeof entry[1] === "string",
171 ),
172 );
173 });
174
175 const findCluster = Effect.fn(function* (id: string, instanceId: string) {
176 const summaries = yield* dsql.listClusters.items({}).pipe(Stream.runCollect);
177 for (const summary of summaries) {
178 const tags = yield* readTags(summary.arn);
179 if (tags["alchemy::instance"] === instanceId && (yield* hasAlchemyTags(id, tags))) {
180 return yield* readCluster(summary.identifier);
181 }
182 }
183 });
184
185 // Bound readiness to 50 seconds; a later deploy can resume provisioning.
186 const waitForActive = Effect.fn(function* (identifier: string) {
187 const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]);
188 return yield* readCluster(identifier).pipe(
189 Effect.flatMap((cluster) => {
190 if (cluster === undefined) {
191 return Effect.fail(
192 new DSQLClusterNotReady({ message: `DSQL cluster '${identifier}' not found` }),
193 );
194 }
195 if (!activeStatuses.has(cluster.status)) {
196 return Effect.fail(
197 new DSQLClusterNotReady({
198 message: `DSQL cluster '${identifier}' not active (status: ${cluster.status})`,
199 }),
200 );
201 }
202 return Effect.succeed(cluster);
203 }),
204 Effect.retry({ schedule: policy }),
205 );
206 });
207
208 const toAttrs = (
209 cluster: dsql.GetClusterOutput | dsql.CreateClusterOutput,
210 region: string,
211 ): Cluster["Attributes"] => ({
212 clusterId: cluster.identifier,
213 clusterArn: cluster.arn,
214 status: cluster.status,
215 endpoint: cluster.endpoint ?? endpointFor(cluster.identifier, region),
216 deletionProtectionEnabled: cluster.deletionProtectionEnabled,
217 migrationsDir: undefined,
218 migrationsTable: undefined,
219 migrationsHashes: {},
220 });
221
222 return {
223 stables: ["clusterId", "clusterArn", "endpoint"],
224
225 diff: Effect.fn(function* ({ olds = {}, news, output }) {
226 if (!isResolved(news)) return undefined;
227 const input = migrationsInputOf(news);
228 if (input) yield* validateDsqlMigrations(input, output?.migrationsHashes);
229 // KMS key is create-only; changing it forces a replacement.
230 if ((news.kmsEncryptionKey ?? undefined) !== (olds.kmsEncryptionKey ?? undefined)) {
231 return { action: "replace" } as const;
232 }
233 if (yield* diffMigrations({ news, output })) {
234 return { action: "update" } as const;
235 }
236 }),
237
238 read: Effect.fn(function* ({ id, instanceId, output }) {
239 const { region } = yield* AWSEnvironment.current;
240 const cluster = output?.clusterId
241 ? yield* readCluster(output.clusterId)
242 : yield* findCluster(id, instanceId);
243 if (cluster === undefined || cluster.status === "DELETED") {
244 return undefined;
245 }
246 const tags = yield* readTags(cluster.arn);
247 const attrs = {
248 ...toAttrs(cluster, region),
249 migrationsDir: output?.migrationsDir,
250 migrationsTable: output?.migrationsTable,
251 migrationsHashes: output?.migrationsHashes ?? {},
252 };
253 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
254 }),
255
256 reconcile: Effect.fn(function* ({ id, instanceId, news = {}, output, session }) {
257 const input = migrationsInputOf(news);
258 if (input) yield* validateDsqlMigrations(input, output?.migrationsHashes);
259 const { region } = yield* AWSEnvironment.current;
260 const internalTags = yield* createInternalTags(id);
261 const desiredTags = {
262 ...news.tags,
263 ...internalTags,
264 "alchemy::instance": instanceId,
265 };
266
267 // 1. Observe — cloud state is authoritative; output caches the id.
268 let observed =
269 output?.clusterId === undefined
270 ? yield* findCluster(id, instanceId)
271 : yield* readCluster(output.clusterId);
272
273 // 2. Ensure — create if missing. DSQL assigns the identifier.
274 let identifier = observed?.identifier ?? output?.clusterId;
275 if (observed === undefined) {
276 const created = yield* dsql.createCluster({
277 clientToken: instanceId,
278 deletionProtectionEnabled: news.deletionProtectionEnabled ?? false,
279 kmsEncryptionKey: news.kmsEncryptionKey,
280 tags: desiredTags,
281 });
282 identifier = created.identifier;
283 }
284
285 // Wait for ACTIVE so subsequent syncs do not hit ConflictException.
286 const active = yield* waitForActive(identifier!);
287 observed = active;
288
289 // 3. Sync deletion protection against observed state.
290 if (
291 news.deletionProtectionEnabled !== undefined &&
292 news.deletionProtectionEnabled !== observed.deletionProtectionEnabled
293 ) {
294 yield* dsql.updateCluster({
295 identifier: identifier!,
296 deletionProtectionEnabled: news.deletionProtectionEnabled,
297 });
298 observed = yield* waitForActive(identifier!);
299 }
300
301 // 3b. Sync tags — diff against OBSERVED cloud tags.
302 const observedTags = yield* readTags(observed.arn);
303 const { upsert, removed } = diffTags(observedTags, desiredTags);
304 if (upsert.length > 0) {
305 yield* dsql.tagResource({
306 resourceArn: observed.arn,
307 tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
308 });
309 }
310 if (removed.length > 0) {
311 yield* dsql.untagResource({
312 resourceArn: observed.arn,
313 tagKeys: removed,
314 });
315 }
316
317 yield* session.note(identifier!);
318 const attrs = toAttrs(observed, region);
319 const run = input
320 ? yield* runDsqlMigrations({
321 endpoint: attrs.endpoint,
322 input,
323 stamped: stampedOf(output),
324 })
325 : undefined;
326 return { ...attrs, ...migrationsAttrs({ input, run, output }) };
327 }),
328
329 delete: Effect.fn(function* ({ output }) {
330 const identifier = output.clusterId;
331 const existing = yield* readCluster(identifier);
332 if (existing === undefined) return;
333 // Deletion protection blocks delete — disable it first.
334 if (existing.deletionProtectionEnabled) {
335 yield* dsql
336 .updateCluster({
337 identifier,
338 deletionProtectionEnabled: false,
339 })
340 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
341 }
342 yield* dsql.deleteCluster({ identifier }).pipe(
343 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
344 // A cluster still CREATING rejects delete with ConflictException;
345 // retry briefly until it settles into a deletable state.
346 Effect.retry({
347 while: (e) => e._tag === "ConflictException",
348 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]),
349 }),
350 );
351 }),
352
353 list: () =>
354 Effect.gen(function* () {
355 const { region } = yield* AWSEnvironment.current;
356 const summaries = yield* dsql.listClusters.items({}).pipe(
357 Stream.runCollect,
358 Effect.map((c) => Array.from(c)),
359 );
360 return yield* Effect.forEach(
361 summaries,
362 (summary) =>
363 readCluster(summary.identifier).pipe(
364 Effect.map((cluster) =>
365 cluster === undefined || cluster.status === "DELETED"
366 ? undefined
367 : toAttrs(cluster, region),
368 ),
369 ),
370 { concurrency: 4 },
371 ).pipe(
372 Effect.map((attrs) =>
373 attrs.filter((a): a is NonNullable<typeof a> => a !== undefined),
374 ),
375 );
376 }),
377 };
378 }),
379 );