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

import { Retry } from "@distilled.cloud/prisma";
import {
  type GetProjectDatabasesResponse,
  type GetProjectsResponse,
  getProjects,
  getProject,
  getProjectDatabases,
  updateProject,
  createProject,
  createProjectDatabase,
} 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 Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import { extractConnectionSecrets } from "./Client.ts";
import { destroyProjectApps } from "./ComputeLifecycle.ts";
import {
  hasCanonicalConnectionSecrets,
  mergeConnectionSecrets,
  recoverDatabaseConnectionSecrets,
} from "./internal/DatabaseSecrets.ts";
import { DEV_TIMESTAMP, devId, devProvider } from "./internal/DevStub.ts";
import type { ObservedDatabase, ObservedProject } from "./internal/Observed.ts";
import { PrismaPaginationError } from "./internal/Pagination.ts";
import { isInputObject, isPrismaDevId } from "./internal/Refs.ts";
import type { Providers } from "./Providers.ts";
import type { PrismaSecretConnection, PrismaRegionId } from "./Types.ts";

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

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

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

export interface ProjectProps {
  /**
   * Project display name. If omitted, Alchemy generates a stable physical name.
   */
  name?: string;
  /**
   * Whether to create a default Prisma Postgres database with the project.
   *
   * @default true
   */
  createDatabase?: boolean;
  /**
   * Region for the default database created with the project.
   *
   * When `createDatabase` is false, omitting this leaves the project's default
   * region unset.
   *
   * @default "us-east-1" when a default database is created
   */
  region?: PrismaRegionId;
  /**
   * Opaque project settings passed through to the Management API.
   */
  settings?: Record<string, unknown>;
  /**
   * Rotate the adopted default database connection to recover its one-time
   * credentials. Prisma revokes the previous key on a best-effort basis and
   * rotation may interrupt existing consumers, so adoption leaves credentials
   * unset unless explicitly opted in.
   *
   * @default false
   */
  rotateCredentialsOnAdopt?: boolean;
}

export interface Project extends Resource<
  "Prisma.Project",
  ProjectProps,
  {
    /**
     * Prisma project ID.
     */
    projectId: string;
    /**
     * Prisma project display name.
     */
    projectName: string;
    /**
     * Workspace ID that owns the project.
     */
    workspaceId: string;
    /**
     * ISO timestamp when the project was created.
     */
    createdAt: string;
    /**
     * Default Prisma Postgres region for the project, when available.
     */
    defaultRegion: string | null;
    /**
     * Default database ID created with or discovered for the project.
     */
    databaseId: string | undefined;
    /**
     * Default database connection ID, when a database exists.
     */
    defaultConnectionId: string | undefined;
    /**
     * Direct Postgres connection string, redacted in state.
     */
    directConnectionString: Redacted.Redacted<string> | undefined;
    /**
     * Pooled Postgres connection string, redacted in state.
     */
    pooledConnectionString: Redacted.Redacted<string> | undefined;
    /**
     * Accelerate connection string, redacted in state.
     */
    accelerateConnectionString: Redacted.Redacted<string> | undefined;
    /**
     * Direct database host, when returned by Prisma.
     */
    host: string | null | undefined;
    /**
     * Direct database username, when returned by Prisma.
     */
    user: string | null | undefined;
    /**
     * Direct database password, redacted in state.
     */
    password: Redacted.Redacted<string> | undefined;
  },
  never,
  Providers
> {}

/**
 * A Prisma project, optionally with a default Prisma Postgres database.
 *
 * A Project is the ownership boundary for its databases, branches, apps, and
 * repository link. Destroying this resource deletes the project and its
 * contained data. Set `createDatabase: false` when you want standalone
 * `Prisma.Database` resources with independent lifecycles.
 *
 * ### Creating a Project
 * **Example:** Project with a default database
 * ```typescript
 * const project = yield* Prisma.Project("app", {
 *   name: "app",
 *   region: "us-east-1",
 * });
 * ```
 *
 * **Example:** Project only
 * ```typescript
 * const project = yield* Prisma.Project("control-plane", {
 *   createDatabase: false,
 * });
 * ```
 *
 * @resource
 * @product Project
 */
export const Project = Resource<Project>("Prisma.Project");

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

// Distilled emits the Management API's cursor-paginated list operations as
// plain ops, so callers walk `pagination` themselves — the same shape the Neon
// provider uses (see `src/Neon/Project.ts` findProjectByName).
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 findProjectByName = (name: string) =>
  listProjects().pipe(
    Effect.flatMap((projects) => {
      const matches = projects.filter((p) => p.name === name);
      return matches.length > 1
        ? Effect.fail(
            new ProjectConflict({
              message: `Multiple Prisma projects are named '${name}'; use a unique project name before managing it with Alchemy.`,
            }),
          )
        : Effect.succeed(matches[0]);
    }),
  );

