@gaganref/confect-test 10.3.1-fork.90 → 10.3.1-fork.92

package/dist/internal/Subscriptions.js

@@ -0,0 +1,186 @@
+import { conflict } from "./Kernel.js";
+import { withIdentity } from "./Execution.js";
+import { compareValues, convexToJson } from "convex/values";
+//#region src/internal/Subscriptions.ts
+/**
+* Why `run` is stale, if it is: a commit since its snapshot changed something
+* it read, as an attempt's read set conflicts, or it read its subscriber's
+* identity and that identity has changed. The clock never makes a run stale.
+* The binary does not rerun a query because time passed, so a run keeps the
+* time it read until something else invalidates it.
+*/
+const invalidation = (run, state, identityVersion) => {
+	const change = conflict(state, run.snapshot, run.reads);
+	if (change !== void 0) return {
+		kind: "commit",
+		change
+	};
+	if (run.observedIdentity && run.identityVersion !== identityVersion) return {
+		kind: "identity",
+		from: run.identityVersion,
+		to: identityVersion
+	};
+};
+/**
+* A thrown value as JSON: a Convex value as Convex writes it, and anything else
+* as its string, beside its type so `"1"` and `1` differ.
+*/
+const thrownKey = (thrown) => {
+	try {
+		return [typeof thrown, convexToJson(thrown)];
+	} catch {
+		return [typeof thrown, String(thrown)];
+	}
+};
+const errorKey = (error) => JSON.stringify(error instanceof Error ? [
+	"error",
+	error.name,
+	error.message,
+	thrownKey(error.data)
+] : ["thrown", thrownKey(error)]);
+/**
+* Whether two outcomes show a client the same thing: equal values, failures
+* with errors of the same name, message and data, or failures that threw equal
+* bare values.
+*/
+const sameOutcome = (a, b) => a._tag === "returned" ? b._tag === "returned" && compareValues(a.value, b.value) === 0 : b._tag === "failed" && errorKey(a.error) === errorKey(b.error);
+/**
+* Run `f` over `items` one at a time, in order, and keep what it answers.
+*/
+const inTurn = (items, f) => items.reduce((previous, item) => previous.then((kept) => f(item).then((b) => b === void 0 ? kept : [...kept, b])), Promise.resolve([]));
+/**
+* One client's query set. Its subscriptions share one caller, whose identity
+* `authenticate` replaces, bumping the identity version.
+*/
+var Subscriber = class {
+	registry;
+	who;
+	version = 0;
+	constructor(registry, who) {
+		this.registry = registry;
+		this.who = who;
+	}
+	get caller() {
+		return this.who;
+	}
+	get identityVersion() {
+		return this.version;
+	}
+	subscribe(reference, args) {
+		return this.registry.subscribe(this, reference, args ?? {});
+	}
+	/**
+	* Replace the caller's identity, or sign it out with `null`. Each
+	* subscription that read the identity is stale until the next refresh.
+	*/
+	authenticate(identity) {
+		this.who = identity === null ? {
+			...this.who,
+			identity: null,
+			token: null
+		} : withIdentity(this.who, identity);
+		this.version++;
+	}
+};
+/**
+* Every live subscription on one world. A commit or an identity change makes a
+* subscription stale. `refresh` reruns the stale ones, and `reference` reruns
+* every one from scratch to check that none was missed.
+*/
+var Registry = class {
+	world;
+	live = /* @__PURE__ */ new Map();
+	nextId = 1;
+	constructor(world) {
+		this.world = world;
+	}
+	subscriber(caller) {
+		return new Subscriber(this, caller);
+	}
+	subscribe(subscriber, reference, args) {
+		return this.run(subscriber, reference, args, { journal: null }).then((run) => {
+			const live = {
+				id: `subscription-${this.nextId++}`,
+				subscriber,
+				reference,
+				args,
+				run
+			};
+			this.live.set(live.id, live);
+			return {
+				id: live.id,
+				current: () => live.run,
+				unsubscribe: () => {
+					this.live.delete(live.id);
+				}
+			};
+		});
+	}
+	/**
+	* Rerun each stale subscription at the latest commit and the kernel's time
+	* now, oldest first, until none is stale. Lists each one whose value
+	* changed.
+	*/
+	refresh() {
+		const stale = Array.from(this.live.values()).flatMap((live) => {
+			const because = invalidation(live.run, this.world.state, live.subscriber.identityVersion);
+			return because === void 0 ? [] : [{
+				live,
+				because
+			}];
+		});
+		if (stale.length === 0) return Promise.resolve([]);
+		return inTurn(stale, ({ live, because }) => this.run(live.subscriber, live.reference, live.args, { journal: live.run.journal }).then((run) => {
+			if (this.live.get(live.id) !== live) return void 0;
+			const from = live.run.outcome;
+			live.run = run;
+			return sameOutcome(from, run.outcome) ? void 0 : {
+				subscription: live.id,
+				from,
+				to: run.outcome,
+				because
+			};
+		})).then((transitions) => this.refresh().then((later) => [...transitions, ...later]));
+	}
+	/**
+	* Rerun every subscription's query from scratch, at the latest commit and
+	* under its subscriber's identity now, and list each whose value differs. A
+	* paginated run keeps its page end.
+	*/
+	reference() {
+		return inTurn(Array.from(this.live.values()), (live) => this.rerun(live).then(({ outcome }) => sameOutcome(live.run.outcome, outcome) ? void 0 : {
+			subscription: live.id,
+			incremental: live.run.outcome,
+			reference: outcome
+		}));
+	}
+	/**
+	* A full rerun of `live`'s query. A run that read the time first reruns at
+	* that time, since the clock alone never invalidates it. When that rerun's
+	* own reads show the run was owed a rerun, it reruns again at the kernel's
+	* time now, as `refresh` would. The rerun was owed when a commit since the
+	* run changed something the rerun read, or the rerun read an identity that
+	* has changed since. The check reads neither the run's recorded reads nor
+	* `invalidation`, so a dependency `refresh` missed still disagrees.
+	*/
+	rerun(live) {
+		const { run } = live;
+		const now = () => this.run(live.subscriber, live.reference, live.args, { journal: run.journal });
+		if (run.time === null) return now();
+		return this.run(live.subscriber, live.reference, live.args, {
+			journal: run.journal,
+			time: run.time
+		}).then((atRunTime) => conflict(this.world.state, run.snapshot, atRunTime.reads) !== void 0 || atRunTime.observedIdentity && atRunTime.identityVersion !== run.identityVersion ? now() : atRunTime);
+	}
+	run(subscriber, reference, args, pinned) {
+		const identityVersion = subscriber.identityVersion;
+		return this.world.subscribed(subscriber.caller, reference, args, pinned).then((run) => ({
+			...run,
+			identityVersion
+		}));
+	}
+};
+//#endregion
+export { Registry, Subscriber, invalidation, sameOutcome };
+
+//# sourceMappingURL=Subscriptions.js.map

