@samebase/alchemy-convex 0.1.0 → 0.2.0

package/src/EnvironmentVariable.ts

@@ -5,32 +5,54 @@
 // deploy key, not with the Management API token. Setting a variable and
 // removing it are the same call: update_environment_variables with
 // `value: null` removes the variable.
+//
+// A variable that exists but is not in state belongs to someone else: its
+// old value is lost when this resource writes it. Alchemy takes it over only
+// with --adopt.
+//
+// The variable's name and deployment cannot change. A change fails with
+// VariableIdentityChange: use a new resource with a new logical id. A
+// replacement could let the engine delete an old generation that names the
+// live variable, and a rename in place needs a cleanup that can fail and
+// leave a variable or a revoked key behind.
+//
+// The attributes keep the deploy key of the variable's deployment. After a
+// refused change, the props can name another deployment and its key, so
+// read and delete use the attributes, not the props.
 import { createDeploymentClient } from "@convex-dev/platform";
 import { Resource } from "alchemy";
 import { isResolved } from "alchemy/Diff";
+import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
 import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
-import { absentAsUndefined, ManagementApi, settleVoid } from "./ManagementApi.ts";
+import { shouldAdopt } from "./Adoption.ts";
+import {
+  absentAsUndefined,
+  ManagementApi,
+  type ManagementApiService,
+  retryIdempotentWrite,
+  settleVoid,
+} from "./ManagementApi.ts";
 import type { Providers } from "./Providers.ts";
 
 /**
- * Attributes when the listing has `name`. Own keys only: a valid variable
- * name such as `toString` must not match the object prototype.
+ * The variable's identity when the listing has `name`. Own keys only: a
+ * valid variable name such as `toString` must not match the object prototype.
  */
 export const findVariable = (
   list: typeof EnvironmentVariableList.Type,
   deployment: string,
   name: string,
-): EnvironmentVariableAttributes | undefined =>
+): { readonly deployment: string; readonly name: string } | undefined =>
   Object.hasOwn(list.environmentVariables, name) ? { deployment, name } : undefined;
 
 /**
- * Sets one variable, or removes it when `value` is null. The deployment
- * answers 200 with an empty body, so this reads no response data.
+ * One attempt to set one variable, or to remove it when `value` is null. The
+ * deployment answers 200 with an empty body, so this reads no response data.
  */
