@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, 06:00 UTC

main
ts 839 lines 30.3 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 createProjectBranch,
11 createProjectEndpoint,
12 deleteProjectEndpoint,
13 getProject,
14 listProjectBranchEndpoints,
15 updateProjectEndpoint,
16 deleteProjectBranch,
17 getConnectionURI,
18 getProjectBranch,
19 listProjectBranchDatabases,
20 listProjectBranches,
21 type ListProjectBranchesResponse,
22 listProjects,
23 type ListProjectsResponse,
24 updateProjectBranch,
25 } from "@distilled.cloud/neon";
26 import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
27 import { isResolved } from "alchemy/Diff";
28 import { createPhysicalName } from "alchemy/PhysicalName";
29 import * as Provider from "alchemy/Provider";
30 import { Resource } from "alchemy/Resource";
31 import { recordsEqual } from "alchemy/Util/equal";
32 import * as Data from "effect/Data";
33 import * as Effect from "effect/Effect";
34 import * as Redacted from "effect/Redacted";
35 import * as Schedule from "effect/Schedule";
36 import { runImports, runPgMigrations } from "./Migrations.ts";
37 import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts";
38 import { DeletionPending, type Project, waitForOperations } from "./Project.ts";
39 import type { Providers } from "./Providers.ts";
40
41 export type BranchSource = Project | { projectId: string };
42
43 export type ParentBranchSource = Branch | { branchId: string } | { name: string };
44
45 export type BranchEndpointConfig = {
46 /** Endpoint access mode. A branch has exactly one read-write endpoint. */
47 type: "read_only" | "read_write";
48 /** Minimum compute units. Removing this setting restores the project default. */
49 autoscalingLimitMinCu?: number;
50 /** Maximum compute units. Removing this setting restores the project default. */
51 autoscalingLimitMaxCu?: number;
52 /** Idle timeout in seconds; 0 selects the plan default and -1 disables suspension. */
53 suspendTimeoutSeconds?: number;
54 };
55
56 export type BranchProps = {
57 /**
58 * The Neon project (or `{ projectId }`) to create the branch in.
59 */
60 project: BranchSource;
61 /**
62 * Branch name. If omitted, a unique name is generated from
63 * `${app}-${stage}-${id}`.
64 */
65 name?: string;
66 /**
67 * The parent branch to fork from. Accepts a `Branch`, a
68 * `{ branchId }`, or `{ name }` to look up by name. Defaults to the
69 * project's default branch.
70 */
71 parentBranch?: ParentBranchSource;
72 /**
73 * A Log Sequence Number on the parent branch. The new branch is created
74 * with parent data as of this LSN.
75 */
76 parentLsn?: string;
77 /**
78 * An ISO-8601 timestamp identifying a point in time on the parent branch
79 * to fork from.
80 */
81 parentTimestamp?: string;
82 /**
83 * Whether the branch is protected from deletion / mutation.
84 *
85 * @default false
86 */
87 protected?: boolean;
88 /**
89 * Initialization source.
90 *
91 * - `parent-data` (default) — copy schema and data from the parent.
92 * - `schema-only` — copy only the schema.
93 */
94 initSource?: "schema-only" | "parent-data";
95 /**
96 * RFC-3339 timestamp at which Neon should auto-delete the branch.
97 * Useful for ephemeral preview branches.
98 */
99 expiresAt?: string;
100 /**
101 * Compute endpoints owned by this branch. Exactly one `read_write` endpoint
102 * is required for the connection outputs. Settings update in place; removing
103 * a setting restores the project default and removing an endpoint deletes it.
104 * Do not independently manage endpoints on a branch managed by this resource.
105 *
106 * @default [{ type: "read_write" }]
107 */
108 endpoints?: BranchEndpointConfig[];
109 /**
110 * SQL migrations to apply against the branch. Accepts a directory path, a
111 * `Drizzle.Schema` resource, or `{ dir, table? }`.
112 *
113 * Bookkeeping always lives in Alchemy's `__alchemy_migrations` table. A
114 * database previously migrated by drizzle-kit or Prisma is adopted by a
115 * one-way conversion on first deploy: the old tool's applied history is
116 * copied into Alchemy's table and the old table is left frozen. No
117 * baselining required.
118 */
119 migrations?: MigrationsInput;
120 /**
121 * Paths to additional `.sql` files to apply after migrations.
122 */
123 importFiles?: string[];
124 };
125
126 export type Branch = Resource<
127 "Neon.Branch",
128 BranchProps,
129 {
130 /** Neon branch identifier. */
131 branchId: string;
132 /** Observed branch name. */
133 branchName: string;
134 /** Owning project identifier. */
135 projectId: string;
136 /** Parent branch identifier, when present. */
137 parentBranchId: string | undefined;
138 /** Parent log sequence number used for the fork. */
139 parentLsn: string | undefined;
140 /** Parent timestamp used for the fork. */
141 parentTimestamp: string | undefined;
142 /** Whether the fork copied data or only schema. */
143 initSource: "schema-only" | "parent-data" | undefined;
144 /** Whether deletion and mutation protection is enabled. */
145 protected: boolean;
146 /** Whether this is the project's current default branch. */
147 default: boolean;
148 /** Automatic expiration timestamp, when configured. */
149 expiresAt: string | undefined;
150 /** Database selected for connection outputs and migrations. */
151 databaseName: string;
152 /** Observed owner of the selected database. */
153 roleName: string;
154 /** Postgres connection URI for the branch's primary database. */
155 connectionUri: string;
156 /** Pooled connection URI (uses pgbouncer). */
157 pooledConnectionUri: string;
158 /**
159 * Parsed connection components ready to feed into a Postgres origin
160 * — e.g. `Cloudflare.Hyperdrive`'s `origin` prop. Points at the
161 * direct (non-pooled) endpoint, which is the recommended target
162 * when fronting Neon with another pooler like Hyperdrive.
163 */
164 origin: PostgresOrigin;
165 /**
166 * Parsed pooled connection components. Useful as a Hyperdrive `dev`
167 * origin when local workers bypass Hyperdrive and connect directly.
168 */
169 pooledOrigin: PostgresOrigin;
170 /** Directory of the applied SQL migrations. */
171 migrationsDir: string | undefined;
172 /** Migration bookkeeping table. */
173 migrationsTable: string | undefined;
174 /** Applied migration content hashes. */
175 migrationsHashes: Record<string, string>;
176 /** Applied SQL import content hashes. */
177 importHashes: Record<string, string>;
178 },
179 never,
180 Providers
181 >;
182
183 /**
184 * A branch of a Neon project.
185 *
186 * Branches are first-class, copy-on-write copies of a parent branch — they
187 * share storage with the parent until the new branch starts diverging.
188 * ### Branching from a project's default branch
189 * **Example:** Basic branch
190 * ```typescript
191 * const project = yield* Neon.Project("my-project");
192 * const dev = yield* Neon.Branch("dev-branch", { project });
193 * ```
194 *
195 * ### Branching from another branch
196 * **Example:** Branch off another branch
197 * ```typescript
198 * const dev = yield* Neon.Branch("dev", { project });
199 * const featureBranch = yield* Neon.Branch("feature", {
200 * project,
201 * parentBranch: dev,
202 * });
203 * ```
204 *
205 * ### Point-in-time branches
206 * **Example:** Branch from a parent at a specific LSN
207 * ```typescript
208 * const branch = yield* Neon.Branch("at-lsn", {
209 * project,
210 * parentLsn: "0/3FA01B0",
211 * });
212 * ```
213 *
214 * ### Configuring the default branch
215 * Adopt the project's default branch to manage its compute. Destroying the
216 * stack leaves the branch to be removed with its project, since Neon does
217 * not delete a project's root or default branch on its own.
218 *
219 * **Example:** Adopt the default branch
220 * ```typescript
221 * const project = yield* Neon.Project("my-project");
222 * const main = yield* Neon.Branch("main", {
223 * project,
224 * name: "main",
225 * endpoints: [{ type: "read_write", autoscalingLimitMaxCu: 1 }],
226 * }).pipe(adopt(true));
227 * ```
228 *
229 * ### Migrations on a branch
230 * **Example:** Apply migrations on the branch only
231 * ```typescript
232 * const featureBranch = yield* Neon.Branch("feature", {
233 * project,
234 * migrations: "./migrations",
235 * });
236 * ```
237 *
238 * @see https://neon.tech/docs/manage/branches/
239 *
240 * @resource
241 * @product Branch
242 */
243 export const Branch = Resource<Branch>("Neon.Branch");
244
245 export const BranchProvider = () =>
246 Provider.succeed(Branch, {
247 stables: ["branchId", "projectId"],
248 diff: Effect.fn(function* ({ id, olds, news, output }) {
249 // Normally we short-circuit on `isResolved(news)` at the beginning.
250 // However, this wouldn't detect an upstream project change, causing an update when what we really want is a replace.
251 // So, we check the project first before short-circuiting. `projectId` is a stable attribute of `Project`, so the
252 // planning engine resolves `news.project` to a plain object carrying that stable id (even when the project is being
253 // updated in place). An unchanged project therefore resolves to the same string; a changed/replaced project resolves
254 // to either a different string or an unresolved output, so `oldProjectId !== newProjectId` evaluates correctly.
255 // An Output-valued `project` doesn't survive a `creating`-state
256 // round-trip (it deserializes as `undefined`) — when the old project is
257 // unknown, fall through to the create/update recovery path rather than
258 // force a replacement.
259 const oldProjectId =
260 output?.projectId ??
261 (olds.project !== undefined
262 ? maybeResolveProjectId(olds.project as BranchSource)
263 : undefined);
264 const newProjectId =
265 "project" in news ? maybeResolveProjectId(news.project as BranchSource) : undefined;
266 if (oldProjectId !== undefined && oldProjectId !== newProjectId) {
267 return { action: "replace" } as const;
268 }
269 const pending = news as Partial<BranchProps>;
270 const replacement = {
271 action: "replace",
272 deleteFirst:
273 pending.name !== undefined &&
274 pending.name === (output?.branchName ?? olds.name) &&
275 oldProjectId === newProjectId,
276 } as const;
277 // A fork point only known at apply time cannot be proven unchanged, and
278 // `reconcile` never re-forks an existing branch, so an update would
279 // silently keep the old data.
280 if (
281 output &&
282 !isResolved([
283 pending.parentBranch,
284 pending.parentLsn,
285 pending.parentTimestamp,
286 pending.initSource,
287 ])
288 ) {
289 return replacement;
290 }
291 if (!isResolved(news)) return undefined;
292 if (
293 olds.parentLsn !== news.parentLsn ||
294 olds.parentTimestamp !== news.parentTimestamp ||
295 (olds.initSource ?? "parent-data") !== (news.initSource ?? "parent-data")
296 ) {
297 return replacement;
298 }
299 if (output && news.parentBranch) {
300 const parent = yield* resolveParentBranchId(
301 news.parentBranch as ParentBranchSource,
302 output.projectId,
303 );
304 // Schema-only branches are roots; the source is a creation input,
305 // not an observed parent relationship.
306 const previousParent =
307 news.initSource === "schema-only"
308 ? yield* resolveParentBranchId(
309 olds.parentBranch as ParentBranchSource | undefined,
310 output.projectId,
311 )
312 : output.parentBranchId;
313 if (parent !== previousParent) return replacement;
314 } else if (output && olds.parentBranch && !news.parentBranch) {
315 return replacement;
316 }
317 const oldName = output?.branchName ?? (yield* createBranchName(id, olds.name));
318 // Auto-generated names are engine-owned: the deployed name stays
319 // authoritative even if the generator would name this id differently
320 // today. Only an explicit user-provided name can force a rename.
321 const newName = news.name ?? oldName;
322 if (
323 newName !== oldName ||
324 (news.protected ?? false) !== (output?.protected ?? false) ||
325 (news.expiresAt ?? undefined) !== (output?.expiresAt ?? undefined)
326 ) {
327 return { action: "update" } as const;
328 }
329 if (yield* diffMigrations({ news, output })) {
330 return { action: "update" } as const;
331 }
332 if (news.importFiles?.length) {
333 const newHashes = yield* hashImports(news.importFiles, yield* rootDir);
334 if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
335 return { action: "update" } as const;
336 }
337 }
338 return undefined;
339 }),
340 read: Effect.fn(function* ({ id, output, olds, previous }) {
341 if (output?.branchId) {
342 return yield* getProjectBranch({
343 project_id: output.projectId,
344 branch_id: output.branchId,
345 }).pipe(
346 Effect.flatMap(({ branch }) => hydrateBranch(output.projectId, branch, output)),
347 Effect.catchTag("NotFound", () => Effect.undefined),
348 );
349 }
350 if (!olds?.project) return undefined;
351 const projectId = maybeResolveProjectId(olds.project as BranchSource);
352 if (projectId === undefined) {
353 // The project reference survived as an object but its Output-valued
354 // `projectId` did not — there is nothing to look the branch up in.
355 return undefined;
356 }
357 const name = yield* createBranchName(id, olds.name);
358 // The whole project may already be gone (out-of-band deletion); the
359 // branch is gone with it, so recovery observes an absent branch.
360 const matches = yield* findBranchByName(projectId, name).pipe(
361 Effect.catchTag("NotFound", () => Effect.succeed([])),
362 );
363 if (matches.length > 1)
364 return yield* new BranchStateError({ reason: "Ambiguous branch name" });
365 const match = matches[0];
366 if (!match) return undefined;
367 const attrs = yield* hydrateBranch(projectId, match);
368 // The generation a replacement is replacing is ours.
369 if (attrs && attrs.branchId === previous?.branchId) return attrs;
370 return attrs && Unowned(attrs);
371 }),
372 reconcile: Effect.fn(function* ({ id, news, output }) {
373 const projectId = yield* resolveProjectId(news.project as BranchSource);
374 const newName = news.name ?? output?.branchName ?? (yield* createBranchName(id, undefined));
375 const endpoints = news.endpoints ?? [{ type: "read_write" as const }];
376 if (endpoints.filter((endpoint) => endpoint.type === "read_write").length !== 1) {
377 return yield* new BranchStateError({
378 reason: "Branch requires exactly one read_write endpoint for its connection outputs",
379 });
380 }
381 // Approval of a cached branch never authorizes a different same-name ID.
382 const authorize = (
383 branch: ListProjectBranchesResponse["branches"][number],
384 ): Effect.Effect<ListProjectBranchesResponse["branches"][number], OwnedBySomeoneElse> =>
385 projectId === output?.projectId && branch.id === output.branchId
386 ? Effect.succeed(branch)
387 : Effect.fail(
388 new OwnedBySomeoneElse({
389 message: `Neon branch "${newName}" requires explicit adoption`,
390 resourceType: "Neon.Branch",
391 logicalId: id,
392 physicalName: branch.id,
393 }),
394 );
395 let observed =
396 output?.branchId && output.projectId === projectId
397 ? yield* getProjectBranch({
398 project_id: projectId,
399 branch_id: output.branchId,
400 }).pipe(
401 Effect.map(({ branch }) => branch),
402 Effect.catchTag("NotFound", () => Effect.undefined),
403 )
404 : undefined;
405 if (!observed) {
406 const matches = yield* findBranchByName(projectId, newName);
407 if (matches.length > 1)
408 return yield* new BranchStateError({
409 reason: "Ambiguous branch name",
410 });
411 observed = matches[0] ? yield* authorize(matches[0]) : undefined;
412 }
413 if (!observed) {
414 const parentBranchId = yield* resolveParentBranchId(
415 news.parentBranch as ParentBranchSource | undefined,
416 projectId,
417 );
418 const created = yield* createProjectBranch({
419 project_id: projectId,
420 branch: {
421 name: newName,
422 parent_id: parentBranchId,
423 parent_lsn: news.parentLsn,
424 parent_timestamp: news.parentTimestamp,
425 init_source: news.initSource,
426 protected: news.protected,
427 expires_at: news.expiresAt,
428 },
429 endpoints: buildEndpoints(endpoints),
430 }).pipe(
431 Effect.catchTag("Conflict", (error) =>
432 findBranchByName(projectId, newName).pipe(
433 Effect.flatMap(
434 Effect.fn(function* (matches) {
435 if (matches.length !== 1) return yield* error;
436 const branch = yield* authorize(matches[0]!);
437 return { branch, operations: [] };
438 }),
439 ),
440 ),
441 ),
442 );
443 yield* waitForOperations(created.operations);
444 observed = created.branch;
445 }
446 if (
447 observed.name !== newName ||
448 observed.protected !== (news.protected ?? false) ||
449 observed.expires_at !== news.expiresAt
450 ) {
451 const updated = yield* updateProjectBranch({
452 project_id: projectId,
453 branch_id: observed.id,
454 branch: {
455 name: observed.name !== newName ? newName : undefined,
456 protected:
457 observed.protected !== (news.protected ?? false)
458 ? (news.protected ?? false)
459 : undefined,
460 expires_at:
461 observed.expires_at !== news.expiresAt ? (news.expiresAt ?? null) : undefined,
462 },
463 });
464 yield* waitForOperations(updated.operations);
465 }
466 yield* syncEndpoints(projectId, observed.id, endpoints);
467 const current = yield* getProjectBranch({
468 project_id: projectId,
469 branch_id: observed.id,
470 });
471 const branchInfo = yield* hydrateBranch(
472 projectId,
473 current.branch,
474 output?.branchId === observed.id ? output : undefined,
475 );
476 if (!branchInfo)
477 return yield* new BranchStateError({
478 reason: "Branch has no database or connection endpoint",
479 });
480 const previous = branchInfo.branchId === output?.branchId ? output : undefined;
481
482 const connectionUri = Redacted.make(branchInfo.connectionUri);
483 const migrationsInput = migrationsInputOf(news);
484 const migrations = migrationsInput
485 ? yield* runPgMigrations({
486 connectionUri,
487 input: migrationsInput,
488 stamped: stampedOf(previous),
489 })
490 : undefined;
491 const importHashes = news.importFiles?.length
492 ? yield* runImports(
493 connectionUri,
494 news.importFiles,
495 yield* rootDir,
496 previous?.importHashes ?? {},
497 )
498 : {};
499
500 return {
501 ...branchInfo,
502 ...migrationsAttrs({
503 input: migrationsInput,
504 run: migrations,
505 output: previous,
506 }),
507 importHashes,
508 };
509 }),
510 delete: Effect.fn(function* ({ output }) {
511 const retained = yield* Effect.gen(function* () {
512 const { branch } = yield* getProjectBranch({
513 project_id: output.projectId,
514 branch_id: output.branchId,
515 });
516 // Neon refuses to delete a project's root or default branch (an
517 // adopted `main`, say); it is removed together with the project.
518 // Schema-only branches are parentless too, but they are deletable.
519 if (
520 branch.default ||
521 (branch.parent_id === undefined &&
522 branch.init_source !== "parent-schema" &&
523 branch.init_source !== "schema-only")
524 ) {
525 return true;
526 }
527 if (branch.protected) {
528 const updated = yield* updateProjectBranch({
529 project_id: output.projectId,
530 branch_id: output.branchId,
531 branch: { protected: false },
532 });
533 yield* waitForOperations(updated.operations);
534 }
535 const deleted = yield* deleteProjectBranch({
536 project_id: output.projectId,
537 branch_id: output.branchId,
538 });
539 yield* waitForOperations(deleted.operations);
540 return false;
541 }).pipe(Effect.catchTag("NotFound", () => Effect.succeed(false)));
542 if (retained) return;
543 yield* getProjectBranch({
544 project_id: output.projectId,
545 branch_id: output.branchId,
546 }).pipe(
547 Effect.flatMap(() => Effect.fail(new DeletionPending({ resourceId: output.branchId }))),
548 Effect.catchTag("NotFound", () => Effect.void),
549 Effect.retry({
550 while: (error) => error._tag === "NeonDeletionPending",
551 schedule: Schedule.spaced("2 seconds"),
552 times: 8,
553 }),
554 Effect.timeout("20 seconds"),
555 );
556 }),
557 // Parent fan-out: branches are scoped to a project, and there is no
558 // account-wide branch enumeration API. Enumerate every project, then
559 // list+hydrate the branches of each (bounded concurrency), producing
560 // the exact `read` Attributes shape for each branch.
561 list: Effect.fn(function* () {
562 const projects = yield* listAllProjects;
563 const perProject = yield* Effect.forEach(
564 projects,
565 (project) =>
566 Effect.gen(function* () {
567 const branches = yield* listAllBranches(project.id);
568 return yield* Effect.forEach(branches, (branch) => hydrateBranch(project.id, branch), {
569 concurrency: 10,
570 });
571 }).pipe(
572 // The project may be deleted between enumeration and listing.
573 Effect.catchTag("NotFound", () => Effect.succeed([])),
574 ),
575 { concurrency: 10 },
576 );
577 return perProject.flat().filter((row): row is Branch["Attributes"] => row !== undefined);
578 }),
579 });
580
581 const listAllProjects = Effect.gen(function* () {
582 const projects: ListProjectsResponse["projects"][number][] = [];
583 let cursor: string | undefined;
584 while (true) {
585 const page = yield* listProjects(cursor !== undefined ? { cursor } : {});
586 projects.push(...page.projects);
587 const nextCursor = page.pagination?.cursor;
588 // Neon returns a `pagination.cursor` on every response (the `created_at`
589 // of the last row), not a "has next page" flag — stop once a page comes
590 // back empty or the cursor stops advancing to avoid an infinite loop.
591 if (page.projects.length === 0 || nextCursor === undefined || nextCursor === cursor) {
592 break;
593 }
594 cursor = nextCursor;
595 }
596 return projects;
597 });
598
599 const listAllBranches = (projectId: string) =>
600 Effect.gen(function* () {
601 const branches: ListProjectBranchesResponse["branches"][number][] = [];
602 let cursor: string | undefined;
603 do {
604 const page = yield* listProjectBranches({
605 project_id: projectId,
606 ...(cursor !== undefined ? { cursor } : {}),
607 });
608 branches.push(...page.branches);
609 cursor = page.pagination?.next;
610 } while (cursor);
611 return branches;
612 });
613
614 const hydrateBranch = (
615 projectId: string,
616 branch: ListProjectBranchesResponse["branches"][number],
617 previous?: Branch["Attributes"],
618 ) =>
619 Effect.gen(function* () {
620 const dbs = yield* listProjectBranchDatabases({
621 project_id: projectId,
622 branch_id: branch.id,
623 });
624 const db = dbs.databases.find((db) => db.name === previous?.databaseName) ?? dbs.databases[0];
625 if (!db) return undefined;
626 const conn = yield* fetchConnection(projectId, branch.id, db.name, db.owner_name);
627 const attributes: Branch["Attributes"] = {
628 branchId: branch.id,
629 branchName: branch.name,
630 projectId,
631 parentBranchId: branch.parent_id,
632 parentLsn: branch.parent_lsn,
633 parentTimestamp: branch.parent_timestamp,
634 initSource:
635 branch.init_source === "parent-schema" || branch.init_source === "schema-only"
636 ? "schema-only"
637 : branch.init_source === "parent-data"
638 ? "parent-data"
639 : undefined,
640 protected: branch.protected,
641 default: branch.default,
642 expiresAt: branch.expires_at,
643 databaseName: db.name,
644 roleName: db.owner_name,
645 connectionUri: conn.uri,
646 pooledConnectionUri: conn.pooled,
647 origin: parsePostgresOrigin(conn.uri),
648 pooledOrigin: parsePostgresOrigin(conn.pooled),
649 migrationsDir: previous?.migrationsDir,
650 migrationsTable: previous?.migrationsTable,
651 migrationsHashes: previous?.migrationsHashes ?? {},
652 importHashes: previous?.importHashes ?? {},
653 };
654 return attributes;
655 }).pipe(
656 // A branch/database/endpoint can disappear mid-enumeration — skip it.
657 Effect.catchTag("NotFound", () => Effect.undefined),
658 );
659
660 const rootDir = Effect.sync(() => process.cwd());
661 const createBranchName = (id: string, name: string | undefined) =>
662 Effect.gen(function* () {
663 return name ?? (yield* createPhysicalName({ id }));
664 });
665
666 const findBranchByName = (projectId: string, name: string) =>
667 Effect.gen(function* () {
668 const matches: ListProjectBranchesResponse["branches"][number][] = [];
669 let cursor: string | undefined;
670 do {
671 const page = yield* listProjectBranches({
672 project_id: projectId,
673 search: name,
674 ...(cursor !== undefined ? { cursor } : {}),
675 });
676 for (const b of page.branches) {
677 if (b.name === name) matches.push(b);
678 }
679 cursor = page.pagination?.next;
680 } while (cursor);
681 return matches;
682 });
683
684 const maybeResolveProjectId = (source: BranchSource): string | undefined => {
685 if (source && "projectId" in source && typeof source.projectId === "string") {
686 return source.projectId;
687 }
688 return undefined;
689 };
690
691 const resolveProjectId = (source: BranchSource) => {
692 const projectId = maybeResolveProjectId(source);
693 return projectId
694 ? Effect.succeed(projectId)
695 : Effect.fail(
696 new BranchStateError({
697 reason: "Invalid Neon project source: must be a Project or { projectId }",
698 }),
699 );
700 };
701
702 const resolveParentBranchId = (source: ParentBranchSource | undefined, projectId: string) =>
703 Effect.gen(function* () {
704 if (!source) return undefined as string | undefined;
705 if ("branchId" in source && typeof source.branchId === "string") {
706 if (
707 "projectId" in source &&
708 typeof source.projectId === "string" &&
709 source.projectId !== projectId
710 ) {
711 return yield* new BranchStateError({
712 reason: "Parent branch belongs to another project",
713 });
714 }
715 return source.branchId;
716 }
717 if ("name" in source && source.name) {
718 const matches = yield* findBranchByName(projectId, source.name);
719 if (matches.length === 0) {
720 return yield* new BranchStateError({
721 reason: `Parent branch "${source.name}" not found in project ${projectId}`,
722 });
723 }
724 if (matches.length > 1) {
725 return yield* new BranchStateError({
726 reason: `Multiple branches with name "${source.name}" in project ${projectId}`,
727 });
728 }
729 return matches[0]!.id;
730 }
731 return undefined as string | undefined;
732 });
733
734 export class BranchStateError extends Data.TaggedError("NeonBranchStateError")<{
735 reason: string;
736 }> {}
737
738 const syncEndpoints = Effect.fn(function* (
739 projectId: string,
740 branchId: string,
741 desired: BranchEndpointConfig[],
742 ) {
743 const { project } = yield* getProject({ project_id: projectId });
744 const defaults = project.default_endpoint_settings ?? {};
745 const { endpoints } = yield* listProjectBranchEndpoints({
746 project_id: projectId,
747 branch_id: branchId,
748 });
749 const remaining = [...endpoints].sort((a, b) => a.id.localeCompare(b.id));
750 for (const config of desired) {
751 const index = remaining.findIndex((endpoint) => endpoint.type === config.type);
752 let observed = index < 0 ? undefined : remaining.splice(index, 1)[0];
753 const settings = {
754 autoscaling_limit_min_cu:
755 config.autoscalingLimitMinCu ?? defaults.autoscaling_limit_min_cu ?? 0.25,
756 autoscaling_limit_max_cu:
757 config.autoscalingLimitMaxCu ?? defaults.autoscaling_limit_max_cu ?? 2,
758 suspend_timeout_seconds:
759 config.suspendTimeoutSeconds ?? defaults.suspend_timeout_seconds ?? 0,
760 };
761 if (!observed) {
762 const created = yield* createProjectEndpoint({
763 project_id: projectId,
764 endpoint: { branch_id: branchId, type: config.type, ...settings },
765 }).pipe(
766 Effect.catchTag("Conflict", (error) =>
767 listProjectBranchEndpoints({
768 project_id: projectId,
769 branch_id: branchId,
770 }).pipe(
771 Effect.flatMap(({ endpoints }) => {
772 const matches = endpoints.filter((endpoint) => endpoint.type === "read_write");
773 return config.type === "read_write" && matches.length === 1
774 ? Effect.succeed({ endpoint: matches[0]!, operations: [] })
775 : Effect.fail(error);
776 }),
777 ),
778 ),
779 );
780 yield* waitForOperations(created.operations);
781 observed = created.endpoint;
782 }
783 if (
784 observed.autoscaling_limit_min_cu !== settings.autoscaling_limit_min_cu ||
785 observed.autoscaling_limit_max_cu !== settings.autoscaling_limit_max_cu ||
786 observed.suspend_timeout_seconds !== settings.suspend_timeout_seconds
787 ) {
788 const updated = yield* updateProjectEndpoint({
789 project_id: projectId,
790 endpoint_id: observed.id,
791 endpoint: settings,
792 });
793 yield* waitForOperations(updated.operations);
794 }
795 }
796 for (const endpoint of remaining) {
797 yield* deleteProjectEndpoint({
798 project_id: projectId,
799 endpoint_id: endpoint.id,
800 }).pipe(
801 Effect.flatMap(({ operations }) => waitForOperations(operations)),
802 Effect.catchTag("NotFound", () => Effect.void),
803 );
804 }
805 });
806
807 const buildEndpoints = (endpoints: BranchEndpointConfig[] | undefined) => {
808 const list = endpoints ?? [{ type: "read_write" as const }];
809 return list.map((e) => ({
810 type: e.type,
811 autoscaling_limit_min_cu: e.autoscalingLimitMinCu,
812 autoscaling_limit_max_cu: e.autoscalingLimitMaxCu,
813 suspend_timeout_seconds: e.suspendTimeoutSeconds,
814 }));
815 };
816
817 const fetchConnection = (
818 projectId: string,
819 branchId: string,
820 databaseName: string,
821 roleName: string,
822 ) =>
823 Effect.gen(function* () {
824 const direct = yield* getConnectionURI({
825 project_id: projectId,
826 branch_id: branchId,
827 database_name: databaseName,
828 role_name: roleName,
829 pooled: false,
830 });
831 const pooled = yield* getConnectionURI({
832 project_id: projectId,
833 branch_id: branchId,
834 database_name: databaseName,
835 role_name: roleName,
836 pooled: true,
837 });
838 return { uri: direct.uri, pooled: pooled.uri };
839 });