alchemy 2.0.0-beta.61 → 2.0.0-beta.63

package/src/Planetscale/MySQL/MySQLDatabase.ts

@@ -18,6 +18,7 @@ import {
 } from "../Util.ts";
 import {
   ensureMySQLProductionBranchClusterSize,
+  observeDefaultKeyspaceReplicas,
   type MySQLClusterSize,
 } from "./MySQLClusterSize.ts";
 import { runMySQLImports, runMySQLMigrations } from "./MySQLMigrations.ts";
@@ -32,6 +33,16 @@ export interface MySQLDatabaseProps extends BaseDatabaseProps {
    */
   clusterSize: MySQLClusterSize;
 
+  /**
+   * Desired total number of replicas for the database's default keyspace.
+   * Each cluster size includes a fixed number of replicas (2 for
+   * production `PS_*` sizes); higher values add extra replicas. Changes
+   * are reconciled in place via PlanetScale's keyspace resize lifecycle —
+   * never by replacing the database.
+   * @see https://planetscale.com/docs/vitess/sharding/keyspaces
+   */
+  replicas?: number;
+
   /**
    * Whether to copy migration data to new branches and in deploy requests.
    */
@@ -67,6 +78,12 @@ export interface MySQLDatabaseProps extends BaseDatabaseProps {
  * Output attributes of a deployed MySQL PlanetScale database.
  */
 export interface MySQLDatabaseAttributes extends BaseDatabaseAttributes {
+  /**
+   * Observed total replica count of the default keyspace on the default
+   * branch, or `undefined` while the keyspace is still provisioning.
+   */
+  replicas: number | undefined;
+
   /**
    * Whether to copy migration data to new branches and in deploy requests.
    */
@@ -168,8 +185,14 @@ export const MySQLDatabaseProvider = () =>
       ) {
         return { action: "replace" } as const;
       }
-      if (news.replicas !== olds.replicas) {
-        return { action: "replace" } as const;
+      // Replicas reconcile in place via a keyspace resize — never a
+      // replacement. Diff against the observed keyspace replica count so
+      // an adopted database whose live state already matches plans no-op.
+      if (
+        news.replicas !== undefined &&
+        news.replicas !== (output?.replicas ?? olds.replicas)
+      ) {
+        return { action: "update" } as const;
       }
       if (news.migrationsDir) {
         const newHashes = yield* hashMigrations(news.migrationsDir);
@@ -203,46 +226,57 @@ export const MySQLDatabaseProvider = () =>
           database: databaseName,
         })
         .pipe(
-          Effect.flatMap((data) => {
-            if (data.kind !== "mysql") {
-              return Effect.fail(
-                new PlanetscaleConflict({
-                  message:
-                    `Planetscale database "${data.name}" has kind "${data.kind}" but this resource ` +
-                    `is a MySQLDatabase. Use Planetscale.${data.kind === "postgresql" ? "PostgresDatabase" : data.kind}() instead, ` +
-                    `or delete the existing database and retry.`,
-                }),
+          Effect.flatMap(
+            Effect.fn(function* (data) {
+              if (data.kind !== "mysql") {
+                return yield* Effect.fail(
+                  new PlanetscaleConflict({
+                    message:
+                      `Planetscale database "${data.name}" has kind "${data.kind}" but this resource ` +
+                      `is a MySQLDatabase. Use Planetscale.${data.kind === "postgresql" ? "PostgresDatabase" : data.kind}() instead, ` +
+                      `or delete the existing database and retry.`,
+                  }),
+                );
+              }
+              // Observe the default keyspace's live replica configuration
+              // so adopted databases diff against reality.
+              const replicas = yield* observeDefaultKeyspaceReplicas(
+                organization,
+                data.name,
+                data.default_branch ?? "main",
               );
-            }
-            return Effect.succeed({
-              id: data.id,
-              name: data.name,
-              organization,
-              state: data.state,
-              defaultBranch: data.default_branch ?? "main",
-              plan: data.plan ?? "hobby",
-              createdAt: data.created_at,
-              updatedAt: data.updated_at,
-              htmlUrl: data.html_url,
-              region: { slug: data.region.slug },
-              migrationsDir: output?.migrationsDir ?? olds?.migrationsDir,
-              migrationsTable: output?.migrationsTable ?? olds?.migrationsTable,
-              migrationsHashes: output?.migrationsHashes ?? {},
-              importHashes: output?.importHashes ?? {},
-              clusterSize: output?.clusterSize ?? "",
-              requireApprovalForDeploy:
-                data.require_approval_for_deploy ?? false,
-              restrictBranchRegion: data.restrict_branch_region ?? false,
-              insightsRawQueries: data.insights_raw_queries ?? false,
-              productionBranchWebConsole:
-                data.production_branch_web_console ?? false,
-              automaticMigrations: data.automatic_migrations ?? false,
-              migrationFramework: data.migration_framework ?? undefined,
-              migrationTableName: data.migration_table_name ?? undefined,
-              allowDataBranching: data.allow_data_branching ?? false,
-              allowForeignKeyConstraints: data.foreign_keys_enabled ?? false,
-            });
-          }),
+              return {
+                id: data.id,
+                name: data.name,
+                organization,
+                state: data.state,
+                defaultBranch: data.default_branch ?? "main",
+                replicas,
+                plan: data.plan ?? "hobby",
+                createdAt: data.created_at,
+                updatedAt: data.updated_at,
+                htmlUrl: data.html_url,
+                region: { slug: data.region.slug },
+                migrationsDir: output?.migrationsDir ?? olds?.migrationsDir,
+                migrationsTable:
+                  output?.migrationsTable ?? olds?.migrationsTable,
+                migrationsHashes: output?.migrationsHashes ?? {},
+                importHashes: output?.importHashes ?? {},
+                clusterSize: output?.clusterSize ?? "",
+                requireApprovalForDeploy:
+                  data.require_approval_for_deploy ?? false,
+                restrictBranchRegion: data.restrict_branch_region ?? false,
+                insightsRawQueries: data.insights_raw_queries ?? false,
+                productionBranchWebConsole:
+                  data.production_branch_web_console ?? false,
+                automaticMigrations: data.automatic_migrations ?? false,
+                migrationFramework: data.migration_framework ?? undefined,
+                migrationTableName: data.migration_table_name ?? undefined,
+                allowDataBranching: data.allow_data_branching ?? false,
+                allowForeignKeyConstraints: data.foreign_keys_enabled ?? false,
+              };
+            }),
+          ),
           Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
         );
     }),
@@ -272,13 +306,14 @@ export const MySQLDatabaseProvider = () =>
       // Ensure — if missing, create.
       if (!observed) {
         yield* session.note("Creating database...");
+        // Note: the API rejects the `replicas` param for mysql databases;
+        // replicas are converged below via the keyspace resize lifecycle.
         observed = yield* planetscale.createDatabase({
           organization,
           name: newName,
           region: news.region?.slug,
           kind: "mysql",
           cluster_size: clusterSize,
-          replicas: news.replicas,
         });
       }
 
@@ -345,13 +380,16 @@ export const MySQLDatabaseProvider = () =>
         default_branch: news.defaultBranch,
       });
 