-export const updateVariable = (
+const writeVariable = (
   deployment: string,
   deployKey: Redacted.Redacted<string>,
   name: string,
@@ -47,11 +69,44 @@ export const updateVariable = (
     ),
   );
 
+/**
+ * Sets one variable, or removes it when `value` is null. The call sets a
+ * value, so it runs again after a write conflict or a 5xx answer, for example
+ * when another resource writes a variable of the same deployment at the same
+ * time. Use it only where the variable is already ours to set.
+ */
+export const updateVariable = (
+  deployment: string,
+  deployKey: Redacted.Redacted<string>,
+  name: string,
+  value: string | Redacted.Redacted<string> | null,
+) => retryIdempotentWrite(writeVariable(deployment, deployKey, name, value));
+
 /** GET https://<deployment>.convex.cloud/api/v1/list_environment_variables */
 export const EnvironmentVariableList = Schema.Struct({
   environmentVariables: Schema.Record(Schema.String, Schema.String),
 });
 
+/** The variable's identity, or undefined when the variable or the deployment is absent. */
+const readVariable = (
+  api: ManagementApiService,
+  deployment: string,
+  deployKey: Redacted.Redacted<string>,
+  name: string,
+) =>
+  // 404: the deployment no longer exists, so neither does the variable.
+  absentAsUndefined(
+    api.deploymentRequest("list environment variables", deployment, deployKey, (client) =>
+      client.GET("/list_environment_variables"),
+    ),
+  ).pipe(
+    Effect.map((body) =>
+      body === undefined
+        ? undefined
+        : findVariable(Schema.decodeUnknownSync(EnvironmentVariableList)(body), deployment, name),
+    ),
+  );
+
 export interface EnvironmentVariableProps {
   /** Deployment name, or its URL for deployments outside US East. */
   readonly deployment: string;
@@ -64,6 +119,8 @@ export interface EnvironmentVariableProps {
 export interface EnvironmentVariableAttributes {
   readonly deployment: string;
   readonly name: string;
+  /** Deploy key for `deployment`, for read and delete. Undefined in state from 0.1.x. */
+  readonly deployKey: Redacted.Redacted<string> | undefined;
 }
 
 export type EnvironmentVariable = Resource<
@@ -75,6 +132,56 @@ export type EnvironmentVariable = Resource<
 >;
 export const EnvironmentVariable = Resource<EnvironmentVariable>("Convex.EnvironmentVariable");
 
+/**
+ * The props name another variable than the one in state. Used by
+ * Convex.EnvironmentVariable and Convex.DefaultEnvironmentVariable.
+ */
+export class VariableIdentityChange extends Schema.TaggedError<VariableIdentityChange>()(
+  "VariableIdentityChange",
+  {
+    resourceType: Schema.String,
+    field: Schema.Literals(["name", "deployment", "projectId", "deploymentType"]),
+    current: Schema.String,
+    requested: Schema.String,
+  },
+) {
+  override get message() {
+    return `${this.resourceType} cannot change its ${this.field} from ${this.current} to ${this.requested}. Create a new resource with a new logical id for the new name or deployment, and remove this one.`;
+  }
+}
+
+/** Fails with {@link VariableIdentityChange} when the props name another variable than the one in state. */
+const checkIdentity = (output: EnvironmentVariableAttributes, news: EnvironmentVariableProps) =>
+  output.name !== news.name
+    ? Effect.fail(
+        new VariableIdentityChange({
+          resourceType: EnvironmentVariable.Type,
+          field: "name",
+          current: output.name,
+          requested: news.name,
+        }),
+      )
+    : output.deployment !== news.deployment
+      ? Effect.fail(
+          new VariableIdentityChange({
+            resourceType: EnvironmentVariable.Type,
+            field: "deployment",
+            current: output.deployment,
+            requested: news.deployment,
+          }),
+        )
+      : Effect.void;
+
+/**
+ * The deploy key for the variable in state: from the attributes, or, for
+ * state from 0.1.x, from props that name the same deployment.
+ */
+const keyOf = (
+  output: EnvironmentVariableAttributes,
+  olds: EnvironmentVariableProps | undefined,
+): Redacted.Redacted<string> | undefined =>
+  output.deployKey ?? (olds?.deployment === output.deployment ? olds.deployKey : undefined);
+
 export const EnvironmentVariableProvider = () =>
   Provider.effect(
     EnvironmentVariable,
@@ -82,47 +189,73 @@ export const EnvironmentVariableProvider = () =>
       const api = yield* ManagementApi;
 
       return {
-        stables: ["deployment", "name"],
-
-        diff: ({ olds, news }) => {
-          if (!isResolved(news)) return Effect.succeed(undefined);
-          // Otherwise undefined: the engine updates when any prop changed and
-          // compares Redacted values, such as the value and the deploy key, by content.
-          return Effect.succeed(
-            olds.deployment !== news.deployment || olds.name !== news.name
-              ? ({ action: "replace" } as const)
-              : undefined,
-          );
-        },
+        // Compares with the attributes: after a refused change, `olds` are
+        // the refused props. Otherwise undefined: the engine updates when any
+        // prop changed and compares Redacted values, such as the value and
+        // the deploy key, by content.
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news) || output === undefined) return undefined;
+          yield* checkIdentity(output, news);
+          return undefined;
+        }),
 
-        read: Effect.fn(function* ({ olds }) {
-          // 404: the deployment no longer exists, so neither does the variable.
-          const body = yield* absentAsUndefined(
-            api.deploymentRequest(
-              "list environment variables",
-              olds.deployment,
-              olds.deployKey,
-              (client) => client.GET("/list_environment_variables"),
-            ),
-          );
-          if (body === undefined) return undefined;
-          return findVariable(
-            Schema.decodeUnknownSync(EnvironmentVariableList)(body),
-            olds.deployment,
-            olds.name,
-          );
+        read: Effect.fn(function* ({ olds, output }) {
+          if (output !== undefined) {
+            const key = keyOf(output, olds);
+            // Without a key for the deployment in state, keep the state as it is.
+            if (key === undefined) return output;
+            const found = yield* readVariable(api, output.deployment, key, output.name);
+            return found === undefined ? undefined : output;
+          }
+          const found = yield* readVariable(api, olds.deployment, olds.deployKey, olds.name);
+          // No state: the variable belongs to someone else until the user passes --adopt.
+          return found === undefined ? undefined : Unowned({ ...found, deployKey: olds.deployKey });
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
-          yield* updateVariable(news.deployment, news.deployKey, news.name, news.value);
-          return { deployment: news.deployment, name: news.name };
+        reconcile: Effect.fn(function* ({ fqn, news, output }) {
+          // Also here: with an unresolved prop in plan, diff could not check.
+          if (output !== undefined) yield* checkIdentity(output, news);
+          const write = writeVariable(news.deployment, news.deployKey, news.name, news.value);
+          if (output !== undefined || (yield* shouldAdopt(fqn))) {
+            // In state, or adopted: the variable is ours to set.
+            yield* retryIdempotentWrite(write);
+          } else {
+            // Not in state: overwriting a variable that exists loses its
+            // value, so that needs adoption. Each attempt checks first, so a
+            // retry after a write conflict never overwrites a variable that
+            // another writer created in the meantime.
+            yield* retryIdempotentWrite(
+              Effect.gen(function* () {
+                const existing = yield* readVariable(
+                  api,
+                  news.deployment,
+                  news.deployKey,
+                  news.name,
+                );
+                if (existing !== undefined) {
+                  return yield* new OwnedBySomeoneElse({
+                    message: `Environment variable ${news.name} already exists on deployment ${news.deployment}. Re-run with --adopt to take it over and overwrite its value, or use a different name.`,
+                    resourceType: EnvironmentVariable.Type,
+                    physicalName: news.name,
+                  });
+                }
+                yield* write;
+              }),
+            );
+          }
+          return { deployment: news.deployment, name: news.name, deployKey: news.deployKey };
         }),
 
         delete: Effect.fn(function* ({ olds, output }) {
+          const key = keyOf(output, olds);
+          if (key === undefined) {
+            yield* Effect.logWarning(
+              `Environment variable ${output.name} on deployment ${output.deployment} stays: Alchemy has no deploy key for that deployment. Remove it in the Convex dashboard.`,
+            );
+            return;
+          }
           // Removing an absent variable succeeds; 404 means the deployment is gone.
-          yield* absentAsUndefined(
-            updateVariable(output.deployment, olds.deployKey, output.name, null),
-          );
+          yield* absentAsUndefined(updateVariable(output.deployment, key, output.name, null));
         }),
       };
     }),

package/src/ManagementApi.ts

@@ -9,6 +9,7 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
 import * as Schema from "effect/Schema";
 import { Credentials } from "./Credentials.ts";
 
@@ -70,8 +71,19 @@ export interface ManagementApiService {
   ) => Effect.Effect<T, ConvexApiError>;
   /** Team id for a slug or numeric id. */
   readonly resolveTeamId: (team: string | number) => Effect.Effect<number, ConvexApiError>;
+  /**
+   * True when a deploy key that Convex returned carries the token of the
+   * Management API credential itself. With an OAuth token, create_deploy_key
+   * and create_preview_deploy_key create no new key: they return the OAuth
+   * token with a new prefix, and the part after "|" is the same. A delete of
+   * that key would revoke the credential.
+   */
+  readonly isCredentialToken: (secret: string) => Effect.Effect<boolean>;
 }
 
+/** The part of a Convex token after the first "|", or the whole value when it has none. */
+const tokenPart = (value: string) => value.slice(value.indexOf("|") + 1);
+
 export class ManagementApi extends Context.Service<ManagementApi, ManagementApiService>()(
   "@samebase/alchemy-convex/ManagementApi",
 ) {}
@@ -111,6 +123,43 @@ export const settleVoid = (
     ),
   );
 
