@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 547 lines 18.5 KB
Raw
1 import * as planetscale from "@distilled.cloud/planetscale";
2 import { Credentials } from "@distilled.cloud/planetscale/Credentials";
3 import { deepEqual, 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 Effect from "effect/Effect";
8 import * as Redacted from "effect/Redacted";
9 import * as Stream from "effect/Stream";
10 import type { Providers } from "../Providers.ts";
11 import { isKnownError, PlanetscaleConflict, waitForBranchReady } from "../Util.ts";
12 import type { PostgresBranch } from "./PostgresBranch.ts";
13 import type { PostgresDatabase } from "./PostgresDatabase.ts";
14 import type { PostgresOrigin } from "./PostgresOrigin.ts";
15
16 /**
17 * Built-in PostgreSQL roles that can be inherited from. Custom role names
18 * (referencing other Role resources) are also accepted.
19 */
20 export type InheritedRole =
21 | "pscale_managed"
22 | "pg_checkpoint"
23 | "pg_create_subscription"
24 | "pg_maintain"
25 | "pg_monitor"
26 | "pg_read_all_data"
27 | "pg_read_all_settings"
28 | "pg_read_all_stats"
29 | "pg_signal_backend"
30 | "pg_stat_scan_tables"
31 | "pg_use_reserved_connections"
32 | "pg_write_all_data"
33 | "postgres"
34 | (string & {});
35
36 type SDKInheritedRole =
37 | "pscale_managed"
38 | "pg_checkpoint"
39 | "pg_create_subscription"
40 | "pg_maintain"
41 | "pg_monitor"
42 | "pg_read_all_data"
43 | "pg_read_all_settings"
44 | "pg_read_all_stats"
45 | "pg_signal_backend"
46 | "pg_stat_scan_tables"
47 | "pg_use_reserved_connections"
48 | "pg_write_all_data"
49 | "postgres";
50
51 /**
52 * Properties for creating or updating a PlanetScale PostgreSQL role.
53 *
54 * Roles are only meant for PostgreSQL databases. For MySQL,
55 * use {@link MySQLPassword} instead.
56 */
57 export interface PostgresRoleProps {
58 /**
59 * Role name. If not provided, a physical name will be generated.
60 */
61 name?: string;
62 /**
63 * PostgreSQL database — string name or {@link PostgresDatabase} resource.
64 */
65 database: string | PostgresDatabase;
66
67 /**
68 * Branch — string name or {@link PostgresBranch} resource.
69 * @default "main"
70 */
71 branch?: string | PostgresBranch;
72
73 /**
74 * Time to live in seconds.
75 */
76 ttl?: number;
77
78 /**
79 * Roles to inherit from. Either a list of built-in role names, or
80 * another {@link PostgresRole} resource (whose `inheritedRoles` are reused).
81 */
82 inheritedRoles: InheritedRole[] | PostgresRole;
83
84 /**
85 * Give the role the REPLICATION attribute, for a logical-replication
86 * consumer (Electric, Debezium, a CDC pipeline). PlanetScale only grants
87 * it alongside `inheritedRoles: ["postgres"]`. Create-only: changing it
88 * replaces the role.
89 * @default false
90 */
91 withReplication?: boolean;
92
93 /**
94 * Successor role to reassign ownership to before dropping. Used during
95 * delete.
96 * @default "postgres"
97 */
98 successor?: string | PostgresRole;
99 }
100
101 /**
102 * Output attributes of a deployed PlanetScale role.
103 */
104 export interface PostgresRoleAttributes {
105 /** Unique identifier for the role (stable). */
106 id: string;
107 /** The Postgres role name (assigned by PlanetScale). */
108 name: string;
109 /** ISO 8601 timestamp at which the role expires. */
110 expiresAt: string | null;
111 /** Hostname for the database connection. */
112 host: string;
113 /** Username for database authentication. */
114 username: string;
115 /** Password for database authentication (Redacted). */
116 password: Redacted.Redacted<string>;
117 /** The database name. */
118 database: string;
119 /** The Postgres database name inside the branch. */
120 databaseName: string;
121 /** Parsed direct (port 5432) connection components ready to feed into Cloudflare Hyperdrive. */
122 origin: PostgresOrigin;
123 /** Parsed pooled (PSBouncer, port 6432) connection components, e.g. for a Hyperdrive `dev` origin. */
124 pooledOrigin: PostgresOrigin;
125 /**
126 * Private connection host or DNS zone for this branch, supplied by
127 * PlanetScale. GCP Private Service Connect requires an endpoint name before
128 * this DNS zone.
129 */
130 privateHost: string;
131 /** Service name for this branch supplied by PlanetScale to establish a private connection. */
132 privateConnectionServiceName: string;
133 /** Direct connection URL for the database (Redacted). */
134 connectionUrl: Redacted.Redacted<string>;
135 /** Pooled connection URL via PSBouncer (port 6432, Redacted). */
136 connectionUrlPooled: Redacted.Redacted<string>;
137 /** Inherited roles. */
138 inheritedRoles: InheritedRole[];
139 /** Whether the role carries the REPLICATION attribute. */
140 withReplication: boolean;
141 /** The successor role used during delete. */
142 successor: string;
143 /** Resolved organization slug. */
144 organization: string;
145 /** Resolved branch name. */
146 branch: string;
147 /** Time-to-live for the role in seconds. */
148 ttl: number | null;
149 }
150
151 /**
152 * A PlanetScale role for accessing a PostgreSQL database branch.
153 *
154 * For MySQL databases, use {@link MySQLPassword} instead.
155 *
156 * ### Creating a Role
157 * **Example:** Postgres admin role
158 * ```typescript
159 * const admin = yield* Planetscale.PostgresRole("Admin", {
160 * database: "my-db",
161 * inheritedRoles: ["postgres"],
162 * });
163 * ```
164 *
165 * **Example:** Read-only role
166 * ```typescript
167 * const reader = yield* Planetscale.PostgresRole("Reader", {
168 * database: "my-db",
169 * inheritedRoles: ["pg_read_all_data", "pg_read_all_settings"],
170 * });
171 * ```
172 *
173 * **Example:** Role with TTL
174 * ```typescript
175 * const tempReader = yield* Planetscale.PostgresRole("TempReader", {
176 * database: "my-db",
177 * inheritedRoles: ["pg_read_all_data"],
178 * ttl: 3600,
179 * });
180 * ```
181 */
182 export type PostgresRole = Resource<
183 "Planetscale.PostgresRole",
184 PostgresRoleProps,
185 PostgresRoleAttributes,
186 never,
187 Providers
188 >;
189
190 /** @resource */
191 export const PostgresRole = Resource<PostgresRole>("Planetscale.PostgresRole");
192
193 export const PostgresRoleProvider = () =>
194 Provider.succeed(PostgresRole, {
195 stables: ["id"],
196
197 diff: Effect.fn(function* ({ id, news, olds, output }) {
198 if (!isResolved(news)) return undefined;
199
200 // Successor is the only updatable property — everything else
201 // requires replacement.
202 if (news.ttl !== olds.ttl) {
203 return { action: "replace" } as const;
204 }
205 const newDb = resolveDatabaseName(news.database);
206 const oldDb = olds.database ? resolveDatabaseName(olds.database) : undefined;
207 if (oldDb && newDb !== oldDb) {
208 return { action: "replace" } as const;
209 }
210 const newBranch = resolveBranchName(news.branch);
211 const oldBranch = resolveBranchName(olds.branch);
212 if (newBranch !== oldBranch) {
213 return { action: "replace" } as const;
214 }
215 const newRoles = [...resolveInheritedRoles(news.inheritedRoles)].sort();
216 const oldRoles = [...(output?.inheritedRoles ?? [])].sort();
217 if (!deepEqual(newRoles, oldRoles)) {
218 return { action: "replace" } as const;
219 }
220 if ((news.withReplication ?? false) !== (output?.withReplication ?? false)) {
221 return { action: "replace" } as const;
222 }
223 const oldName = output?.name ?? (yield* resolveName(id, olds?.name));
224 const newName = yield* resolveName(id, news.name);
225
226 if (newName !== oldName) {
227 return { action: "update" } as const;
228 }
229
230 return undefined;
231 }),
232
233 read: Effect.fn(function* ({ output }) {
234 if (!output?.id) return undefined;
235
236 return yield* planetscale
237 .getRole({
238 branch: output.branch,
239 database: output.database,
240 organization: output.organization,
241 id: output.id,
242 })
243 .pipe(
244 Effect.map((token) =>
245 buildAttributes(token, output.password, {
246 inheritedRoles: token.inherited_roles as InheritedRole[],
247 successor: output.successor,
248 organization: output.organization,
249 database: output.database,
250 branch: token.branch.name,
251 }),
252 ),
253 Effect.catchTags({
254 Forbidden: () => Effect.undefined,
255 NotFound: () => Effect.undefined,
256 }),
257 );
258 }),
259
260 reconcile: Effect.fn(function* ({ id, news, output }) {
261 const { organization: envOrg } = yield* yield* Credentials;
262 const organization = resolveDatabaseOrg(news.database) ?? envOrg;
263 const databaseName = resolveDatabaseName(news.database);
264 const branchName = resolveBranchName(news.branch);
265 const inheritedRoles = resolveInheritedRoles(news.inheritedRoles);
266 const successor = resolveSuccessorName(news.successor);
267 const desiredName = yield* resolveName(id, news.name);
268
269 // 1. Observe — fetch live state if we know the role id. Roles
270 // can only be looked up by id; without a cached id there is
271 // no way to find the live role, so we fall through to ensure.
272 const observed = output?.id
273 ? yield* planetscale
274 .getRole({
275 id: output.id,
276 branch: branchName,
277 organization,
278 database: databaseName,
279 })
280 .pipe(Effect.catchTag("NotFound", () => Effect.undefined))
281 : undefined;
282
283 // 2. Ensure — create if missing. Single branch covers both
284 // greenfield (no output) and out-of-band-deletion (output
285 // cached but cloud lost it). The latter is structurally a
286 // rotation: the new role has fresh id/host/username/plaintext
287 // that propagate downstream through the dependency graph.
288 // There is no path to recover the original plaintext, so
289 // recreating is the only way to converge.
290 //
291 // Planetscale returns the plaintext password value exactly
292 // once on create; on an observe-hit we re-use the cached
293 // plaintext from output (which is why adoption requires
294 // pre-existing state — see `read`).
295 let live: planetscale.GetRoleOutput;
296 let plaintext: Redacted.Redacted<string>;
297 if (observed) {
298 live = observed;
299 plaintext = output!.password;
300 } else {
301 const branchInfo = yield* planetscale.getBranch({
302 organization,
303 database: databaseName,
304 branch: branchName,
305 });
306 if (branchInfo.kind !== "postgresql") {
307 return yield* new PlanetscaleConflict({
308 message: `Cannot create a Role on MySQL database "${databaseName}". Roles are only supported on PostgreSQL. Use Password for MySQL.`,
309 });
310 }
311 if (!branchInfo.ready) {
312 yield* waitForBranchReady(organization, databaseName, branchName);
313 }
314 const created = yield* planetscale.createRole({
315 name: desiredName,
316 branch: branchName,
317 organization,
318 database: databaseName,
319 ttl: news.ttl,
320 inherited_roles: inheritedRoles as SDKInheritedRole[],
321 with_replication: news.withReplication,
322 });
323 if (!created.password) {
324 return yield* Effect.die(
325 `Planetscale did not return a password for Role "${desiredName}".`,
326 );
327 }
328 plaintext = created.password;
329 live = created;
330 }
331
332 // 3. Sync — only `name` is mutable in place; diff observed
333 // against desired and skip the API call when nothing
334 // changed. Everything else triggers a replace via diff().
335 if (live.name !== desiredName) {
336 live = yield* planetscale.updateRole({
337 id: live.id,
338 branch: branchName,
339 organization,
340 database: databaseName,
341 name: desiredName,
342 });
343 }
344
345 // 4. Return — fresh attrs sourced from observed cloud state,
346 // with cached or freshly-issued plaintext.
347 return buildAttributes(live, plaintext, {
348 inheritedRoles: live.inherited_roles as InheritedRole[],
349 successor,
350 organization,
351 database: databaseName,
352 branch: branchName,
353 });
354 }),
355
356 delete: Effect.fn(function* ({ output }) {
357 yield* planetscale
358 .deleteRole({
359 organization: output.organization,
360 database: output.database,
361 branch: output.branch,
362 id: output.id,
363 successor: output.successor,
364 })
365 .pipe(
366 Effect.catchTag("NotFound", () => Effect.void),
367 // 422 (UnprocessableEntity): role is still referenced. Log a
368 // warning rather than failing — the role will be cleaned up
369 // when the database/branch is deleted.
370 Effect.catchIf(
371 isKnownError("UnprocessableEntity", "Role is still referenced and cannot be dropped."),
372 () => Effect.void,
373 ),
374 );
375 }),
376
377 list: Effect.fn(function* () {
378 const { organization } = yield* yield* Credentials;
379
380 const databases = yield* planetscale.listDatabases.pages({ organization }).pipe(
381 Stream.runCollect,
382 Effect.map((chunk) =>
383 Array.from(chunk).flatMap((page) => page.data.filter((db) => db.kind === "postgresql")),
384 ),
385 );
386
387 const rows = yield* Effect.forEach(
388 databases,
389 (db) =>
390 planetscale.listBranches.pages({ organization, database: db.name }).pipe(
391 Stream.runCollect,
392 Effect.map((branchPages) =>
393 Array.from(branchPages).flatMap((page) =>
394 page.data.filter((branch) => branch.kind === "postgresql"),
395 ),
396 ),
397 Effect.catchTag("NotFound", () =>
398 Effect.succeed([{ name: db.default_branch ?? "main" }]),
399 ),
400 Effect.flatMap((branches) =>
401 Effect.forEach(
402 branches,
403 (branch) =>
404 planetscale.listRoles
405 .pages({
406 organization,
407 database: db.name,
408 branch: branch.name,
409 })
410 .pipe(
411 Stream.runCollect,
412 Effect.map((rolePages): PostgresRoleAttributes[] =>
413 Array.from(rolePages).flatMap((page) =>
414 page.data
415 .filter((role) => !role.default)
416 .map((role) =>
417 buildAttributes(role, Redacted.make(""), {
418 inheritedRoles: role.inherited_roles as InheritedRole[],
419 successor: "postgres",
420 organization,
421 database: db.name,
422 branch: branch.name,
423 }),
424 ),
425 ),
426 ),
427 Effect.catchTags({
428 NotFound: () => Effect.succeed([] as PostgresRoleAttributes[]),
429 Forbidden: () => Effect.succeed([] as PostgresRoleAttributes[]),
430 }),
431 ),
432 { concurrency: 10 },
433 ).pipe(Effect.map((perBranch) => perBranch.flat())),
434 ),
435 ),
436 { concurrency: 10 },
437 );
438
439 return rows.flat();
440 }),
441 });
442
443 // Structural shapes for runtime-resolved Resource references — see notes
444 // in Password.ts.
445 type DatabaseRef = string | { name: string; organization?: string };
446 type BranchRef = string | { name: string };
447 type RoleRef = string | { name: string; inheritedRoles: InheritedRole[] };
448
449 const resolveDatabaseName = (database: string | PostgresDatabase): string => {
450 const ref = database as unknown as DatabaseRef;
451 return typeof ref === "string" ? ref : ref.name;
452 };
453
454 const resolveDatabaseOrg = (database: string | PostgresDatabase): string | undefined => {
455 const ref = database as unknown as DatabaseRef;
456 return typeof ref === "string" ? undefined : ref.organization;
457 };
458
459 const resolveBranchName = (branch: string | PostgresBranch | undefined): string => {
460 const ref = branch as unknown as BranchRef | undefined;
461 return !ref ? "main" : typeof ref === "string" ? ref : ref.name;
462 };
463
464 const resolveSuccessorName = (successor: string | PostgresRole | undefined): string => {
465 const ref = successor as unknown as RoleRef | undefined;
466 return !ref ? "postgres" : typeof ref === "string" ? ref : ref.name;
467 };
468
469 const resolveInheritedRoles = (inheritedRoles: InheritedRole[] | PostgresRole): InheritedRole[] => {
470 if (Array.isArray(inheritedRoles)) {
471 return inheritedRoles;
472 }
473 // At runtime, a Role passed in is its resolved attributes (with
474 // `inheritedRoles` as a plain array); statically `Role.inheritedRoles`
475 // is `Output<InheritedRole[]>`.
476 return (inheritedRoles as unknown as RoleRef as { inheritedRoles: InheritedRole[] })
477 .inheritedRoles;
478 };
479
480 const resolveName = (id: string, name: string | undefined) =>
481 Effect.gen(function* () {
482 return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 63 }));
483 });
484
485 const buildAttributes = (
486 role: {
487 id: string;
488 name: string;
489 expires_at: string | null;
490 with_replication: boolean;
491 access_host_url: string;
492 private_access_host_url: string;
493 private_connection_service_name: string;
494 username: string;
495 database_name: string;
496 ttl: number | null;
497 },
498 password: Redacted.Redacted<string>,
499 context: {
500 inheritedRoles: InheritedRole[];
501 successor: string;
502 organization: string;
503 database: string;
504 branch: string;
505 },
506 ): PostgresRoleAttributes => {
507 const passwordValue = Redacted.value(password);
508 const connectionUrl = `postgresql://${role.username}:${passwordValue}@${role.access_host_url}:5432/${role.database_name}?sslmode=verify-full`;
509 const connectionUrlPooled = `postgresql://${role.username}:${passwordValue}@${role.access_host_url}:6432/${role.database_name}?sslmode=verify-full`;
510
511 return {
512 id: role.id,
513 name: role.name,
514 expiresAt: role.expires_at,
515 host: role.access_host_url,
516 username: role.username,
517 password,
518 connectionUrl: Redacted.make(connectionUrl),
519 connectionUrlPooled: Redacted.make(connectionUrlPooled),
520 privateHost: role.private_access_host_url,
521 privateConnectionServiceName: role.private_connection_service_name,
522 inheritedRoles: context.inheritedRoles,
523 withReplication: role.with_replication,
524 successor: context.successor,
525 organization: context.organization,
526 database: context.database,
527 databaseName: role.database_name,
528 origin: {
529 scheme: "postgres",
530 host: role.access_host_url,
531 port: 5432,
532 database: role.database_name,
533 user: role.username,
534 password,
535 },
536 pooledOrigin: {
537 scheme: "postgres",
538 host: role.access_host_url,
539 port: 6432,
540 database: role.database_name,
541 user: role.username,
542 password,
543 },
544 branch: context.branch,
545 ttl: role.ttl,
546 };
547 };