@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 684 lines 23.6 KB
Raw
1 import {
2 diffMigrations,
3 migrationsAttrs,
4 migrationsInputOf,
5 stampedOf,
6 type MigrationsInput,
7 } from "@alchemy.run/sql/Migrations";
8 import { hashImports } from "@alchemy.run/sql/SqlFile";
9 import {
10 deleteProject,
11 getConnectionURI,
12 getProject,
13 getProjectOperation,
14 listProjectBranchDatabases,
15 listProjectBranches,
16 listProjects,
17 type ListProjectsResponse,
18 type Project as NeonProject,
19 createProject as sdkCreateProject,
20 updateProject,
21 } from "@distilled.cloud/neon";
22 import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
23 import { isResolved } from "alchemy/Diff";
24 import { createPhysicalName } from "alchemy/PhysicalName";
25 import * as Provider from "alchemy/Provider";
26 import { Resource } from "alchemy/Resource";
27 import { recordsEqual } from "alchemy/Util/equal";
28 import * as Data from "effect/Data";
29 import * as Effect from "effect/Effect";
30 import * as Redacted from "effect/Redacted";
31 import * as Schedule from "effect/Schedule";
32 import { runImports, runPgMigrations } from "./Migrations.ts";
33 import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts";
34 import type { Providers } from "./Providers.ts";
35
36 const DEFAULT_REGION: NeonRegion = "aws-us-east-1";
37 const DEFAULT_PG_VERSION: NeonPgVersion = 17;
38
39 export type NeonRegion =
40 | "aws-us-east-1"
41 | "aws-us-east-2"
42 | "aws-us-west-2"
43 | "aws-eu-central-1"
44 | "aws-eu-west-2"
45 | "aws-ap-southeast-1"
46 | "aws-ap-southeast-2"
47 | "aws-sa-east-1"
48 | "azure-eastus2"
49 | "azure-westus3"
50 | "azure-gwc";
51
52 export type NeonPgVersion = 14 | 15 | 16 | 17 | 18;
53
54 export type ProjectProps = {
55 /**
56 * Mutable project name. If omitted at creation, a unique name is generated
57 * from `${app}-${stage}-${id}`. Omitting it later preserves the deployed name.
58 */
59 name?: string;
60 /**
61 * Region where the project is provisioned. Cannot be changed after
62 * creation.
63 *
64 * @default "aws-us-east-1"
65 */
66 region?: NeonRegion;
67 /**
68 * Postgres version. Cannot be changed after creation.
69 *
70 * @default 17
71 */
72 pgVersion?: NeonPgVersion;
73 /**
74 * Name of the default branch. Defaults to Neon's default ("main"). Cannot
75 * be changed after creation.
76 */
77 defaultBranchName?: string;
78 /**
79 * Name of the default role created with the project. Defaults to
80 * `neondb_owner` on creation; omission preserves the observed role on adoption
81 * and updates. An explicit change replaces the project.
82 */
83 roleName?: string;
84 /**
85 * Name of the default database created with the project. Defaults to
86 * `neondb` on creation; omission preserves the observed database on adoption
87 * and updates. An explicit change replaces the project.
88 */
89 databaseName?: string;
90 /**
91 * Number of seconds of WAL history retained on the project for
92 * point-in-time branching/restore.
93 *
94 * @default 86400
95 */
96 historyRetentionSeconds?: number;
97 /**
98 * Optional Neon organization ID. Cannot be changed after creation.
99 */
100 orgId?: string;
101 /**
102 * Enable Postgres logical replication on the project. Once enabled,
103 * Neon does not support disabling it again.
104 *
105 * @default false
106 * @see https://neon.tech/docs/guides/logical-replication-neon
107 */
108 enableLogicalReplication?: boolean;
109 /**
110 * SQL migrations to apply against the default branch's primary database.
111 * Accepts a directory path, a `Drizzle.Schema` resource, or
112 * `{ dir, table? }`.
113 *
114 * Bookkeeping always lives in Alchemy's `__alchemy_migrations` table. A
115 * database previously migrated by drizzle-kit or Prisma is adopted by a
116 * one-way conversion on first deploy: the old tool's applied history is
117 * copied into Alchemy's table and the old table is left frozen. No
118 * baselining required.
119 */
120 migrations?: MigrationsInput;
121 /**
122 * Paths to additional `.sql` files to apply after migrations. Each file
123 * is hashed; only files whose contents change are re-applied on
124 * subsequent deploys.
125 */
126 importFiles?: string[];
127 };
128
129 export type Project = Resource<
130 "Neon.Project",
131 ProjectProps,
132 {
133 /** Neon project identifier. */
134 projectId: string;
135 /** Observed project name. */
136 projectName: string;
137 /** Immutable Postgres region. */
138 region: NeonRegion;
139 /** Immutable Postgres major version. */
140 pgVersion: NeonPgVersion;
141 /** Current default branch identifier. */
142 defaultBranchId: string;
143 /** Current default branch name. */
144 defaultBranchName: string;
145 /** Database selected for connection outputs and migrations. */
146 databaseName: string;
147 /** Observed owner of the selected database. */
148 roleName: string;
149 /** Postgres connection URI for the default branch + database. */
150 connectionUri: string;
151 /** Pooled connection URI (uses pgbouncer). */
152 pooledConnectionUri: string;
153 /**
154 * Parsed connection components ready to feed into a Postgres origin
155 * — e.g. `Cloudflare.Hyperdrive`'s `origin` prop. Points at the
156 * direct (non-pooled) endpoint, which is the recommended target
157 * when fronting Neon with another pooler like Hyperdrive.
158 */
159 origin: PostgresOrigin;
160 /**
161 * Parsed pooled connection components. Useful as a Hyperdrive `dev`
162 * origin when local workers bypass Hyperdrive and connect directly.
163 */
164 pooledOrigin: PostgresOrigin;
165 /** Observed history retention window in seconds. */
166 historyRetentionSeconds: number;
167 /** Whether logical replication is enabled. Once enabled it cannot be disabled. */
168 enableLogicalReplication: boolean;
169 /** Directory of the applied SQL migrations. */
170 migrationsDir: string | undefined;
171 /** Migration bookkeeping table. */
172 migrationsTable: string | undefined;
173 /** Applied migration content hashes. */
174 migrationsHashes: Record<string, string>;
175 /** Applied SQL import content hashes. */
176 importHashes: Record<string, string>;
177 },
178 never,
179 Providers
180 >;
181
182 type ProjectAttributes = Project["Attributes"];
183
184 /**
185 * A Neon serverless Postgres project.
186 *
187 * Creating a project also provisions the project's default branch (named
188 * "main" by default), an initial role, an initial database, and a
189 * read-write compute endpoint, exposed as `connectionUri`.
190 * ### Creating a Project
191 * **Example:** Basic project
192 * ```typescript
193 * const project = yield* Neon.Project("my-project");
194 * ```
195 *
196 * **Example:** Project with explicit region and PG version
197 * ```typescript
198 * const project = yield* Neon.Project("my-project", {
199 * region: "aws-eu-central-1",
200 * pgVersion: 17,
201 * });
202 * ```
203 *
204 * **Example:** Project with logical replication enabled
205 * ```typescript
206 * const project = yield* Neon.Project("my-project", {
207 * enableLogicalReplication: true,
208 * });
209 * ```
210 *
211 * ### Migrations and seed data
212 * **Example:** Apply migrations and seed files
213 * ```typescript
214 * const project = yield* Neon.Project("my-project", {
215 * migrations: "./migrations",
216 * importFiles: ["./seed/users.sql"],
217 * });
218 * ```
219 *
220 * ### Branching
221 * **Example:** Create a branch off the project's default branch
222 * ```typescript
223 * const project = yield* Neon.Project("my-project");
224 * const dev = yield* Neon.Branch("dev-branch", { project });
225 * ```
226 *
227 * @see https://neon.tech/docs/manage/projects/
228 *
229 * @resource
230 * @product Project
231 */
232 export const Project = Resource<Project>("Neon.Project");
233
234 export const ProjectProvider = () =>
235 Provider.succeed(Project, {
236 stables: ["projectId", "defaultBranchId"],
237 list: Effect.fn(function* () {
238 // Account-scoped collection: enumerate every project via the Neon
239 // projects list API, then hydrate each into the exact `read`
240 // Attributes shape with bounded concurrency.
241 const projects = yield* listAllProjects;
242 const rows = yield* Effect.forEach(
243 projects,
244 (project) =>
245 hydrateProjectAttributes(project).pipe(
246 // A project can be deleted between the list call and
247 // hydration — skip it rather than fail the whole enumeration.
248 Effect.catchTag("NotFound", () => Effect.undefined),
249 ),
250 { concurrency: 10 },
251 );
252 return rows.filter((row): row is ProjectAttributes => row !== undefined);
253 }),
254 diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
255 if (!isResolved(news)) return undefined;
256 const oldName = output?.projectName ?? (yield* createProjectName(id, olds.name));
257 // Preserve generated names; only an explicit name requests a rename.
258 const name = news.name ?? oldName;
259 if (
260 (news.region ?? output?.region ?? DEFAULT_REGION) !==
261 (output?.region ?? olds.region ?? DEFAULT_REGION) ||
262 (news.pgVersion ?? output?.pgVersion ?? DEFAULT_PG_VERSION) !==
263 (output?.pgVersion ?? olds.pgVersion ?? DEFAULT_PG_VERSION) ||
264 (news.defaultBranchName ?? output?.defaultBranchName) !== output?.defaultBranchName ||
265 (news.databaseName ?? output?.databaseName ?? "neondb") !==
266 (output?.databaseName ?? olds.databaseName ?? "neondb") ||
267 (news.roleName ?? output?.roleName ?? "neondb_owner") !==
268 (output?.roleName ?? olds.roleName ?? "neondb_owner") ||
269 news.orgId !== olds.orgId
270 ) {
271 return {
272 action: "replace",
273 deleteFirst: news.name === oldName && news.orgId === olds.orgId,
274 } as const;
275 }
276 if (
277 oldName !== name ||
278 (news.historyRetentionSeconds ?? 86400) !== (output?.historyRetentionSeconds ?? 86400)
279 ) {
280 return { action: "update" } as const;
281 }
282 if (
283 news.enableLogicalReplication !== undefined &&
284 news.enableLogicalReplication !== (output?.enableLogicalReplication ?? false)
285 ) {
286 return { action: "update" } as const;
287 }
288 if (yield* diffMigrations({ news, output })) {
289 return { action: "update" } as const;
290 }
291 if (news.importFiles?.length) {
292 const newHashes = yield* hashImports(news.importFiles, yield* rootDir);
293 if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
294 return { action: "update" } as const;
295 }
296 }
297 return undefined;
298 }),
299 read: Effect.fn(function* ({ id, output, olds, previous }) {
300 if (output?.projectId) {
301 return yield* getProject({ project_id: output.projectId }).pipe(
302 Effect.flatMap(({ project }) => hydrateProjectAttributes(project, output)),
303 Effect.catchTag("NotFound", () => Effect.undefined),
304 );
305 }
306 const name = yield* createProjectName(id, olds?.name);
307 const matches = yield* findProjectByName(name, olds?.orgId);
308 if (matches.length > 1) {
309 return yield* new ProjectStateError({
310 reason: "Ambiguous project name",
311 });
312 }
313 const match = matches[0];
314 if (!match) return undefined;
315 const attrs = yield* hydrateProjectAttributes(match, {
316 defaultBranchName: olds?.defaultBranchName,
317 migrationsDir: (olds && migrationsInputOf(olds))?.dir,
318 migrationsTable: (olds && migrationsInputOf(olds))?.table,
319 });
320 // The generation a delete-first replacement is about to free is ours.
321 if (attrs && attrs.projectId === previous?.projectId) return attrs;
322 return attrs && Unowned(attrs);
323 }),
324 reconcile: Effect.fn(function* ({ id, news = {}, output }) {
325 const name = news.name ?? output?.projectName ?? (yield* createProjectName(id, undefined));
326 // Names are not ownership evidence; approval applies only to the observed ID.
327 const authorize = (
328 project: ObservedProject,
329 ): Effect.Effect<ObservedProject, OwnedBySomeoneElse> =>
330 project.id === output?.projectId
331 ? Effect.succeed(project)
332 : Effect.fail(
333 new OwnedBySomeoneElse({
334 message: `Neon project "${name}" requires explicit adoption`,
335 resourceType: "Neon.Project",
336 logicalId: id,
337 physicalName: project.id,
338 }),
339 );
340 let observed: ObservedProject | undefined = output?.projectId
341 ? yield* getProject({ project_id: output.projectId }).pipe(
342 Effect.map(({ project }) => project),
343 Effect.catchTag("NotFound", () => Effect.undefined),
344 )
345 : undefined;
346 if (!observed) {
347 const matches = yield* findProjectByName(name, news.orgId);
348 if (matches.length > 1) {
349 return yield* new ProjectStateError({
350 reason: "Ambiguous project name",
351 });
352 }
353 observed = matches[0] ? yield* authorize(matches[0]) : undefined;
354 }
355 if (!observed) {
356 const created = yield* sdkCreateProject({
357 project: {
358 name,
359 region_id: news.region ?? DEFAULT_REGION,
360 pg_version: news.pgVersion ?? DEFAULT_PG_VERSION,
361 branch: {
362 name: news.defaultBranchName,
363 role_name: news.roleName,
364 database_name: news.databaseName,
365 },
366 history_retention_seconds: news.historyRetentionSeconds,
367 org_id: news.orgId,
368 settings: news.enableLogicalReplication
369 ? { enable_logical_replication: true }
370 : undefined,
371 },
372 }).pipe(
373 Effect.catchTag("Conflict", (error) =>
374 findProjectByName(name, news.orgId).pipe(
375 Effect.flatMap(
376 Effect.fn(function* (matches) {
377 if (matches.length !== 1) return yield* error;
378 const project = yield* authorize(matches[0]!);
379 return { project, operations: [] };
380 }),
381 ),
382 ),
383 ),
384 );
385 yield* waitForOperations(created.operations);
386 observed = created.project;
387 }
388 const replication = observed.settings?.enable_logical_replication === true;
389 if (replication && news.enableLogicalReplication === false) {
390 return yield* new ProjectStateError({
391 reason: "Neon logical replication cannot be disabled once enabled",
392 });
393 }
394 const retention = news.historyRetentionSeconds ?? 86400;
395 if (
396 observed.name !== name ||
397 observed.history_retention_seconds !== retention ||
398 (news.enableLogicalReplication === true && !replication)
399 ) {
400 const updated = yield* updateProject({
401 project_id: observed.id,
402 project: {
403 name: observed.name !== name ? name : undefined,
404 history_retention_seconds:
405 observed.history_retention_seconds !== retention ? retention : undefined,
406 settings:
407 news.enableLogicalReplication === true && !replication
408 ? { enable_logical_replication: true }
409 : undefined,
410 },
411 });
412 yield* waitForOperations(updated.operations);
413 }
414 const current = yield* getProject({ project_id: observed.id });
415 const projectInfo = yield* hydrateProjectAttributes(current.project, {
416 defaultBranchName: news.defaultBranchName,
417 databaseName:
418 news.databaseName ??
419 (output?.projectId === observed.id ? output.databaseName : undefined),
420 });
421 if (!projectInfo) {
422 return yield* new ProjectStateError({
423 reason: "Project has no default branch or database",
424 });
425 }
426 const previous = projectInfo.projectId === output?.projectId ? output : undefined;
427
428 const connectionUri = Redacted.make(projectInfo.connectionUri);
429 const migrationsInput = migrationsInputOf(news);
430 const migrations = migrationsInput
431 ? yield* runPgMigrations({
432 connectionUri,
433 input: migrationsInput,
434 stamped: stampedOf(previous),
435 })
436 : undefined;
437 const importHashes = news.importFiles?.length
438 ? yield* runImports(
439 connectionUri,
440 news.importFiles,
441 yield* rootDir,
442 previous?.importHashes ?? {},
443 )
444 : {};
445
446 return {
447 ...projectInfo,
448 ...migrationsAttrs({
449 input: migrationsInput,
450 run: migrations,
451 output: previous,
452 }),
453 importHashes,
454 };
455 }),
456 delete: Effect.fn(function* ({ output }) {
457 yield* deleteProject({ project_id: output.projectId }).pipe(
458 Effect.catchTag("NotFound", () => Effect.void),
459 );
460 yield* getProject({ project_id: output.projectId }).pipe(
461 Effect.flatMap(() => Effect.fail(new DeletionPending({ resourceId: output.projectId }))),
462 Effect.catchTag("NotFound", () => Effect.void),
463 Effect.retry({
464 while: (error) => error._tag === "NeonDeletionPending",
465 schedule: Schedule.spaced("2 seconds"),
466 times: 8,
467 }),
468 Effect.timeout("20 seconds"),
469 );
470 }),
471 });
472
473 const rootDir = Effect.sync(() => process.cwd());
474
475 const createProjectName = (id: string, name: string | undefined) =>
476 Effect.gen(function* () {
477 return name ?? (yield* createPhysicalName({ id }));
478 });
479
480 const resolveConnection = (
481 projectId: string,
482 branchId: string,
483 databaseName: string,
484 roleName: string,
485 ) =>
486 Effect.gen(function* () {
487 const direct = yield* getConnectionURI({
488 project_id: projectId,
489 branch_id: branchId,
490 database_name: databaseName,
491 role_name: roleName,
492 pooled: false,
493 });
494 const pooled = yield* getConnectionURI({
495 project_id: projectId,
496 branch_id: branchId,
497 database_name: databaseName,
498 role_name: roleName,
499 pooled: true,
500 });
501 return { uri: direct.uri, pooled: pooled.uri };
502 });
503
504 export class ProjectStateError extends Data.TaggedError("NeonProjectStateError")<{
505 reason: string;
506 }> {}
507
508 export class DeletionPending extends Data.TaggedError("NeonDeletionPending")<{
509 resourceId: string;
510 }> {}
511
512 export class OperationFailed extends Data.TaggedError("NeonOperationFailed")<{
513 operationId: string;
514 action: string;
515 status: string;
516 }> {
517 override get message() {
518 return `Neon operation ${this.operationId} (${this.action}) ended ${this.status}`;
519 }
520 }
521
522 export class OperationPending extends Data.TaggedError("NeonOperationPending")<{
523 operationId: string;
524 status: string;
525 }> {}
526
527 type PendingOperation = {
528 readonly id: string;
529 readonly project_id: string;
530 readonly action: string;
531 readonly status: string;
532 };
533
534 const checkOperation = (
535 op: PendingOperation,
536 ): Effect.Effect<void, OperationFailed | OperationPending> => {
537 if (op.status === "finished" || op.status === "skipped") return Effect.void;
538 if (op.status === "failed" || op.status === "error" || op.status === "cancelled") {
539 return Effect.fail(
540 new OperationFailed({
541 operationId: op.id,
542 action: op.action,
543 status: op.status,
544 }),
545 );
546 }
547 return Effect.fail(new OperationPending({ operationId: op.id, status: op.status }));
548 };
549
550 /** Wait at most 55 seconds; pending, cancelled and failed operations never succeed. */
551 export const waitForOperations = (operations: ReadonlyArray<PendingOperation>) =>
552 Effect.forEach(
553 operations,
554 (op) =>
555 checkOperation(op).pipe(
556 Effect.catchTag("NeonOperationPending", () =>
557 getProjectOperation({
558 project_id: op.project_id,
559 operation_id: op.id,
560 }).pipe(
561 Effect.flatMap(({ operation }) => checkOperation(operation)),
562 Effect.retry({
563 while: (error) => error._tag === "NeonOperationPending",
564 schedule: Schedule.spaced("5 seconds"),
565 times: 8,
566 }),
567 ),
568 ),
569 ),
570 { concurrency: 10, discard: true },
571 ).pipe(Effect.timeout("55 seconds"));
572
573 const findProjectByName = (name: string, orgId?: string) =>
574 Effect.gen(function* () {
575 const matches: ListProjectsResponse["projects"][number][] = [];
576 let cursor: string | undefined;
577 while (true) {
578 const page = yield* listProjects({
579 search: name,
580 ...(orgId !== undefined ? { org_id: orgId } : {}),
581 ...(cursor !== undefined ? { cursor } : {}),
582 });
583 for (const p of page.projects) {
584 if (p.name === name) matches.push(p);
585 }
586 const nextCursor = page.pagination?.cursor;
587 // Neon returns a `pagination.cursor` on every response — it's the
588 // `created_at` of the last row, not a "has next page" flag — so we
589 // can't loop on cursor presence alone or we spin forever re-fetching
590 // empty/identical pages. Stop once a page comes back empty or the
591 // cursor stops advancing.
592 if (page.projects.length === 0 || nextCursor === undefined || nextCursor === cursor) {
593 break;
594 }
595 cursor = nextCursor;
596 }
597 return matches;
598 });
599
600 /**
601 * Exhaustively enumerate every project in the account. Uses the same
602 * cursor-stop heuristic as {@link findProjectByName} because Neon returns a
603 * `pagination.cursor` on every page (it's the last row's `created_at`, not a
604 * "has next page" flag), so we'd otherwise loop forever re-fetching.
605 */
606 const listAllProjects = Effect.gen(function* () {
607 const projects: ListProjectsResponse["projects"][number][] = [];
608 let cursor: string | undefined;
609 while (true) {
610 const page = yield* listProjects(cursor !== undefined ? { cursor } : {});
611 projects.push(...page.projects);
612 const nextCursor = page.pagination?.cursor;
613 if (page.projects.length === 0 || nextCursor === undefined || nextCursor === cursor) {
614 break;
615 }
616 cursor = nextCursor;
617 }
618 return projects;
619 });
620
621 type ObservedProject = NeonProject | ListProjectsResponse["projects"][number];
622
623 /**
624 * Hydrate a project summary (from the list API) into the exact `read`
625 * Attributes shape — resolving the default branch, its primary database, and
626 * the direct + pooled connection URIs. Returns `undefined` when the project
627 * has no branch or database yet (mirrors `read`).
628 */
629 const hydrateProjectAttributes = (
630 project: ObservedProject,
631 opts: {
632 defaultBranchName?: string;
633 databaseName?: string;
634 migrationsDir?: string;
635 migrationsTable?: string;
636 migrationsHashes?: Record<string, string>;
637 importHashes?: Record<string, string>;
638 } = {},
639 ) =>
640 Effect.gen(function* () {
641 const branches: import("@distilled.cloud/neon").Branch[] = [];
642 let cursor: string | undefined;
643 do {
644 const page = yield* listProjectBranches({
645 project_id: project.id,
646 cursor,
647 });
648 branches.push(...page.branches);
649 const next = page.pagination?.next;
650 if (!next || next === cursor || page.branches.length === 0) break;
651 cursor = next;
652 } while (cursor);
653 const defaultBranch = branches.find((b) => b.default);
654 if (!defaultBranch) return undefined;
655 const databases = yield* listProjectBranchDatabases({
656 project_id: project.id,
657 branch_id: defaultBranch.id,
658 });
659 const db = opts.databaseName
660 ? databases.databases.find((db) => db.name === opts.databaseName)
661 : databases.databases[0];
662 if (!db) return undefined;
663 const conn = yield* resolveConnection(project.id, defaultBranch.id, db.name, db.owner_name);
664 return {
665 projectId: project.id,
666 projectName: project.name,
667 region: project.region_id as NeonRegion,
668 pgVersion: project.pg_version as NeonPgVersion,
669 defaultBranchId: defaultBranch.id,
670 defaultBranchName: defaultBranch.name,
671 databaseName: db.name,
672 roleName: db.owner_name,
673 connectionUri: conn.uri,
674 pooledConnectionUri: conn.pooled,
675 origin: parsePostgresOrigin(conn.uri),
676 pooledOrigin: parsePostgresOrigin(conn.pooled),
677 historyRetentionSeconds: project.history_retention_seconds ?? 86400,
678 enableLogicalReplication: project.settings?.enable_logical_replication === true,
679 migrationsDir: opts.migrationsDir,
680 migrationsTable: opts.migrationsTable,
681 migrationsHashes: opts.migrationsHashes ?? {},
682 importHashes: opts.importHashes ?? {},
683 } satisfies ProjectAttributes;
684 });