sailfork / t3code-github / .repos/ alchemy-effect/ packages/ prisma/ src/ Branch.ts

import { Retry } from "@distilled.cloud/prisma";
import {
  type GetProjectBranchesResponse,
  type GetProjectsResponse,
  deleteBranch,
  getBranch,
  getProjects,
  getProjectBranches,
  updateBranch,
  createProjectBranch,
} from "@distilled.cloud/prisma/management";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { DEV_TIMESTAMP, attrOrString, devId, devProvider } from "./internal/DevStub.ts";
import type { ObservedBranch } from "./internal/Observed.ts";
import { PrismaPaginationError } from "./internal/Pagination.ts";
import {
  concreteIdsChanged,
  isInputObject,
  isPrismaDevId,
  resolveProjectId,
  unresolvedProjectIdOf,
} from "./internal/Refs.ts";
import type { Project } from "./Project.ts";
import type { Providers } from "./Providers.ts";

export class BranchConflict extends Data.TaggedError("BranchConflict")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class BranchOperationFailed extends Data.TaggedError("BranchOperationFailed")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class BranchUnexpectedResponse extends Data.TaggedError("BranchUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface BranchProps {
  /**
   * Project ID or `project.projectId` output that owns this branch.
   */
  project: string | Project;
  /**
   * Git-style branch name. If omitted, Alchemy generates a stable physical
   * name.
   */
  gitName?: string;
  /**
   * Promote this branch to be the project's default branch. Setting this to
   * `false` does not demote a current default because the Management API only
   * supports promotion; promoting another branch atomically demotes it.
   * Promotion changes `isDefault`, not the branch's immutable `preview` role.
   *
   * @default false
   */
  isDefault?: boolean;
}

export interface Branch extends Resource<
  "Prisma.Branch",
  BranchProps,
  {
    /**
     * Prisma branch ID.
     */
    branchId: string;
    /**
     * Git-style branch name.
     */
    gitName: string;
    /**
     * Project ID that owns the branch.
     */
    projectId: string;
    /**
     * Whether this branch is the project's default branch.
     */
    isDefault: boolean;
    /**
     * Branch that was default before this preview branch was promoted. Alchemy
     * restores it before deleting this resource so destroy remains reversible.
     */
    previousDefaultBranchId?: string;
    /**
     * Branch role used by Prisma to resolve deploy-time environment variables.
     */
    role: "production" | "preview";
    /**
     * ISO timestamp when the branch was created.
     */
    createdAt: string;
    /**
     * ISO timestamp when the branch was last updated.
     */
    updatedAt: string;
  },
  never,
  Providers
> {}

/**
 * A Prisma project branch for preview-class databases and compute resources.
 *
 * Standalone Branch resources always have the `preview` role. Promotion
 * changes only the default branch; Alchemy restores the previous default
 * before deleting a promoted branch.
 *
 * ### Creating a Branch
 * **Example:** Preview branch
 * ```typescript
 * const branch = yield* Prisma.Branch("preview", {
 *   project: project.projectId,
 *   gitName: "feature/search", // optional — omitted, a stable name is generated
 * });
 *
 * branch.role;      // "preview"
 * branch.isDefault; // false
 * ```
 *
 * ### Promoting a Branch
 * **Example:** Make a preview branch the default
 * ```typescript
 * const release = yield* Prisma.Branch("release", {
 *   project,
 *   gitName: "release/next",
 *   isDefault: true,
 * });
 *
 * release.role;      // still "preview"
 * release.isDefault; // true
 * ```
 *
 * @resource
 * @product Project
 */
export const Branch = Resource<Branch>("Prisma.Branch");

const createGitName = (id: string, gitName: string | undefined) =>
  gitName === undefined ? createPhysicalName({ id }) : Effect.succeed(gitName);

