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

package/src/Planetscale/AuthProvider.ts

@@ -1,7 +1,13 @@
+import * as PsCredentialsModule from "@distilled.cloud/planetscale/Credentials";
+import { listOrganizations } from "@distilled.cloud/planetscale/Operations";
 import * as Console from "effect/Console";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as Match from "effect/Match";
 import * as Redacted from "effect/Redacted";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as HttpClient from "effect/unstable/http/HttpClient";
 import {
   AuthError,
   AuthProviderLayer,
@@ -14,6 +20,7 @@ import {
   retryOnce,
 } from "../Auth/Env.ts";
 import * as Clank from "../Util/Clank.ts";
+import * as OAuthClient from "./OAuthClient.ts";
 
 /**
  * Canonical name registered in {@link AuthProviders}. Use this key to look
@@ -21,6 +28,66 @@ import * as Clank from "../Util/Clank.ts";
  */
 export const PLANETSCALE_AUTH_PROVIDER_NAME = "Planetscale";
 
+/**
+ * Provide PlanetScale `Credentials` + `HttpClient` to an Effect using a
+ * just-obtained OAuth access token. Used during configure to call
+ * org-discovery endpoints before the user has chosen an org.
+ *
+ * `organization` is required by the credential type but isn't consulted by
+ * `listOrganizations` (it's a user-scoped endpoint), so an empty string is
+ * fine here.
+ */
+const withOAuthCredentials = <A, E>(
+  accessToken: string,
+  effect: Effect.Effect<
+    A,
+    E,
+    PsCredentialsModule.Credentials | HttpClient.HttpClient
+  >,
+): Effect.Effect<A, E> =>
+  Effect.provide(
+    effect,
+    Layer.mergeAll(
+      PsCredentialsModule.fromOAuth({
+        accessToken,
+        organization: "",
+      }),
+      FetchHttpClient.layer,
+    ),
+  );
+
+/**
+ * List the organizations the OAuth user belongs to and either auto-pick
+ * (one org) or prompt the user to choose. Returns the org's URL slug
+ * (`name` field, used as `{organization}` in API paths).
+ */
+const selectOrganization = (accessToken: string) =>
+  Effect.gen(function* () {
+    const list = yield* listOrganizations;
+    const response = yield* list({});
+    const orgs = response.data;
+    if (orgs.length === 0) {
+      return yield* new AuthError({
+        message: "Planetscale: no organizations found for this credential.",
+      });
+    }
+    if (orgs.length === 1) {
+      const org = orgs[0]!;
+      yield* Clank.info(
+        `Planetscale: using organization: ${org.name} (${org.id})`,
+      );
+      return org.name;
+    }
+    return yield* Clank.select({
+      message: "Select a Planetscale organization",
+      options: orgs.map((o) => ({
+        value: o.name,
+        label: o.name,
+        hint: o.id,
+      })),
+    }).pipe(retryOnce);
+  }).pipe((e) => withOAuthCredentials(accessToken, e));
+
 const options: Array<{
   value: PlanetscaleAuthConfig["method"];
   label: string;
@@ -31,12 +98,16 @@ const options: Array<{
     label: "Environment Variables",
     hint: "PLANETSCALE_API_TOKEN_ID + PLANETSCALE_API_TOKEN + PLANETSCALE_ORGANIZATION",
   },
+  {
+    value: "oauth",
+    label: "OAuth",
+    hint: "recommended — browser-based login with automatic token refresh",
+  },
   {
     value: "stored",
     label: "Service Token",
     hint: "enter service token interactively, stored in ~/.alchemy/credentials",
   },
-  //todo(pear): add planetscale oauth
 ];
 
 /**
@@ -44,13 +115,17 @@ const options: Array<{
  * PlanetScale provider.
  *
  * - `env`: read credentials from environment variables at resolution time.
- * - `stored`: read credentials from `~/.alchemy/credentials/<profile>/planetscale-stored.json`.
- *
- * OAuth is intentionally not implemented because PlanetScale does not
- * publish a redirect-based OAuth client; service tokens are the canonical
- * credential.
+ * - `stored`: read service-token credentials from
+ *   `~/.alchemy/credentials/<profile>/planetscale-stored.json`.
+ * - `oauth`: browser-based login; the access/refresh tokens are stored at
+ *   `~/.alchemy/credentials/<profile>/planetscale-oauth.json` and refreshed
+ *   on demand. PlanetScale has no PKCE flow, so the OAuth application's
+ *   `client_secret` ships in the CLI — see {@link OAuthClient}.
  */
-export type PlanetscaleAuthConfig = { method: "env" } | { method: "stored" };
+export type PlanetscaleAuthConfig =
+  | { method: "env" }
+  | { method: "stored" }
+  | { method: "oauth"; organization: string };
 
 /**
  * apiToken credentials persisted to disk for `method: "stored"`.
@@ -65,18 +140,30 @@ export interface PlanetscaleStoredCredentials {
 
 /**
  * Resolved in-memory PlanetScale credentials returned by
- * {@link AuthProviderImpl.read}.
+ * {@link AuthProviderImpl.read}. Either a service token (`tokenId`/`token`)
+ * or an OAuth access token.
  */
-export interface PlanetscaleResolvedCredentials {
-  type: "apiToken";
-  tokenId: Redacted.Redacted<string>;
-  token: Redacted.Redacted<string>;
-  organization: string;
-  source: {
-    type: PlanetscaleAuthConfig["method"];
-    details?: string;
-  };
-}
+export type PlanetscaleResolvedCredentials =
+  | {
+      type: "apiToken";
+      tokenId: Redacted.Redacted<string>;
+      token: Redacted.Redacted<string>;
+      organization: string;
+      source: {
+        type: PlanetscaleAuthConfig["method"];
+        details?: string;
+      };
+    }
+  | {
+      type: "oauth";
+      accessToken: Redacted.Redacted<string>;
+      expires: number;
+      organization: string;
+      source: {
+        type: PlanetscaleAuthConfig["method"];
+        details?: string;
+      };
+    };
 
 /**
  * Layer that registers the PlanetScale {@link AuthProvider} into the
@@ -87,6 +174,8 @@ export interface PlanetscaleResolvedCredentials {
  * - `env`: reads `PLANETSCALE_API_TOKEN_ID`/`PLANETSCALE_API_TOKEN`/`PLANETSCALE_ORGANIZATION`.
  * - `stored`: prompts for a service token interactively and writes it to
  *   `~/.alchemy/credentials/<profile>/planetscale-stored.json`.
+ * - `oauth`: browser-based login storing access/refresh tokens at
+ *   `~/.alchemy/credentials/<profile>/planetscale-oauth.json`.
  */
 export const PlanetscaleAuth = AuthProviderLayer<
   PlanetscaleAuthConfig,
@@ -96,6 +185,54 @@ export const PlanetscaleAuth = AuthProviderLayer<
   Effect.gen(function* () {
     const store = yield* CredentialsStore;
 
+    const oauthLogin = (profileName: string) =>
+      Effect.gen(function* () {
+        const authorization = OAuthClient.authorize();
+
+        yield* Clank.info("Planetscale: opening browser for OAuth login...");
+        yield* Clank.info(authorization.url);
+        yield* Clank.openUrl(authorization.url).pipe(
+          Effect.catch(() =>
+            Clank.warn(
+              "Planetscale: could not open browser automatically. Please open the URL above manually.",
+            ),
+          ),
+        );
+        yield* Clank.info(
+          "Planetscale: waiting for authorization (up to 5 minutes)...",
+        );
+
+        const credentials = yield* OAuthClient.callback(authorization);
+        yield* store.write(profileName, "planetscale-oauth", credentials);
+        yield* Clank.success("Planetscale: OAuth credentials saved.");
+        return credentials;
+      });
+
+    const configureOAuth = Effect.fn(function* (profileName: string) {
+      const oauthCreds = yield* oauthLogin(profileName);
+
+      // Use the just-issued access token to list the user's orgs and let
+      // them pick (mirrors Cloudflare's selectAccount). Requires the
+      // `user:read_organizations` scope. If the call fails for any
+      // reason — missing scope, network, off-spec response — fall back
+      // to a manual prompt so login still completes.
+      const organization = yield* selectOrganization(oauthCreds.access).pipe(
+        Effect.catch((e) =>
+          Effect.gen(function* () {
+            yield* Clank.warn(
+              `Planetscale: could not auto-list organizations (${String(e)}). Falling back to manual entry.`,
+            );
+            return yield* Clank.text({
+              message: "Planetscale Organization (URL slug)",
+              validate: (v) => (v.length === 0 ? "Required" : undefined),
+            }).pipe(retryOnce);
+          }),
+        ),
+      );
+
+      return { method: "oauth" as const, organization };
+    });
+
     const loginStored = Effect.fn(function* (profileName: string) {
       const tokenId = yield* Clank.text({
         message: "Planetscale Service Token ID",
@@ -134,6 +271,7 @@ export const PlanetscaleAuth = AuthProviderLayer<
         Effect.flatMap((method) =>
           Match.value(method).pipe(
             Match.when("env", () => Effect.succeed({ method: "env" as const })),
+            Match.when("oauth", () => configureOAuth(profileName)),
             Match.when("stored", () => loginStored(profileName)),
             Match.exhaustive,
           ),
@@ -214,6 +352,48 @@ export const PlanetscaleAuth = AuthProviderLayer<
               ),
             ),
         ),
+        Match.when({ method: "oauth" }, (cfg) =>
+          Effect.gen(function* () {
+            const creds = yield* store.read<OAuthClient.OAuthCredentials>(
+              profileName,
+              "planetscale-oauth",
+            );
+            if (creds == null || creds.type !== "oauth") {
+              return yield* Effect.fail(
+                new AuthError({
+                  message:
+                    "Planetscale OAuth credentials not found. Run: alchemy login",
+                }),
+              );
+            }
+            // Refresh proactively if the token has expired (or is within
+            // 10s of expiring). Persist the refreshed creds so subsequent
+            // resolves don't repeat the round-trip.
+            const fresh =
+              creds.expires > Date.now() + 10_000
+                ? creds
+                : yield* OAuthClient.refresh(creds).pipe(
+                    Effect.tap((refreshed) =>
+                      store.write(profileName, "planetscale-oauth", refreshed),
+                    ),
+                    Effect.mapError(
+                      (e) =>
+                        new AuthError({
+                          message:
+                            "Planetscale OAuth refresh failed. Run: alchemy login",
+                          cause: e,
+                        }),
+                    ),
+                  );
+            return {
+              type: "oauth" as const,
+              accessToken: Redacted.make(fresh.access),
+              expires: fresh.expires,
+              organization: cfg.organization,
+              source: { type: "oauth" as const },
+            } satisfies PlanetscaleResolvedCredentials;
+          }),
+        ),
         Match.exhaustive,
       );
 
@@ -229,6 +409,17 @@ export const PlanetscaleAuth = AuthProviderLayer<
               ),
             ),
         ),
+        // PlanetScale publishes no token-revocation endpoint, so logout just
+        // drops the locally stored tokens.
+        Match.when({ method: "oauth" }, () =>
+          store
+            .delete(profileName, "planetscale-oauth")
+            .pipe(
+              Effect.andThen(
+                Clank.success("Planetscale: OAuth credentials removed."),
+              ),
+            ),
+        ),
         Match.exhaustive,
       );
 