class GeneratedProjectNotVisible extends Data.TaggedError("GeneratedProjectNotVisible")<{
  readonly message: string;
}> {}

const generatedProjectRecoverySchedule = Schedule.max([
  Schedule.exponential("250 millis"),
  Schedule.recurs(6),
]);

const recoverGeneratedProjectAfterConflict = (name: string) =>
  findProjectByName(name).pipe(
    Effect.flatMap((project) =>
      project
        ? Effect.succeed(project)
        : Effect.fail(
            new GeneratedProjectNotVisible({
              message: `Generated Prisma project '${name}' already exists but is not visible yet.`,
            }),
          ),
    ),
    Effect.retry({
      while: (error) => error instanceof GeneratedProjectNotVisible,
      schedule: generatedProjectRecoverySchedule,
    }),
  );

const listProjectDatabases = (projectId: string) =>
  Effect.gen(function* () {
    const databases: GetProjectDatabasesResponse["data"][number][] = [];
    let cursor: string | undefined;
    while (true) {
      const page = yield* getProjectDatabases(
        cursor === undefined ? { projectId, limit: 100 } : { projectId, limit: 100, cursor },
      );
      databases.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 getProjectDatabases: hasMore was true without a non-empty nextCursor",
        });
      }
      cursor = nextCursor;
    }
    return databases;
  });

const defaultDatabase = (projectId: string) =>
  listProjectDatabases(projectId).pipe(
    Effect.flatMap((databases) => {
      const matches = databases.filter((db) => db.isDefault);
      return matches.length > 1
        ? Effect.fail(
            new ProjectConflict({
              message: `Prisma project '${projectId}' has multiple default databases; refusing to select one arbitrarily.`,
            }),
          )
        : Effect.succeed(matches[0]);
    }),
  );

class DefaultDatabaseConsistencyError extends Data.TaggedError("DefaultDatabaseConsistencyError")<{
  readonly message: string;
}> {}

const defaultDatabaseConsistencySchedule = Schedule.max([
  Schedule.exponential("250 millis"),
  Schedule.recurs(6),
]);

const requireDefaultDatabaseInRegion = (
  database: ObservedDatabase | undefined,
  projectName: string,
  desiredRegion: string,
) =>
  database?.region?.id === desiredRegion
    ? Effect.succeed(database)
    : Effect.fail(
        new DefaultDatabaseConsistencyError({
          message: database
            ? `Prisma project '${projectName}' still has default database '${database.id}' in region '${database.region?.id ?? "unknown"}', but region '${desiredRegion}' was requested. Retry after any in-progress default database promotion completes.`
            : `Prisma project '${projectName}' does not expose the requested default database in region '${desiredRegion}'. Retry after any in-progress default database creation completes.`,
        }),
      );

type ProjectDatabaseAttrs = ObservedDatabase;

const observeDesiredDefaultDatabase = (
  projectName: string,
  projectId: string,
  expectedDatabaseId: string,
  desiredRegion: string,
) =>
  Effect.gen(function* () {
    const project = (yield* getProject({ id: projectId }).pipe(
      Effect.catchTag("NotFound", () =>
        Effect.fail(
          new DefaultDatabaseConsistencyError({
            message: `Prisma project '${projectName}' (${projectId}) is not visible yet while verifying its new default database.`,
          }),
        ),
      ),
    )).data;
    const database = yield* requireDefaultDatabaseInRegion(
      yield* defaultDatabase(projectId).pipe(
        Effect.catchTag("NotFound", () =>
          Effect.fail(
            new DefaultDatabaseConsistencyError({
              message: `Prisma project '${projectName}' default database list is not visible yet.`,
            }),
          ),
        ),
      ),
      projectName,
      desiredRegion,
    );
    if (database.id !== expectedDatabaseId) {
      return yield* new DefaultDatabaseConsistencyError({
        message: `Prisma project '${projectName}' exposes default database '${database.id}', but newly created database '${expectedDatabaseId}' was expected. Retry after the in-progress default database promotion completes.`,
      });
    }
    if (project.defaultRegion !== desiredRegion) {
      return yield* new DefaultDatabaseConsistencyError({
        message: `Prisma project '${projectName}' still reports default region '${project.defaultRegion ?? "unknown"}', but region '${desiredRegion}' was requested. Retry after the in-progress default database promotion completes.`,
      });
    }
    return { project, database };
  }).pipe(
    Effect.retry({
      while: (error) => error instanceof DefaultDatabaseConsistencyError,
      schedule: defaultDatabaseConsistencySchedule,
    }),
  );