package/dist/internal/Subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Subscriptions.js","names":["Kernel.conflict","Execution.withIdentity"],"sources":["../../src/internal/Subscriptions.ts"],"sourcesContent":["import type { UserIdentity } from \"convex/server\";\nimport { compareValues, convexToJson, type Value } from \"convex/values\";\nimport * as Execution from \"./Execution.js\";\nimport * as Kernel from \"./Kernel.js\";\n\n/**\n * One run of a subscribed query, and the identity version its subscriber had\n * when it ran.\n */\nexport interface Run extends Execution.QueryRun {\n  readonly identityVersion: number;\n}\n\n/**\n * Why a run no longer shows what its query answers now.\n */\nexport type Invalidation =\n  | { readonly kind: \"commit\"; readonly change: Kernel.Change }\n  | {\n      readonly kind: \"identity\";\n      readonly from: number;\n      readonly to: number;\n    };\n\n/**\n * Why `run` is stale, if it is: a commit since its snapshot changed something\n * it read, as an attempt's read set conflicts, or it read its subscriber's\n * identity and that identity has changed. The clock never makes a run stale.\n * The binary does not rerun a query because time passed, so a run keeps the\n * time it read until something else invalidates it.\n */\nexport const invalidation = (\n  run: Run,\n  state: Kernel.State,\n  identityVersion: number,\n): Invalidation | undefined => {\n  const change = Kernel.conflict(state, run.snapshot, run.reads);\n  if (change !== undefined) return { kind: \"commit\", change };\n  if (run.observedIdentity && run.identityVersion !== identityVersion) {\n    return { kind: \"identity\", from: run.identityVersion, to: identityVersion };\n  }\n  return undefined;\n};\n\n/**\n * A thrown value as JSON: a Convex value as Convex writes it, and anything else\n * as its string, beside its type so `\"1\"` and `1` differ.\n */\nconst thrownKey = (thrown: unknown): unknown => {\n  try {\n    return [typeof thrown, convexToJson(thrown as Value)];\n  } catch {\n    return [typeof thrown, String(thrown)];\n  }\n};\n\nconst errorKey = (error: unknown): string =>\n  JSON.stringify(\n    error instanceof Error\n      ? [\n          \"error\",\n          error.name,\n          error.message,\n          thrownKey((error as { readonly data?: unknown }).data),\n        ]\n      : [\"thrown\", thrownKey(error)],\n  );\n\n/**\n * Whether two outcomes show a client the same thing: equal values, failures\n * with errors of the same name, message and data, or failures that threw equal\n * bare values.\n */\nexport const sameOutcome = (\n  a: Execution.Outcome,\n  b: Execution.Outcome,\n): boolean =>\n  a._tag === \"returned\"\n    ? b._tag === \"returned\" && compareValues(a.value, b.value) === 0\n    : b._tag === \"failed\" && errorKey(a.error) === errorKey(b.error);\n\n/**\n * A subscription's value changed when a refresh reran it.\n */\nexport interface Transition {\n  readonly subscription: string;\n  readonly from: Execution.Outcome;\n  readonly to: Execution.Outcome;\n  readonly because: Invalidation;\n}\n\n/**\n * A subscription whose value differs from what a full rerun of its query\n * answers.\n */\nexport interface Disagreement {\n  readonly subscription: string;\n  readonly incremental: Execution.Outcome;\n  readonly reference: Execution.Outcome;\n}\n\n/**\n * Run `f` over `items` one at a time, in order, and keep what it answers.\n */\nconst inTurn = <A, B>(\n  items: ReadonlyArray<A>,\n  f: (item: A) => Promise<B | undefined>,\n): Promise<Array<B>> =>\n  items.reduce<Promise<Array<B>>>(\n    (previous, item) =>\n      previous.then((kept) =>\n        f(item).then((b) => (b === undefined ? kept : [...kept, b])),\n      ),\n    Promise.resolve([]),\n  );\n\nexport interface Subscription {\n  readonly id: string;\n  /**\n   * The latest run: its value and the dependencies it took.\n   */\n  readonly current: () => Run;\n  readonly unsubscribe: () => void;\n}\n\ninterface Live {\n  readonly id: string;\n  readonly subscriber: Subscriber;\n  readonly reference: unknown;\n  readonly args: unknown;\n  run: Run;\n}\n\n/**\n * One client's query set. Its subscriptions share one caller, whose identity\n * `authenticate` replaces, bumping the identity version.\n */\nexport class Subscriber {\n  private version = 0;\n\n  constructor(\n    private readonly registry: Registry,\n    private who: Execution.Caller,\n  ) {}\n\n  get caller(): Execution.Caller {\n    return this.who;\n  }\n\n  get identityVersion(): number {\n    return this.version;\n  }\n\n  subscribe(reference: unknown, args?: unknown): Promise<Subscription> {\n    return this.registry.subscribe(this, reference, args ?? {});\n  }\n\n  /**\n   * Replace the caller's identity, or sign it out with `null`. Each\n   * subscription that read the identity is stale until the next refresh.\n   */\n  authenticate(identity: Partial<UserIdentity> | null) {\n    this.who =\n      identity === null\n        ? { ...this.who, identity: null, token: null }\n        : Execution.withIdentity(this.who, identity);\n    this.version++;\n  }\n}\n\n/**\n * Every live subscription on one world. A commit or an identity change makes a\n * subscription stale. `refresh` reruns the stale ones, and `reference` reruns\n * every one from scratch to check that none was missed.\n */\nexport class Registry {\n  private readonly live = new Map<string, Live>();\n  private nextId = 1;\n\n  constructor(private readonly world: Execution.World) {}\n\n  subscriber(caller: Execution.Caller): Subscriber {\n    return new Subscriber(this, caller);\n  }\n\n  subscribe(\n    subscriber: Subscriber,\n    reference: unknown,\n    args: unknown,\n  ): Promise<Subscription> {\n    return this.run(subscriber, reference, args, { journal: null }).then(\n      (run) => {\n        const live: Live = {\n          id: `subscription-${this.nextId++}`,\n          subscriber,\n          reference,\n          args,\n          run,\n        };\n        this.live.set(live.id, live);\n        return {\n          id: live.id,\n          current: () => live.run,\n          unsubscribe: () => {\n            this.live.delete(live.id);\n          },\n        };\n      },\n    );\n  }\n\n  /**\n   * Rerun each stale subscription at the latest commit and the kernel's time\n   * now, oldest first, until none is stale. Lists each one whose value\n   * changed.\n   */\n  refresh(): Promise<ReadonlyArray<Transition>> {\n    const stale = Array.from(this.live.values()).flatMap((live) => {\n      const because = invalidation(\n        live.run,\n        this.world.state,\n        live.subscriber.identityVersion,\n      );\n      return because === undefined ? [] : [{ live, because }];\n    });\n    if (stale.length === 0) return Promise.resolve([]);\n    return inTurn(stale, ({ live, because }) =>\n      this.run(live.subscriber, live.reference, live.args, {\n        journal: live.run.journal,\n      }).then((run): Transition | undefined => {\n        if (this.live.get(live.id) !== live) return undefined;\n        const from = live.run.outcome;\n        live.run = run;\n        return sameOutcome(from, run.outcome)\n          ? undefined\n          : { subscription: live.id, from, to: run.outcome, because };\n      }),\n    ).then((transitions) =>\n      this.refresh().then((later) => [...transitions, ...later]),\n    );\n  }\n\n  /**\n   * Rerun every subscription's query from scratch, at the latest commit and\n   * under its subscriber's identity now, and list each whose value differs. A\n   * paginated run keeps its page end.\n   */\n  reference(): Promise<ReadonlyArray<Disagreement>> {\n    return inTurn(Array.from(this.live.values()), (live) =>\n      this.rerun(live).then(({ outcome }): Disagreement | undefined =>\n        sameOutcome(live.run.outcome, outcome)\n          ? undefined\n          : {\n              subscription: live.id,\n              incremental: live.run.outcome,\n              reference: outcome,\n            },\n      ),\n    );\n  }\n\n  /**\n   * A full rerun of `live`'s query. A run that read the time first reruns at\n   * that time, since the clock alone never invalidates it. When that rerun's\n   * own reads show the run was owed a rerun, it reruns again at the kernel's\n   * time now, as `refresh` would. The rerun was owed when a commit since the\n   * run changed something the rerun read, or the rerun read an identity that\n   * has changed since. The check reads neither the run's recorded reads nor\n   * `invalidation`, so a dependency `refresh` missed still disagrees.\n   */\n  private rerun(live: Live): Promise<Run> {\n    const { run } = live;\n    const now = () =>\n      this.run(live.subscriber, live.reference, live.args, {\n        journal: run.journal,\n      });\n    if (run.time === null) return now();\n    return this.run(live.subscriber, live.reference, live.args, {\n      journal: run.journal,\n      time: run.time,\n    }).then((atRunTime) =>\n      Kernel.conflict(this.world.state, run.snapshot, atRunTime.reads) !==\n        undefined ||\n      (atRunTime.observedIdentity &&\n        atRunTime.identityVersion !== run.identityVersion)\n        ? now()\n        : atRunTime,\n    );\n  }\n\n  private run(\n    subscriber: Subscriber,\n    reference: unknown,\n    args: unknown,\n    pinned: { readonly time?: number; readonly journal: string | null },\n  ): Promise<Run> {\n    const identityVersion = subscriber.identityVersion;\n    return this.world\n      .subscribed(subscriber.caller, reference, args, pinned)\n      .then((run) => ({ ...run, identityVersion }));\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@gaganref/confect-test",
-  "version": "10.3.1-fork.90",
+  "version": "10.3.1-fork.92",
   "peerDependencies": {
-    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.90",
-    "@confect/server": "npm:@gaganref/confect-server@10.3.1-fork.90",
+    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.92",
+    "@confect/server": "npm:@gaganref/confect-server@10.3.1-fork.92",
     "convex": "^1.32.0",
     "convex-test": ">=0.0.65 <0.1.0",
     "effect": ">=4.0.0 <4.1.0"

package/src/internal/Attempt.ts

@@ -4,6 +4,7 @@ import type { Attempt as AttemptNumber } from "./Invocation.js";
 import * as Kernel from "./Kernel.js";
 import type { DocumentId, StoredDocument } from "./KernelValues.js";
 import { tableNameFromId } from "./KernelValues.js";
+import * as Metering from "./Metering.js";
 import type * as ReadSet from "./ReadSet.js";
 
 /**
@@ -44,19 +45,55 @@ export class KernelAttempt {
   private readonly overlay: Overlay = new Map();
   private readonly life: Life = { running: 0, started: 0, open: true };
   private readonly allReads: Array<ReadSet.Read>;
+  /**
+   * The attempt's transaction-limit accounting. A nested mutation's frame
+   * meters into its own child, so its writes merge or drop with it while its
+   * reads stay.
+   */
+  readonly meter: Metering.Meter;
+  /**
+   * Whether the attempt asked for its caller's identity, and the time it read.
+   * Every frame of the attempt shares them, as it shares the reads.
+   */
+  private readonly observed: { identity: boolean; time: number | null };
 
   constructor(
     readonly snapshot: Kernel.State,
     readonly number: AttemptNumber = 1,
     private readonly parent?: KernelAttempt,
+    meter?: Metering.Meter,
   ) {
     this.allReads = parent?.allReads ?? [];
+    this.meter = meter ?? parent?.meter.child() ?? new Metering.Meter();
+    this.observed = parent?.observed ?? { identity: false, time: null };
   }
 
   get reads(): ReadonlyArray<ReadSet.Read> {
     return this.allReads;
   }
 
+  /**
+   * Whether the function asked for its caller's identity.
+   */
+  get observedIdentity(): boolean {
+    return this.observed.identity;
+  }
+
+  /**
+   * The pinned time the function read, or `null` when it never read the time.
+   */
+  get observedTime(): number | null {
+    return this.observed.time;
+  }
+
+  observeIdentity() {
+    this.observed.identity = true;
+  }
+
+  observeTime(at: number) {
+    this.observed.time = at;
+  }
+
   get closed(): boolean {
     return !this.life.open;
   }
@@ -151,6 +188,20 @@ export class KernelAttempt {
     writes.set(id, doc);
   }
 
+  /**
+   * A query run on this attempt's snapshot rather than its pending writes. It
+   * reads and meters on its own, and its meter starts with this attempt's
+   * scheduling counters, as the binary's snapshot clone does.
+   */
+  staleSnapshot(): KernelAttempt {
+    return new KernelAttempt(
+      this.snapshot,
+      this.number,
+      undefined,
+      this.meter.forStaleSnapshot(),
+    );
+  }
+
   /**
    * A nested mutation begins, in a frame of its own. Dropping a failed one is
    * forgetting it.
@@ -172,6 +223,7 @@ export class KernelAttempt {
     }
     for (const [componentPath, writes] of this.overlay)
       for (const [id, doc] of writes) this.parent.write(componentPath, id, doc);
+    this.meter.merge();
   }
 
   /**

package/src/internal/ConvexTest.ts

@@ -7,6 +7,7 @@ import { componentsGeneric } from "convex/server";
 import * as Execution from "./Execution.js";
 import type * as Kernel from "./Kernel.js";
 import * as KernelRefusal from "./KernelRefusal.js";
+import * as Subscriptions from "./Subscriptions.js";
 import type * as Scheduling from "./Scheduling.js";
 
 type Modules = Record<string, () => Promise<any>>;
@@ -25,6 +26,24 @@ export interface KernelControls {
   ) => Promise<Execution.HeldAttempt>;
   readonly apply: (id: string) => Promise<Execution.KernelApply>;
   readonly held: () => ReadonlyArray<Execution.HeldAttempt>;
+  readonly withIdentity: (identity: Partial<UserIdentity>) => KernelControls;
+  readonly withRequestMetadata: (metadata: {
+    readonly ip?: string | null;
+    readonly userAgent?: string | null;
+  }) => KernelControls;
+  /**
+   * A client's query set under this accessor's caller.
+   */
+  readonly subscriber: () => Subscriptions.Subscriber;
+  /**
+   * Rerun every stale subscription. Lists each one whose value changed.
+   */
+  readonly refresh: () => Promise<ReadonlyArray<Subscriptions.Transition>>;
+  /**
+   * Rerun every subscription from scratch. Lists each one whose value differs
+   * from the full rerun.
+   */
+  readonly reference: () => Promise<ReadonlyArray<Subscriptions.Disagreement>>;
   /**
    * Move the kernel's clock forward, running each job due on the way at its
    * deadline.
@@ -69,7 +88,11 @@ const isSchemaDefinition = (
   "tables" in value &&
   typeof (value as { tables: unknown }).tables === "object";
 
-const accessor = (world: Execution.World, caller: Execution.Caller): any => ({
+const accessor = (
+  world: Execution.World,
+  subscriptions: Subscriptions.Registry,
+  caller: Execution.Caller,
+): any => ({
   query: (reference: any, args?: any) => world.query(caller, reference, args),
   mutation: (reference: any, args?: any) =>
     world.mutation(caller, reference, args),
@@ -78,16 +101,19 @@ const accessor = (world: Execution.World, caller: Execution.Caller): any => ({
     world.prepare(caller, reference, args),
   apply: (id: string) => world.apply(id),
   held: () => world.held(),
+  subscriber: () => subscriptions.subscriber(caller),
+  refresh: () => subscriptions.refresh(),
+  reference: () => subscriptions.reference(),
   run: (handler: (ctx: any) => any) => world.run(caller, "", handler),
   runInComponent: (componentPath: string, handler: (ctx: any) => any) =>
     world.run(caller, componentPath, handler),
   withIdentity: (identity: Partial<UserIdentity>) =>
-    accessor(world, Execution.withIdentity(caller, identity)),
+    accessor(world, subscriptions, Execution.withIdentity(caller, identity)),
   withRequestMetadata: (metadata: {
     readonly ip?: string | null;
     readonly userAgent?: string | null;
   }) =>
-    accessor(world, {
+    accessor(world, subscriptions, {
       ...caller,
       ip: metadata.ip ?? null,
       userAgent: metadata.userAgent ?? null,
@@ -112,7 +138,9 @@ const accessor = (world: Execution.World, caller: Execution.Caller): any => ({
  * it, and `apply` validates and publishes a held attempt. `mutation` applies
  * each attempt it prepares at once and prepares the next on a conflict, up to
  * attempt 5. `runtime` supplies the clock and commit timestamps. Scheduled
- * functions run on the kernel's clock, never on a host timer.
+ * functions run on the kernel's clock, never on a host timer. A subscriber's
+ * subscriptions go stale when a commit changes what they read or the identity
+ * they read changes, and `refresh` reruns them.
  */
 export function convexTest(
   schemaOrOptions?:
@@ -144,7 +172,7 @@ export function convexTest(
   }
   const world = new Execution.World(schema, modules, runtime);
   return {
-    ...accessor(world, Execution.anonymous),
+    ...accessor(world, new Subscriptions.Registry(world), Execution.anonymous),
     registerComponent: (
       componentPath: string,
       componentSchema: SchemaDefinition<GenericSchema, boolean>,