@samebase/alchemy-convex 0.7.0 → 0.9.0

package/src/store/convex/reader.ts

@@ -0,0 +1,131 @@
+import { v, type Infer } from "convex/values";
+import { env, internalMutation, query } from "./_generated/server.js";
+import { runRecord, validate } from "./runRecord.ts";
+
+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",
+        },
+      }),
+    };
+  },
+});
+
+const stage = v.object({
+  name: v.string(),
+  record: runRecord,
+  deployedHeadCommit: v.union(v.string(), v.null()),
+  resources: v.array(v.object({ fqn: v.string(), value: v.string() })),
+  output: v.string(),
+});
+
+/** Alchemy encodes a secret as an object with __redacted__; discard that whole object's contents. */
+function withoutSecrets(text: string): unknown {
+  return JSON.parse(text, (_key, value: unknown) =>
+    typeof value === "object" && value !== null && "__redacted__" in value
+      ? { __redacted__: null }
+      : value,
+  );
+}
+
+/** A native subscription reads only the repository named in its verified capability. */
+export const repository = query({
+  args: {},
+  returns: v.object({
+    store: v.literal("found"),
+    stacks: v.array(v.object({ name: v.string(), stages: v.array(stage) })),
+  }),
+  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.");
+    }
+    const name = identity.repository;
+    // The exact name and its slash-prefixed children exclude names such as owner/app-other.
+    // All four reads share the query transaction, including writes made while provisioning.
+    const [rootResources, childResources, rootOutputs, childOutputs] = await Promise.all([
+      ctx.db
+        .query("resources")
+        .withIndex("by_fqn", (q) => q.eq("stack", name))
+        .collect(),
+      ctx.db
+        .query("resources")
+        .withIndex("by_fqn", (q) => q.gte("stack", `${name}/`).lt("stack", `${name}0`))
+        .collect(),
+      ctx.db
+        .query("outputs")
+        .withIndex("by_stage", (q) => q.eq("stack", name))
+        .collect(),
+      ctx.db
+        .query("outputs")
+        .withIndex("by_stage", (q) => q.gte("stack", `${name}/`).lt("stack", `${name}0`))
+        .collect(),
+    ]);
+    const stacks = new Map<string, Map<string, Infer<typeof stage>>>();
+    for (const row of [...rootOutputs, ...childOutputs]) {
+      const record = row.currentRun;
+      if (record === undefined || record.repository !== name) continue;
+      // The output keeps the record of the last completed deploy under `samebase.run`.
+      let output = row.value === undefined ? null : withoutSecrets(row.value);
+      let deployed: unknown = null;
+      if (typeof output === "object" && output !== null && "samebase.run" in output) {
+        ({ "samebase.run": deployed, ...output } = output);
+      }
+      let stages = stacks.get(row.stack);
+      if (stages === undefined) {
+        stages = new Map();
+        stacks.set(row.stack, stages);
+      }
+      stages.set(row.stage, {
+        name: row.stage,
+        record,
+        deployedHeadCommit:
+          validate(runRecord, deployed) && deployed.repository === name
+            ? deployed.headCommit
+            : null,
+        resources: [],
+        output: JSON.stringify(output),
+      });
+    }
+    for (const row of [...rootResources, ...childResources]) {
+      stacks
+        .get(row.stack)
+        ?.get(row.stage)
+        ?.resources.push({
+          fqn: row.fqn,
+          value: JSON.stringify(withoutSecrets(row.value)),
+        });
+    }
+    return {
+      store: "found" as const,
+      stacks: [...stacks]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([name, stages]) => ({
+          name,
+          stages: [...stages.values()].sort((a, b) =>
+            a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+          ),
+        })),
+    };
+  },
+});

package/src/store/convex/runRecord.ts

@@ -0,0 +1,41 @@
+import { v, type GenericValidator, type Infer } from "convex/values";
+
+export const runRecord = v.object({
+  version: v.literal(1),
+  repository: v.string(),
+  stackFile: v.string(),
+  branch: v.string(),
+  pullRequest: v.union(v.number(), v.null()),
+  headCommit: v.string(),
+  runUrl: v.union(v.string(), v.null()),
+  source: v.union(v.literal("github-actions"), v.literal("laptop")),
+  recordedAt: v.string(),
+});
+
+/** Whether `value` passes `validator`. Only the kinds of {@link runRecord} pass; another kind fails. */
+export const validate = <V extends GenericValidator>(
+  validator: V,
+  value: unknown,
+): value is Infer<V> => {
+  switch (validator.kind) {
+    case "object": {
+      if (typeof value !== "object" || value === null) return false;
+      const fields = new Map(Object.entries(value));
+      return Object.entries(validator.fields).every(([key, field]) =>
+        validate(field, fields.get(key)),
+      );
+    }
+    case "union":
+      return validator.members.some((member) => validate(member, value));
+    case "literal":
+      return value === validator.value;
+    case "string":
+      return typeof value === "string";
+    case "float64":
+      return typeof value === "number";
+    case "null":
+      return value === null;
+    default:
+      return false;
+  }
+};

package/src/store/convex/schema.ts

@@ -1,5 +1,6 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
+import { runRecord } from "./runRecord.ts";
 
 // `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
@@ -14,6 +15,7 @@ export default defineSchema({
   outputs: defineTable({
     stack: v.string(),
     stage: v.string(),
-    value: v.string(),
+    value: v.optional(v.string()),
+    currentRun: v.optional(runRecord),
   }).index("by_stage", ["stack", "stage"]),
 });

package/src/store/convex/state.ts

@@ -1,17 +1,16 @@
 // The state functions of the alchemy-state project: one project for each
