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

main
ts 498 lines 16.8 KB
Raw
1 import * as sqladmin from "@distilled.cloud/gcp/sqladmin_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import { GcpEnvironment } from "../Environment.ts";
12 import { alchemyLabelKeys, createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
13 import type { Providers } from "../Providers.ts";
14 import { waitForSqlOperation } from "./operations.ts";
15 import {
16 encodeDescription,
17 hasOwnershipMarker,
18 instanceIdOf,
19 lastSegment,
20 matchesOwnership,
21 parseDescription,
22 } from "./ownership.ts";
23
24 export type BackupProps = {
25 /**
26 * Cloud SQL instance id (the `{instance}` segment of
27 * `projects/{project}/instances/{instance}`). Full resource names are
28 * accepted and reduced to the last path segment. Immutable — changing
29 * it replaces the backup.
30 */
31 instance: string;
32 /**
33 * Storage location of the backup (`us`, `us-central1`, …). If omitted,
34 * Cloud SQL picks the closest multi-region. Immutable — changing it
35 * replaces the backup.
36 */
37 location?: string;
38 /**
39 * Human-readable description. Cloud SQL backups have no labels field,
40 * so Alchemy stamps ownership into the description at create. On-demand
41 * backups cannot update description in place (`updateBackupBackups`
42 * applies to FINAL backups only).
43 */
44 description?: string;
45 /**
46 * Time-to-live in days (1–365). Input-only on create. Ignored on
47 * subsequent reconciles of on-demand backups.
48 */
49 ttlDays?: number | string;
50 /**
51 * RFC3339 expiration. Writable only on FINAL backups; ignored for
52 * on-demand backups after create.
53 */
54 expiryTime?: string;
55 /**
56 * Existing backup id (the `{backup}` segment of
57 * `projects/{project}/backups/{backup}`) used to observe a backup when
58 * state is missing. The create API assigns ids — this is not sent on
59 * insert.
60 */
61 backupId?: string;
62 };
63
64 export type Backup = Resource<
65 "GCP.SQL.Backup",
66 BackupProps,
67 {
68 /** Full resource name `projects/{project}/backups/{backup}`. */
69 name: string;
70 /** Backup id (last path segment). */
71 backupId: string;
72 /** Project id. */
73 project: string;
74 /** Source Cloud SQL instance id. */
75 instance: string;
76 /** Storage location. */
77 location: string | undefined;
78 /** User description with the Alchemy ownership prefix stripped. */
79 description: string | undefined;
80 /** Backup type (`ON_DEMAND`, `AUTOMATED`, `FINAL`). */
81 type: string | undefined;
82 /** Server-reported state (`ENQUEUED`, `RUNNING`, `SUCCESSFUL`, …). */
83 state: string | undefined;
84 /** Kind of backup (`SNAPSHOT`, `PHYSICAL`). */
85 backupKind: string | undefined;
86 /** Input-only TTL in days, if the API echoes it. */
87 ttlDays: string | undefined;
88 /** RFC3339 expiration. */
89 expiryTime: string | undefined;
90 /** Database version at backup time. */
91 databaseVersion: string | undefined;
92 /** Mapped backup-run resource name, if any. */
93 backupRun: string | undefined;
94 /** SQL Admin self-link. */
95 selfLink: string | undefined;
96 /** Backup time zone (SQL Server). */
97 timeZone: string | undefined;
98 /** KMS key used to encrypt the backup. */
99 kmsKey: string | undefined;
100 /** Maximum chargeable bytes. */
101 maxChargeableBytes: string | undefined;
102 /** Inclusive/exclusive backup interval. */
103 backupInterval: sqladmin.Interval | undefined;
104 },
105 never,
106 Providers
107 >;
108
109 /**
110 * An on-demand Cloud SQL backup (`projects/{project}/backups/{backup}`).
111 *
112 * The create API assigns the backup id. Alchemy stamps ownership into
113 * `description` so `list` / `pnpm nuke:gcp` can find leaked rows.
114 * Changing `instance` or `location` replaces the backup. Description,
115 * `ttlDays`, and `expiryTime` are create-time for on-demand backups;
116 * FINAL backups can update description and expiration in place.
117 *
118 * ### Creating a Backup
119 * **Example:** On-demand backup of a Cloud SQL instance
120 * ```typescript
121 * const instance = yield* GCP.SQL.Instance("AppDb", {
122 * tier: "db-f1-micro",
123 * backup: { enabled: true },
124 * });
125 * const backup = yield* GCP.SQL.Backup("Nightly", {
126 * instance: instance.instanceName,
127 * });
128 * ```
129 *
130 * **Example:** Description, location, and TTL
131 * ```typescript
132 * const backup = yield* GCP.SQL.Backup("Nightly", {
133 * instance: instance.instanceName,
134 * location: "us",
135 * description: "pre-release",
136 * ttlDays: 7,
137 * });
138 * ```
139 *
140 * @resource
141 * @category SQL
142 */
143 export const Backup = Resource<Backup>("GCP.SQL.Backup");
144
145 export class BackupNotResolved extends Data.TaggedError("GCP.SQL.BackupNotResolved")<{
146 resourceName: string;
147 }> {}
148
149 export class BackupNotReady extends Data.TaggedError("GCP.SQL.BackupNotReady")<{
150 resourceName: string;
151 state: string | undefined;
152 }> {}
153
154 export class BackupStillExists extends Data.TaggedError("GCP.SQL.BackupStillExists")<{
155 resourceName: string;
156 }> {}
157
158 const backupNameOf = (project: string, backupId: string) =>
159 backupId.includes("/") ? backupId : `projects/${project}/backups/${backupId}`;
160
161 const normalizeLocation = (value: string | undefined) =>
162 value === undefined || value.length === 0 ? undefined : lastSegment(value).toLowerCase();
163
164 const ttlDaysOf = (value: number | string | undefined) =>
165 value === undefined ? undefined : String(value);
166
167 const toUserDescription = (id: string, description: string | undefined, existing?: string) =>
168 Effect.gen(function* () {
169 if (description !== undefined) return description;
170 if (existing !== undefined) return existing;
171 return yield* createPhysicalName({
172 id,
173 maxLength: 63,
174 lowercase: true,
175 });
176 });
177
178 const toAttrs = (backup: sqladmin.Backup, project: string) => {
179 const name = backup.name ?? "";
180 return {
181 name,
182 backupId: lastSegment(name),
183 project,
184 instance: instanceIdOf(backup.instance ?? ""),
185 location: backup.location,
186 description: parseDescription(backup.description).description,
187 type: backup.type,
188 state: backup.state,
189 backupKind: backup.backupKind,
190 ttlDays: backup.ttlDays,
191 expiryTime: backup.expiryTime,
192 databaseVersion: backup.databaseVersion,
193 backupRun: backup.backupRun,
194 selfLink: backup.selfLink,
195 timeZone: backup.timeZone,
196 kmsKey: backup.kmsKey,
197 maxChargeableBytes: backup.maxChargeableBytes,
198 backupInterval: backup.backupInterval,
199 };
200 };
201
202 /**
203 * Cloud SQL answers `SqlBackupAccessDenied` (403) both for a backup uid that
204 * does not exist and for callers without permission. Recover with
205 * `onMissing` only once the project's backup list confirms it is gone.
206 */
207 const recoverIfBackupMissing =
208 <B>(name: string, onMissing: () => B) =>
209 <A, E extends { readonly _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
210 effect.pipe(
211 Effect.catchIf(
212 (error): error is Extract<E, { readonly _tag: "SqlBackupAccessDenied" }> =>
213 error._tag === "SqlBackupAccessDenied",
214 (error) =>
215 listBackups(name.split("/")[1] ?? "").pipe(
216 Effect.flatMap((backups) =>
217 backups.some((backup) => backup.name === name)
218 ? Effect.fail(error)
219 : Effect.succeed(onMissing()),
220 ),
221 ),
222 ),
223 );
224
225 const getByName = (name: string) =>
226 name.length === 0
227 ? Effect.undefined
228 : sqladmin.getBackupBackups({ name }).pipe(
229 Effect.catchTag("NotFound", () => Effect.undefined),
230 recoverIfBackupMissing(name, () => undefined),
231 );
232
233 const listBackups = (project: string) =>
234 sqladmin.listBackupsBackups
235 .pages({
236 parent: `projects/${project}`,
237 pageSize: 500,
238 })
239 .pipe(
240 Stream.flatMap((page) => Stream.fromIterable(page.backups ?? [])),
241 Stream.runCollect,
242 Effect.map((chunk) => Array.from(chunk)),
243 );
244
245 const findByOwnership = (project: string, labels: Record<string, string>) =>
246 listBackups(project).pipe(
247 Effect.map((backups) => backups.find((backup) => matchesOwnership(backup.description, labels))),
248 );
249
250 const observe = (project: string, name: string | undefined, labels: Record<string, string>) =>
251 Effect.gen(function* () {
252 if (name !== undefined && name.length > 0) {
253 const existing = yield* getByName(name);
254 if (existing !== undefined) return existing;
255 }
256 return yield* findByOwnership(project, labels);
257 });
258
259 const waitForOperation = (
260 project: string,
261 operation: sqladmin.Operation,
262 options?: { notFoundOk?: boolean },
263 ) =>
264 waitForSqlOperation(project, operation, {
265 budget: "20 minutes",
266 notFoundOk: options?.notFoundOk,
267 });
268
269 const waitUntilExists = (name: string) =>
270 getByName(name).pipe(
271 Effect.flatMap((backup) =>
272 backup ? Effect.succeed(backup) : Effect.fail(new BackupNotResolved({ resourceName: name })),
273 ),
274 Effect.retry({
275 while: (error) => error._tag === "GCP.SQL.BackupNotResolved",
276 times: 8,
277 schedule: Schedule.spaced("2 seconds"),
278 }),
279 );
280
281 const isBusy = (state: string | undefined) =>
282 state === "ENQUEUED" ||
283 state === "RUNNING" ||
284 state === "SQL_BACKUP_STATE_UNSPECIFIED" ||
285 state === undefined;
286
287 const waitUntilReady = (name: string) =>
288 getByName(name).pipe(
289 Effect.filterOrFail(
290 (backup): backup is sqladmin.Backup => backup !== undefined,
291 () => new BackupNotResolved({ resourceName: name }),
292 ),
293 Effect.filterOrFail(
294 (backup) => !isBusy(backup.state),
295 (backup) =>
296 new BackupNotReady({
297 resourceName: name,
298 state: backup.state,
299 }),
300 ),
301 Effect.retry({
302 while: (error) =>
303 error._tag === "GCP.SQL.BackupNotReady" || error._tag === "GCP.SQL.BackupNotResolved",
304 times: 10,
305 schedule: Schedule.spaced("8 seconds"),
306 }),
307 );
308
309 const waitUntilGone = (name: string) =>
310 getByName(name).pipe(
311 Effect.flatMap((backup) =>
312 backup === undefined
313 ? Effect.void
314 : Effect.fail(new BackupStillExists({ resourceName: name })),
315 ),
316 Effect.retry({
317 while: (error) => error._tag === "GCP.SQL.BackupStillExists",
318 times: 10,
319 schedule: Schedule.spaced("5 seconds"),
320 }),
321 );
322
323 const nameFromOperation = (project: string, operation: sqladmin.Operation) => {
324 const fromContext = operation.backupContext?.name;
325 if (fromContext !== undefined && fromContext.length > 0) return fromContext;
326 const backupId = operation.backupContext?.backupId;
327 if (backupId !== undefined && backupId.length > 0) {
328 return backupNameOf(project, backupId);
329 }
330 return undefined;
331 };
332
333 export const BackupProvider = () =>
334 Provider.succeed(Backup, {
335 stables: ["name", "backupId", "project", "instance", "selfLink", "backupRun"],
336
337 diff: Effect.fn(function* ({ news, olds, output }) {
338 if (!isResolved(news)) return undefined;
339 const previousInstance = olds?.instance ?? output?.instance;
340 const nextInstance = news.instance;
341 const previousLocation = normalizeLocation(olds?.location ?? output?.location);
342 const nextLocation = normalizeLocation(news.location ?? output?.location);
343 const instanceChanged =
344 previousInstance !== undefined &&
345 instanceIdOf(previousInstance) !== instanceIdOf(nextInstance);
346 const locationChanged =
347 news.location !== undefined &&
348 previousLocation !== undefined &&
349 nextLocation !== undefined &&
350 previousLocation !== nextLocation;
351 if (!instanceChanged && !locationChanged) return undefined;
352 return {
353 action: "replace" as const,
354 deleteFirst: false,
355 };
356 }),
357
358 read: Effect.fn(function* ({ id, olds, output }) {
359 const env = yield* GcpEnvironment.current;
360 const ownership = yield* createInternalLabels(id);
361 const name =
362 output?.name ??
363 (olds?.backupId || output?.backupId
364 ? backupNameOf(env.project, olds?.backupId ?? output!.backupId)
365 : undefined);
366 const existing = yield* observe(env.project, name, ownership);
367 if (existing === undefined) return undefined;
368 const attrs = toAttrs(existing, env.project);
369 const { labels } = parseDescription(existing.description);
370 return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
371 }),
372
373 list: () =>
374 Effect.gen(function* () {
375 const env = yield* GcpEnvironment.current;
376 const backups = yield* listBackups(env.project);
377 return backups
378 .filter((backup) => hasOwnershipMarker(backup.description))
379 .map((backup) => toAttrs(backup, env.project));
380 }),
381
382 reconcile: Effect.fn(function* ({ id, news, output }) {
383 const env = yield* GcpEnvironment.current;
384 const instance = instanceIdOf(news.instance);
385 const ownership = yield* createInternalLabels(id);
386 const userDescription = yield* toUserDescription(id, news.description, output?.description);
387 const desiredDescription = encodeDescription(ownership, userDescription);
388 const name =
389 output?.name ?? (news.backupId ? backupNameOf(env.project, news.backupId) : undefined);
390
391 let current = yield* observe(env.project, name, ownership);
392
393 if (current === undefined) {
394 const created = yield* sqladmin
395 .createBackupBackups({
396 parent: `projects/${env.project}`,
397 body: {
398 instance,
399 description: desiredDescription,
400 location: news.location,
401 ttlDays: ttlDaysOf(news.ttlDays),
402 },
403 })
404 .pipe(
405 Effect.catchTag("Conflict", (error) =>
406 findByOwnership(env.project, ownership).pipe(
407 Effect.flatMap((existing) => (existing ? Effect.undefined : Effect.fail(error))),
408 ),
409 ),
410 Effect.retry({
411 while: (error) => error._tag === "Conflict",
412 times: 8,
413 schedule: Schedule.spaced("5 seconds"),
414 }),
415 );
416
417 if (created !== undefined) {
418 const done = yield* waitForOperation(env.project, created);
419 const createdName =
420 nameFromOperation(env.project, done) ?? nameFromOperation(env.project, created);
421 if (createdName !== undefined) {
422 current = yield* waitUntilExists(createdName);
423 }
424 }
425 if (current === undefined) {
426 current = yield* findByOwnership(env.project, ownership).pipe(
427 Effect.flatMap((existing) =>
428 existing
429 ? Effect.succeed(existing)
430 : Effect.fail(
431 new BackupNotResolved({
432 resourceName:
433 name ?? `projects/${env.project}/backups/${ownership[alchemyLabelKeys.id]}`,
434 }),
435 ),
436 ),
437 Effect.retry({
438 while: (error) => error._tag === "GCP.SQL.BackupNotResolved",
439 times: 8,
440 schedule: Schedule.spaced("2 seconds"),
441 }),
442 );
443 }
444 }
445
446 const currentName = current.name ?? "";
447 if (currentName.length === 0) {
448 return yield* new BackupNotResolved({ resourceName: currentName });
449 }
450
451 if (isBusy(current.state)) {
452 current = yield* waitUntilReady(currentName);
453 }
454
455 const isFinal = (current.type ?? "").toUpperCase() === "FINAL";
456 const descriptionChanged = (current.description ?? "") !== desiredDescription;
457 const expiryChanged =
458 news.expiryTime !== undefined && (current.expiryTime ?? "") !== news.expiryTime;
459
460 if (isFinal && (descriptionChanged || expiryChanged)) {
461 const patched = yield* sqladmin.updateBackupBackups({
462 name: currentName,
463 updateMask: [
464 descriptionChanged ? "description" : undefined,
465 expiryChanged ? "expiryTime" : undefined,
466 ]
467 .filter((field): field is string => field !== undefined)
468 .join(","),
469 body: {
470 description: desiredDescription,
471 expiryTime: news.expiryTime,
472 },
473 });
474 yield* waitForOperation(env.project, patched);
475 current = yield* waitUntilExists(currentName);
476 }
477
478 return toAttrs(current, env.project);
479 }),
480
481 delete: Effect.fn(function* ({ output }) {
482 const name = output.name;
483 if (name.length === 0) return;
484 yield* sqladmin.deleteBackupBackups({ name }).pipe(
485 Effect.flatMap((operation) =>
486 waitForOperation(output.project, operation, { notFoundOk: true }),
487 ),
488 Effect.catchTag("NotFound", () => Effect.void),
489 recoverIfBackupMissing(name, () => undefined),
490 Effect.retry({
491 while: (error) => error._tag === "Conflict",
492 times: 8,
493 schedule: Schedule.spaced("5 seconds"),
494 }),
495 );
496 yield* waitUntilGone(name);
497 }),
498 });