// Distilled emits the cursor-paginated list operations as plain ops, so
// callers walk `pagination` themselves (see `src/Neon/Project.ts`).
const listBranches = (projectId: string, query?: { readonly gitName?: string }) =>
  Effect.gen(function* () {
    const branches: GetProjectBranchesResponse["data"][number][] = [];
    let cursor: string | undefined;
    while (true) {
      const page = yield* getProjectBranches({
        projectId,
        ...(query?.gitName === undefined ? {} : { gitName: query.gitName }),
        ...(cursor === undefined ? {} : { cursor }),
      });
      branches.push(...page.data);
      const nextCursor = page.pagination.nextCursor;
      if (!page.pagination.hasMore) break;
      if (nextCursor === null) {
        return yield* new PrismaPaginationError({
          message:
            "Invalid Prisma Management API pagination response from getProjectBranches: hasMore was true without a non-empty nextCursor",
        });
      }
      cursor = nextCursor;
    }
    return branches;
  });

const listProjects = () =>
  Effect.gen(function* () {
    const projects: GetProjectsResponse["data"][number][] = [];
    let cursor: string | undefined;
    while (true) {
      const page = yield* getProjects(cursor === undefined ? {} : { cursor });
      projects.push(...page.data);
      const nextCursor = page.pagination.nextCursor;
      if (!page.pagination.hasMore) break;
      if (nextCursor === null) {
        return yield* new PrismaPaginationError({
          message:
            "Invalid Prisma Management API pagination response from getProjects: hasMore was true without a non-empty nextCursor",
        });
      }
      cursor = nextCursor;
    }
    return projects;
  });

const findBranch = (projectId: string, gitName: string) =>
  listBranches(projectId, { gitName }).pipe(
    Effect.flatMap((branches) => {
      const matches = branches.filter((b: ObservedBranch) => b.gitName === gitName);
      return matches.length > 1
        ? Effect.fail(
            new BranchConflict({
              message: `Prisma project '${projectId}' has multiple branches named '${gitName}'; refusing to select one arbitrarily.`,
            }),
          )
        : Effect.succeed(matches[0]);
    }),
  );

const attrsFrom = (
  branch: ObservedBranch,
  previousDefaultBranchId?: string,
): Branch["Attributes"] => ({
  branchId: branch.id,
  gitName: branch.gitName,
  projectId: branch.project.id,
  isDefault: branch.isDefault,
  ...(previousDefaultBranchId === undefined ? {} : { previousDefaultBranchId }),
  role: branch.role,
  createdAt: branch.createdAt,
  updatedAt: branch.updatedAt,
});

const ensureBranchIdentity = (
  branch: ObservedBranch,
  expected: { projectId: string; gitName: string },
) =>
  branch.project.id === expected.projectId && branch.gitName === expected.gitName
    ? Effect.void
    : Effect.fail(
        new BranchConflict({
          message: `Prisma branch '${branch.id}' belongs to project '${branch.project.id}' with git name '${branch.gitName}', but this resource requires project '${expected.projectId}' and git name '${expected.gitName}'. Refusing to promote or delete a mismatched branch.`,
        }),
      );