-      // Sync cluster size on the active default branch.
+      // Sync cluster size and replicas on the active default branch —
+      // both converge in place via PlanetScale's keyspace resize
+      // lifecycle, diffed against the observed default keyspace.
       const branch = news.defaultBranch ?? updated.default_branch ?? "main";
-      yield* ensureMySQLProductionBranchClusterSize(
+      const keyspace = yield* ensureMySQLProductionBranchClusterSize(
         organization,
         updated.name,
         branch,
         news.clusterSize,
+        news.replicas,
       );
 
       const migrationTarget = {
@@ -394,6 +432,7 @@ export const MySQLDatabaseProvider = () =>
         htmlUrl: updated.html_url,
         region: { slug: updated.region.slug },
         clusterSize,
+        replicas: keyspace.replicas,
         migrationsDir: news.migrationsDir,
         migrationsTable: news.migrationsDir ? migrationsTable : undefined,
         migrationsHashes,
@@ -445,6 +484,7 @@ export const MySQLDatabaseProvider = () =>
                 migrationsHashes: {},
                 importHashes: {},
                 clusterSize: "",
+                replicas: undefined,
                 requireApprovalForDeploy:
                   data.require_approval_for_deploy ?? false,
                 restrictBranchRegion: data.restrict_branch_region ?? false,

package/src/Planetscale/MySQL/MySQLMigrations.ts

@@ -217,9 +217,10 @@ const withTemporaryMySQLPassword = <A, E, R>(
           // Already-deleted passwords are a success: nothing to clean up.
           Effect.catchTag("NotFound", () => Effect.void),
           Effect.retry({
-            schedule: Schedule.exponential("500 millis").pipe(
-              Schedule.both(Schedule.recurs(5)),
-            ),
+            schedule: Schedule.max([
+              Schedule.exponential("500 millis"),
+              Schedule.recurs(5),
+            ]),
           }),
           // Migrations succeeded; don't fail the parent over a release-step
           // hiccup. The password's TTL bounds the orphan window; log loudly

package/src/Planetscale/OAuthClient.ts

@@ -0,0 +1,307 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import crypto from "node:crypto";
+import http from "node:http";
+import { AUTH_ERROR_URL, AUTH_SUCCESS_URL } from "../Auth/AuthProvider.ts";
+
+export class OAuthError extends Data.TaggedError("OAuthError")<{
+  error: string;
+  errorDescription: string;
+}> {}
+
+export interface OAuthCredentials {
+  type: "oauth";
+  access: string;
+  refresh: string;
+  expires: number;
+  scopes: string[];
+}
+
+export interface Authorization {
+  url: string;
+  state: string;
+}
+
+/**
+ * Registered PlanetScale OAuth application credentials.
+ *
+ * Unlike Cloudflare, PlanetScale OAuth has **no public-client flow** — the
+ * token endpoint requires client authentication for every grant (PKCE is
+ * advertised in their discovery doc but does not lift that requirement), so
+ * exchanging the authorization code (and refreshing the token) requires the
+ * application's `client_secret`. There is no way to keep that secret out of
+ * a distributed CLI, so it ships here: the exposure is the same posture as a
+ * public `client_id` (a stolen refresh token is usable, exactly like
+ * Cloudflare's secret-less refresh), and it can be rotated by cutting a new
+ * release. PlanetScale's own CLI ships its OAuth `client_secret` in source
+ * the same way:
+ * https://github.com/planetscale/cli/blob/main/internal/auth/authenticator.go
+ *
+ * Registered at https://app.planetscale.com with redirect URI
+ * {@link OAUTH_REDIRECT_URI}. Scopes are configured on the application
+ * itself, not requested per-authorization. Rotate by registering a new
+ * secret and cutting a release.
+ */
+export const OAUTH_CLIENT_ID = "pscale_app_aa12e3938baebb788aac443f66e422da";
+export const OAUTH_CLIENT_SECRET =
+  "pscale_app_secret_yyZ3Q8oe99GP9_yA5wrA5er6RuN6Lz9dC66Bj1OJzpg";
+
+export const OAUTH_REDIRECT_URI = "http://localhost:9976/auth/callback";
+export const OAUTH_ENDPOINTS = {
+  // PlanetScale's own .well-known OAuth discovery doc declares this as
+  // the authorization_endpoint — NOT auth.planetscale.com/oauth/authorize
+  // (which their public docs cite). The auth.planetscale.com alias does
+  // render a consent screen but emits codes whose resulting tokens lack
+  // a `sub` claim, so the resource API at api.planetscale.com rejects
+  // them as invalid. Use the canonical endpoint.
+  authorize: "https://app.planetscale.com/oauth/authorize",
+  token: "https://auth.planetscale.com/oauth/token",
+};
+
+function generateState(length = 32): string {
+  return crypto.randomBytes(length).toString("base64url");
+}
+
+function extractCredentials(json: {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  scope: string;
+}): OAuthCredentials {
+  return {
+    type: "oauth",
+    access: json.access_token,
+    refresh: json.refresh_token,
+    expires: Date.now() + json.expires_in * 1000,
+    scopes: json.scope ? json.scope.split(" ") : [],
+  };
+}
+
+const tokenRequest = (
+  params: Record<string, string>,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  Effect.gen(function* () {
+    // PlanetScale's docs show the token endpoint with all parameters in
+    // the query string (https://planetscale.com/docs/api/reference/oauth).
+    // Their .well-known discovery doc advertises client_secret_basic /
+    // client_secret_post instead, but both behave identically to the
+    // query-string form in practice, so we follow the public docs
+    // literally.
+    const url = new URL(OAUTH_ENDPOINTS.token);
+    for (const [k, v] of Object.entries(params)) {
+      url.searchParams.set(k, v);
+    }
+
+    const res = yield* Effect.tryPromise({
+      try: () =>
+        fetch(url.toString(), {
+          method: "POST",
+          headers: { Accept: "application/json" },
+        }),
+      catch: (err) =>
+        new OAuthError({
+          error: "network_error",
+          errorDescription: `Token request failed: ${err}`,
+        }),
+    });
+
+    if (!res.ok) {
+      const json = yield* Effect.tryPromise({
+        try: () =>
+          res.json() as Promise<{ error: string; error_description: string }>,
+        catch: () =>
+          new OAuthError({
+            error: "parse_error",
+            errorDescription: `Token endpoint returned ${res.status}`,
+          }),
+      });
+      return yield* new OAuthError({
+        error: json.error,
+        errorDescription: json.error_description,
+      });
+    }
+
+    const json = yield* Effect.tryPromise({
+      try: () =>
+        res.json() as Promise<{
+          access_token: string;
+          refresh_token: string;
+          expires_in: number;
+          scope: string;
+        }>,
+      catch: () =>
+        new OAuthError({
+          error: "parse_error",
+          errorDescription: "Failed to parse token response",
+        }),
+    });
+    return extractCredentials(json);
+  });
+
+/**
+ * Generate a PlanetScale authorization URL.
+ *
+ * No `scope` parameter is sent: PlanetScale scopes are configured on the
+ * OAuth application itself, not requested per-authorization, so the
+ * consent screen shows whatever the app is registered with.
+ */
+export function authorize(): Authorization {
+  const state = generateState();
+  const url = new URL(OAUTH_ENDPOINTS.authorize);
+  url.searchParams.set("client_id", OAUTH_CLIENT_ID);
+  url.searchParams.set("redirect_uri", OAUTH_REDIRECT_URI);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("state", state);
+  return { url: url.toString(), state };
+}
+
+/**
+ * Exchange an authorization code for OAuth credentials.
+ */
+export const exchange = (
+  code: string,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  tokenRequest({
+    grant_type: "authorization_code",
+    code,
+    client_id: OAUTH_CLIENT_ID,
+    client_secret: OAUTH_CLIENT_SECRET,
+    redirect_uri: OAUTH_REDIRECT_URI,
+  });
+
+/**
+ * Refresh expired OAuth credentials.
+ */
+export const refresh = (
+  credentials: OAuthCredentials,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  tokenRequest({
+    grant_type: "refresh_token",
+    refresh_token: credentials.refresh,
+    client_id: OAUTH_CLIENT_ID,
+    client_secret: OAUTH_CLIENT_SECRET,
+  });
+
+/**
+ * Start a local HTTP server to listen for the OAuth callback, exchange
+ * the authorization code, and return the credentials.
+ *
+ * Times out after 5 minutes.
+ */
+export const callback = (
+  authorization: Authorization,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  Effect.tryPromise({
+    try: () => callbackPromise(authorization),
+    catch: (err) => {
+      if (err instanceof OAuthError) return err;
+      return new OAuthError({
+        error: "callback_error",
+        errorDescription: `OAuth callback failed: ${err}`,
+      });
+    },
+  });
+
+function callbackPromise(
+  authorization: Authorization,
+): Promise<OAuthCredentials> {
+  const { pathname, port } = new URL(OAUTH_REDIRECT_URI);
+
+  return new Promise<OAuthCredentials>((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+
+      if (url.pathname !== pathname) {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return;
+      }
+
+      const error = url.searchParams.get("error");
+      const errorDescription = url.searchParams.get("error_description");
+      if (error) {
+        res.writeHead(302, { Location: AUTH_ERROR_URL });
+        res.end();
+        cleanup();
+        reject(
+          new OAuthError({
+            error,
+            errorDescription: errorDescription ?? "An unknown error occurred.",
+          }),
+        );
+        return;
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!code || !state) {
+        res.writeHead(302, { Location: AUTH_ERROR_URL });
+        res.end();
+        cleanup();
+        reject(
+          new OAuthError({
+            error: "invalid_request",
+            errorDescription: "Missing code or state",
+          }),
+        );
+        return;
+      }
+
+      if (state !== authorization.state) {
+        res.writeHead(302, { Location: AUTH_ERROR_URL });
+        res.end();
+        cleanup();
+        reject(
+          new OAuthError({
+            error: "invalid_request",
+            errorDescription: "Invalid state",
+          }),
+        );
+        return;
+      }
+
+      try {
+        const credentials = await Effect.runPromise(exchange(code));
+        res.writeHead(302, { Location: AUTH_SUCCESS_URL });
+        res.end();
+        cleanup();
+        resolve(credentials);
+      } catch (err) {
+        res.writeHead(302, { Location: AUTH_ERROR_URL });
+        res.end();
+        cleanup();
+        reject(err);
+      }
+    });
+
+    const timeout = setTimeout(
+      () => {
+        cleanup();
+        reject(
+          new OAuthError({
+            error: "timeout",
+            errorDescription: "The authorization process timed out.",
+          }),
+        );
+      },
+      5 * 60 * 1000,
+    );
+
+    function cleanup() {
+      clearTimeout(timeout);
+      server.close();
+    }
+
+    server.on("error", (err) => {
+      cleanup();
+      reject(
+        new OAuthError({
+          error: "server_error",
+          errorDescription: `Failed to start callback server: ${err.message}`,
+        }),
+      );
+    });
+
+    server.listen(Number(port));
+  });
+}

package/src/Planetscale/Postgres/PostgresClusterSize.ts

@@ -60,9 +60,10 @@ export function toPostgresClusterSku(input: {
  * routinely take longer than the default 10-minute polling budget, so
  * give change requests a 60-minute budget (720 × 5s).
  */
-const changeRequestSchedule = Schedule.spaced("5 seconds").pipe(
-  Schedule.both(Schedule.recurs(720)),
-);
+const changeRequestSchedule = Schedule.max([
+  Schedule.spaced("5 seconds"),
+  Schedule.recurs(720),
+]);
 
 /**
  * Polls branch change requests until all visible changes are in a terminal

package/src/Planetscale/Postgres/PostgresMigrations.ts

@@ -203,9 +203,10 @@ const withTemporaryPostgresRole = <A, E, R>(
           // Already-deleted roles are a success: nothing to clean up.
           Effect.catchTag("NotFound", () => Effect.void),
           Effect.retry({
-            schedule: Schedule.exponential("500 millis").pipe(
-              Schedule.both(Schedule.recurs(5)),
-            ),
+            schedule: Schedule.max([
+              Schedule.exponential("500 millis"),
+              Schedule.recurs(5),
+            ]),
           }),
           // Migrations succeeded; don't fail the parent over a release-step
           // hiccup. The role's TTL bounds the orphan window; log loudly so

package/src/Planetscale/Util.ts

@@ -35,9 +35,10 @@ export class PlanetscaleConflict extends Data.TaggedError(
  * database creates routinely run 10-12 minutes, so a 10-minute budget
  * regularly false-positives as "stuck".
  */
-const defaultSchedule = Schedule.spaced("5 seconds").pipe(
-  Schedule.both(Schedule.recurs(360)),
-);
+const defaultSchedule = Schedule.max([
+  Schedule.spaced("5 seconds"),
+  Schedule.recurs(360),
+]);
 
 /**
  * Generic polling helper that retries until `predicate(value)` returns true