@coda-console/kernel 0.0.0-stage → 0.1.0

package/src/schema.mjs

@@ -0,0 +1,169 @@
+// The kernel's tables and every statement it runs on them. Keeping the statements in one place lets a test check the
+// query plan of each one: none of them may scan a table.
+
+// Entry n upgrades the schema from version n to n + 1. Migrations only go forward: the first entry is the 0.1.0 baseline,
+// and no entry changes once released, since a database already past it would never run it again. A changed table adds
+// an entry at the end.
+export const MIGRATIONS = [
+  `CREATE TABLE kernel_calls (
+     from_addr TEXT NOT NULL,
+     id TEXT NOT NULL,
+     to_addr TEXT NOT NULL,
+     op TEXT NOT NULL,
+     digest TEXT NOT NULL,
+     input TEXT NOT NULL,
+     parent TEXT NOT NULL,
+     lane TEXT,
+     by_from TEXT,
+     by_id TEXT,
+     awaited INTEGER NOT NULL,
+     memo TEXT,
+     state TEXT NOT NULL,
+     status TEXT,
+     rev INTEGER NOT NULL DEFAULT 0,
+     asked INTEGER NOT NULL DEFAULT 0,
+     asking TEXT,
+     result TEXT,
+     error TEXT,
+     progress TEXT,
+     owed INTEGER NOT NULL DEFAULT 0,
+     local INTEGER NOT NULL DEFAULT 0,
+     abandoned INTEGER NOT NULL DEFAULT 0,
+     late TEXT,
+     PRIMARY KEY (from_addr, id)
+   );
+   CREATE INDEX kernel_calls_owed ON kernel_calls (owed) WHERE owed = 1;
+   CREATE INDEX kernel_calls_open ON kernel_calls (state) WHERE state = 'open';
+   CREATE INDEX kernel_calls_state ON kernel_calls (from_addr, state);
+   CREATE INDEX kernel_calls_by ON kernel_calls (by_from, by_id);
+   CREATE TABLE kernel_runs (
+     from_addr TEXT NOT NULL,
+     id TEXT NOT NULL,
+     to_addr TEXT NOT NULL,
+     op TEXT,
+     digest TEXT,
+     parent TEXT,
+     awaited INTEGER NOT NULL,
+     root INTEGER NOT NULL,
+     cancel_asked INTEGER NOT NULL DEFAULT 0,
+     status TEXT NOT NULL,
+     rev INTEGER NOT NULL,
+     asked INTEGER NOT NULL DEFAULT 0,
+     asking TEXT,
+     result TEXT,
+     error TEXT,
+     progress TEXT,
+     PRIMARY KEY (from_addr, id)
+   );
+   CREATE INDEX kernel_runs_status ON kernel_runs (to_addr, status);
+   CREATE TABLE kernel_answers (
+     from_addr TEXT NOT NULL,
+     id TEXT NOT NULL,
+     run_from TEXT NOT NULL,
+     run_id TEXT NOT NULL,
+     asked INTEGER NOT NULL,
+     PRIMARY KEY (from_addr, id)
+   );
+   CREATE UNIQUE INDEX kernel_answers_question ON kernel_answers (run_from, run_id, asked);
+   CREATE TABLE kernel_timers (
+     from_addr TEXT NOT NULL,
+     id TEXT NOT NULL,
+     to_addr TEXT NOT NULL,
+     op TEXT NOT NULL,
+     digest TEXT NOT NULL,
+     input TEXT NOT NULL,
+     parent TEXT NOT NULL,
+     lane TEXT,
+     by_from TEXT,
+     by_id TEXT,
+     awaited INTEGER NOT NULL,
+     memo TEXT,
+     due INTEGER NOT NULL,
+     PRIMARY KEY (from_addr, id)
+   );
+   CREATE INDEX kernel_timers_due ON kernel_timers (due);
+   CREATE INDEX kernel_timers_by ON kernel_timers (by_from, by_id);
+   CREATE TABLE kernel_outbox (
+     seq INTEGER PRIMARY KEY AUTOINCREMENT,
+     pos INTEGER NOT NULL,
+     from_addr TEXT NOT NULL,
+     to_addr TEXT NOT NULL,
+     lane TEXT,
+     kind TEXT NOT NULL,
+     call_from TEXT NOT NULL,
+     call_id TEXT NOT NULL,
+     envelope TEXT NOT NULL
+   );
+   CREATE UNIQUE INDEX kernel_outbox_pos ON kernel_outbox (pos);
+   CREATE INDEX kernel_outbox_lane ON kernel_outbox (lane, pos);
+   CREATE INDEX kernel_outbox_call ON kernel_outbox (call_from, call_id);
+   CREATE INDEX kernel_outbox_from ON kernel_outbox (from_addr, pos);`,
+];
+
+export const META = 'CREATE TABLE IF NOT EXISTS kernel_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL)';
+
+const UNENDED_CALL = "state IN ('sending', 'open')";
+const UNENDED_RUN = "status IN ('working', 'input-required')";
+
+export const SQL = {
+  version: "SELECT value FROM kernel_meta WHERE key = 'version'",
+  setVersion: "INSERT INTO kernel_meta (key, value) VALUES ('version', ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value",
+
+  call: 'SELECT * FROM kernel_calls WHERE from_addr = ? AND id = ?',
+  addCall: `INSERT INTO kernel_calls (from_addr, id, to_addr, op, digest, input, parent, lane, by_from, by_id, awaited, memo, state)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'sending')`,
+  // A receipt says the callee took the call; the run it took is working at version 1 (C6).
+  openCall: "UPDATE kernel_calls SET state = 'open', status = 'working', rev = 1 WHERE from_addr = ? AND id = ? AND state = 'sending'",
+  hearCall: "UPDATE kernel_calls SET state = 'open', status = ?, rev = ?, asked = ?, asking = ?, progress = ? WHERE from_addr = ? AND id = ? RETURNING *",
+  endCall: 'UPDATE kernel_calls SET state = ?, result = ?, error = ?, progress = ?, owed = 1, local = ? WHERE from_addr = ? AND id = ?',
+  paidCall: 'UPDATE kernel_calls SET owed = 0 WHERE from_addr = ? AND id = ?',
+  owedCalls: 'SELECT from_addr, id FROM kernel_calls WHERE owed = 1',
+  openCalls: "SELECT * FROM kernel_calls WHERE state = 'open'",
+  detach: 'UPDATE kernel_calls SET awaited = 0 WHERE from_addr = ? AND id = ?',
+  // The caller ends the call itself and takes no result from it; a late outcome is kept apart (C12).
+  abandonCall: "UPDATE kernel_calls SET state = 'failed', error = ?, local = 1, abandoned = 1 WHERE from_addr = ? AND id = ?",
+  lateCall: 'UPDATE kernel_calls SET late = ?, owed = 1 WHERE from_addr = ? AND id = ?',
+  awaiting: `SELECT * FROM kernel_calls WHERE by_from = ? AND by_id = ? AND awaited = 1 AND ${UNENDED_CALL}`,
+  calls: `SELECT * FROM kernel_calls WHERE from_addr = ? AND ${UNENDED_CALL} AND state = coalesce(?, state)`,
+
+  run: 'SELECT * FROM kernel_runs WHERE from_addr = ? AND id = ?',
+  addRun: `INSERT INTO kernel_runs (from_addr, id, to_addr, op, digest, parent, awaited, root, status, rev)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'working', 1)`,
+  dropRun: 'DELETE FROM kernel_runs WHERE from_addr = ? AND id = ?',
+  haltRun: 'UPDATE kernel_runs SET cancel_asked = 1 WHERE from_addr = ? AND id = ?',
+  updateRun: 'UPDATE kernel_runs SET status = ?, asked = ?, asking = ?, progress = ?, rev = rev + 1 WHERE from_addr = ? AND id = ? RETURNING *',
+  // Without a progress of its own, an outcome carries the run's last one (C4).
+  endRun: `UPDATE kernel_runs SET status = ?, result = ?, error = ?, progress = coalesce(?, progress), rev = rev + 1
+           WHERE from_addr = ? AND id = ? RETURNING to_addr, root, progress`,
+  runs: `SELECT * FROM kernel_runs WHERE to_addr = ? AND ${UNENDED_RUN} AND status = coalesce(?, status)`,
+
+  timer: 'SELECT * FROM kernel_timers WHERE from_addr = ? AND id = ?',
+  timers: 'SELECT * FROM kernel_timers WHERE from_addr = ?',
+  addTimer: `INSERT INTO kernel_timers (from_addr, id, to_addr, op, digest, input, parent, lane, by_from, by_id, awaited, memo, due)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  dropTimer: 'DELETE FROM kernel_timers WHERE from_addr = ? AND id = ?',
+  detachTimer: 'UPDATE kernel_timers SET awaited = 0 WHERE from_addr = ? AND id = ?',
+  // Timers due at the same time come due in the order they were registered (7).
+  dueTimers: 'SELECT * FROM kernel_timers WHERE due <= ? ORDER BY due, rowid',
+  firstDue: 'SELECT min(due) AS due FROM kernel_timers',
+  awaitedTimer: 'SELECT 1 FROM kernel_timers WHERE by_from = ? AND by_id = ? AND awaited = 1',
+  dropRunTimers: 'DELETE FROM kernel_timers WHERE by_from = ? AND by_id = ?',
+
+  // Only the number of an answer taken is kept, and which question it answered (C8, S8).
+  answer: 'SELECT 1 FROM kernel_answers WHERE from_addr = ? AND id = ?',
+  addAnswer: 'INSERT INTO kernel_answers (from_addr, id, run_from, run_id, asked) VALUES (?, ?, ?, ?, ?)',
+
+  // A letter is identified by `seq` and ordered by `pos`: a letter that replaces another takes the other's `pos` (R3).
+  owe: `INSERT INTO kernel_outbox (pos, from_addr, to_addr, lane, kind, call_from, call_id, envelope)
+        VALUES (coalesce(?, (SELECT coalesce(max(pos), 0) + 1 FROM kernel_outbox)), ?, ?, ?, ?, ?, ?, ?)`,
+  // The first letter after `pos` that may go now: one without a lane, or the oldest of its lane (C10).
+  next: `SELECT * FROM kernel_outbox AS o
+         WHERE pos > ? AND (lane IS NULL OR pos = (SELECT min(pos) FROM kernel_outbox WHERE lane = o.lane))
+         ORDER BY pos LIMIT 1`,
+  dropLetter: 'DELETE FROM kernel_outbox WHERE seq = ?',
+  dropCallLetter: "DELETE FROM kernel_outbox WHERE call_from = ? AND call_id = ? AND kind = 'call' RETURNING pos",
+  cancelLetter: "SELECT 1 FROM kernel_outbox WHERE call_from = ? AND call_id = ? AND kind = 'cancel'",
+  dropCancelLetter: "DELETE FROM kernel_outbox WHERE call_from = ? AND call_id = ? AND kind = 'cancel'",
+  dropStatusLetter: "DELETE FROM kernel_outbox WHERE call_from = ? AND call_id = ? AND kind = 'status' RETURNING pos",
+  letters: 'SELECT kind, to_addr, call_from, call_id FROM kernel_outbox WHERE from_addr = ? ORDER BY pos',
+};

package/src/transaction.mjs

@@ -0,0 +1,75 @@
+/**
+ * Transactions and the output gate (T1, T3, T5). Effects registered while a transaction is open wait for the outermost
+ * COMMIT; a rollback at any level drops what that level registered.
+ */
+export class Transactions {
+  #db;
+  #report;
+  #committed;
+  /** @type {Array<Array<() => void>>} effects registered per open level, outermost first */
+  #levels = [];
+
+  /**
+   * @param {import('node:sqlite').DatabaseSync} db
+   * @param {(error: unknown) => void} report
+   * @param {() => void} committed runs after every outermost commit, once its effects have run
+   */
+  constructor(db, report, committed) {
+    this.#db = db;
+    this.#report = report;
+    this.#committed = committed;
+  }
+
+  get open() {
+    return this.#levels.length > 0;
+  }
+
+  /**
+   * @template T
+   * @param {() => T} fn
+   * @returns {T}
+   */
+  run(fn) {
+    const depth = this.#levels.length;
+    const name = `kernel_${depth}`;
+    this.#db.exec(depth === 0 ? 'BEGIN IMMEDIATE' : `SAVEPOINT ${name}`);
+    this.#levels.push([]);
+    let value;
+    try {
+      value = fn();
+      if (typeof value?.then === 'function') throw new Error('a transaction function must be synchronous');
+    } catch (error) {
+      this.#levels.pop();
+      this.#db.exec(depth === 0 ? 'ROLLBACK' : `ROLLBACK TO ${name}; RELEASE ${name}`);
+      throw error;
+    }
+    const effects = this.#levels.pop();
+    if (depth > 0) {
+      this.#db.exec(`RELEASE ${name}`);
+      this.#levels[depth - 1].push(...effects);
+      return value;
+    }
+    try {
+      this.#db.exec('COMMIT');
+    } catch (error) {
+      // A failed COMMIT may leave the transaction open; nothing of it may survive, and nothing is released (T5).
+      if (this.#db.isTransaction) this.#db.exec('ROLLBACK');
+      throw error;
+    }
+    for (const effect of effects) {
+      try {
+        effect();
+      } catch (error) {
+        this.#report(error);
+      }
+    }
+    this.#committed();
+    return value;
+  }
+
+  /** @param {() => void} fn */
+  after(fn) {
+    if (!this.open) throw new Error('afterCommit() must be called inside kernel.transaction()');
+    this.#levels.at(-1).push(fn);
+  }
+}