@samebase/alchemy-convex 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",
@@ -35,6 +35,18 @@
     "./state/convex.config": {
       "types": "./src/store/component/convex.config.ts",
       "default": "./src/store/component/convex.config.ts"
+    },
+    "./state/_generated/component.js": {
+      "types": "./src/store/component/_generated/component.ts",
+      "default": "./src/store/component/_generated/component.ts"
+    },
+    "./state/functions": {
+      "types": "./src/store/functions.ts",
+      "default": "./src/store/functions.ts"
+    },
+    "./state/auth.config": {
+      "types": "./src/store/authConfig.ts",
+      "default": "./src/store/authConfig.ts"
     }
   },
   "publishConfig": {

package/src/State.ts

@@ -4,18 +4,21 @@
 // every stack and stage of the team in its production deployment: the
 // tables `resources (stack, stage, fqn, value)` and `outputs (stack, stage,
 // value)` of the alchemyState component (src/store/component), served by the
-// functions of src/store/convex. The store lives
-// outside every resource that a stack manages, so a stack can create and
-// destroy its own project. See docs/design/convex-state.md.
+// functions of src/store/functions.ts. Two apps serve them: the store app of
+// src/store/convex (a seed), which this provider pushes, and the base app of
+// the team (a base), which mounts the component next to its own components.
+// The store lives outside every resource that a stack manages, so a stack
+// can create and destroy its own project. See docs/design/convex-state.md.
 //
 // Bootstrap, on the first call of the run: the team token (CONVEX_ACCESS_TOKEN,
 // or the Convex CLI login) finds the project by name, or creates it; a deploy
 // key of its production deployment that can run internal queries and
 // mutations, and nothing else, is created for the run and deleted at its
-// end; the `state:version` query says whether the deployment has the store
-// of this version. Without one, or with an older one, the installed Convex
-// CLI pushes src/store/convex to it, with a push key that is deleted after
-// the push. The raw state functions are internal; authenticated readers get
+// end; the `state:version` query says the store version and the app that
+// serves it. Without one, or with an older seed, the installed Convex CLI
+// pushes src/store/convex to it, with a push key that is deleted after the
+// push. An older base fails the run: a push of the store app would erase the
+// base app. The raw state functions are internal; authenticated readers get
 // repository-scoped subscriptions with secret values removed. A key that stops working during a
 // long run (it expires after two hours) is replaced once per call.
 //
@@ -24,10 +27,10 @@
 // anything, and uses the oldest: both runs end on one store.
 //
 // Samebase reads `stacks`, `getOutput`, `readStack`, and `reader:repository`
-// by name. The store and its readers are released and upgraded together:
-// STORE_VERSION rises with each change of a function, and a client works only
-// with a store of its own version. An older store is pushed over; a newer one
-// fails the run.
+// by name. STORE_VERSION is the wire contract: it rises only when a function
+// that a released client calls changes or goes away, and a client works only
+// with a store of its own version. An older seed is pushed over; an older base
+// and a newer store fail the run.
 //
 // The stage output that `setOutput` stores is the stack's output plus the
 // run record of src/RunRecord.ts under the key `samebase.run`: the
@@ -241,6 +244,39 @@ const storeVersion = (api: FunctionApi) =>
       ),
     );
 
