@jskit-ai/resource-runtime 0.0.0-stage → 0.2.13

package/src/test/index.js

@@ -0,0 +1,123 @@
+import { AssertionError } from "node:assert";
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createPackageTestKnex, requireTestDatabase, tableNames, TestDatabaseMissingError } from "@jskit-ai/database-runtime/server/testDatabases";
+import { createResourceHost } from "../server/resourceHost.js";
+import { createResourceRuntime } from "../server/resourceRuntime.js";
+import { expectFlatQueries } from "./expectFlatQueries.js";
+import { expectScoped } from "./expectScoped.js";
+
+// Tables every migrated database has that no feature owns: the migration ledger.
+const MIGRATION_TABLES = Object.freeze(["knex_migrations", "knex_migrations_lock"]);
+
+/**
+ * A resource runtime on the test's own Knex, for a package test that owns
+ * tables without booting a server: `runtime.own(featureId, owns)` answers handles.
+ * With `createTables`, own() also creates each owned table from its resource's
+ * schema, for a SQLite test whose shipped migrations are written for another database.
+ * `hostHooks` are json-rest-api hooks the test installs on the runtime's host,
+ * such as an afterCommit that fails on request.
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} [options.logger]
+ * @param {number} [options.requestRowLimit]
+ * @param {number} [options.serverPageSize]
+ * @param {boolean} [options.createTables]
+ * @param {Record<string, Function>} [options.hostHooks]
+ */
+async function createTestResourceRuntime({ knex, logger = silentLogger, requestRowLimit, serverPageSize, createTables = false, hostHooks }) {
+  const api = await createResourceHost({ knex, logger });
+  if (hostHooks) {
+    await api.customize({ hooks: hostHooks });
+  }
+  const runtime = createResourceRuntime({ api, requestRowLimit, serverPageSize });
+  if (!createTables) {
+    return runtime;
+  }
+  return Object.freeze({
+    ...runtime,
+    async own(featureId, owns) {
+      const handles = await runtime.own(featureId, owns);
+      for (const name of Object.keys(handles)) {
+        await api.resources[name].createKnexTable();
+      }
+      return handles;
+    }
+  });
+}
+
+/**
+ * Starts features as an application's server does, on the test's own Knex and
+ * without HTTP: the kernel orders them by what they require, the resource
+ * runtime gives each owner its handles and system context (with `createTables`,
+ * it also creates each owned table from its resource), and every boot runs, so
+ * a registry that seals at boot, such as `crud.contracts`, is sealed. The
+ * runtime's events and actions are started with them; `inputs` give anything
+ * else the features require, by capability id, and `requires` names what the
+ * test reads, as a feature's own requires do. `stop()` shuts them down.
+ * @template {Record<string, string>} R
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex
+ * @param {ReadonlyArray<ReturnType<typeof defineProvider>>} options.features The features and providers under test.
+ * @param {R} [options.requires] What the test reads: local name to capability id.
+ * @param {Record<string, unknown>} [options.inputs] Capability values given as they are, by capability id.
+ * @param {boolean} [options.createTables]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} [options.logger]
+ * @returns {Promise<{ capabilities: { [K in keyof R]: any }, resources: ReturnType<typeof createResourceRuntime>, stop: () => Promise<unknown> }>}
+ */
+async function startTestFeatures({ knex, features, requires = {}, inputs = {}, createTables = false, logger = silentLogger }) {
+  const resources = await createTestResourceRuntime({ knex, logger, createTables });
+  let capabilities = {};
+  const reader = defineProvider({
+    id: "test.features.reader",
+    requires,
+    /** @param {Record<string, unknown>} values The capabilities the test reads. */
+    setup(values) {
+      capabilities = Object.freeze({ ...values });
+      return {};
+    }
+  });
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.logger": logger, ...inputs, "runtime.resources": resources },
+    providers: [EventProvider, ActionProvider, ...features, reader]
+  });
+  await runtime.start();
+  return Object.freeze({
+    capabilities,
+    resources,
+    stop: () => runtime.shutdown()
+  });
+}
+
+/**
+ * Fails when the migrated test database holds a table no feature owns and no
+ * package declares as infrastructure (the migration ledger always is).
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex The test database.
+ * @param {{ ownedTables(): ReadonlyArray<{ tableName: string }> }} options.runtime The resource runtime every feature owned its tables through.
+ * @param {ReadonlyArray<string>} [options.infrastructureTables] Tables a package keeps outside resources, such as sessions of a sign-in library.
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The test's environment, such as `process.env`.
+ */
+async function expectEveryTableOwned({ knex, runtime, infrastructureTables = [], environment }) {
+  requireTestDatabase(environment);
+  const accounted = new Set([...MIGRATION_TABLES, ...infrastructureTables, ...runtime.ownedTables().map(({ tableName }) => tableName)]);
+  const unowned = (await tableNames(knex)).filter((table) => !accounted.has(table));
+  if (unowned.length > 0) {
+    throw new AssertionError({
+      message: `Tables no feature owns: ${unowned.join(", ")}. Each table is a table resource one feature owns, or a declared infrastructure table.`
+    });
+  }
+}
+
+export {
+  TestDatabaseMissingError,
+  createPackageTestKnex,
+  createTestResourceRuntime,
+  expectEveryTableOwned,
+  expectFlatQueries,
+  expectScoped,
+  requireTestDatabase,
+  startTestFeatures
+};