+/**
+ * True when an idempotent write can succeed on a new attempt:
+ *
+ * - A Convex write conflict. Two parallel update_environment_variables calls
+ *   on one deployment gave HTTP 503 `OptimisticConcurrencyControlFailure`,
+ *   "Data read or written in this mutation changed while it was being run",
+ *   in a live run. The platform codes `OCC` and `WriteConflict` and the
+ *   message "... changed while this mutation was being run ..." mean the same.
+ * - Any other 5xx answer. Two parallel delete_preview_deploy_key calls on one
+ *   project gave HTTP 500 `InternalServerError`, "Your request couldn't be
+ *   completed. Try again later.", in a live run. The next attempt succeeded.
+ */
+export const isRetryableWriteError = (error: ConvexApiError): boolean =>
+  error.code === "OptimisticConcurrencyControlFailure" ||
+  error.code === "OCC" ||
+  error.code === "WriteConflict" ||
+  /changed while (it|this mutation) was being run/.test(error.message) ||
+  error.status >= 500;
+
+/**
+ * Runs an idempotent write again after a retryable Convex error: at most
+ * four more attempts, with exponential backoff from 100 ms and jitter. Other
+ * errors fail at once, and so does the last retryable error. Use it only for
+ * a write that has the same result when it runs twice, such as setting a
+ * value or deleting by id. Never for a create that does not check first.
+ */
+export const retryIdempotentWrite = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.retry({
+      while: (error: E) => error instanceof ConvexApiError && isRetryableWriteError(error),
+      times: 4,
+      schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered),
+    }),
+  );
+
 /** Turns a 404 into `undefined` so read and delete stay idempotent. */
 export const absentAsUndefined = <A, R>(
   effect: Effect.Effect<A, ConvexApiError, R>,
@@ -188,6 +237,13 @@ export const ManagementApiLive = (): Layer.Layer<ManagementApi, never, Credentia
           return match.id;
         });
 