+/**
+ * The app that serves the store. A store without `state:host` is a seed: it
+ * was pushed before 0.14.0, and only the store app of this package served
+ * those stores.
+ */
+const storeHost = (api: FunctionApi) =>
+  api
+    .call("state:host", {})
+    .pipe(
+      Effect.flatMap((reply) =>
+        reply.status === "error" && MISSING_FUNCTION.test(reply.errorMessage)
+          ? Effect.succeed("seed" as const)
+          : valueOf(reply).pipe(
+              Effect.flatMap(decode(Schema.Literals(["seed", "base"]), "store host")),
+            ),
+      ),
+    );
+
+/**
+ * The base app of the team serves an older store. Convex.state() never
+ * pushes its store app over a base, because the push replaces every function
+ * of the deployment and so erases the base app.
+ */
+export class OutdatedBase extends Schema.TaggedError<OutdatedBase>()("OutdatedBase", {
+  team: Schema.Union([Schema.String, Schema.Number]),
+  deployment: Schema.String,
+  version: Schema.Number,
+}) {
+  override get message() {
+    return `The base of team ${this.team} (${this.deployment}) answers store version ${this.version}, and this package needs store version ${STORE_VERSION}. Convex.state does not push over a base. Upgrade the dependency @samebase/alchemy-convex of the base app to the version of this package, and push the base app.`;
+  }
+}
+
 /**
  * The functions directory of the store app, `src/store/convex` of this
  * package. This file is `src/State.ts` in a checkout and a chunk in `lib/`
@@ -330,8 +366,8 @@ const createStoreProject = (api: ManagementApiService, teamId: number, team: str
 
 /**
  * The StateService over the `samebase` project of the team: found or
- * created, its store pushed when it is missing or older, and read and
- * written with the keys of this run.
+ * created, its store app pushed when the store is missing or an older seed,
+ * and read and written with the keys of this run.
  */
 export const makeConvexState = (options: StoreOptions) =>
   Effect.gen(function* () {
@@ -379,22 +415,38 @@ export const makeConvexState = (options: StoreOptions) =>
         ),
     };
 
+    // The store app is pushed only over no store or an older seed. A base
+    // serves the same functions, and a push would erase the base app.
+    const needsPush = (found: number | undefined) =>
+      found === undefined
+        ? Effect.succeed(true)
+        : found < STORE_VERSION
+          ? storeHost(functions).pipe(Effect.map((host) => host === "seed"))
+          : Effect.succeed(false);
     let version = yield* storeVersion(functions);
