sailfork / t3code-github / .repos/ alchemy-effect/ packages/ planetscale/ src/ MySQL/ MySQLPassword.ts

import * as planetscale from "@distilled.cloud/planetscale";
import { Credentials } from "@distilled.cloud/planetscale/Credentials";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
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 type { MySQLBranch } from "./MySQLBranch.ts";
import type { MySQLDatabase } from "./MySQLDatabase.ts";
import type { MySQLOrigin } from "./MySQLOrigin.ts";

/**
 * Properties for creating or updating a PlanetScale MySQL password.
 *
 * Passwords are only meant for MySQL databases. For PostgreSQL,
 * use {@link PostgresRole} instead.
 */
export interface MySQLPasswordProps {
  /**
   * Password name. If omitted, a unique name is generated from
   * `${app}-${stage}-${id}`.
   */
  name?: string;

  /**
   * MySQL database — string name or {@link MySQLDatabase} resource.
   */
  database: string | MySQLDatabase;

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

  /**
   * The MySQL role granted to the password.
   */
  role: "reader" | "writer" | "admin" | "readwriter";

  /**
   * Whether the password is for a read replica.
   */
  replica?: boolean;

  /**
   * Time to live (seconds). The password is invalidated after this period.
   */
  ttl?: number;

  /**
   * IP CIDR ranges allowed to use this password.
   */
  cidrs?: string[];
}

/**
 * Output attributes of a deployed PlanetScale password.
 */
export interface MySQLPasswordAttributes {
  /** Unique identifier for the password (stable). */
  id: string;
  /** Password name. If omitted, a unique name is generated from `${app}-${stage}-${id}`. */
  name: string;
  /** ISO 8601 timestamp at which the password expires. `null` if no TTL. */
  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>;
  /** Parsed connection components ready to feed into Cloudflare Hyperdrive. */
  origin: MySQLOrigin;
  /** Resolved organization slug. */
  organization: string;
  /** Resolved database name. */
  database: string;
  /** Resolved branch name. */
  branch: string;
  /** The role granted. */
  role: "reader" | "writer" | "admin" | "readwriter" | (string & {});
  /** Whether this password is for a read replica. */
  replica: boolean | undefined;
  /** TTL in seconds (if set). */
  ttl: number | undefined;
  /** IP CIDR ranges allowed to use this password. */
  cidrs: readonly string[] | undefined;
}

/**
 * A PlanetScale password for accessing a MySQL database branch.
 *
 * For PostgreSQL databases, use {@link PostgresRole} instead.
 *
 * ### Creating a Password
 * **Example:** Reader password
 * ```typescript
 * const reader = yield* Planetscale.MySQLPassword("AppReader", {
 *   database: "my-db",
 *   role: "reader",
 * });
 * ```
 *
 * **Example:** Writer password with TTL
 * ```typescript
 * const writer = yield* Planetscale.MySQLPassword("AppWriter", {
 *   database: "my-db",
 *   role: "writer",
 *   ttl: 86400,
 * });
 * ```
 *
 * **Example:** Admin password with IP allowlist
 * ```typescript
 * const admin = yield* Planetscale.MySQLPassword("Admin", {
 *   database: "my-db",
 *   role: "admin",
 *   cidrs: ["203.0.113.0/24", "198.51.100.0/24"],
 * });
 * ```
 */
export type MySQLPassword = Resource<
  "Planetscale.MySQLPassword",
  MySQLPasswordProps,
  MySQLPasswordAttributes,
  never,
  Providers