package/test/callSettings.test.js

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { passedOn } from "../src/server/index.js";
+import { createPackageTestKnex, createTestResourceRuntime } from "../src/test/index.js";
+
+// SQLite in memory, or a PostgreSQL schema of its own on a DB_CLIENT=pg run (see createPackageTestKnex).
+const testKnex = (t) => createPackageTestKnex(t, { environment: process.env });
+
+// A call's settings (returning, missing, format, lockVersion...) are for that one call. What it hands on, to the work
+// of a transaction, to an afterWrite hook or to the handle's own nested calls, is its context and transaction only.
+
+const WORKSPACE = Object.freeze({ context: Object.freeze({ workspace: { id: "1" } }) });
+// Every setting a caller may have spread into the options it hands on.
+const SETTINGS = Object.freeze({ returning: "none", missing: "skip", format: "jsonapi", fields: ["title"], lockVersion: 3 });
+const notFound = (error) => error.code === "REST_API_RESOURCE" && error.subtype === "not_found";
+
+async function createNotes(t, hooks) {
+  const knex = await testKnex(t);
+  await knex.schema.createTable("notes", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").nullable();
+    table.string("title").notNullable();
+    table.integer("lock_version").notNullable().defaultTo(0);
+  });
+  await knex.schema.createTable("counters", (table) => {
+    table.string("id").primary();
+    table.integer("value").notNullable();
+  });
+  // lockOrCreate creates on the id alone, so it runs on a table without owners.
+  const counters = defineTableResource({
+    name: "counters",
+    tableName: "counters",
+    ownership: "public",
+    schema: { id: { type: "string", primary: true }, value: { type: "integer", required: true } }
+  });
+  const resource = defineTableResource({
+    name: "notes",
+    tableName: "notes",
+    ownership: "workspace",
+    lockVersionField: "lockVersion",
+    schema: {
+      id: { type: "id", primary: true },
+      workspaceId: { type: "id", nullable: true, search: true, storage: { column: "workspace_id" } },
+      title: { type: "string", required: true, search: true },
+      lockVersion: { type: "integer", defaultTo: 0, storage: { column: "lock_version" } }
+    }
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const owned = await runtime.own("notes.feature", [hooks ? { resource, hooks } : resource, { normalizeId: String, resource: counters }]);
+  return { notes: owned.notes, counters: owned.counters };
+}
+
+test("withTransaction's work receives the context and the transaction, never the caller's settings", async (t) => {
+  const { notes } = await createNotes(t);
+  const keys = await notes.withTransaction({ ...WORKSPACE, ...SETTINGS }, async (txOptions) => {
+    // A create inside answers its record: an outer returning: "none" never reached it.
+    const created = await notes.create({ title: "inside" }, txOptions);
+    assert.equal(created.title, "inside");
+    // A get of a missing record throws: an outer missing: "skip" never reached it.
+    await assert.rejects(notes.get("999", {}, txOptions), notFound);
+    // Inside the caller's transaction too.
+    const nested = await notes.withTransaction({ ...txOptions, ...SETTINGS }, async (inner) => Object.keys(inner).sort());
+    assert.deepEqual(nested, ["context", "trx"]);
+    return Object.keys(txOptions).sort();
+  });
+  assert.deepEqual(keys, ["context", "trx"]);
+  assert.deepEqual(Object.keys(passedOn({ ...WORKSPACE, ...SETTINGS })), ["context"]);
+});
+
+test("an afterWrite hook and lockOrCreate's work receive only the context and the transaction", async (t) => {
+  const seen = [];
+  const { notes, counters } = await createNotes(t, { afterWrite: ({ options }) => { seen.push(Object.keys(options).sort()); } });
+  await notes.create({ title: "hooked" }, { ...WORKSPACE, returning: "id" });
+  await notes.withTransaction(WORKSPACE, (txOptions) => notes.create({ title: "inside" }, { ...txOptions, returning: "none" }));
+  assert.deepEqual(seen, [["context", "trx"], ["context", "trx"]]);
+
+  const outside = await counters.lockOrCreate({ id: "visits", value: 0 }, { ...WORKSPACE, returning: "none" }, (row, txOptions) => Object.keys(txOptions).sort());
+  assert.deepEqual(outside, ["context", "trx"]);
+  const inside = await counters.withTransaction(WORKSPACE, (txOptions) => counters.lockOrCreate(
+    { id: "visits", value: 5 },
+    { ...txOptions, returning: "none" },
+    (row, work) => [row.value, Object.keys(work).sort()]
+  ));
+  assert.deepEqual(inside, [0, ["context", "trx"]]);
+});
+
+test("findOrCreate answers the record under an outer returning: none, and a patch keeps its own format", async (t) => {
+  const { notes } = await createNotes(t);
+  const found = await notes.findOrCreate({ id: 7, title: "first" }, { ...WORKSPACE, returning: "none" });
+  assert.equal(found.title, "first");
+  assert.equal((await notes.findOrCreate({ id: 7, title: "again" }, { ...WORKSPACE, returning: "none" })).title, "first");
+
+  // The patch's own settings still reach its own write and read inside the transaction it opens for its lockVersion.
+  const document = await notes.patch(7, { title: "second" }, { ...WORKSPACE, lockVersion: 0, format: "jsonapi" });
+  assert.equal(document.data.attributes.title, "second");
+  const advanced = await notes.patch(7, {}, { ...WORKSPACE, lockVersion: 1, format: "jsonapi" });
+  assert.equal(advanced.data.attributes.lockVersion, 2);
+  assert.equal((await notes.patch(7, {}, { ...WORKSPACE, format: "jsonapi" })).data.id, "7");
+});

package/test/changes.postgres.test.js

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { createPackageTestKnex, createTestResourceRuntime } from "../src/test/index.js";
+
+// What changed since a horizon, on PostgreSQL, with real concurrent transactions. Each row carries the transaction
+// that last wrote it, an xid8 change stamp that a trigger sets on every insert and update, whatever the write sent, read
+// through an xid8 field with changedSince (>=) and changedBefore (<) filters. A reader takes
+// changeHorizon() before it reads; every transaction below the horizon had finished, so a later read of the rows
+// stamped at or above it finds everything the first read could not see. Each test works in a schema of its own in
+// TEST_DB_NAME (createPackageTestKnex); other sessions on the server may hold the horizon lower, never higher, so the
+// tests check what a read must include and what it must leave out.
+
+const skip = process.env.DB_CLIENT === "pg" ? false : "a PostgreSQL test: it runs on a DB_CLIENT=pg run, with TEST_DB_NAME";
+const WORKSPACE = Object.freeze({ context: Object.freeze({ workspace: Object.freeze({ id: "1" }) }) });
+
+const messageResource = defineTableResource({
+  name: "messages",
+  tableName: "messages",
+  ownership: "workspace",
+  defaultSort: ["id"],
+  schema: {
+    id: { type: "id", primary: true },
+    workspaceId: { type: "id", nullable: true, search: true, storage: { column: "workspace_id" } },
+    body: { type: "string", required: true, search: true },
+    // The database stamps it; nothing writes it.
+    changed: { type: "xid8", nullable: true }
+  },
+  searchSchema: {
+    changedSince: { type: "xid8", actualField: "changed", filterOperator: ">=" },
+    changedBefore: { type: "xid8", actualField: "changed", filterOperator: "<" }
+  }
+});
+
+async function database(t) {
+  const knex = await createPackageTestKnex(t, { environment: process.env });
+  await knex.schema.createTable("messages", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").nullable();
+    table.string("body").notNullable();
+    table.specificType("changed", "xid8").notNullable().defaultTo(knex.raw("pg_current_xact_id()"));
+  });
+  await knex.raw(
+    "create function messages_changed() returns trigger language plpgsql as $$ " +
+    "begin new.changed := pg_current_xact_id(); return new; end $$"
+  );
+  await knex.raw("create trigger messages_changed before insert or update on messages for each row execute function messages_changed()");
+  const runtime = await createTestResourceRuntime({ knex });
+  const { messages } = await runtime.own("messages.feature", [messageResource]);
+  return { knex, messages };
+}
+
+const bodies = (records) => new Map(records.map(({ id, body }) => [String(id), body]));
+
+test("a read from the change horizon finds what a transaction still open at the horizon wrote, which the highest id seen misses", { skip }, async (t) => {
+  const { knex, messages } = await database(t);
+  const [first] = (await messages.createMany([{ body: "first" }], { ...WORKSPACE, returning: "ids" })).map(String);
+
+  // A writer still open when the reader reads: it changes the first message and adds one, taking its id now.
+  const writer = await knex.transaction();
+  t.after(() => (writer.isCompleted() ? undefined : writer.rollback()));
+  await writer("messages").where({ id: first }).update({ body: "first, edited" });
+  const [{ id: added }] = await writer("messages").insert({ workspace_id: 1, body: "added by the open writer" }, ["id"]);
+  const [{ id: theirs }] = await writer("messages").insert({ workspace_id: 2, body: "another workspace's" }, ["id"]);
+  const { rows: [{ xid: writerXid }] } = await writer.raw("select pg_current_xact_id()::text as xid");
+  // A later writer adds one and commits at once, so its id is above the open writer's.
+  const [later] = (await messages.createMany([{ body: "added later" }], { ...WORKSPACE, returning: "ids" })).map(String);
+
+  const horizon = await messages.changeHorizon(WORKSPACE);
+  const page = await messages.queryAll({}, WORKSPACE);
+  assert.deepEqual([...bodies(page)], [[first, "first"], [later, "added later"]]);
+  assert.match(horizon, /^\d{1,20}$/u);
+  assert.ok(BigInt(horizon) <= BigInt(writerXid), `the open writer's transaction ${writerXid} is at or above the horizon ${horizon}`);
+
+  await writer.commit();
+  const caughtUp = bodies(await messages.queryAll({ filters: { changedSince: horizon } }, WORKSPACE));
+  assert.equal(caughtUp.get(first), "first, edited", "the change of an older message");
+  assert.equal(caughtUp.get(String(added)), "added by the open writer", "the message whose id was taken before it committed");
+  assert.equal(caughtUp.has(String(theirs)), false, "another workspace's message stays out");
+  // "Past the highest id seen" misses both: the edit kept its id, and the added message's id is below the later one's.
+  const highestSeen = Math.max(...page.map(({ id }) => Number(id)));
+  assert.deepEqual([Number(first) < highestSeen, Number(added) < highestSeen], [true, true]);
+});
+
+test("changedSince and changedBefore read the window between two horizons; what the window leaves out, the next read from its end finds", { skip }, async (t) => {
+  const { messages } = await database(t);
+  const start = await messages.changeHorizon(WORKSPACE);
+  const [a] = (await messages.createMany([{ body: "a" }], { ...WORKSPACE, returning: "ids" })).map(String);
+  const end = await messages.changeHorizon(WORKSPACE);
+  const [b] = (await messages.createMany([{ body: "b" }], { ...WORKSPACE, returning: "ids" })).map(String);
+
+  const window = bodies(await messages.queryAll({ filters: { changedSince: start, changedBefore: end } }, WORKSPACE));
+  const next = bodies(await messages.queryAll({ filters: { changedSince: end } }, WORKSPACE));
+  // b was written after the end horizon was read, so its transaction is at or above it: never in the window.
+  assert.equal(window.has(b), false);
+  assert.equal(next.get(b), "b");
+  // a is in the window or, while another session held the end horizon below a's transaction, in the next read.
+  assert.equal(window.get(a) ?? next.get(a), "a");
+  assert.ok(BigInt(start) <= BigInt(end), "the horizon never moves back");
+});
+
+test("a stamp compares as a transaction id: from a row's own stamp it is found, from the next one not, a malformed cursor is refused, and a patch moves the stamp on", { skip }, async (t) => {
+  const { knex, messages } = await database(t);
+  // The trigger stamps the writing transaction whatever the write sends.
+  const [created] = await messages.createMany([{ body: "one", changed: "1" }], { ...WORKSPACE, returning: "records" });
+  const stamp = BigInt(created.changed);
+  assert.ok(stamp > 1n, `stamped ${created.changed}`);
+  const found = async (filters) => (await messages.queryAll({ filters }, WORKSPACE)).map(({ body }) => body);
+  const next = String(stamp + 1n);
+  assert.deepEqual(
+    [await found({ changedSince: created.changed }), await found({ changedSince: next }), await found({ changedBefore: created.changed }), await found({ changedBefore: next })],
+    [["one"], [], [], ["one"]]
+  );
+  // They compare as numbers, not as text, where "9" would sort above a stamp starting with a lower digit.
+  assert.deepEqual([await found({ changedSince: "9" }), await found({ changedBefore: "9" })], [["one"], []]);
+  assert.deepEqual(await found({ changedSince: "18446744073709551615" }), []);
+  // A cursor is decimal text below 2^64, leading zeros allowed; anything else is refused before any statement.
+  assert.deepEqual(await found({ changedSince: `000${created.changed}` }), ["one"]);
+  const statements = [];
+  const counted = ({ sql }) => statements.push(sql);
+  knex.on("query", counted);
+  for (const cursor of ["not a position", "-1", "18446744073709551616", "1.5"]) {
+    await assert.rejects(found({ changedSince: cursor }), { code: "REST_API_VALIDATION" }, cursor);
+  }
+  knex.off("query", counted);
+  assert.deepEqual(statements, []);
+  await messages.patch(created.id, { body: "one, edited" }, { ...WORKSPACE, returning: "none" });
+  const [{ changed: moved }] = await knex("messages").where({ id: created.id }).select(knex.raw("changed::text as changed"));
+  assert.ok(BigInt(moved) > stamp, "a patch stamps its own transaction");
+  assert.deepEqual(await found({ changedSince: next }), ["one, edited"]);
+});
+
+test("changeHorizon() reads in the caller's transaction and checks the call's context, as every handle call does", { skip }, async (t) => {
+  const { messages } = await database(t);
+  const inside = await messages.withTransaction(WORKSPACE, async (txOptions) => {
+    await messages.create({ body: "x" }, { ...txOptions, returning: "none" });
+    return messages.changeHorizon(txOptions);
+  });
+  assert.match(inside, /^\d{1,20}$/u);
+  await assert.rejects(messages.changeHorizon({}), { code: "RESOURCE_MISSING_SCOPE" });
+});