@@ -248,6 +439,39 @@ export const PlanetscaleAuth = AuthProviderLayer<
                 ),
               ),
           ),
+          Match.when({ method: "oauth" }, (c) =>
+            Effect.gen(function* () {
+              const creds = yield* store.read<OAuthClient.OAuthCredentials>(
+                profileName,
+                "planetscale-oauth",
+              );
+
+              if (creds?.type === "oauth") {
+                yield* Clank.info(
+                  "Planetscale: refreshing OAuth credentials...",
+                );
+                yield* OAuthClient.refresh(creds).pipe(
+                  Effect.flatMap((refreshed) =>
+                    store
+                      .write(profileName, "planetscale-oauth", refreshed)
+                      .pipe(
+                        Effect.andThen(
+                          Clank.success(
+                            "Planetscale: OAuth credentials refreshed.",
+                          ),
+                        ),
+                      ),
+                  ),
+                  Effect.catchTag("OAuthError", () =>
+                    oauthLogin(profileName).pipe(Effect.asVoid),
+                  ),
+                );
+                return;
+              }
+
+              yield* oauthLogin(profileName);
+            }),
+          ),
           Match.exhaustive,
         )
         .pipe(
@@ -262,16 +486,32 @@ export const PlanetscaleAuth = AuthProviderLayer<
           const sourceStr = creds.source.details
             ? `${creds.source.type} - ${creds.source.details}`
             : creds.source.type;
-          return Effect.all([
-            Console.log(`  tokenId: ${displayRedacted(creds.token, 3)}`),
-            Console.log(`  token: ${displayRedacted(creds.token, 6)}`),
-            Console.log(`  organization: ${creds.organization}`),
-            Console.log(`  source: ${sourceStr}`),
-          ]);
+          return Match.value(creds).pipe(
+            Match.when({ type: "apiToken" }, (c) =>
+              Effect.all([
+                Console.log(`  tokenId: ${displayRedacted(c.tokenId, 3)}`),
+                Console.log(`  token: ${displayRedacted(c.token, 6)}`),
+                Console.log(`  organization: ${c.organization}`),
+                Console.log(`  source: ${sourceStr}`),
+              ]),
+            ),
+            Match.when({ type: "oauth" }, (c) => {
+              const remainingMs = c.expires - Date.now();
+              const expiresAt = new Date(c.expires).toISOString();
+              const expiresStr =
+                remainingMs <= 0
+                  ? `expired (${expiresAt})`
+                  : `in ${Duration.format(Duration.millis(remainingMs))} (${expiresAt})`;
+              return Effect.all([
+                Console.log(`  accessToken: ${displayRedacted(c.accessToken)}`),
+                Console.log(`  expires: ${expiresStr}`),
+                Console.log(`  organization: ${c.organization}`),
+                Console.log(`  source: ${sourceStr}`),
+              ]);
+            }),
+            Match.exhaustive,
+          );
         }),
