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

main
ts 443 lines 15.5 KB
Raw
1 import * as spanner from "@distilled.cloud/gcp/spanner_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import * as Stream from "effect/Stream";
10 import { GcpEnvironment } from "../Environment.ts";
11 import type { Providers } from "../Providers.ts";
12 import {
13 backupName,
14 databaseIdOf,
15 databaseNameOf,
16 instanceIdOf,
17 instanceName,
18 listAlchemyInstances,
19 MAX_BACKUP_ID_LENGTH,
20 parentOwned,
21 parseResourceName,
22 retryConcurrentChanges,
23 toPhysicalId,
24 waitForOperation,
25 } from "./operations.ts";
26
27 const DEFAULT_EXPIRE_MS = 7 * 24 * 60 * 60 * 1000;
28
29 export type BackupEncryptionConfig = {
30 /**
31 * Encryption type (`USE_DATABASE_ENCRYPTION`,
32 * `GOOGLE_DEFAULT_ENCRYPTION`, `CUSTOMER_MANAGED_ENCRYPTION`).
33 */
34 encryptionType?:
35 | spanner.CreateProjectsInstancesBackupsEncryptionConfig_encryptionTypeEnum
36 | (string & {});
37 /**
38 * Cloud KMS key. Use only when the key location matches the instance
39 * config exactly. Prefer `kmsKeyNames` for new backups.
40 */
41 kmsKeyName?: string;
42 /**
43 * Cloud KMS keys covering every region of the instance config.
44 */
45 kmsKeyNames?: string[];
46 };
47
48 export type InstancesBackupProps = {
49 /**
50 * Parent instance id or full name
51 * (`projects/{project}/instances/{instance}`). Must be the instance
52 * that owns `database`. Immutable — changing it replaces the backup.
53 */
54 instance: string;
55 /**
56 * Source database id or full name
57 * (`projects/{project}/instances/{instance}/databases/{database}`).
58 * Immutable — changing it replaces the backup.
59 */
60 database: string;
61 /**
62 * Backup id (the `{backup}` segment of
63 * `projects/{project}/instances/{instance}/backups/{backup}`). If
64 * omitted, a unique name is generated. Must match
65 * `^[a-z][-a-z0-9]*[a-z0-9]$` (2–60 characters). Immutable —
66 * changing it replaces the backup.
67 */
68 backupId?: string;
69 /**
70 * RFC3339 expiration. Must be at least 6 hours and at most 366 days
71 * from create time. Defaults to 7 days from reconcile time on create.
72 */
73 expireTime?: string;
74 /**
75 * Externally consistent version timestamp. Defaults to create time.
76 * Immutable — changing it replaces the backup.
77 */
78 versionTime?: string;
79 /**
80 * Backup encryption. Immutable — changing it replaces the backup.
81 */
82 encryptionConfig?: BackupEncryptionConfig;
83 };
84
85 export type InstancesBackup = Resource<
86 "GCP.Spanner.InstancesBackup",
87 InstancesBackupProps,
88 {
89 /** Full resource name `projects/{project}/instances/{instance}/backups/{backup}`. */
90 name: string;
91 /** Backup id (last path segment). */
92 backupId: string;
93 /** Parent instance id. */
94 instanceId: string;
95 /** Project id. */
96 project: string;
97 /** Source database resource name. */
98 database: string | undefined;
99 /** RFC3339 expiration. */
100 expireTime: string | undefined;
101 /** Version timestamp captured in the backup. */
102 versionTime: string | undefined;
103 /** RFC3339 create time. */
104 createTime: string | undefined;
105 /** Size in bytes (decimal string). */
106 sizeBytes: string | undefined;
107 /** Bytes freed by deleting this backup. */
108 freeableSizeBytes: string | undefined;
109 /** Incremental exclusive size in bytes. */
110 exclusiveSizeBytes: string | undefined;
111 /** Server-reported state (`CREATING`, `READY`). */
112 state: string | undefined;
113 /** Databases restored from this backup. */
114 referencingDatabases: string[];
115 /** Encryption info. */
116 encryptionInfo: spanner.EncryptionInfo | undefined;
117 /** SQL dialect of the source database. */
118 databaseDialect: string | undefined;
119 /** Destination backups copying this backup. */
120 referencingBackups: string[];
121 /** Max allowed expiration. */
122 maxExpireTime: string | undefined;
123 /** Backup schedule names that produced this backup. */
124 backupSchedules: string[];
125 /** Incremental backup chain id, if any. */
126 incrementalBackupChainId: string | undefined;
127 /** Oldest retained version timestamp. */
128 oldestVersionTime: string | undefined;
129 /** Instance partitions stored in the backup. */
130 instancePartitions: string[];
131 /** Minimum edition required to restore. */
132 minimumRestorableEdition: string | undefined;
133 },
134 never,
135 Providers
136 >;
137
138 /**
139 * A Cloud Spanner backup of a database, stored on the parent instance.
140 *
141 * Backups have no labels field. Alchemy treats a backup as owned when
142 * its parent instance carries Alchemy labels, so `list` /
143 * `pnpm nuke:gcp` can find it. Changing `backupId`, `instance`,
144 * `database`, `versionTime`, or encryption replaces the backup.
145 * `expireTime` updates in place.
146 *
147 * ### Creating a Backup
148 * **Example:** 7-day backup of an existing database
149 * ```typescript
150 * const backup = yield* GCP.Spanner.InstancesBackup("Nightly", {
151 * instance: instance.instanceId,
152 * database: database.databaseId,
153 * });
154 * ```
155 *
156 * **Example:** Explicit id and expiration
157 * ```typescript
158 * const backup = yield* GCP.Spanner.InstancesBackup("Nightly", {
159 * instance: instance.name,
160 * database: database.name,
161 * backupId: "nightly",
162 * expireTime: "2026-12-31T00:00:00Z",
163 * });
164 * ```
165 *
166 * @resource
167 * @category Spanner
168 */
169 export const InstancesBackup = Resource<InstancesBackup>("GCP.Spanner.InstancesBackup");
170
171 export class BackupNotResolved extends Data.TaggedError("GCP.Spanner.BackupNotResolved")<{
172 resourceName: string;
173 }> {}
174
175 export class BackupNotReady extends Data.TaggedError("GCP.Spanner.BackupNotReady")<{
176 resourceName: string;
177 state: string;
178 }> {}
179
180 export class BackupStillExists extends Data.TaggedError("GCP.Spanner.BackupStillExists")<{
181 resourceName: string;
182 }> {}
183
184 const toId = (id: string, backupId: string | undefined, existing?: string) =>
185 toPhysicalId(id, backupId, existing, MAX_BACKUP_ID_LENGTH);
186
187 const defaultExpireTime = () =>
188 Effect.sync(() => new Date(Date.now() + DEFAULT_EXPIRE_MS).toISOString());
189
190 const encryptionKey = (config: BackupEncryptionConfig | undefined) =>
191 JSON.stringify({
192 encryptionType: (config?.encryptionType ?? "").toUpperCase(),
193 kmsKeyName: config?.kmsKeyName ?? "",
194 kmsKeyNames: [...(config?.kmsKeyNames ?? [])].sort(),
195 });
196
197 const toAttrs = (backup: spanner.Backup, project: string): InstancesBackup["Attributes"] => {
198 const name = backup.name ?? "";
199 const parsed = parseResourceName(name);
200 return {
201 name,
202 backupId: parsed.backupId,
203 instanceId: parsed.instanceId,
204 project: parsed.project || project,
205 database: backup.database,
206 expireTime: backup.expireTime,
207 versionTime: backup.versionTime,
208 createTime: backup.createTime,
209 sizeBytes: backup.sizeBytes,
210 freeableSizeBytes: backup.freeableSizeBytes,
211 exclusiveSizeBytes: backup.exclusiveSizeBytes,
212 state: backup.state,
213 referencingDatabases: backup.referencingDatabases ?? [],
214 encryptionInfo: backup.encryptionInfo,
215 databaseDialect: backup.databaseDialect,
216 referencingBackups: backup.referencingBackups ?? [],
217 maxExpireTime: backup.maxExpireTime,
218 backupSchedules: backup.backupSchedules ?? [],
219 incrementalBackupChainId: backup.incrementalBackupChainId,
220 oldestVersionTime: backup.oldestVersionTime,
221 instancePartitions: (backup.instancePartitions ?? [])
222 .map((item) => item.instancePartition)
223 .filter((item): item is string => typeof item === "string"),
224 minimumRestorableEdition: backup.minimumRestorableEdition,
225 };
226 };
227
228 const getByName = (name: string) =>
229 spanner
230 .getProjectsInstancesBackups({ name })
231 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
232
233 const isBusy = (state: string | undefined) =>
234 state === "CREATING" || state === "STATE_UNSPECIFIED" || state === undefined;
235
236 const waitUntilExists = (name: string) =>
237 getByName(name).pipe(
238 Effect.flatMap((backup) =>
239 backup ? Effect.succeed(backup) : Effect.fail(new BackupNotResolved({ resourceName: name })),
240 ),
241 Effect.retry({
242 while: (error) => error._tag === "GCP.Spanner.BackupNotResolved",
243 times: 8,
244 schedule: Schedule.spaced("2 seconds"),
245 }),
246 );
247
248 const waitUntilReady = (name: string) =>
249 getByName(name).pipe(
250 Effect.filterOrFail(
251 (backup): backup is spanner.Backup => backup !== undefined,
252 () => new BackupNotResolved({ resourceName: name }),
253 ),
254 Effect.filterOrFail(
255 (backup) => !isBusy(backup.state),
256 (backup) =>
257 new BackupNotReady({
258 resourceName: name,
259 state: backup.state ?? "STATE_UNSPECIFIED",
260 }),
261 ),
262 Effect.retry({
263 while: (error) =>
264 error._tag === "GCP.Spanner.BackupNotReady" ||
265 error._tag === "GCP.Spanner.BackupNotResolved",
266 times: 8,
267 schedule: Schedule.spaced("5 seconds"),
268 }),
269 );
270
271 const refreshOrFail = (name: string) =>
272 getByName(name).pipe(
273 Effect.flatMap((backup) =>
274 backup ? Effect.succeed(backup) : Effect.fail(new BackupNotResolved({ resourceName: name })),
275 ),
276 );
277
278 const waitUntilGone = (name: string) =>
279 getByName(name).pipe(
280 Effect.flatMap((backup) =>
281 backup === undefined
282 ? Effect.void
283 : Effect.fail(new BackupStillExists({ resourceName: name })),
284 ),
285 Effect.retry({
286 while: (error) => error._tag === "GCP.Spanner.BackupStillExists",
287 times: 10,
288 schedule: Schedule.spaced("5 seconds"),
289 }),
290 );
291
292 const expireEquals = (left: string | undefined, right: string | undefined) => {
293 if (left === right) return true;
294 if (left === undefined || right === undefined) return false;
295 const leftMs = Date.parse(left);
296 const rightMs = Date.parse(right);
297 if (Number.isNaN(leftMs) || Number.isNaN(rightMs)) return left === right;
298 return Math.abs(leftMs - rightMs) < 1000;
299 };
300
301 export const InstancesBackupProvider = () =>
302 Provider.succeed(InstancesBackup, {
303 stables: ["name", "backupId", "instanceId", "project", "database", "createTime", "versionTime"],
304
305 diff: Effect.fn(function* ({ news, olds, output }) {
306 if (!isResolved(news)) return undefined;
307
308 const previousId = olds?.backupId ?? output?.backupId;
309 const nextId = news.backupId ?? previousId;
310 const previousInstance = instanceIdOf(olds?.instance ?? output?.instanceId ?? "");
311 const nextInstance = instanceIdOf(news.instance);
312 const previousDatabase = databaseIdOf(olds?.database ?? output?.database ?? "");
313 const nextDatabase = databaseIdOf(news.database);
314 const previousVersion = olds?.versionTime ?? output?.versionTime ?? "";
315 const nextVersion = news.versionTime ?? previousVersion;
316 const previousEncryption = encryptionKey(olds?.encryptionConfig);
317 const nextEncryption = encryptionKey(news.encryptionConfig ?? olds?.encryptionConfig);
318
319 const replace =
320 (previousId !== undefined && nextId !== undefined && previousId !== nextId) ||
321 (previousInstance.length > 0 && previousInstance !== nextInstance) ||
322 (previousDatabase.length > 0 && previousDatabase !== nextDatabase) ||
323 (news.versionTime !== undefined &&
324 previousVersion.length > 0 &&
325 previousVersion !== nextVersion) ||
326 (news.encryptionConfig !== undefined && previousEncryption !== nextEncryption);
327
328 if (!replace) return undefined;
329 return { action: "replace" as const };
330 }),
331
332 read: Effect.fn(function* ({ id, olds, output }) {
333 const env = yield* GcpEnvironment.current;
334 const backupId = yield* toId(id, olds?.backupId, output?.backupId);
335 const instanceId = instanceIdOf(olds?.instance ?? output?.instanceId ?? "");
336 if (instanceId.length === 0) return undefined;
337 const name = output?.name ?? backupName(env.project, instanceId, backupId);
338 const existing = yield* getByName(name);
339 if (existing === undefined) return undefined;
340 const attrs = toAttrs(existing, env.project);
341 return (yield* parentOwned(instanceName(attrs.project, attrs.instanceId)))
342 ? attrs
343 : Unowned(attrs);
344 }),
345
346 list: () =>
347 Effect.gen(function* () {
348 const env = yield* GcpEnvironment.current;
349 const instances = yield* listAlchemyInstances(env.project);
350 const pages = yield* Effect.forEach(
351 instances,
352 (instance) => {
353 const parent = instance.name;
354 if (parent === undefined || parent.length === 0) {
355 return Effect.succeed([] as InstancesBackup["Attributes"][]);
356 }
357 return spanner.listProjectsInstancesBackups
358 .pages({
359 parent,
360 pageSize: 1000,
361 })
362 .pipe(
363 Stream.flatMap((page) => Stream.fromIterable(page.backups ?? [])),
364 Stream.map((backup) => toAttrs(backup, env.project)),
365 Stream.runCollect,
366 Effect.map((chunk) => Array.from(chunk)),
367 Effect.catchTag("NotFound", () =>
368 Effect.succeed([] as InstancesBackup["Attributes"][]),
369 ),
370 );
371 },
372 { concurrency: 4 },
373 );
374 return pages.flat();
375 }),
376
377 reconcile: Effect.fn(function* ({ id, news, output }) {
378 const env = yield* GcpEnvironment.current;
379 const instanceId = instanceIdOf(news.instance);
380 const backupId = yield* toId(id, news.backupId, output?.backupId);
381 const name = backupName(env.project, instanceId, backupId);
382 const parent = instanceName(env.project, instanceId);
383 const database = databaseNameOf(env.project, news.instance, news.database);
384 const expireTime = news.expireTime ?? (yield* defaultExpireTime());
385
386 let current = yield* getByName(output?.name ?? name);
387
388 if (current === undefined) {
389 const created = yield* spanner
390 .createProjectsInstancesBackups({
391 parent,
392 backupId,
393 "encryptionConfig.encryptionType": news.encryptionConfig?.encryptionType,
394 "encryptionConfig.kmsKeyName": news.encryptionConfig?.kmsKeyName,
395 "encryptionConfig.kmsKeyNames": news.encryptionConfig?.kmsKeyNames,
396 body: {
397 database,
398 expireTime,
399 versionTime: news.versionTime,
400 },
401 })
402 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
403 if (created !== undefined && created.done === true) {
404 yield* waitForOperation(created, { alreadyExistsOk: true });
405 }
406 current = yield* waitUntilExists(name);
407 }
408
409 if (isBusy(current.state)) {
410 current = yield* waitUntilReady(name).pipe(
411 Effect.catchTag(["GCP.Spanner.BackupNotReady", "GCP.Spanner.BackupNotResolved"], () =>
412 refreshOrFail(name),
413 ),
414 );
415 }
416
417 if (news.expireTime !== undefined && !expireEquals(current.expireTime, news.expireTime)) {
418 current = yield* retryConcurrentChanges(
419 spanner.patchProjectsInstancesBackups({
420 name,
421 updateMask: "expire_time",
422 body: {
423 expireTime: news.expireTime,
424 },
425 }),
426 );
427 }
428
429 return toAttrs(current, env.project);
430 }),
431
432 delete: Effect.fn(function* ({ output }) {
433 yield* spanner.deleteProjectsInstancesBackups({ name: output.name }).pipe(
434 Effect.catchTag("NotFound", () => Effect.void),
435 Effect.retry({
436 while: (error) => error._tag === "Conflict",
437 times: 8,
438 schedule: Schedule.spaced("5 seconds"),
439 }),
440 );
441 yield* waitUntilGone(output.name);
442 }),
443 });