sailfork / t3code-github / .repos/ alchemy-effect/ packages/ planetscale/ src/ Postgres/ PostgresDefaultRole.ts

import * as planetscale from "@distilled.cloud/planetscale";
import { Credentials } from "@distilled.cloud/planetscale/Credentials";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { PlanetscaleConflict, waitForBranchReady } from "../Util.ts";
import type { PostgresBranch } from "./PostgresBranch.ts";
import type { PostgresDatabase } from "./PostgresDatabase.ts";
import type { InheritedRole } from "./PostgresRole.ts";

/**
 * Properties for creating or updating the default PlanetScale PostgreSQL
 * role for a branch.
 *
 * Default roles are only meant for PostgreSQL databases. For MySQL,
 * use {@link MySQLPassword} instead.
 */
export interface PostgresDefaultRoleProps {
  /**
   * PostgreSQL database — string name or {@link PostgresDatabase} resource.
   */
  database: string | PostgresDatabase;

  /**
   * Branch — string name or {@link PostgresBranch} resource.
   * @default "main"
   */
  branch?: string | PostgresBranch;

  /**
   * Whether to force-reset the default role if it already exists.
   * Adopting an existing default role is not supported because the
   * password is only returned at create time.
   * @default false
   */
  forceReset?: boolean;
}

/**
 * Output attributes of a deployed PlanetScale default role.
 */
export interface PostgresDefaultRoleAttributes {
  /** Unique identifier for the role (stable). */
  id: string;
  /** The Postgres role name. */
  name: string;
  /** ISO 8601 timestamp at which the role expires. */
  expiresAt: string | null;
  /** Hostname for the database connection. */
  host: string;
  /** Username for database authentication. */
  username: string;
  /** Password for database authentication (Redacted). */
  password: Redacted.Redacted<string>;
  /** TTL in seconds (if set). */
  ttl: number | null;
  /** The database name. */
  databaseName: string;
  /** Direct connection URL for the database (Redacted). */
  connectionUrl: Redacted.Redacted<string>;
  /** Pooled connection URL via PSBouncer (Redacted). */
  connectionUrlPooled: Redacted.Redacted<string>;
  /**
   * Private connection host or DNS zone for this branch, supplied by
   * PlanetScale. GCP Private Service Connect requires an endpoint name before
   * this DNS zone.
   */
  privateHost: string;
  /** Service name for this branch supplied by PlanetScale to establish a private connection. */
  privateConnectionServiceName: string;
  /** Inherited roles. */
  inheritedRoles: InheritedRole[];
  /** Resolved organization slug. */
  organization: string;
  /** Resolved database name (for delete). */
  database: string;
  /** Resolved branch name. */
  branch: string;
}

/**
 * The default PlanetScale PostgreSQL role for a database branch.
 *
 * ### Creating a Default Role
 * **Example:** Default role on the main branch
 * ```typescript
 * const db = yield* Planetscale.PostgresDatabase("MyDb", {
 *   clusterSize: "PS_10",
 * });
 * const defaultRole = yield* Planetscale.PostgresDefaultRole("MainRole", {
 *   database: db,
 *   forceReset: true,
 * });
 * ```
 */
export type PostgresDefaultRole = Resource<
  "Planetscale.PostgresDefaultRole",
  PostgresDefaultRoleProps,
  PostgresDefaultRoleAttributes,
  never,
  Providers
>;

/** @resource */
export const PostgresDefaultRole = Resource<PostgresDefaultRole>("Planetscale.PostgresDefaultRole");