-        Effect.catch((e) =>
-          Console.error(`  Failed to retrieve credentials: ${e}`),
-        ),
       );
 
     return {

package/src/Planetscale/Branch.ts

@@ -484,9 +484,10 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
           // rejected with an UnprocessableEntity. Retry until it clears.
           const retryWhileResizing = Effect.retry({
             while: isResizeInProgress,
-            schedule: Schedule.spaced("5 seconds").pipe(
-              Schedule.both(Schedule.recurs(120)),
-            ),
+            schedule: Schedule.max([
+              Schedule.spaced("5 seconds"),
+              Schedule.recurs(120),
+            ]),
           });
           current = desiredProduction
             ? yield* planetscale

package/src/Planetscale/Credentials.ts

@@ -1,5 +1,6 @@
 import { ConfigError } from "@distilled.cloud/core/errors";
 import {
+  type Config as PlanetscaleClientConfig,
   Credentials,
   DEFAULT_API_BASE_URL,
 } from "@distilled.cloud/planetscale/Credentials";
@@ -82,12 +83,23 @@ export const fromAuthProvider = () =>
         Effect.flatMap((config) =>
           auth.read(profileName, config as PlanetscaleAuthConfig),
         ),
-        Effect.map((creds) => ({
-          tokenId: creds.tokenId,
-          token: creds.token,
-          organization: creds.organization,
-          apiBaseUrl,
-        })),
+        Effect.map(
+          (creds): PlanetscaleClientConfig =>
+            creds.type === "oauth"
+              ? {
+                  type: "oauth",
+                  accessToken: creds.accessToken,
+                  organization: creds.organization,
+                  apiBaseUrl,
+                }
+              : {
+                  type: "serviceToken",
+                  tokenId: creds.tokenId,
+                  token: creds.token,
+                  organization: creds.organization,
+                  apiBaseUrl,
+                },
+        ),
         Effect.mapError(
           (e) =>
             new ConfigError({

package/src/Planetscale/Database.ts

@@ -29,7 +29,8 @@ export interface BaseDatabaseProps {
 
   /**
    * Number of replicas for the database. `0` for non-HA, `2+` for HA.
-   * Create-only.
+   * Create-only for PostgreSQL databases; MySQL databases reconcile
+   * changes in place ({@link MySQLDatabaseProps.replicas}).
    */
   replicas?: number;
 

package/src/Planetscale/MySQL/MySQLClusterSize.ts

@@ -1,6 +1,7 @@
 import * as ops from "@distilled.cloud/planetscale/Operations";
 import * as Effect from "effect/Effect";
-import { pollUntil } from "../Util.ts";
+import * as Schedule from "effect/Schedule";
+import { PlanetscaleConflict, pollUntil } from "../Util.ts";
 
 /**
  * Available PlanetScale MySQL (Vitess) cluster sizes.
@@ -55,15 +56,15 @@ export const waitForKeyspaceReady = Effect.fn(function* (
 });
 
 /**
- * Ensures the default keyspace of a MySQL production branch has the
- * expected cluster size, triggering a resize if it doesn't. Cluster sizes
- * can only be configured on production branches.
+ * 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.
  */
-export const ensureMySQLProductionBranchClusterSize = Effect.fn(function* (
+const observeDefaultKeyspace = Effect.fn(function* (
   organization: string,
   database: string,
   branch: string,
-  expectedClusterSize: MySQLClusterSize,
 ) {
   const keyspaces = yield* ops.listKeyspaces({
     organization,
@@ -72,31 +73,129 @@ export const ensureMySQLProductionBranchClusterSize = Effect.fn(function* (
     page: 1,
     per_page: 100,
   });
-  // Default keyspace is always the same name as the database.
-  const defaultKeyspace = keyspaces.data.find((x) => x.name === database);
-  if (!defaultKeyspace) {
+  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.succeed(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,
-    defaultKeyspace.name,
-  );
+  yield* waitForKeyspaceReady(organization, database, branch, keyspace.name);
 
-  if (defaultKeyspace.cluster_name !== expectedClusterSize) {
+  if (keyspace.cluster_name !== expectedClusterSize) {
     yield* ops.updateBranchClusterConfig({
       organization,
       database,
       branch,
       cluster_size: expectedClusterSize,
     });
-    yield* waitForKeyspaceReady(
-      organization,
-      database,
-      branch,
-      defaultKeyspace.name,
+    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* Effect.fail(
+        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* ops
+      .createKeyspaceResizeRequest({
+        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`,
+      ops.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;
 });