const ProviderLive = () =>
  Provider.effect(
    Branch,
    Effect.gen(function* () {
      return {
        stables: ["branchId"],
        list: Effect.fn(function* () {
          const projects = yield* listProjects();
          const branches = yield* Effect.forEach(
            projects,
            (project) =>
              listBranches(project.id).pipe(Effect.catchTag("NotFound", () => Effect.succeed([]))),
            { concurrency: 8 },
          );
          // Current defaults and production-role branches are project-owned
          // and undeletable through the Branch API. Project deletion removes
          // them; omit them here so unsafe nuke only receives deletable rows.
          return branches
            .flat()
            .filter((branch) => !branch.isDefault && branch.role !== "production")
            .map((branch) => attrsFrom(branch));
        }),
        diff: Effect.fn(function* ({ id, olds, news, output }) {
          if (!isInputObject(news)) return undefined;
          if (isPrismaDevId(output?.branchId)) {
            return { action: "update" } as const;
          }
          const oldProjectId = output?.projectId ?? unresolvedProjectIdOf(olds.project);
          const newProjectId = isResolved(news.project)
            ? unresolvedProjectIdOf(news.project)
            : undefined;
          const newGitName = isResolved(news.gitName)
            ? yield* createGitName(id, news.gitName)
            : undefined;
          if (
            concreteIdsChanged(oldProjectId, newProjectId) ||
            (newGitName !== undefined &&
              newGitName !== (output?.gitName ?? (yield* createGitName(id, olds.gitName))))
          ) {
            return { action: "replace" } as const;
          }
          if (!isResolved(news.isDefault)) return undefined;
          // The Management API can promote a branch, atomically demoting the
          // old default, but explicitly rejects demoting the current default.
          // `false` therefore means "do not promote", not "demote".
          if (news.isDefault === true && output?.isDefault !== true) {
            return { action: "update" } as const;
          }
          return undefined;
        }),
        read: Effect.fn(function* ({ id, output, olds }) {
          const branchId = isPrismaDevId(output?.branchId) ? undefined : output?.branchId;
          const findBranchInProject = Effect.gen(function* () {
            const projectId = unresolvedProjectIdOf(olds.project);
            return projectId
              ? yield* findBranch(projectId, yield* createGitName(id, olds.gitName))
              : undefined;
          });
          const branch = branchId
            ? yield* getBranch({ branchId }).pipe(
                Effect.map((response) => response.data),
                Effect.catchTag("NotFound", () => Effect.undefined),
              )
            : yield* findBranchInProject;
          if (!branch) return undefined;
          const attrs = attrsFrom(branch, output?.previousDefaultBranchId);
          return branchId === undefined ? Unowned(attrs) : attrs;
        }),
        reconcile: Effect.fn(function* ({ id, news, output }) {
          const projectId = yield* resolveProjectId(news.project);
          const gitName = yield* createGitName(id, news.gitName);
          let previousDefaultBranchId = output?.previousDefaultBranchId;
          const branchId = isPrismaDevId(output?.branchId) ? undefined : output?.branchId;
          let branch = branchId
            ? yield* getBranch({ branchId }).pipe(
                Effect.map((response) => response.data),
                Effect.catchTag("NotFound", () => Effect.undefined),
              )
            : undefined;
          if (!branch) {
            const liveBranches = yield* listBranches(projectId);
            const defaults = liveBranches.filter((candidate) => candidate.isDefault);
            if (defaults.length !== 1) {
              return yield* new BranchConflict({
                message:
                  defaults.length === 0
                    ? `Prisma project '${projectId}' has no default branch. Refusing to create a standalone Branch because the Management API would make it the undeletable production branch; create or repair the owning Prisma.Project first.`
                    : `Prisma project '${projectId}' has ${defaults.length} default branches. Refusing to create a Branch until the project invariant is repaired.`,
              });
            }
            previousDefaultBranchId = defaults[0]!.id;
            branch = yield* createProjectBranch({
              projectId,
              gitName,
              ...(news.isDefault === undefined ? {} : { isDefault: news.isDefault }),
            }).pipe(
              // A replayed create would make a second branch; the retry
              // policy cannot see the request, so opt out explicitly.
              Retry.none,
              Effect.map((response) => response.data),
              Effect.catchTag("Conflict", () =>
                Effect.fail(
                  new BranchConflict({
                    message: `Prisma branch '${gitName}' appeared after the adoption check. Refusing to take it over; rerun with adoption enabled if it is the intended branch.`,
                  }),
                ),
              ),
            );
          }
          yield* ensureBranchIdentity(branch, {
            projectId,
            gitName,
          });
          if (news.isDefault === true && !branch.isDefault) {
            const liveBranches = yield* listBranches(projectId);
            const defaults = liveBranches.filter((candidate) => candidate.isDefault);
            if (defaults.length !== 1 || defaults[0]!.id === branch.id) {
              return yield* new BranchConflict({
                message: `Prisma project '${projectId}' does not have exactly one different default branch to restore later. Refusing to promote '${branch.gitName}'.`,
              });
            }
            previousDefaultBranchId = defaults[0]!.id;
            branch = (yield* updateBranch({
              branchId: branch.id,
              isDefault: true,
            })).data;
            yield* ensureBranchIdentity(branch, {
              projectId,
              gitName,
            });
            if (!branch.isDefault) {
              return yield* new BranchUnexpectedResponse({
                message: `Prisma branch '${branch.id}' promotion did not converge to the default branch.`,
              });
            }
          }
          return attrsFrom(branch, previousDefaultBranchId);
        }),
        delete: Effect.fn(function* ({ output }) {
          if (isPrismaDevId(output.branchId)) return;
          const branch = yield* getBranch({
            branchId: output.branchId,
          }).pipe(
            Effect.map((response) => response.data),
            Effect.catchTag("NotFound", () => Effect.undefined),
          );
          if (!branch) return;
          yield* ensureBranchIdentity(branch, {
            projectId: output.projectId,
            gitName: output.gitName,
          });
          if (branch.role === "production") {
            return yield* new BranchConflict({
              message: `Cannot delete Prisma branch '${branch.gitName ?? output.branchId}' directly because its production role is immutable. Delete the owning Prisma.Project.`,
            });
          }
          if (branch.isDefault) {
            const previousDefaultBranchId = output.previousDefaultBranchId;
            if (previousDefaultBranchId === undefined || previousDefaultBranchId === branch.id) {
              return yield* new BranchConflict({
                message: `Cannot safely delete default Prisma branch '${branch.gitName}' because state does not identify the branch it displaced. Promote another branch explicitly before deleting this resource.`,
              });
            }
            const previous = yield* getBranch({
              branchId: previousDefaultBranchId,
            }).pipe(
              Effect.map((response) => response.data),
              Effect.catchTag("NotFound", () =>
                Effect.fail(
                  new BranchOperationFailed({
                    message: `Cannot restore previous default Prisma branch '${previousDefaultBranchId}' because it no longer exists. Promote another branch explicitly before deleting '${branch.gitName}'.`,
                  }),
                ),
              ),
            );
            if (previous.project.id !== output.projectId || previous.id === branch.id) {
              return yield* new BranchConflict({
                message: `Previous default Prisma branch '${previous.id}' does not belong to project '${output.projectId}'. Refusing an unsafe promotion.`,
              });
            }
            const restored = previous.isDefault
              ? previous
              : (yield* updateBranch({
                  branchId: previous.id,
                  isDefault: true,
                })).data;
            if (
              restored.id !== previous.id ||
              restored.project.id !== output.projectId ||
              !restored.isDefault
            ) {
              return yield* new BranchUnexpectedResponse({
                message: `Prisma did not confirm restoration of previous default branch '${previous.id}'. Refusing to delete '${branch.gitName}'.`,
              });
            }
            const demoted = yield* getBranch({
              branchId: branch.id,
            }).pipe(
              Effect.map((response) => response.data),
              Effect.catchTag("NotFound", () => Effect.undefined),
            );
            if (!demoted) return;
            yield* ensureBranchIdentity(demoted, {
              projectId: output.projectId,
              gitName: output.gitName,
            });
            if (demoted.isDefault) {
              return yield* new BranchUnexpectedResponse({
                message: `Prisma branch '${branch.gitName}' remained default after restoring '${previous.gitName}'. Refusing to delete it.`,
              });
            }
          }
          // A member deleted moments ago (e.g. an App) can still count as
          // live until Prisma's control plane catches up.
          yield* deleteBranch({
            branchId: output.branchId,
          }).pipe(
            Effect.retry({
              while: (error) => error._tag === "Conflict",
              schedule: Schedule.exponential("500 millis"),
              times: 6,
            }),
            Effect.catchTag("NotFound", () => Effect.void),
          );
        }),
      };
    }),
  );

const ProviderLocal = () =>
  devProvider(Branch, ["branchId"], ({ id, news }) => ({
    branchId: devId("branch", id),
    gitName: news.gitName ?? id,
    projectId: attrOrString(news.project, "projectId"),
    isDefault: news.isDefault ?? false,
    role: news.isDefault ? "production" : "preview",
    createdAt: DEV_TIMESTAMP,
    updatedAt: DEV_TIMESTAMP,
  }));

export const BranchProvider = () =>
  ProviderLayer.dual(Branch, {
    local: () => ProviderLocal(),
    live: () => ProviderLive(),
  });