-      return { request, requestVoid, deploymentRequest, resolveTeamId };
+      const isCredentialToken: ManagementApiService["isCredentialToken"] = (secret) =>
+        credentials.pipe(
+          Effect.map(
+            (resolved) => tokenPart(Redacted.value(resolved.accessToken)) === tokenPart(secret),
+          ),
+        );
+
+      return { request, requestVoid, deploymentRequest, resolveTeamId, isCredentialToken };
     }),
   );

package/src/PreviewDeployKey.ts

@@ -2,17 +2,25 @@
 // deployments, such as the key CI passes to `npx convex deploy` for a branch.
 //
 // Convex returns the secret only once, from create_preview_deploy_key. The
-// listing shows each key under a unique name, the requested name plus a short
-// id suffix, and delete_preview_deploy_key accepts that unique name. A key
-// cannot be changed after creation, so every property change is a replacement.
+// identity rules are the same as for Convex.DeployKey: a requested name that
+// is unique for each resource instance, exactly one listed key after the
+// create with its numeric id in state, delete by the secret only, and never
+// keep a key that is the OAuth credential itself. A key cannot change after
+// creation, so every property change is a replacement.
 import { Resource } from "alchemy";
 import { havePropsChanged, isResolved } from "alchemy/Diff";
 import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
-import { ListedKey, selectCreatedKey } from "./DeployKey.ts";
-import { absentAsUndefined, ManagementApi } from "./ManagementApi.ts";
+import {
+  createTrackedKey,
+  isKeyListed,
+  ListedKey,
+  requestedKeyName,
+  secretToDelete,
+} from "./DeployKey.ts";
+import { absentAsUndefined, ManagementApi, retryIdempotentWrite } from "./ManagementApi.ts";
 import type { Providers } from "./Providers.ts";
 
 /** GET /projects/{project_id}/list_preview_deploy_keys */