>;

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

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

      // Replace on any immutable-in-place change; engine falls through
      // to reconcile for everything else (which authoritatively diffs
      // against observed cloud state).
      if (news.role !== olds.role) return { action: "replace" } as const;
      if (news.replica !== olds.replica) {
        return { action: "replace" } as const;
      }
      if (news.ttl !== olds.ttl) return { action: "replace" } as const;

      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: the PlanetScale API
      // never re-issues plaintext, so even if we found a matching live
      // password by listing+name we couldn't deliver the `password`
      // attribute. Fall through to greenfield create in `reconcile`.
      if (!output) return undefined;

      // Refresh — verify the cached password still exists and
      // re-emit the persisted output (with plaintext intact).
      // If it's gone, return undefined so the engine routes to
      // reconcile, which will surface the unrecoverable-rotation
      // condition explicitly.
      return yield* planetscale
        .getPassword({
          organization: output.organization,
          database: output.database,
          branch: output.branch,
          id: output.id,
        })
        .pipe(
          Effect.map((password) =>
            buildAttributes(password, output.password, {
              organization: output.organization,
              database: output.database,
              branch: output.branch,
            }),
          ),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const newName = yield* createPasswordName(id, news.name);

      // Identifiers — stable across update (diff replaces on
      // database/branch changes), so we can pull from `output` first
      // and fall back to `news` for greenfield.
      const { organization: envOrg } = yield* yield* Credentials;
      const organization = output?.organization ?? resolveDatabaseOrg(news.database) ?? envOrg;
      const databaseName = output?.database ?? resolveDatabaseName(news.database);
      const branchName = output?.branch ?? resolveBranchName(news.branch);

      // 1. Observe — read live state. The PlanetScale API has no
      //    "lookup by name" path (names aren't unique within a branch)
      //    so the only way to find the live password is by id. Without
      //    a cached output we cannot observe and fall straight through
      //    to ensure (greenfield create).
      const observed = output
        ? yield* planetscale
            .getPassword({
              organization,
              database: databaseName,
              branch: branchName,
              id: output.id,
            })
            .pipe(Effect.catchTag("NotFound", () => Effect.undefined))
        : undefined;

      // 2. Ensure — create the password if it doesn't exist live.
      //    This single branch covers greenfield (no output) AND the
      //    out-of-band-deletion case (output cached but cloud lost it).
      //    The latter is structurally a rotation: the new password
      //    has a fresh id/host/username/plaintext that propagate
      //    downstream through the dependency graph. There is no path
      //    to recover the original plaintext, so recreating is the
      //    only way to converge.
      let live: planetscale.GetPasswordOutput;
      let plaintext: Redacted.Redacted<string>;
      if (observed) {
        live = observed;
        // We re-use the cached plaintext: the API never re-issues it.
        plaintext = output!.password;
      } else {
        const created = yield* planetscale.createPassword({
          organization,
          database: databaseName,
          branch: branchName,
          name: newName,
          role: news.role,
          replica: news.replica,
          ttl: news.ttl,
          cidrs: news.cidrs,
        });
        plaintext = created.plain_text;
        live = created;
      }

      // 3. Sync — diff observed cloud state against desired and patch
      //    only what changed. Only `name` and `cidrs` are mutable in
      //    place; everything else triggers a replace via diff().
      //    Skip the API entirely when there's no delta.
      const wantsRename = newName !== live.name;
      const observedCidrs = normalizeCidrs(live.cidrs);
      const desiredCidrs = normalizeCidrs(news.cidrs);
      const wantsCidrs = !deepEqual(desiredCidrs, observedCidrs);

      if (wantsRename || wantsCidrs) {
        live = yield* planetscale.updatePassword({
          organization,
          database: databaseName,
          branch: branchName,
          id: live.id,
          name: wantsRename ? newName : undefined,
          cidrs: wantsCidrs ? news.cidrs : undefined,
        });
      }

      // 4. Return — fresh attrs sourced from observed cloud state,
      //    re-using cached plaintext when we didn't just create.
      return buildAttributes(live, plaintext, {
        organization,
        database: databaseName,
        branch: branchName,
      });
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* planetscale
        .deletePassword({
          organization: output.organization,
          database: output.database,
          branch: output.branch,
          id: output.id,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),

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

      const databases = yield* planetscale.listDatabases.pages({ organization }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) => page.data.filter((db) => db.kind === "mysql")),
        ),
      );

      const rows = yield* Effect.forEach(
        databases,
        (db) =>
          planetscale.listBranches.pages({ organization, database: db.name }).pipe(
            Stream.runCollect,
            Effect.map((branchPages) =>
              Array.from(branchPages).flatMap((page) =>
                page.data.filter((branch) => branch.kind === "mysql"),
              ),
            ),
            Effect.catchTag("NotFound", () =>
              Effect.succeed([{ name: db.default_branch ?? "main" }]),
            ),
            Effect.flatMap((branches) =>
              Effect.forEach(
                branches,
                (branch) =>
                  planetscale.listPasswords
                    .pages({
                      organization,
                      database: db.name,
                      branch: branch.name,
                    })
                    .pipe(
                      Stream.runCollect,
                      Effect.map((passwordPages): MySQLPasswordAttributes[] =>
                        Array.from(passwordPages).flatMap((page) =>
                          page.data.map((password) =>
                            buildAttributes(password, Redacted.make(""), {
                              organization,
                              database: db.name,
                              branch: branch.name,
                            }),
                          ),
                        ),
                      ),
                      Effect.catchTag("NotFound", () =>
                        Effect.succeed([] as MySQLPasswordAttributes[]),
                      ),
                    ),
                { concurrency: 10 },
              ).pipe(Effect.map((perBranch) => perBranch.flat())),
            ),
          ),
        { concurrency: 10 },
      );

      return rows.flat();
    }),
  });

// At runtime, Resource references in props are resolved to their full
// attributes — so `news.database` (when a Database resource was passed)
// is `{ name: string; organization: string; ... }` rather than the
// statically-typed Resource (whose attributes are `Output<...>`). We
// cast through structural shapes here.
type DatabaseRef = string | { name: string; organization?: string };
type BranchRef = string | { name: string };

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

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

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

const createPasswordName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 63 }));
  });

// Normalize the API's nullable `cidrs` field into the `string[] | undefined`
// shape we persist so downstream comparisons line up regardless of the
// API returning `null` vs `[]` vs an actual list.
const normalizeCidrs = (
  cidrs: readonly string[] | null | undefined,
): readonly string[] | undefined => (cidrs == null || cidrs.length === 0 ? undefined : cidrs);

const buildAttributes = (
  password: {
    id: string;
    name: string;
    expires_at: string | null;
    access_host_url: string;
    username: string;
    role: "reader" | "writer" | "admin" | "readwriter" | (string & {});
    replica: boolean;
    ttl_seconds: number | null;
    cidrs: readonly string[] | null;
  },
  plaintext: Redacted.Redacted<string>,
  context: {
    organization: string;
    database: string;
    branch: string;
  },
): MySQLPasswordAttributes => ({
  id: password.id,
  name: password.name,
  expiresAt: password.expires_at,
  host: password.access_host_url,
  username: password.username,
  password: plaintext,
  origin: {
    scheme: "mysql",
    host: password.access_host_url,
    port: 3306,
    database: context.database,
    user: password.username,
    password: plaintext,
  },
  organization: context.organization,
  database: context.database,
  branch: context.branch,
  role: password.role,
  replica: password.replica,
  ttl: password.ttl_seconds ?? undefined,
  cidrs: normalizeCidrs(password.cidrs),
});