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

package/src/internal/Globals.ts

@@ -0,0 +1,113 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Convex gives every function execution its own globals. The kernel gives each
+ * function call it starts its own copy of the globals a test invocation pins,
+ * as convex-test 0.0.65 does for every handler (its `dist/index.js:1744`,
+ * `:1883-1905` and `:1927-1930`). An assignment inside the call lands in its
+ * copy only, so the invocation bridge's pins stay with the handler that made
+ * them, and overlapping or nested calls keep their own.
+ */
+
+const names = ["Date", "Math", "crypto"] as const;
+
+type Name = (typeof names)[number];
+
+type Copies = { [name in Name]?: unknown };
+
+interface State {
+  readonly copies: AsyncLocalStorage<Copies>;
+  /**
+   * The getters this module installed, so a later install skips them.
+   */
+  readonly getters: WeakSet<() => unknown>;
+}
+
+const key = Symbol.for("@confect/test/Globals");
+
+// One store per test runtime, so every copy of this module reads the same
+// copies.
+const state = (): State =>
+  ((globalThis as { [key]?: State })[key] ??= {
+    copies: new AsyncLocalStorage(),
+    getters: new WeakSet(),
+  });
+
+/**
+ * Whether `accessor`, another library's, already reads through one of this
+ * module's, as convex-test's does once it wraps the kernel's: it answers a
+ * value only a fresh copy holds. convex-test reinstalls its accessor whenever
+ * another is on top (its `dist/index.js:1854-1866`), so wrapping it again would
+ * add a layer at every call while both kinds of world are live.
+ */
+const readsThrough = (
+  copies: State["copies"],
+  accessor: PropertyDescriptor,
+  name: Name,
+): boolean => {
+  const probe = {};
+  return (
+    copies.run({ [name]: probe }, () => accessor.get?.call(globalThis)) ===
+    probe
+  );
+};
+
+/**
+ * Point each global at the calling function's copy, falling back to the
+ * global's own value outside one. A test that redefines a global, as
+ * `vi.stubGlobal` does, removes the accessor, so every call installs it again
+ * over what the test left.
+ */
+const install = ({ copies, getters }: State) => {
+  const global = globalThis as unknown as Record<Name, unknown>;
+  for (const name of names) {
+    const own = Object.getOwnPropertyDescriptor(global, name);
+    // oxlint-disable-next-line typescript/unbound-method -- Compared by identity, never called.
+    if (own?.get !== undefined && getters.has(own.get)) continue;
+    if (own?.get !== undefined && readsThrough(copies, own, name)) continue;
+    const base: PropertyDescriptor = own ?? {
+      value: undefined,
+      writable: true,
+    };
+    const get = () => {
+      const copy = copies.getStore();
+      if (copy !== undefined && name in copy) return copy[name];
+      return "value" in base ? base.value : base.get?.call(global);
+    };
+    const set = (value: unknown) => {
+      const copy = copies.getStore();
+      if (copy !== undefined) copy[name] = value;
+      else if ("value" in base && base.writable === true) base.value = value;
+      else if (base.set !== undefined) base.set.call(global, value);
+      else throw new TypeError(`Cannot assign to read only global '${name}'`);
+    };
+    try {
+      Object.defineProperty(global, name, {
+        get,
+        set,
+        configurable: true,
+        enumerable: own?.enumerable ?? false,
+      });
+      getters.add(get);
+    } catch {
+      // A global that cannot be redefined keeps no copy, and the bridge
+      // refuses to pin it.
+    }
+  }
+};
+
+/**
+ * Run `call` with a fresh copy of the globals. It starts from the test
+ * environment's, whatever the caller assigned in its own copy.
+ */
+export const own = <A>(call: () => A): A => {
+  const current = state();
+  install(current);
+  return current.copies.run({}, call);
+};
+
+/**
+ * Read `read` against the test environment's globals, never a function call's
+ * copy, as the kernel's own clock must.
+ */
+export const host = <A>(read: () => A): A => state().copies.exit(read);

package/src/internal/Invocation.ts

