@coda-console/kernel 0.0.0-stage → 0.1.0

package/sim/host.mjs

@@ -0,0 +1,256 @@
+import assert from 'node:assert/strict';
+import { Busy, Rejected } from '../kernel.mjs';
+
+// The host the kernel's own tests run in the simulated world: one op, `work`, whose input says how the handler behaves.
+// It keeps the runs it leaves working in a table of its own, and its memory is lost on a crash like the kernel's.
+
+const TABLES = `
+  CREATE TABLE IF NOT EXISTS host_held (from_addr TEXT NOT NULL, id TEXT NOT NULL, addr TEXT NOT NULL, goal TEXT NOT NULL,
+    throws INTEGER NOT NULL DEFAULT 0, settles INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (from_addr, id));`;
+
+const key = (from, id) => `${from}/${id}`;
+
+/** What a run's handler may report while it works, in turn (C6). */
+export const CHANGES = [
+  { progress: { step: 1 } },
+  { status: 'input-required', asking: { question: 1 } },
+  { status: 'input-required', asking: { question: 1 }, progress: { step: 2 } },
+  { status: 'input-required', asking: { question: 2 } },
+  { status: 'working' },
+];
+
+/**
+ * The setup of the test host: every address takes `work` and its answers, and every address hears its statuses and
+ * results. Returns the host, which is also `node.host`.
+ * @param {{ kernel: object, node: import('./world.mjs').SimNode, world: import('./world.mjs').World }} context
+ */
+export function host(context) {
+  const it = new TestHost(context);
+  for (const address of context.node.addresses) {
+    context.kernel.handle(address, 'work', { accept: call => it.accept(call), cancel: run => it.cancel(run), answer: (run, given) => it.answer(run, given) });
+    context.kernel.results(address, { status: call => it.status(call), result: call => it.result(call), late: call => it.late(call) });
+  }
+  return it;
+}
+
+/**
+ * The runs the test host of `node` left working, in the order it took them. A test or a check reads them straight from
+ * the database, whether the node is up or not; the host itself never needs the list.
+ * @param {import('./world.mjs').SimNode} node
+ */
+export function held(node) {
+  return node.q('SELECT from_addr, id, addr, goal FROM host_held ORDER BY rowid').all();
+}
+
+/**
+ * Finishes every run the test hosts of the world hold, as quiesce() asks: true while there was one.
+ * @param {import('./world.mjs').World} world
+ */
+export function advance(world) {
+  let moved = false;
+  for (const node of world.nodes)
+    if (node.up && node.host instanceof TestHost)
+      for (const row of held(node)) {
+        moved = true;
+        world.act(node, kernel => node.host.finish(kernel, row));
+      }
+  return moved;
+}
+
+/** @type {WeakSet<import('./world.mjs').World>} worlds that run the test host's checks */
+const watched = new WeakSet();
+
+// The test host's own check after every step: what it scans again on start (T4) is what it keeps working.
+function watch(world) {
+  if (watched.has(world)) return;
+  watched.add(world);
+  world.onStep(() => {
+    for (const node of world.nodes) {
+      if (!node.up || !(node.host instanceof TestHost)) continue;
+      const runs = node.addresses.flatMap(address => node.kernel.runs({ address })).map(run => key(run.from, run.id));
+      assert.deepEqual(runs.sort(), held(node).map(row => key(row.from_addr, row.id)).sort(), `runs() of ${node.name} are not the runs its host keeps`);
+    }
+  });
+}
+
+/** The test host of one generation of an instance. It reaches its database only through the generation's `node.db`. */
+export class TestHost {
+  busy = new Map();
+  thrown = new Map();
+  statements = new Map();
+
+  /** @param {{ kernel: object, node: import('./world.mjs').SimNode, world: import('./world.mjs').World }} context */
+  constructor({ kernel, node, world }) {
+    this.kernel = kernel;
+    this.node = node;
+    this.world = world;
+    node.db.exec(TABLES);
+    node.host = this;
+    watch(world);
+  }
+
+  q(sql) {
+    let statement = this.statements.get(sql);
+    if (!statement) this.statements.set(sql, statement = this.node.db.prepare(sql));
+    return statement;
+  }
+
+  /**
+   * @param {{ from: string, id: string, to: string,
+   *   input: { mode: string, n?: number, goal?: string, kids?: object[], cancelThrows?: boolean, cancelSettles?: boolean } }} call
+   */
+  accept(call) {
+    const { mode } = call.input;
+    if (mode === 'busy' && !this.world.calm) {
+      const times = this.busy.get(key(call.from, call.id)) ?? 0;
+      if (times < 2) {
+        this.busy.set(key(call.from, call.id), times + 1);
+        throw new Busy();
+      }
+    }
+    switch (mode) {
+      case 'fail':
+        return { outcome: 'failed', error: { code: 'broke', message: 'it broke', effects: 'some', retryAfterMs: 50 } };
+      case 'parent':
+        this.spawn({ from: call.from, id: call.id }, call.to, call.input.kids);
+      // falls through: a parent is held like any other run
+      case 'hold':
+        this.q('INSERT INTO host_held (from_addr, id, addr, goal, throws, settles) VALUES (?, ?, ?, ?, ?, ?)')
+          .run(call.from, call.id, call.to, call.input.goal ?? 'completed', call.input.cancelThrows ? 1 : 0, call.input.cancelSettles ? 1 : 0);
+        return undefined;
+      case 'reject':
+        throw new Rejected('refused', 'not this one');
+      case 'throw':
+        throw new Error('handler blew up');
+      case 'hasty':
+        // An outcome at once from a run that awaits a call it made is a handler_error (C9).
+        this.spawn({ from: call.from, id: call.id }, call.to, call.input.kids);
+        if (call.input.kids?.some(kid => kid.awaited)) this.world.count('accept gave an outcome while awaiting');
+      // falls through
+      default:
+        return { outcome: 'completed', result: { by: call.to, n: call.input.n } };
+    }
+  }
+
+  /**
+   * A run makes calls while it works (C9).
+   * @param {{ from: string, id: string }} run
+   * @param {string} address the run's own address
+   * @param {Array<{ to: string, mode: string, goal?: string, awaited: boolean }>} kids
+   */
+  spawn(run, address, kids = []) {
+    if (kids.length > 0 && run.id.includes('>')) this.world.count('calls three levels down');
+    kids.forEach(({ to, mode, goal, awaited, kids, cancelThrows, cancelSettles, delayMs }, index) => {
+      const call = { from: address, id: `${run.from}:${run.id}>${index}`, to, op: 'work', input: { mode, goal, kids, cancelThrows, cancelSettles }, by: run, awaited };
+      if (delayMs === undefined) this.kernel.call(call);
+      else this.kernel.after({ ...call, delayMs });
+    });
+  }
+
+  /** A host starts a root run that makes calls, and keeps it working (2). */
+  root(kernel, { address, id, goal, kids }) {
+    kernel.root({ address, op: 'work', id, parent: { started: 'by the host' } });
+    this.q('INSERT INTO host_held (from_addr, id, addr, goal) VALUES (?, ?, ?, ?)').run(address, id, address, goal);
+    this.spawn({ from: address, id }, address, kids);
+  }
+
+  /** @param {{ from: string, id: string, rev: number, memo?: { statusThrows?: boolean } }} call */
+  status(call) {
+    if (!this.world.calm && call.memo?.statusThrows) throw new Error('status handler blew up');
+  }
+
+  /** @param {{ from: string, id: string, outcome: string, memo?: { resultThrows?: number } }} call */
+  result(call) {
+    this.heard(call, 'result handler blew up');
+  }
+
+  /** An abandoned call's own outcome came after all (C12). It throws as often as `result` would. */
+  late(call) {
+    this.world.count('late outcome');
+    this.heard(call, 'late handler blew up');
+  }
+
+  heard(call, message) {
+    const thrown = this.thrown.get(key(call.from, call.id)) ?? 0;
+    if (!this.world.calm && thrown < (call.memo?.resultThrows ?? 0)) {
+      this.thrown.set(key(call.from, call.id), thrown + 1);
+      throw new Error(message);
+    }
+  }
+
+  /**
+   * The caller asked to cancel a run this host keeps working: the host means to end it canceled. While the world is not
+   * calm, a run taken with `cancelThrows` has a cancel function that throws instead (C7, T6). A run taken with
+   * `cancelSettles` ends canceled at once, unless it awaits a call it made.
+   * @param {{ from: string, id: string, to: string }} run
+   */
+  cancel(run) {
+    const row = this.q('SELECT throws, settles FROM host_held WHERE from_addr = ? AND id = ?').get(run.from, run.id);
+    if (!this.world.calm && row.throws === 1) {
+      this.world.count('cancel function threw');
+      throw new Error('cancel handler blew up');
+    }
+    if (row.settles === 1) {
+      try {
+        this.kernel.settle(run, { outcome: 'canceled' });
+        this.q('DELETE FROM host_held WHERE from_addr = ? AND id = ?').run(run.from, run.id);
+        this.world.count('cancel function settled at once');
+        return;
+      } catch (error) {
+        if (!/still awaits/.test(error.message)) throw error;
+      }
+    }
+    this.q("UPDATE host_held SET goal = 'canceled' WHERE from_addr = ? AND id = ?").run(run.from, run.id);
+  }
+
+  /**
+   * A run waiting for input takes an answer (C8). The answer says what the host does with it: takes it, refuses it,
+   * throws, takes it and asks again, or takes it and ends the run, unless the run awaits a call it made.
+   * @param {{ from: string, id: string, to: string }} run
+   * @param {{ from: string, id: string, asked: number, answer: { mode: string } }} given
+   */
+  answer(run, { asked, answer }) {
+    this.world.count(`answer: to its question (${answer.mode})`);
+    switch (answer.mode) {
+      case 'refuse':
+        throw new Rejected('not_this', 'not this answer');
+      case 'throw':
+        throw new Error('answer handler blew up');
+      case 'ask':
+        this.kernel.update(run, { status: 'input-required', asking: { question: asked + 1 } });
+        break;
+      case 'settle':
+        this.finish(this.kernel, this.q('SELECT from_addr, id, addr, goal FROM host_held WHERE from_addr = ? AND id = ?').get(run.from, run.id));
+    }
+  }
+
+  /** The host reports how a run it left working is going. */
+  nudge(kernel, { from_addr, id }, change) {
+    kernel.update({ from: from_addr, id }, change);
+  }
+
+  /**
+   * The host finishes a run it left working. The kernel refuses while the run awaits a call it made (C9): then the host
+   * waits for another turn, or with `detach` stops waiting for those calls and finishes now. Only a completed run gives a
+   * progress of its own; the others end with their last one.
+   */
+  finish(kernel, { from_addr, id, addr, goal }, { detach = false } = {}) {
+    const run = { from: from_addr, id };
+    const outcome = goal === 'failed'
+      ? { outcome: 'failed', error: { code: 'gave_up', message: 'gave up', effects: 'unknown' } }
+      : goal === 'canceled' ? { outcome: 'canceled' } : { outcome: 'completed', result: { late: true } };
+    const settle = () => kernel.settle(run, outcome, goal === 'completed' ? { progress: { step: 3 } } : {});
+    try {
+      settle();
+    } catch (error) {
+      if (!/still awaits/.test(error.message)) throw error;
+      const { calls, timers } = kernel.pending({ address: addr });
+      const mine = calls.concat(timers).filter(item => item.awaited && item.by?.from === from_addr && item.by?.id === id);
+      if (mine.some(item => item.state === 'scheduled')) this.world.count('a timer it awaits holds a run back');
+      if (!detach) return;
+      for (const item of mine) kernel.detach(item);
+      settle();
+    }
+    this.q('DELETE FROM host_held WHERE from_addr = ? AND id = ?').run(from_addr, id);
+  }
+}