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

import * as ps from "@distilled.cloud/planetscale";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { PlanetscaleConflict, pollUntil } from "../Util.ts";

/**
 * Available PlanetScale MySQL (Vitess) cluster sizes.
 *
 * `PS_*` sizes are backed by network-attached storage (NAS) and can be
 * specified either as the short size (`"PS_10"`) or the API SKU
 * (`"PS_10_AWS_X86"`)
 *
 * @see https://planetscale.com/docs/concepts/planetscale-skus
 */
export type MySQLClusterSize =
  | "PS_DEV"
  | "PS_5"
  | "PS_10"
  | "PS_20"
  | "PS_40"
  | "PS_80"
  | "PS_160"
  | "PS_320"
  | "PS_400"
  | "PS_640"
  | "PS_700"
  | "PS_900"
  | "PS_1280"
  | "PS_1400"
  | "PS_1800"
  | "PS_2100"
  | "PS_2560"
  | "PS_2700"
  | "PS_2800"
  | (string & {});

/**
 * Polls keyspaces in a branch until the named keyspace reports
 * `resizing === false` (i.e. any in-flight resize has completed).
 */
export const waitForKeyspaceReady = Effect.fn(function* (
  organization: string,
  database: string,
  branch: string,
  keyspace: string,
) {
  yield* pollUntil(
    `keyspace "${keyspace}" not resizing`,
    ps.listKeyspaces({ organization, database, branch }),
    (page) => {
      const ks = page.data.find((x) => x.name === keyspace);
      // If keyspace is missing, treat as ready (caller will re-check)
      return ks ? !ks.resizing : true;
    },
  );
});

/**
 * Observes the default keyspace of a branch. The default keyspace usually
 * shares the database's name, but a renamed database keeps its original
 * keyspace name, so prefer the `default` flag and fall back to name
 * matching.
 */
const observeDefaultKeyspace = Effect.fn(function* (
  organization: string,
  database: string,
  branch: string,
) {
  const keyspaces = yield* ps.listKeyspaces({
    organization,
    database,
    branch,
    page: 1,
    per_page: 100,
  });
  return keyspaces.data.find((x) => x.default) ?? keyspaces.data.find((x) => x.name === database);
});

/**
 * Observes the total replica count of a branch's default keyspace, or
 * `undefined` when the branch or keyspace does not exist (yet).
 */
export const observeDefaultKeyspaceReplicas = Effect.fn(function* (
  organization: string,
  database: string,
  branch: string,
) {
  return yield* observeDefaultKeyspace(organization, database, branch).pipe(
    Effect.map((keyspace) => keyspace?.replicas),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );
});

/**
 * Ensures the default keyspace of a MySQL production branch has the
 * expected cluster size and (optionally) total replica count, driving
 * PlanetScale's in-place keyspace resize lifecycle when it doesn't.
 * Cluster sizes can only be configured on production branches. Returns
 * the final observed keyspace.
 */
export const ensureMySQLProductionBranchClusterSize = Effect.fn(function* (
  organization: string,
  database: string,
  branch: string,
  expectedClusterSize: MySQLClusterSize,
  expectedReplicas?: number,
) {
  let keyspace = yield* observeDefaultKeyspace(organization, database, branch);
  if (!keyspace) {
    return yield* Effect.die(`No default keyspace found for branch ${branch}`);
  }

  yield* waitForKeyspaceReady(organization, database, branch, keyspace.name);

  if (keyspace.cluster_name !== expectedClusterSize) {
    yield* ps.updateBranchClusterConfig({
      organization,
      database,
      branch,
      cluster_size: expectedClusterSize,
    });
    yield* waitForKeyspaceReady(organization, database, branch, keyspace.name);
    // Re-observe so the replica sync below diffs against the post-resize
    // keyspace state.
    keyspace = (yield* observeDefaultKeyspace(organization, database, branch)) ?? keyspace;
  }

  // Sync replicas — MySQL databases cannot configure replicas at
  // creation time (the API rejects the `replicas` param for mysql), so
  // the desired total replica count is converged in place via a keyspace
  // resize request.
  if (expectedReplicas !== undefined && keyspace.replicas !== expectedReplicas) {
    // Each cluster size includes a fixed number of replicas (2 for
    // production PS_* sizes); the resize API only accepts the count of
    // additional replicas beyond that.
    const includedReplicas = keyspace.replicas - keyspace.extra_replicas;
    const extraReplicas = expectedReplicas - includedReplicas;
    if (extraReplicas < 0) {
      return yield* new PlanetscaleConflict({
        message:
          `Cannot set replicas to ${expectedReplicas} on keyspace "${keyspace.name}": ` +
          `cluster size ${keyspace.cluster_name} always includes ${includedReplicas} replicas. ` +
          `Set replicas to ${includedReplicas} or more (or omit it).`,
      });
    }

    const resize = yield* ps
      .updateKeyspaceResizeRequest({
        organization,
        database,
        branch,
        keyspace: keyspace.name,
        extra_replicas: extraReplicas,
      })
      .pipe(
        // A prior resize (e.g. the cluster-size change above) can still
        // be finalizing after the keyspace reports `resizing: false`;
        // PlanetScale rejects new resize requests during that window.
        Effect.retry({
          while: (e): boolean =>
            e._tag === "UnprocessableEntity" && e.message.includes("resize in progress"),
          schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(120)]),
        }),
      );

    yield* pollUntil(
      `keyspace "${keyspace.name}" resize completed`,
      ps.listKeyspaceResizeRequests({
        organization,
        database,
        branch,
        keyspace: keyspace.name,
      }),
      (page) => {
        const request = page.data.find((r) => r.id === resize.id);
        // If the request is missing, treat as settled (caller re-observes).
        return request ? request.state === "completed" : true;
      },
    );

    keyspace = (yield* observeDefaultKeyspace(organization, database, branch)) ?? keyspace;
  }

  return keyspace;
});