@@ -24,13 +32,18 @@ export const CreatedPreviewDeployKey = Schema.Struct({ previewDeployKey: Schema.
 export interface PreviewDeployKeyProps {
   /** Numeric project id, such as `project.projectId`. */
   readonly projectId: number;
-  /** Requested key name. Convex appends a short id to make it unique. */
+  /**
+   * Key name. The provider requests this name, a dash, and a hash of the
+   * resource identity, so two resources with one `name` get different keys.
+   */
   readonly name: string;
 }
 
 export interface PreviewDeployKeyAttributes {
-  /** The name Convex lists the key under, such as "ci (6308e666)". */
+  /** The name Convex lists the key under, such as "ci-3f2a1b0c9d8e". */
   readonly uniqueName: string;
+  /** Numeric id of the key in the listing. Undefined in state written by 0.1.x. */
+  readonly keyId: number | undefined;
   readonly projectId: number;
   /** The secret, such as `preview:<team>:<project>|<token>`. Convex returns it only at creation. */
   readonly previewDeployKey: Redacted.Redacted<string>;
@@ -60,6 +73,20 @@ export const PreviewDeployKeyProvider = () =>
           )
           .pipe(Effect.map((body) => Schema.decodeUnknownSync(PreviewDeployKeyList)(body).items));
 
+      /**
+       * `id` is the secret: Convex accepts it, and it matches only the key
+       * that this resource created. A second delete answers 404.
+       */
+      const deleteKey = (projectId: number, secret: string) =>
+        retryIdempotentWrite(
+          api.requestVoid("delete preview deploy key", (client) =>
+            client.POST("/projects/{project_id}/delete_preview_deploy_key", {
+              params: { path: { project_id: projectId } },
+              body: { id: secret },
+            }),
+          ),
+        );
+
       return {
         stables: ["uniqueName", "projectId"],
 
@@ -79,47 +106,47 @@ export const PreviewDeployKeyProvider = () =>
           // A key that is not in state has no known secret, so it is never adopted.
           if (output === undefined) return undefined;
           const entries = yield* absentAsUndefined(listKeys(output.projectId));
-          return entries?.some((entry) => entry.name === output.uniqueName) ? output : undefined;
+          return entries !== undefined && isKeyListed(entries, output) ? output : undefined;
         }),
 
-        reconcile: Effect.fn(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           if (output !== undefined) {
             // The secret cannot be read back. A key that still exists keeps the one in state.
-            const entries = yield* listKeys(news.projectId);
-            if (entries.some((entry) => entry.name === output.uniqueName)) return output;
+            if (isKeyListed(yield* listKeys(news.projectId), output)) return output;
           }
-          const created = yield* api.request("create preview deploy key", (client) =>
-            client.POST("/projects/{project_id}/create_preview_deploy_key", {
-              params: { path: { project_id: news.projectId } },
-              body: { name: news.name },
-            }),
-          );
-          const { previewDeployKey } = Schema.decodeUnknownSync(CreatedPreviewDeployKey)(created);
-          const listed = selectCreatedKey(yield* listKeys(news.projectId), news.name);
-          if (listed === undefined) {
-            return yield* Effect.die(
-              new Error(
-                `Convex created preview deploy key "${news.name}" in project ${news.projectId} but does not list it`,
+          const name = requestedKeyName(news.name, fqn, instanceId);
+          const { keyId, uniqueName, secret } = yield* createTrackedKey({
+            target: `project ${news.projectId}`,
+            name,
+            list: listKeys(news.projectId),
+            create: api
+              .request("create preview deploy key", (client) =>
+                client.POST("/projects/{project_id}/create_preview_deploy_key", {
+                  params: { path: { project_id: news.projectId } },
+                  body: { name },
+                }),
+              )
+              .pipe(
+                Effect.map(
+                  (body) =>
+                    Schema.decodeUnknownSync(CreatedPreviewDeployKey)(body).previewDeployKey,
+                ),
               ),
-            );
-          }
-          return {
-            uniqueName: listed.name,
-            projectId: news.projectId,
-            previewDeployKey: Redacted.make(previewDeployKey),
-          };
+            isCredentialToken: api.isCredentialToken,
+          });
+          return { uniqueName, keyId, projectId: news.projectId, previewDeployKey: secret };
         }),
 
         delete: Effect.fn(function* ({ output }) {
-          // 404 PreviewDeployKeyNotFound: an earlier attempt or someone else deleted it.
-          yield* absentAsUndefined(
-            api.requestVoid("delete preview deploy key", (client) =>
-              client.POST("/projects/{project_id}/delete_preview_deploy_key", {
-                params: { path: { project_id: output.projectId } },
-                body: { id: output.uniqueName },
-              }),
-            ),
+          // Only the secret names this key alone: 0.1.x state can hold the
+          // listed name of another resource's key.
+          const secret = yield* secretToDelete(
+            { keyId: output.keyId, secret: output.previewDeployKey },
+            `Convex.PreviewDeployKey "${output.uniqueName}" in project ${output.projectId}`,
           );
+          if (secret === undefined) return;
+          // 404 PreviewDeployKeyNotFound: an earlier attempt or someone else deleted it.
+          yield* absentAsUndefined(deleteKey(output.projectId, secret));
         }),
       };
     }),