-    if (version === undefined || version < STORE_VERSION) {
+    if (yield* needsPush(version)) {
       // Code without `state:version` is another app with the name of the store.
       if (version === undefined && deployment.lastDeployTime) {
         return yield* failure(
           `project ${STORE_PROJECT_NAME} (${project.id}) of team ${team} has code that is not the state store, and Convex.state does not push over it. Rename that project in the Convex dashboard.`,
         );
       }
-      // Another run can push a newer store in the meantime: read again right
-      // before the push. The push itself has no lock (see the design note).
+      // Another run can push a newer store, or the base app, in the meantime:
+      // read again right before the push. The push itself has no lock (see
+      // the design note).
       version = yield* storeVersion(functions);
-      if (version === undefined || version < STORE_VERSION) {
+      if (yield* needsPush(version)) {
         yield* pushStore(options, deployment);
         version = yield* storeVersion(functions);
       }
     }
+    if (
+      version !== undefined &&
+      version < STORE_VERSION &&
+      (yield* storeHost(functions)) === "base"
+    ) {
+      return yield* new OutdatedBase({ team, deployment: deployment.name, version });
+    }
     if (version !== STORE_VERSION) {
       return yield* failure(
         `${deployment.name} answers store version ${version ?? "none"}, and this package needs store version ${STORE_VERSION}.`,
@@ -445,7 +497,8 @@ export const makeConvexState = (options: StoreOptions) =>
  * in CONVEX_ACCESS_TOKEN or the Convex CLI login. A team access token names
  * its team, so `team` is optional with one; the Convex CLI login needs the
  * slug or the id. The first use of the run finds or creates the project and
- * pushes the store when it is missing or older. `alchemy plan` on another
+ * pushes the store app when the store is missing or an older seed. An older
+ * base fails the run with {@link OutdatedBase}. `alchemy plan` on another
  * stack never touches Convex.
  */
 export const state = (

package/src/index.ts

@@ -38,7 +38,7 @@ export {
   runRecord,
   withRunRecord,
 } from "./RunRecord.ts";
-export { state, STORE_PROJECT_NAME } from "./State.ts";
+export { OutdatedBase, state, STORE_PROJECT_NAME } from "./State.ts";
 export {
   CodePushFailed,
   ConvexAppNotFound,

package/src/store/authConfig.ts

@@ -0,0 +1,17 @@
+// The auth config of each app that serves the store: the app verifies the
+// read tokens that `reader:authorize` signs with the key of its own
+// deployment. Exported as `@samebase/alchemy-convex/state/auth.config`.
+import type { AuthConfig } from "convex/server";
+
+/** The auth config of the store readers on the deployment at `cloudUrl`, the app's `env.CONVEX_CLOUD_URL`. */
+export const authConfig = (cloudUrl: string): AuthConfig => ({
+  providers: [
+    {
+      type: "customJwt",
+      issuer: cloudUrl,
+      applicationID: `${cloudUrl}/alchemy-reader`,
+      jwks: `${cloudUrl}/.well-known/jwks.json`,
+      algorithm: "ES256",
+    },
+  ],
+});

package/src/store/component/reader.ts

@@ -3,7 +3,7 @@
 // `ctx.auth`.
 import { v, type Infer } from "convex/values";
 import { query } from "./_generated/server.js";
-import { runRecord, validate } from "./runRecord.ts";
+import { runRecord, validate } from "./runRecord.js";
 
 const stage = v.object({
   name: v.string(),

package/src/store/component/schema.ts

@@ -1,6 +1,6 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
-import { runRecord } from "./runRecord.ts";
+import { runRecord } from "./runRecord.js";
 
 // `value` is the JSON text of Alchemy's encodeState(...): the same text that
 // Alchemy's local state writes to a file. A Convex object would reject keys

package/src/store/component/state.ts

@@ -8,7 +8,7 @@
 import { v, type Infer } from "convex/values";
 import type { MutationCtx, QueryCtx } from "./_generated/server.js";
 import { mutation, query } from "./_generated/server.js";
-import { runRecord } from "./runRecord.ts";
+import { runRecord } from "./runRecord.js";
 
 const stage = { stack: v.string(), stage: v.string() };
 const resource = { ...stage, fqn: v.string() };

package/src/store/convex/auth.config.ts

@@ -1,14 +1,4 @@
-import type { AuthConfig } from "convex/server";
+import { authConfig } from "../authConfig.js";
 import { env } from "./_generated/server.js";
 
-export default {
-  providers: [
-    {
-      type: "customJwt",
-      issuer: env.CONVEX_CLOUD_URL,
-      applicationID: `${env.CONVEX_CLOUD_URL}/alchemy-reader`,
-      jwks: `${env.CONVEX_CLOUD_URL}/.well-known/jwks.json`,
-      algorithm: "ES256",
-    },
-  ],
-} satisfies AuthConfig;
+export default authConfig(env.CONVEX_CLOUD_URL);

package/src/store/convex/convex.config.ts

@@ -1,5 +1,5 @@
 import { defineApp } from "convex/server";
-import alchemyState from "../component/convex.config.ts";
+import alchemyState from "../component/convex.config.js";
 
 const app = defineApp();
 app.use(alchemyState);

package/src/store/convex/reader.ts

@@ -1,51 +1,5 @@
-// Authenticated reads stay in the app: `authorize` signs and `repository`
-// verifies with `ctx.auth`, which a component does not have. The rows and the
-// redaction are in the alchemyState component.
-import { v } from "convex/values";
-import { repositoryReply } from "../component/reader.ts";
+// The authenticated, redacted reads of the store app, from src/store/functions.ts.
+import { readerFunctions } from "../functions.js";
 import { components } from "./_generated/api.js";
-import { env, internalMutation, query } from "./_generated/server.js";
 
-const repositoryName = /^[^/]+\/[^/]+$/;
-
-/** Only a deployment credential can exchange an approved repository for a read token. */
-export const authorize = internalMutation({
-  args: { repository: v.string(), subject: v.string() },
-  returns: v.object({ token: v.string() }),
-  handler: async (ctx, args) => {
-    if (!repositoryName.test(args.repository) || args.subject === "") {
-      throw new Error("A repository and subject are required.");
-    }
-    return {
-      token: await ctx.auth.signJwt({
-        expiresInSeconds: 300,
-        claims: {
-          sub: args.subject,
-          aud: `${env.CONVEX_CLOUD_URL}/alchemy-reader`,
-          repository: args.repository,
-          scope: "alchemy:read",
-        },
-      }),
-    };
-  },
-});
-
-/** A native subscription reads only the repository named in its verified capability. */
-export const repository = query({
-  args: {},
-  returns: repositoryReply,
-  handler: async (ctx) => {
-    const identity = await ctx.auth.getUserIdentity();
-    if (
-      identity === null ||
-      identity.scope !== "alchemy:read" ||
-      typeof identity.repository !== "string" ||
-      !repositoryName.test(identity.repository)
-    ) {
-      throw new Error("Alchemy repository read access is required.");
-    }
-    return await ctx.runQuery(components.alchemyState.reader.repository, {
-      repository: identity.repository,
-    });
-  },
-});
+export const { authorize, repository } = readerFunctions(components.alchemyState);

package/src/store/convex/state.ts

@@ -1,123 +1,23 @@
-// The state functions of the samebase project of a team: one project for each
-// Convex team, pushed by Convex.state() from this directory. These raw state
-// functions are internal. reader.ts exposes authenticated, redacted reads.
-//
-// The rows are in the alchemyState component (src/store/component). Each
-// function here forwards to the component function of the same name, with the
-// same results; an absent `run` or `stage` goes to the component as null.
-// These names and arguments are the wire contract of STORE_VERSION. Samebase
-// reads `stacks`, `getOutput`, and `readStack` by name: a renamed function is
-// a version bump of the store and of Samebase.
-import { v } from "convex/values";
-import { runRecord } from "../component/runRecord.ts";
-import { stackReply } from "../component/state.ts";
+// The state functions of the store app of this package, a seed: Convex.state()
+// pushes this directory to the samebase project of a team. The raw state
+// functions are internal; reader.ts exposes authenticated, redacted reads.
+// The functions come from src/store/functions.ts, which a base app imports
+// too. Each export has its own name, so that Convex finds it.
+import { stateFunctions } from "../functions.js";
 import { components } from "./_generated/api.js";
-import { internalMutation, internalQuery } from "./_generated/server.js";
-import { STORE_VERSION } from "./version.ts";
 
-const state = components.alchemyState.state;
-
-/** The wire version of this store, compared with the client's STORE_VERSION. */
-export const version = internalQuery({
-  args: {},
-  returns: v.number(),
-  handler: async () => STORE_VERSION,
-});
-
-/** Stacks with at least one resource or one output, sorted. */
-export const stacks = internalQuery({
-  args: {},
-  returns: v.array(v.string()),
-  handler: (ctx) => ctx.runQuery(state.stacks, {}),
-});
-
-/** Stages of a stack with at least one resource or one output, sorted. */
-export const stages = internalQuery({
-  args: { stack: v.string() },
-  returns: v.array(v.string()),
-  handler: (ctx, args) => ctx.runQuery(state.stages, { stack: args.stack }),
-});
-
-export const list = internalQuery({
-  args: { stack: v.string(), stage: v.string() },
-  returns: v.array(v.string()),
-  handler: (ctx, args) => ctx.runQuery(state.list, { stack: args.stack, stage: args.stage }),
-});
-
-export const get = internalQuery({
-  args: { stack: v.string(), stage: v.string(), fqn: v.string() },
-  returns: v.union(v.string(), v.null()),
-  handler: (ctx, args) =>
-    ctx.runQuery(state.get, { stack: args.stack, stage: args.stage, fqn: args.fqn }),
-});
-
-/** Resources whose state has `status: "replaced"`. */
-export const replaced = internalQuery({
-  args: { stack: v.string(), stage: v.string() },
-  returns: v.array(v.string()),
-  handler: (ctx, args) => ctx.runQuery(state.replaced, { stack: args.stack, stage: args.stage }),
-});
-
-export const set = internalMutation({
-  args: {
-    stack: v.string(),
-    stage: v.string(),
-    fqn: v.string(),
-    value: v.string(),
-    run: v.optional(runRecord),
-  },
-  returns: v.null(),
-  handler: (ctx, args) =>
-    ctx.runMutation(state.set, {
-      stack: args.stack,
-      stage: args.stage,
-      fqn: args.fqn,
-      value: args.value,
-      run: args.run ?? null,
-    }),
-});
-
-export const remove = internalMutation({
-  args: { stack: v.string(), stage: v.string(), fqn: v.string(), run: v.optional(runRecord) },
-  returns: v.null(),
-  handler: (ctx, args) =>
-    ctx.runMutation(state.remove, {
-      stack: args.stack,
-      stage: args.stage,
-      fqn: args.fqn,
-      run: args.run ?? null,
-    }),
-});
-
-/** Deletes the resources and outputs of one stage, or of every stage of the stack. */
-export const removeStack = internalMutation({
-  args: { stack: v.string(), stage: v.optional(v.string()) },
-  returns: v.null(),
-  handler: (ctx, args) =>
-    ctx.runMutation(state.removeStack, { stack: args.stack, stage: args.stage ?? null }),
-});
-
-export const getOutput = internalQuery({
-  args: { stack: v.string(), stage: v.string() },
-  returns: v.union(v.string(), v.null()),
-  handler: (ctx, args) => ctx.runQuery(state.getOutput, { stack: args.stack, stage: args.stage }),
-});
-
-export const setOutput = internalMutation({
-  args: { stack: v.string(), stage: v.string(), value: v.string(), run: v.optional(runRecord) },
-  returns: v.null(),
-  handler: (ctx, args) =>
-    ctx.runMutation(state.setOutput, {
-      stack: args.stack,
-      stage: args.stage,
-      value: args.value,
-      run: args.run ?? null,
-    }),
-});
-
-/** Every stage of a stack with its resources, output, and current record, in one call. Since store version 2. */
-export const readStack = internalQuery({
-  args: { stack: v.string() },
-  returns: stackReply,
-  handler: (ctx, args) => ctx.runQuery(state.readStack, { stack: args.stack }),
-});
+export const {
+  version,
+  host,
+  stacks,
+  stages,
+  list,
+  get,
+  replaced,
+  set,
+  remove,
+  removeStack,
+  getOutput,
+  setOutput,
+  readStack,
+} = stateFunctions(components.alchemyState, "seed");

package/src/store/convex/version.ts

@@ -1,10 +1,13 @@
-// The wire version of the store: the `state:version` query answers it, and
-// Convex.state() pushes this directory when the store of the team answers an
-// older one or has no `version` yet, and fails the run on a newer one. Raise
-// it with each change of a function of this app or of the alchemyState
-// component (src/store/component). The store and its readers (Samebase) are
-// released and upgraded together: a renamed function is a version bump on
-// both sides.
+// The wire contract of the store: the `state:version` query answers it, and
+// Convex.state() pushes the store app when a seed answers an older one or the
+// deployment has no `version` yet. It fails the run when a base answers an
+// older one, and on a newer one.
+//
+// Each consumer of a team needs this exact number, so a raise moves every
+// consumer of the team at once. Raise it only when a function that a released
+// client calls changes its arguments, its result, or its meaning, or goes
+// away. A new function does not raise it. The store and its readers (Samebase)
+// move together on a raise: a renamed function is a raise on both sides.
 //
 // 1: `version`, `stacks`, `stages`, `list`, `get`, `replaced`, `getOutput`,
 //    `set`, `remove`, `removeStack`, `setOutput` (0.6.0).