@@ -0,0 +1,316 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { FunctionMetadata, RequestMetadata } from "convex/server";
+import type * as Context from "effect/Context";
+import * as Clock from "./Clock.js";
+
+/**
+ * Four re-executions after the first try. A conflict on attempt 5 exhausts.
+ */
+export type Attempt = 1 | 2 | 3 | 4 | 5;
+
+/**
+ * One test backend. Its `services`, `clock` and `random` reach every invocation
+ * it starts on its own, such as a scheduled job.
+ */
+export interface World {
+  readonly name: string;
+  readonly services: Context.Context<never>;
+  /**
+   * The world's controlled clock in epoch milliseconds. An invocation the world
+   * starts on its own pins its start time from one reading. A bound action's
+   * `Date` reads it live.
+   */
+  readonly clock: () => number;
+  /**
+   * The random stream, uniform on [0, 1), that an invocation the world starts
+   * on its own draws from.
+   */
+  readonly random: () => number;
+}
+
+export interface Invocation {
+  readonly world: World;
+  readonly componentPath: string;
+  readonly attempt: Attempt;
+  readonly request: Omit<RequestMetadata, "authToken">;
+  readonly services: Context.Context<never>;
+  /**
+   * The start time in epoch milliseconds. Every query or mutation of the
+   * invocation reads it from `Date.now()` and `new Date()`, so Effect's default
+   * `Clock` reads it too. An action reads its world's clock instead, as it
+   * runs, and a query or mutation an action calls starts at the action's time
+   * then.
+   */
+  readonly startedAt: number;
+  /**
+   * The random stream, uniform on [0, 1). Every handler of the invocation draws
+   * from it through `Math.random` and `crypto.getRandomValues`, so Effect's
+   * default `Random` draws from it too.
+   */
+  readonly random: () => number;
+}
+
+type FunctionType = "query" | "mutation" | "action";
+
+/**
+ * The invocation a handler runs under, and the type of the function it runs.
+ * Test code that binds an invocation runs no function, so it has no type.
+ */
+interface Running {
+  readonly invocation: Invocation;
+  readonly functionType: FunctionType | undefined;
+}
+
+/**
+ * What `runHandlerPromise` in `@confect/server` reads from `globalThis` under
+ * the same key. `start` answers `undefined` when no invocation is bound.
+ */
+interface Bridge {
+  readonly storage: AsyncLocalStorage<Running>;
+  readonly start: <A>(
+    meta: {
+      readonly getFunctionMetadata: () => Promise<FunctionMetadata>;
+      readonly getRequestMetadata?: () => Promise<RequestMetadata>;
+    },
+    run: (services: Context.Context<never>) => Promise<A>,
+    functionType: FunctionType,
+  ) => Promise<A> | undefined;
+}
+
+const key = Symbol.for("@confect/test/Invocation");
+
+/**
+ * A fresh invocation of `world` for a request of its own, as an action or a
+ * scheduled job starts: attempt 1, the world's services and random stream, and
+ * a start time read from the world's clock.
+ */
+export const fresh = (
+  world: World,
+  componentPath: string,
+  { ip, userAgent, requestId, scheduledFunctionId }: Invocation["request"],
+): Invocation => ({
+  world,
+  componentPath,
+  attempt: 1,
+  request: { ip, userAgent, requestId, scheduledFunctionId },
+  services: world.services,
+  startedAt: world.clock(),
+  random: world.random,
+});
+
+/**
+ * The invocation a function of `functionType` called from `running` joins. A
+ * query or mutation an action calls is a transaction of its own, so it starts
+ * at the world's time when it begins. Any other call shares its caller's
+ * start.
+ */
+const caller = (running: Running, functionType: FunctionType): Invocation =>
+  running.functionType === "action" && functionType !== "action"
+    ? { ...running.invocation, startedAt: running.invocation.world.clock() }
+    : running.invocation;
+
+/**
+ * The invocation a handler runs under. A call nested in the bound request joins
+ * it at the callee's component path. A job Convex started from a timer set
+ * inside the bound request is a request of its own: its scheduled function ID
+ * differs, so it gets a fresh record with the world's services, clock and
+ * random stream.
+ */
+const resolve = (
+  bound: Invocation,
+  componentPath: string,
+  request: RequestMetadata | undefined,
+): Invocation => {
+  if (
+    request !== undefined &&
+    request.scheduledFunctionId !== bound.request.scheduledFunctionId
+  ) {
+    return fresh(bound.world, componentPath, request);
+  }
+  return componentPath === bound.componentPath
+    ? bound
+    : { ...bound, componentPath };
+};
+
+/**
+ * What `Date` answers for a function of `functionType` under `invocation`: a
+ * query's or mutation's start, or the world's clock as it runs in an action.
+ */
+const clockOf = (
+  invocation: Invocation,
+  functionType: FunctionType,
+): (() => number) =>
+  functionType === "action"
+    ? invocation.world.clock
+    : () => invocation.startedAt;
+
+const pinnedDate = (
+  base: DateConstructor,
+  now: () => number,
+): DateConstructor =>
+  new Proxy(base, {
+    get: (target, property, receiver) =>
+      property === "now" ? now : Reflect.get(target, property, receiver),
+    construct: (target, args, newTarget) =>
+      Reflect.construct(target, args.length === 0 ? [now()] : args, newTarget),
+    apply: () => new base(now()).toString(),
+  });
+
+const drawingMath = (base: Math, random: () => number): Math =>
+  new Proxy(base, {
+    get: (target, property, receiver) =>
+      property === "random" ? random : Reflect.get(target, property, receiver),
+  });
+
+const drawingCrypto = (base: Crypto, random: () => number): Crypto => {
+  function getRandomValues<T extends Parameters<Crypto["getRandomValues"]>[0]>(
+    this: unknown,
+    array: T,
+  ): T {
+    // The host call checks the receiver and the argument and throws the host's
+    // errors, so a detached call fails as it does in production.
+    // oxlint-disable-next-line typescript/unbound-method -- Applied with the caller's receiver.
+    Reflect.apply(base.getRandomValues, this === drawing ? base : this, [
+      array,
+    ]);
+    if (array === null) return array;
+    const bytes = new Uint8Array(
+      array.buffer,
+      array.byteOffset,
+      array.byteLength,
+    );
+    for (let index = 0; index < bytes.length; index++) {
+      bytes[index] = Math.floor(random() * 256);
+    }
+    return array;
+  }
+  const drawing: Crypto = new Proxy(base, {
+    get: (target, property) => {
+      if (property === "getRandomValues") return getRandomValues;
+      // Crypto's methods and getters need the host object as `this`.
+      const value: unknown = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  return drawing;
+};
+
+/**
+ * Point the calling handler's `Date`, `Math` and `crypto` at `invocation`, its
+ * `Date` through {@link clockOf}. convex-test gives each handler call its own
+ * copy of these globals, and an assignment inside a handler lands in that copy
+ * only, so overlapping handlers and the handler's own nested calls keep
+ * theirs.
+ *
+ * `outside` reads in the test's own async context. Where the handler has no
+ * copy, an assignment either throws or reaches test code, so `pin` puts back
+ * each global that reached it and throws.
+ */
+const pin = (
+  invocation: Invocation,
+  functionType: FunctionType,
+  outside: <R>(read: () => R) => R,
+): void => {
+  const host = globalThis;
+  const previous = { Date: host.Date, Math: host.Math, crypto: host.crypto };
+  // On the kernel, `Date` already answers the running function's time on the
+  // kernel's clock, so `runAfter` schedules on it. The bridge leaves it there.
+  const kernelDate = Clock.answersInvocation(previous.Date);
+  const pinned = {
+    Date: kernelDate
+      ? previous.Date
+      : pinnedDate(previous.Date, clockOf(invocation, functionType)),
+    Math: drawingMath(previous.Math, invocation.random),
+    crypto: drawingCrypto(previous.crypto, invocation.random),
+  };
+  try {
+    if (!kernelDate) host.Date = pinned.Date;
+    host.Math = pinned.Math;
+    host.crypto = pinned.crypto;
+  } catch {
+    // A global without a per-handler copy can be read-only. The check below
+    // refuses the handler.
+  }
+  const reached = outside(() => ({
+    Date: !kernelDate && host.Date === pinned.Date,
+    Math: host.Math === pinned.Math,
+    crypto: host.crypto === pinned.crypto,
+  }));
+  if (
+    host.Date === pinned.Date &&
+    host.Math === pinned.Math &&
+    host.crypto === pinned.crypto &&
+    !reached.Date &&
+    !reached.Math &&
+    !reached.crypto
+  ) {
+    return;
+  }
+  if (reached.Date) host.Date = previous.Date;
+  if (reached.Math) host.Math = previous.Math;
+  if (reached.crypto) host.crypto = previous.crypto;
+  throw new Error(
+    "@confect/test cannot pin this handler's Date, Math and crypto: it runs without convex-test's per-handler globals, so pinning would change them for every caller",
+  );
+};
+
+const make = (): Bridge => {
+  const storage = new AsyncLocalStorage<Running>();
+  // Taken at the first `bind`, which test code calls outside any handler, so
+  // it reads the test environment's globals.
+  const outside = AsyncLocalStorage.snapshot();
+  return {
+    storage,
+    start: (meta, run, functionType) => {
+      const running = storage.getStore();
+      if (running === undefined) return undefined;
+      return Promise.all([
+        meta.getFunctionMetadata(),
+        meta.getRequestMetadata?.(),
+      ]).then(([{ componentPath }, request]) => {
+        const invocation = resolve(
+          caller(running, functionType),
+          componentPath,
+          request,
+        );
+        pin(invocation, functionType, outside);
+        return storage.run({ invocation, functionType }, () =>
+          run(invocation.services),
+        );
+      });
+    },
+  };
+};
+
+// One bridge per test runtime, so every copy of this module that a test loads
+// binds through the store `runHandlerPromise` reads.
+const installed = globalThis as { [key]?: Bridge };
+
+/**
+ * Run `start` with `invocation` bound. Every registered handler it reaches
+ * through convex-test runs with the invocation's services, clock and random
+ * stream.
+ */
+export const bind = <A>(
+  invocation: Invocation,
+  start: () => Promise<A>,
+): Promise<A> =>
+  (installed[key] ??= make()).storage.run(
+    { invocation, functionType: undefined },
+    start,
+  );
+
+/**
+ * Run `start` with no invocation bound, so every registered handler it reaches
+ * keeps its production runtime, whatever the caller has bound.
+ */
+export const unbound = <A>(start: () => Promise<A>): Promise<A> => {
+  const bridge = installed[key];
+  return bridge === undefined ? start() : bridge.storage.exit(start);
+};
+
+/**
+ * The invocation the calling handler runs under, if one is bound.
+ */
+export const current = (): Invocation | undefined =>
+  installed[key]?.storage.getStore()?.invocation;

package/src/internal/Kernel.ts

@@ -0,0 +1,190 @@
+import * as Clock from "./Clock.js";
+import type { DocumentId, StoredDocument } from "./KernelValues.js";
+import { resolveCommittedValues, tableNameFromId } from "./KernelValues.js";
+import * as ReadSet from "./ReadSet.js";
+
+/**
+ * The number of commits the kernel has published. The empty world is 0.
+ */
+export type Version = number;
+
+/**
+ * A committed document and the version that wrote it.
+ */
+export interface Row {
+  readonly doc: StoredDocument;
+  readonly version: Version;
+}
+
+/**
+ * Committed rows, keyed by component path, then table name, then document ID. A
+ * published state is never changed. A commit makes a new one.
+ */
+export type Tables = ReadonlyMap<
+  string,
+  ReadonlyMap<string, ReadonlyMap<DocumentId, Row>>
+>;
+
+/**
+ * One document's final value in a commit. `null` deletes it.
+ */
+export interface Write {
+  readonly componentPath: string;
+  readonly id: DocumentId;
+  readonly doc: StoredDocument | null;
+}
+
+/**
+ * One document a commit changed: its value before and after. `null` is absent.
+ */
+export interface Change {
+  readonly componentPath: string;
+  readonly id: DocumentId;
+  readonly before: StoredDocument | null;
+  readonly after: StoredDocument | null;
+}
+
+export interface Commit {
+  readonly version: Version;
+  readonly commitTs: bigint;
+  readonly changes: ReadonlyArray<Change>;
+}
+
+/**
+ * The kernel's committed state: rows, the latest version and commit timestamp,
+ * and the write log, oldest first.
+ */
+export interface State {
+  readonly tables: Tables;
+  readonly version: Version;
+  readonly commitTs: bigint;
+  readonly log: ReadonlyArray<Commit>;
+}
+
+export const empty: State = {
+  tables: new Map(),
+  version: 0,
+  commitTs: 0n,
+  log: [],
+};
+
+/**
+ * The committed row for `id` in `componentPath`, if any.
+ */
+export const get = (
+  state: State,
+  componentPath: string,
+  id: DocumentId,
+): Row | undefined => {
+  const tableName = tableNameFromId(id);
+  return tableName === null
+    ? undefined
+    : state.tables.get(componentPath)?.get(tableName)?.get(id);
+};
+
+/**
+ * Every committed row of one table in one component.
+ */
+export const rows = (
+  state: State,
+  componentPath: string,
+  tableName: string,
+): Iterable<Row> =>
+  state.tables.get(componentPath)?.get(tableName)?.values() ?? [];
+
+/**
+ * Publish one attempt's writes as a single commit at `commitTs`. Every
+ * component's writes land in the same version, so a reader sees all of them or
+ * none. A commit with no writes publishes nothing and leaves the state as it
+ * was.
+ */
+export const apply = (
+  state: State,
+  writes: ReadonlyArray<Write>,
+  commitTs: bigint,
+): State => {
+  if (writes.length === 0) return state;
+  const version = state.version + 1;
+  const tables = new Map(
+    Array.from(state.tables, ([path, byTable]) => [path, new Map(byTable)]),
+  );
+  const changes = writes.map(({ componentPath, id, doc }): Change => ({
+    componentPath,
+    id,
+    before: get(state, componentPath, id)?.doc ?? null,
+    after: doc === null ? null : resolveCommittedValues(doc, commitTs),
+  }));
+  const touched = new Set<string>();
+  for (const { componentPath, id, after } of changes) {
+    const tableName = tableNameFromId(id)!;
+    const byTable = tables.get(componentPath) ?? new Map();
+    tables.set(componentPath, byTable);
+    const key = `${componentPath}\u0000${tableName}`;
+    const table = touched.has(key)
+      ? byTable.get(tableName)!
+      : new Map(byTable.get(tableName) ?? []);
+    touched.add(key);
+    byTable.set(tableName, table);
+    if (after === null) table.delete(id);
+    else table.set(id, { doc: after, version });
+  }
+  return {
+    tables,
+    version,
+    commitTs,
+    log: [...state.log, { version, commitTs, changes }],
+  };
+};
+
+/**
+ * The first change published after version `snapshot` that invalidates one of
+ * `reads`, if any.
+ */
+export const conflict = (
+  state: State,
+  snapshot: Version,
+  reads: ReadonlyArray<ReadSet.Read>,
+): Change | undefined => {
+  for (const commit of state.log.slice(snapshot)) {
+    for (const change of commit.changes) {
+      if (reads.some((read) => ReadSet.covers(read, change))) return change;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * What the driver supplies. The kernel holds no clock of its own.
+ */
+export interface KernelRuntime {
+  /**
+   * The time in milliseconds. The kernel's clock never reads earlier than the
+   * latest deadline `advance` reached, so a runtime that stands still still
+   * lets jobs run on time.
+   */
+  readonly now: () => number;
+  /**
+   * The commit timestamp of `version`, asked once as it is published. The
+   * answers strictly increase. A mutation that wrote nothing publishes no
+   * version and asks nothing.
+   */
+  readonly commitTs: (version: Version) => bigint;
+}
+
+/**
+ * The wall clock, as convex-test reads it. Each answer is the time in
+ * nanoseconds when it is asked for, bumped past the previous answer when the
+ * clock stands still.
+ */
+export const wallClock = (): KernelRuntime => {
+  let latest = 0n;
+  const now = Clock.hostNow;
+  return {
+    now,
+    commitTs: () => {
+      const nanos = BigInt(now()) * 1_000_000n;
+      latest = nanos > latest ? nanos : latest + 1n;
+      return latest;
+    },
+  };
+};