-// Convex team, pushed by Convex.state() from this directory. Every function
-// is internal: a public function of a root app answers anyone who knows the
-// deployment URL, with no key (measured). An internal function answers only
-// POST /api/function with a deploy key of the production deployment, the
-// call that `convex run` makes.
+// Convex team, pushed by Convex.state() from this directory. These raw state
+// functions are internal. reader.ts exposes authenticated, redacted reads.
 //
 // A stage holds one row for each resource of its stack, so the reads of one
-// stage collect all rows. The function names are a wire contract: Samebase
-// reads `stacks`, `getOutput`, and `readStack` by name, and an older client
-// calls an older set of names. Add functions; never rename or remove one.
+// stage collect all rows. 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 type { QueryCtx } from "./_generated/server.js";
+import type { MutationCtx, QueryCtx } from "./_generated/server.js";
 import { internalMutation, internalQuery } from "./_generated/server.js";
+import { runRecord } from "./runRecord.ts";
+import type { RunRecord } from "../../RunRecord.ts";
 import { STORE_VERSION } from "./version.ts";
 
 /** The wire version of this store, compared with the client's STORE_VERSION. */
@@ -44,6 +43,18 @@ const outputOf = (ctx: QueryCtx, args: { stack: string; stage: string }) =>
     .withIndex("by_stage", (q) => q.eq("stack", args.stack).eq("stage", args.stage))
     .unique();
 
+/** A resource write and its current run become visible in one transaction. */
+const writeCurrentRun = async (
+  ctx: MutationCtx,
+  args: { stack: string; stage: string; run?: RunRecord | undefined },
+) => {
+  const output = await outputOf(ctx, args);
+  // A write without a run record clears the record of the previous run.
+  if (output !== null) await ctx.db.patch("outputs", output._id, { currentRun: args.run });
+  else if (args.run !== undefined)
+    await ctx.db.insert("outputs", { stack: args.stack, stage: args.stage, currentRun: args.run });
+};
+
 /** The sorted union of two lists of names. */
 const union = (a: readonly string[], b: readonly string[]) => [...new Set([...a, ...b])].sort();
 
@@ -153,22 +164,30 @@ export const replaced = internalQuery({
 });
 
 export const set = internalMutation({
-  args: { ...resource, value: v.string() },
+  args: { ...resource, value: v.string(), run: v.optional(runRecord) },
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await rowOf(ctx, args);
-    if (row === null) await ctx.db.insert("resources", args);
+    if (row === null)
+      await ctx.db.insert("resources", {
+        stack: args.stack,
+        stage: args.stage,
+        fqn: args.fqn,
+        value: args.value,
+      });
     else await ctx.db.patch("resources", row._id, { value: args.value });
+    await writeCurrentRun(ctx, args);
     return null;
   },
 });
 
 export const remove = internalMutation({
-  args: resource,
+  args: { ...resource, run: v.optional(runRecord) },
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await rowOf(ctx, args);
     if (row !== null) await ctx.db.delete("resources", row._id);
+    await writeCurrentRun(ctx, args);
     return null;
   },
 });
@@ -208,12 +227,14 @@ export const getOutput = internalQuery({
 });
 
 export const setOutput = internalMutation({
-  args: { ...stage, value: v.string() },
+  args: { ...stage, value: v.string(), run: v.optional(runRecord) },
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await outputOf(ctx, args);
-    if (row === null) await ctx.db.insert("outputs", args);
+    if (row === null)
+      await ctx.db.insert("outputs", { stack: args.stack, stage: args.stage, value: args.value });
     else await ctx.db.patch("outputs", row._id, { value: args.value });
+    await writeCurrentRun(ctx, args);
     return null;
   },
 });
@@ -235,6 +256,7 @@ export const readStack = internalQuery({
         stage: v.string(),
         resources: v.array(v.object({ fqn: v.string(), value: v.string() })),
         output: v.union(v.string(), v.null()),
+        record: v.union(runRecord, v.null()),
       }),
     ),
   }),
@@ -253,13 +275,17 @@ export const readStack = internalQuery({
       [...new Set(outputs.map((row) => row.stage))],
     );
     return {
-      stages: stages.map((stage) => ({
-        stage,
-        resources: resources
-          .filter((row) => row.stage === stage)
-          .map((row) => ({ fqn: row.fqn, value: row.value })),
-        output: outputs.find((row) => row.stage === stage)?.value ?? null,
-      })),
+      stages: stages.map((stage) => {
+        const output = outputs.find((row) => row.stage === stage);
+        return {
+          stage,
+          resources: resources
+            .filter((row) => row.stage === stage)
+            .map((row) => ({ fqn: row.fqn, value: row.value })),
+          output: output?.value ?? null,
+          record: output?.currentRun ?? null,
+        };
+      }),
     };
   },
 });

package/src/store/convex/version.ts

@@ -1,10 +1,12 @@
 // 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. Raise it when a function is added or
-// changes in a way that an older client cannot use. Never rename or remove a
-// function: an older client, and Samebase, call the store by these names.
+// older one or has no `version` yet, and fails the run on a newer one. Raise
+// it with each change of a function. The store and its readers (Samebase) are
+// released and upgraded together: a renamed function is a version bump on
+// both sides.
 //
 // 1: `version`, `stacks`, `stages`, `list`, `get`, `replaced`, `getOutput`,
 //    `set`, `remove`, `removeStack`, `setOutput` (0.6.0).
 // 2: `readStack` (0.7.0).
-export const STORE_VERSION = 2;
+// 3: authenticated subscriptions and current stage run records (0.9.0).
+export const STORE_VERSION = 3;

package/src/store/package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "convex": "^1.46.0"
+    "convex": "^1.48.0"
   }
 }