export const PostgresDefaultRoleProvider = () =>
  Provider.succeed(PostgresDefaultRole, {
    stables: ["id"],
    diff: Effect.fn(function* ({ news, olds = {} }) {
      if (!isResolved(news)) return undefined;

      const newDb = resolveDatabaseName(news.database);
      const oldDb = olds.database ? resolveDatabaseName(olds.database) : undefined;
      if (oldDb && newDb !== oldDb) {
        return { action: "replace" } as const;
      }
      const newBranch = resolveBranchName(news.branch);
      const oldBranch = resolveBranchName(olds.branch);
      if (newBranch !== oldBranch) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output }) {
      // Adoption (no cached output) is impossible without destroying
      // existing credentials. The engine routes adoption through
      // `read`, but here we always defer to reconcile so the
      // `forceReset` props flag remains the user-facing switch for
      // takeover. Returning undefined makes the engine treat the
      // resource as greenfield; reconcile then observes live state
      // and either fails (no forceReset) or resets (forceReset).
      if (!output) return undefined;

      // Refresh — verify the default role still exists and re-emit
      // the persisted output (with plaintext intact). If gone,
      // return undefined so the engine routes through reconcile,
      // which will recreate via reset.
      return yield* planetscale
        .getDefaultRole({
          organization: output.organization,
          database: output.database,
          branch: output.branch,
        })
        .pipe(
          Effect.map((role) => ({
            ...output,
            privateHost: role.private_access_host_url,
            privateConnectionServiceName: role.private_connection_service_name,
          })),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { organization: envOrg } = yield* yield* Credentials;
      const organization = resolveDatabaseOrg(news.database) ?? envOrg;
      const databaseName = resolveDatabaseName(news.database);
      const branchName = resolveBranchName(news.branch);

      // 1. Observe — the default role is the singleton for this
      //    (database, branch); we key on those rather than an id.
      //    Observation runs unconditionally so the adoption guard
      //    below fires on greenfield deploys against branches that
      //    already have a default role (otherwise we would silently
      //    `resetDefault` and destroy their credentials).
      const observed = yield* planetscale
        .getDefaultRole({
          organization,
          database: databaseName,
          branch: branchName,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

      // 2. Sync (no-op) — we own the role and it still exists in the
      //    cloud. Default roles have nothing mutable in place: their
      //    plaintext password isn't retrievable, so we retain the cached
      //    credentials while refreshing the private connection details.
      //    diff() forces a replace when database/branch change.
      if (output && observed) {
        return {
          ...output,
          privateHost: observed.private_access_host_url,
          privateConnectionServiceName: observed.private_connection_service_name,
        };
      }

      // 3. Adoption guard — observed exists but we have no prior
      //    output (greenfield against a pre-existing default role).
      //    Taking over requires a reset (which destroys the existing
      //    password), so gate on an explicit forceReset opt-in.
      if (observed && !news.forceReset) {
        return yield* new PlanetscaleConflict({
          message: `Default role already exists for database "${databaseName}" branch "${branchName}". Use forceReset: true to reset.`,
        });
      }

      // 4. Ensure — (re)create the default role. This branch runs
      //    for greenfield (no output, no observed), drift recovery
      //    (output cached but cloud state gone), and authorised
      //    adoption (observed present + forceReset).
      yield* waitForBranchReady(organization, databaseName, branchName);
      const data = yield* planetscale.resetDefaultRole({
        organization,
        database: databaseName,
        branch: branchName,
      });

      if (!data.password) {
        return yield* Effect.die(`Planetscale did not return a password for Default Role.`);
      }

      const password = Redacted.isRedacted(data.password)
        ? Redacted.value(data.password)
        : data.password;

      const connectionUrl = `postgresql://${data.username}:${password}@${data.access_host_url}:5432/${data.database_name}?sslmode=verify-full`;
      const connectionUrlPooled = `postgresql://${data.username}:${password}@${data.access_host_url}:6432/${data.database_name}?sslmode=verify-full`;

      return {
        id: data.id,
        name: data.name,
        expiresAt: data.expires_at,
        host: data.access_host_url,
        username: data.username,
        password: Redacted.make(password),
        ttl: data.ttl,
        databaseName: data.database_name,
        connectionUrl: Redacted.make(connectionUrl),
        connectionUrlPooled: Redacted.make(connectionUrlPooled),
        privateHost: data.private_access_host_url,
        privateConnectionServiceName: data.private_connection_service_name,
        inheritedRoles: data.inherited_roles as InheritedRole[],
        organization,
        database: databaseName,
        branch: branchName,
      } satisfies PostgresDefaultRoleAttributes;
    }),

    delete: Effect.fn(function* ({ output }) {
      // No delete endpoint — reset to invalidate existing credentials.
      yield* planetscale
        .resetDefaultRole({
          organization: output.organization,
          database: output.database,
          branch: output.branch,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),

    list: Effect.fn(function* () {
      const { organization } = yield* yield* Credentials;

      const roles = yield* planetscale.listDatabases.pages({ organization }).pipe(
        Stream.map((page) => page.data.filter((db) => db.kind === "postgresql")),
        Stream.flattenIterable,
        Stream.flatMap(
          (db) =>
            planetscale.listBranches.pages({ organization, database: db.name }).pipe(
              Stream.map((page) => page.data.filter((branch) => branch.kind === "postgresql")),
              Stream.flattenIterable,
              Stream.catchTag("NotFound", () =>
                Stream.succeed({ name: db.default_branch ?? "main" }),
              ),
              Stream.flatMap(
                (branch) =>
                  planetscale.listRoles
                    .pages({
                      organization,
                      database: db.name,
                      branch: branch.name,
                    })
                    .pipe(
                      Stream.map((page) =>
                        page.data
                          .filter((role) => role.default)
                          .map(
                            (role) =>
                              ({
                                id: role.id,
                                name: role.name,
                                expiresAt: role.expires_at,
                                host: role.access_host_url,
                                username: role.username,
                                password: Redacted.make(""),
                                ttl: role.ttl,
                                databaseName: role.database_name,
                                connectionUrl: Redacted.make(""),
                                connectionUrlPooled: Redacted.make(""),
                                privateHost: role.private_access_host_url,
                                privateConnectionServiceName: role.private_connection_service_name,
                                inheritedRoles: role.inherited_roles as InheritedRole[],
                                organization,
                                database: db.name,
                                branch: branch.name,
                              }) satisfies PostgresDefaultRoleAttributes as PostgresDefaultRoleAttributes,
                          ),
                      ),
                      Stream.flattenIterable,
                      Stream.catchTags({
                        NotFound: () => Stream.empty,
                        Forbidden: () => Stream.empty,
                      }),
                    ),
                { concurrency: 10 },
              ),
            ),
          { concurrency: 10 },
        ),
        Stream.runCollect,
      );

      return Array.from(roles);
    }),
  });

// Structural shapes for runtime-resolved Resource references — see
// notes in Password.ts.
type DatabaseRef = string | { name: string; organization?: string };
type BranchRef = string | { name: string };

const resolveDatabaseName = (database: string | PostgresDatabase): string => {
  const ref = database as unknown as DatabaseRef;
  return typeof ref === "string" ? ref : ref.name;
};

const resolveDatabaseOrg = (database: string | PostgresDatabase): string | undefined => {
  const ref = database as unknown as DatabaseRef;
  return typeof ref === "string" ? undefined : ref.organization;
};

const resolveBranchName = (branch: string | PostgresBranch | undefined): string => {
  const ref = branch as unknown as BranchRef | undefined;
  return !ref ? "main" : typeof ref === "string" ? ref : ref.name;
};