const attrsFrom = (
  project: ObservedProject,
  database: ObservedDatabase | undefined,
  secrets: PrismaSecretConnection,
): Project["Attributes"] => ({
  projectId: project.id,
  projectName: project.name,
  workspaceId: project.workspace.id,
  createdAt: project.createdAt,
  // The default database observation is authoritative. Project.defaultRegion
  // may briefly lag after Prisma atomically promotes a replacement database.
  defaultRegion: database?.region?.id ?? project.defaultRegion,
  databaseId: database?.id,
  defaultConnectionId: database?.defaultConnectionId ?? undefined,
  directConnectionString: secrets.directConnectionString,
  pooledConnectionString: secrets.pooledConnectionString,
  accelerateConnectionString: secrets.accelerateConnectionString,
  host: secrets.host,
  user: secrets.user,
  password: secrets.password,
});

const ProviderLive = () =>
  Provider.effect(
    Project,
    Effect.gen(function* () {
      return {
        stables: ["projectId"],
        list: Effect.fn(function* () {
          const projects = yield* listProjects();
          return yield* Effect.forEach(
            projects,
            Effect.fn(function* (project) {
              const database = yield* defaultDatabase(project.id).pipe(
                Effect.catchTag("NotFound", () => Effect.undefined),
              );
              return attrsFrom(project, database, {});
            }),
            { concurrency: 8 },
          );
        }),
        diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
          if (isPrismaDevId(output?.projectId)) {
            return { action: "update" } as const;
          }
          if (!isInputObject(news)) return undefined;
          if (
            isResolved(news.rotateCredentialsOnAdopt) &&
            news.rotateCredentialsOnAdopt === true &&
            olds.rotateCredentialsOnAdopt !== true
          ) {
            return { action: "update" } as const;
          }
          const desiredCreateDatabase = isResolved(news.createDatabase)
            ? (news.createDatabase ?? true)
            : undefined;
          const desiredRegion = isResolved(news.region) ? (news.region ?? "us-east-1") : undefined;
          const hadDatabase =
            output?.databaseId !== undefined || (!output && (olds.createDatabase ?? true));

          // The API cannot remove a project's last/default database. Moving
          // from a database-bearing project to `createDatabase: false`
          // therefore requires replacing the project itself.
          if (desiredCreateDatabase === false && hadDatabase) {
            // A replacement may coexist when its generated name changes with
            // the instance id, or when this update also changes the explicit
            // name. A stable explicit name collides with the old generation
            // and must be removed before creating the new project.
            const deleteFirst = isResolved(news.name)
              ? news.name !== undefined && (!output || news.name === output.projectName)
              : true;
            return { action: "replace", deleteFirst } as const;
          }

          // Adding a missing default database and replacing only that database
          // for a region change are both supported in-place. Preserve the
          // project (and its apps, repository link, environment, and IDs).
          if (
            desiredCreateDatabase === true &&
            output?.databaseId !== undefined &&
            desiredRegion !== undefined &&
            output.defaultRegion !== desiredRegion
          ) {
            return yield* new ProjectInvalidProps({
              message: `Cannot safely change Prisma project '${output.projectName}' default database region from '${output.defaultRegion ?? "unknown"}' to '${desiredRegion}' in place. The Management API would create an empty default database and leave the data-bearing database to be deleted. Create a replacement project and perform an explicit data migration/cutover instead.`,
            });
          }
          if (
            desiredCreateDatabase === true &&
            (output?.databaseId === undefined || (olds.createDatabase ?? true) === false)
          ) {
            return { action: "update" } as const;
          }
          const updateProps = {
            name: news.name,
            settings: news.settings,
          };
          if (!isResolved(updateProps)) return undefined;
          const resolvedUpdateProps = updateProps as Pick<ProjectProps, "name" | "settings">;
          const nextName = yield* createName(id, resolvedUpdateProps.name);
          const oldName = output?.projectName ?? (yield* createName(id, olds.name));
          if (
            nextName !== oldName ||
            // Settings are write-only in the Management API project
            // response. Re-apply an explicit desired value every deploy so
            // out-of-band changes converge, and write `{}` once when a
            // previously managed settings prop is removed.
            resolvedUpdateProps.settings !== undefined ||
            (olds.settings !== undefined && resolvedUpdateProps.settings === undefined)
          ) {
            return { action: "update" } as const;
          }
          return undefined;
        }),
        read: Effect.fn(function* ({ id, output, olds = {}, previous }) {
          const projectId = isPrismaDevId(output?.projectId) ? undefined : output?.projectId;
          const project = projectId
            ? yield* getProject({ id: projectId }).pipe(
                Effect.map((response) => response.data),
                Effect.catchTag("NotFound", () => Effect.undefined),
              )
            : yield* findProjectByName(yield* createName(id, olds.name));
          if (!project) return undefined;
          const database = yield* defaultDatabase(project.id).pipe(
            Effect.catchTag("NotFound", () => Effect.undefined),
          );
          const cachedSecrets = output?.databaseId === database?.id ? output : undefined;
          const attrs = attrsFrom(project, database, {
            directConnectionString: cachedSecrets?.directConnectionString,
            pooledConnectionString: cachedSecrets?.pooledConnectionString,
            accelerateConnectionString: cachedSecrets?.accelerateConnectionString,
            host: cachedSecrets?.host,
            user: cachedSecrets?.user,
            password: cachedSecrets?.password,
          });
          // An omitted name is derived from this exact PlanScope instance ID.
          // Finding it proves this is create-recovery, not a foreign natural-
          // key match. User-supplied names still require explicit adoption,
          // except for the generation a replacement is replacing.
          return projectId === undefined &&
            olds.name !== undefined &&
            project.id !== previous?.projectId
            ? Unowned(attrs)
            : attrs;
        }),
        reconcile: Effect.fn(function* ({ id, news = {}, olds, output }) {
          const name = yield* createName(id, news.name);
          const outputProjectId = isPrismaDevId(output?.projectId) ? undefined : output?.projectId;
          let project: ObservedProject | undefined = outputProjectId
            ? yield* getProject({ id: outputProjectId }).pipe(
                Effect.map((response) => response.data),
                Effect.catchTag("NotFound", () => Effect.undefined),
              )
            : news.name === undefined
              ? yield* findProjectByName(name)
              : undefined;

          let createdDatabase: ProjectDatabaseAttrs | undefined;
          let secrets: PrismaSecretConnection = {};
          let createdProject = false;
          let recoverCreateSecrets = false;
          if (!project) {
            const result = yield* createProject({
              name,
              createDatabase: news.createDatabase ?? true,
              region: news.region,
            }).pipe(
              // A replayed create would make a second project; the retry
              // policy cannot see the request, so opt out explicitly.
              Retry.none,
              Effect.map((response) => {
                const project: ObservedProject = response.data;
                return {
                  project,
                  database: response.data.database ?? undefined,
                  secrets: extractConnectionSecrets(response.data.database?.connections[0]),
                  created: true,
                  recoverSecrets: true,
                };
              }),
              Effect.catchTag("Conflict", () =>
                news.name === undefined
                  ? recoverGeneratedProjectAfterConflict(name).pipe(
                      Effect.map((project) => ({
                        project,
                        database: undefined,
                        secrets: {},
                        // The generated physical name is owned by this
                        // resource instance. Treat a conflict followed by an
                        // exact read as lost-response recovery so write-only
                        // default credentials are restored.
                        created: false,
                        recoverSecrets: true,
                      })),
                    )
                  : Effect.fail(
                      new ProjectConflict({
                        message: `Prisma project '${name}' appeared after the adoption check. Refusing to take it over; rerun with adoption enabled if it is the intended project.`,
                      }),
                    ),
              ),
            );
            project = result.project;
            createdDatabase = result.database;
            secrets = result.secrets;
            createdProject = result.created;
            recoverCreateSecrets = result.recoverSecrets;
          }
          if (!project) {
            return yield* new ProjectUnexpectedResponse({
              message: `Prisma project '${name}' could not be observed after create recovery.`,
            });
          }
          const ownedGeneratedIdentity = news.name === undefined && project.name === name;

          if (news.createDatabase === false && createdDatabase) {
            return yield* new ProjectUnexpectedResponse({
              message: `Prisma created unexpected default database '${createdDatabase.name}' (${createdDatabase.id}) for project '${project.name}' even though createDatabase was false. Refusing to persist a state the Management API cannot remove in place.`,
            });
          }

          if (news.createDatabase === false && !createdProject) {
            const existingDefault = yield* defaultDatabase(project.id).pipe(
              Effect.catchTag("NotFound", () => Effect.undefined),
            );
            if (existingDefault) {
              return yield* new ProjectConflict({
                message: `Prisma project '${project.name}' already owns default database '${existingDefault.name}' (${existingDefault.id}), which cannot be removed in place. Refusing to adopt or reconcile it as createDatabase: false; replace the Prisma.Project instead.`,
              });
            }
          }

          // Project reads do not expose settings. Whenever settings are
          // explicitly managed, write them during reconcile (including the
          // forced reconcile after adoption) instead of trusting `olds` as an
          // observation of cloud state. When the prop is removed after being
          // managed, an empty object clears the previously managed settings.
          const settingsChanged = news.settings !== undefined || olds?.settings !== undefined;
          if (project.name !== name || settingsChanged) {
            project = (yield* updateProject({
              id: project.id,
              name,
              ...(settingsChanged ? { settings: news.settings ?? {} } : {}),
            })).data;
          }
          const projectId = project.id;

          let database = createdDatabase;
          let defaultDatabaseChanged = false;
          if (news.createDatabase !== false && !database) {
            database = yield* defaultDatabase(projectId).pipe(
              Effect.catchTag("NotFound", () => Effect.undefined),
            );
          }

          if (news.createDatabase !== false) {
            const desiredRegion = news.region ?? "us-east-1";
            if (database && database.region?.id !== desiredRegion) {
              return yield* new ProjectInvalidProps({
                message: `Cannot safely change Prisma project '${name}' default database region from '${database.region?.id ?? "unknown"}' to '${desiredRegion}' in place. The Management API would create an empty default database and risk deleting the existing data-bearing database. Create a replacement project and perform an explicit data migration/cutover instead.`,
              });
            }
            if (!database) {
              defaultDatabaseChanged = true;
              const created: ObservedDatabase = yield* createProjectDatabase({
                projectId,
                region: desiredRegion,
                isDefault: true,
              }).pipe(
                Retry.none,
                Effect.map((response) => response.data),
                Effect.catchTag("Conflict", () =>
                  defaultDatabase(projectId).pipe(
                    Effect.flatMap((database) =>
                      requireDefaultDatabaseInRegion(database, name, desiredRegion),
                    ),
                  ),
                ),
              );
              database = yield* requireDefaultDatabaseInRegion(created, name, desiredRegion);
              secrets = extractConnectionSecrets(created.connections[0]);
            }
          }

          // Project.defaultRegion is derived from the current default database;
          // re-read both resources after an in-place database replacement and
          // verify the Management API actually exposes the desired region.
          if (defaultDatabaseChanged) {
            const changedDatabaseId = database?.id;
            if (changedDatabaseId === undefined) {
              return yield* new DefaultDatabaseConsistencyError({
                message: `Prisma project '${name}' did not return an identifier for its new default database.`,
              });
            }
            const observed = yield* observeDesiredDefaultDatabase(
              name,
              project.id,
              changedDatabaseId,
              news.region ?? "us-east-1",
            );
            project = observed.project;
            database = observed.database;
          }

          const persistedSecrets =
            output && database !== undefined && output.databaseId === database.id
              ? {
                  directConnectionString: output.directConnectionString,
                  pooledConnectionString: output.pooledConnectionString,
                  accelerateConnectionString: output.accelerateConnectionString,
                  host: output.host,
                  user: output.user,
                  password: output.password,
                }
              : {};
          const knownSecrets = mergeConnectionSecrets(secrets, persistedSecrets);
          let finalSecrets = knownSecrets;
          if (
            database &&
            (recoverCreateSecrets ||
              (ownedGeneratedIdentity && !hasCanonicalConnectionSecrets(knownSecrets)) ||
              defaultDatabaseChanged ||
              olds !== undefined ||
              news.rotateCredentialsOnAdopt === true)
          ) {
            const recovered = yield* recoverDatabaseConnectionSecrets(database, knownSecrets);
            database = recovered.database;
            finalSecrets = recovered.secrets;
          }

          return attrsFrom(project, database, finalSecrets);
        }),
        delete: Effect.fn(function* ({ output }) {
          if (isPrismaDevId(output.projectId)) return;
          yield* destroyProjectApps(output.projectId);
        }),
      };
    }),
  );

const ProviderLocal = () =>
  devProvider(Project, ["projectId"], ({ id, news }) => ({
    projectId: devId("project", id),
    projectName: news.name ?? id,
    workspaceId: devId("workspace", "local"),
    createdAt: DEV_TIMESTAMP,
    defaultRegion:
      news.createDatabase === false ? (news.region ?? null) : (news.region ?? "us-east-1"),
    databaseId: news.createDatabase === false ? undefined : devId("database", id),
    defaultConnectionId: news.createDatabase === false ? undefined : devId("connection", id),
    directConnectionString: undefined,
    pooledConnectionString: undefined,
    accelerateConnectionString: undefined,
    host: undefined,
    user: undefined,
    password: undefined,
  }));

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