@blamejs/core 0.4.1

package/lib/cluster-provider-db.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Default cluster-coordination provider — DB-row-based leader election.
+ *
+ * Uses an externalDb backend (already configured via b.externalDb.init)
+ * as the coordination point. A single row in `_blamejs_leader` holds
+ * the current lease; acquireLease is `INSERT ... ON CONFLICT ... DO
+ * UPDATE WHERE expiresAt < now() RETURNING ...`, which is atomic in
+ * Postgres and SQLite.
+ *
+ * Fencing tokens: every successful acquire bumps a monotonic integer.
+ * Leader-only DB writes include the current token; the audit-tip row's
+ * CHECK constraint rejects any incoming token below the stored one,
+ * which fences out a partitioned old leader even if its application-
+ * layer `_requireLeader()` gate somehow allowed the call through.
+ *
+ * Dialects: Postgres and SQLite use identical surface SQL. MySQL's
+ * `ON DUPLICATE KEY UPDATE` doesn't support a WHERE clause; a MySQL
+ * fallback (SELECT ... FOR UPDATE inside an explicit transaction) is
+ * not yet implemented and operators on MySQL must supply their own
+ * provider until it lands.
+ *
+ * Public API:
+ *   create({ externalDbBackend, dialect? }) → provider instance
+ *
+ * Provider instance:
+ *   ensureSchema()                                async; idempotent CREATE
+ *                                                 TABLE + ALTER for
+ *                                                 endpoint migration
+ *   acquireLease(nodeId, leaseTtlMs, opts?)       async; → Lease | null.
+ *                                                 opts.endpoint persists
+ *                                                 in the row for discovery.
+ *   renewLease(lease, opts?)                      async; → Lease (throws on
+ *                                                 takeover). opts.endpoint
+ *                                                 refreshes the row.
+ *   releaseLease(lease)                           async; → void
+ *   currentLeader()                               async; →
+ *                                                 { nodeId, leaseExpiresAt,
+ *                                                   fencingToken,
+ *                                                   endpoint } | null
+ *
+ * Lease object shape:
+ *   { nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint }
+ */
+var { generateToken } = require("./crypto");
+var externalDb = require("./external-db");
+var { ClusterProviderError } = require("./framework-error");
+
+var _err = ClusterProviderError.factory;
+
+function create(config) {
+  if (!config || !config.externalDbBackend) {
+    throw _err("INVALID_CONFIG",
+      "cluster-provider-db requires { externalDbBackend: <name> }", true);
+  }
+  var backendName = config.externalDbBackend;
+  var dialect = (config.dialect || "postgres").toLowerCase();
+  if (dialect !== "postgres" && dialect !== "sqlite") {
+    throw _err("UNSUPPORTED_DIALECT",
+      "cluster-provider-db dialect must be 'postgres' or 'sqlite' (got: " + dialect + ")",
+      true);
+  }
+
+  // Postgres uses $1/$2 placeholders; SQLite accepts the same so we use
+  // them uniformly. If a future dialect needs ?-placeholders, swap here.
+  function _placeholder(n) { return "$" + n; }
+
+  function _q(sql, params) {
+    return externalDb.query(sql, params || [], { backend: backendName });
+  }
+
+  async function ensureSchema() {
+    // Postgres: BIGINT for ms-precision timestamps. SQLite: INTEGER works
+    // for either; pick INTEGER so the same DDL parses on both.
+    var intType = dialect === "postgres" ? "BIGINT" : "INTEGER";
+
+    await _q(
+      "CREATE TABLE IF NOT EXISTS _blamejs_leader (" +
+      "  scope         TEXT PRIMARY KEY," +
+      "  nodeId        TEXT NOT NULL," +
+      "  leaseId       TEXT NOT NULL," +
+      "  acquiredAt    " + intType + " NOT NULL," +
+      "  expiresAt     " + intType + " NOT NULL," +
+      "  fencingToken  " + intType + " NOT NULL," +
+      "  endpoint      TEXT," +
+      "  CHECK (scope = 'leader')" +
+      ")"
+    );
+    // Migration for installs that pre-date the endpoint column. Both
+    // Postgres (≥9.6) and SQLite (≥3.35, March 2021) support ADD COLUMN
+    // IF NOT EXISTS, but we go through try/catch to keep the path
+    // dialect-version-agnostic — the only "expected" failure here is
+    // "column already exists," which we swallow.
+    try {
+      await _q("ALTER TABLE _blamejs_leader ADD COLUMN endpoint TEXT");
+    } catch (_e) { /* column already exists — fine */ }
+
+    // _blamejs_cluster_state — single-row consistency check used to
+    // detect vault-key drift across cluster nodes. Same single-row
+    // invariant pattern as _blamejs_leader (PRIMARY KEY on a
+    // constant-valued scope column + CHECK).
+    await _q(
+      "CREATE TABLE IF NOT EXISTS _blamejs_cluster_state (" +
+      "  scope           TEXT PRIMARY KEY," +
+      "  vaultKeyFp      TEXT NOT NULL," +
+      "  recordedAt      " + intType + " NOT NULL," +
+      "  recordedByNode  TEXT NOT NULL," +
+      "  CHECK (scope = 'state')" +
+      ")"
+    );
+  }
+
+  async function acquireLease(nodeId, leaseTtlMs, opts) {
+    if (!nodeId) throw _err("INVALID_NODE_ID", "nodeId required", true);
+    if (typeof leaseTtlMs !== "number" || leaseTtlMs <= 0) {
+      throw _err("INVALID_TTL", "leaseTtlMs must be a positive number", true);
+    }
+    var endpoint = (opts && opts.endpoint) || null;
+    var leaseId = generateToken(16);
+    var nowMs = Date.now();
+    var expiresAt = nowMs + leaseTtlMs;
+
+    // Atomic acquire: insert if no row, OR steal if existing row's
+    // expiresAt has passed. Bump fencingToken on every successful
+    // mutation. RETURNING gives us the post-write state — which we
+    // compare to our nodeId to know whether we won.
+    var sql =
+      "INSERT INTO _blamejs_leader " +
+      "  (scope, nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint) " +
+      "VALUES " +
+      "  ('leader', " + _placeholder(1) + ", " + _placeholder(2) + ", " +
+      "   " + _placeholder(3) + ", " + _placeholder(4) + ", 1, " + _placeholder(5) + ") " +
+      "ON CONFLICT (scope) DO UPDATE SET " +
+      "  nodeId       = EXCLUDED.nodeId," +
+      "  leaseId      = EXCLUDED.leaseId," +
+      "  acquiredAt   = EXCLUDED.acquiredAt," +
+      "  expiresAt    = EXCLUDED.expiresAt," +
+      "  fencingToken = _blamejs_leader.fencingToken + 1," +
+      "  endpoint     = EXCLUDED.endpoint " +
+      "WHERE _blamejs_leader.expiresAt < " + _placeholder(6) + " " +
+      "RETURNING nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint";
+
+    var result = await _q(sql, [nodeId, leaseId, nowMs, expiresAt, endpoint, nowMs]);
+
+    if (!result.rows || result.rows.length === 0) {
+      // The WHERE clause excluded the row — someone else still holds.
+      return null;
+    }
+    var row = result.rows[0];
+    if (row.nodeId !== nodeId || row.leaseId !== leaseId) {
+      // Another node won the race (RETURNING showed their values, not ours).
+      return null;
+    }
+    return {
+      nodeId:        row.nodeId,
+      leaseId:       row.leaseId,
+      acquiredAt:    Number(row.acquiredAt),
+      expiresAt:     Number(row.expiresAt),
+      fencingToken:  Number(row.fencingToken),
+      endpoint:      row.endpoint || null,
+    };
+  }
+
+  async function renewLease(lease, opts) {
+    if (!lease || !lease.leaseId) throw _err("INVALID_LEASE", "lease required", true);
+    var nowMs = Date.now();
+    var newExpiresAt = nowMs + (lease.expiresAt - lease.acquiredAt);
+    // opts.endpoint, when provided, refreshes the stored endpoint so
+    // operators who hot-update their config see the discovery row catch
+    // up. Default = preserve whatever was stored at acquire time.
+    var endpoint = (opts && opts.endpoint !== undefined) ? opts.endpoint : lease.endpoint || null;
+
+    // Match on (nodeId, leaseId) so a takeover is detectable: if our
+    // leaseId is no longer in the row, 0 rows update and we throw
+    // NotLeader. Don't bump fencingToken on renewal — only on a fresh
+    // acquire.
+    var sql =
+      "UPDATE _blamejs_leader SET " +
+      "  expiresAt = " + _placeholder(1) + "," +
+      "  endpoint  = " + _placeholder(2) + " " +
+      "WHERE scope = 'leader' AND nodeId = " + _placeholder(3) +
+      "  AND leaseId = " + _placeholder(4) + " " +
+      "RETURNING nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint";
+
+    var result = await _q(sql, [newExpiresAt, endpoint, lease.nodeId, lease.leaseId]);
+    if (!result.rows || result.rows.length === 0) {
+      throw _err("LEASE_LOST",
+        "lease for node '" + lease.nodeId + "' was taken over (renewal rejected)",
+        false);
+    }
+    var row = result.rows[0];
+    return {
+      nodeId:        row.nodeId,
+      leaseId:       row.leaseId,
+      acquiredAt:    Number(row.acquiredAt),
+      expiresAt:     Number(row.expiresAt),
+      fencingToken:  Number(row.fencingToken),
+      endpoint:      row.endpoint || null,
+    };
+  }
+
+  async function releaseLease(lease) {
+    if (!lease || !lease.leaseId) return;
+    // Clear our row so the next acquire wins immediately. Match on
+    // leaseId so a takeover-then-release race doesn't clear someone
+    // else's lease.
+    var sql =
+      "UPDATE _blamejs_leader SET " +
+      "  expiresAt = 0 " +
+      "WHERE scope = 'leader' AND nodeId = " + _placeholder(1) +
+      "  AND leaseId = " + _placeholder(2);
+    await _q(sql, [lease.nodeId, lease.leaseId]);
+  }
+
+  async function currentLeader() {
+    var result = await _q(
+      "SELECT nodeId, expiresAt, fencingToken, endpoint FROM _blamejs_leader " +
+      "WHERE scope = 'leader'"
+    );
+    if (!result.rows || result.rows.length === 0) return null;
+    var row = result.rows[0];
+    if (Number(row.expiresAt) < Date.now()) return null;
+    return {
+      nodeId:           row.nodeId,
+      leaseExpiresAt:   Number(row.expiresAt),
+      fencingToken:     Number(row.fencingToken),
+      endpoint:         row.endpoint || null,
+    };
+  }
+
+  return {
+    kind:           "db",
+    backendName:    backendName,
+    dialect:        dialect,
+    ensureSchema:   ensureSchema,
+    acquireLease:   acquireLease,
+    renewLease:     renewLease,
+    releaseLease:   releaseLease,
+    currentLeader: currentLeader,
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/cluster-storage.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Framework-state SQL dispatch — runs against local SQLite in single-
+ * node mode and against external-db in cluster mode.
+ *
+ * audit / consent / sessions / queue / subject all read and write the
+ * framework's own tables (audit_log, consent_log, …). In single-node
+ * mode those tables live in the framework's own SQLite (lib/db.js).
+ * In cluster mode they live in the operator-supplied external-db with
+ * a `_blamejs_` prefix to avoid colliding with app tables.
+ *
+ * This module is the dispatch primitive. Callers write SQL once using
+ * unprefixed table names + `?` placeholders; the dispatcher translates
+ * to the active backend's flavor:
+ *
+ *   single-node     local SQLite via db().prepare(sql).run/get/all(...)
+ *   cluster (sqlite) externalDb.query(sql, params)              ? placeholders
+ *   cluster (postgres) externalDb.query(translated, params)     $1, $2, …
+ *
+ * Tables are translated through frameworkSchema.tableName so callers
+ * use logical names (audit_log) and the resolved name is automatically
+ * prefixed in cluster mode (_blamejs_audit_log).
+ *
+ * The dispatcher is async-only — the operator's external-db driver
+ * is async, and even local-SQLite calls return a resolved Promise to
+ * keep the call shape uniform. Callers `await` this module's methods;
+ * audit / consent / queue / session / subject all thread `async` /
+ * `await` through their own surfaces to match.
+ *
+ * Public API:
+ *   await execute(sql, params?)    { rows, rowCount }
+ *   tableName(local)               external-db prefixed name (or unchanged
+ *                                  in single-node mode)
+ *   placeholderize(sql, dialect)   `?` to `$N` for postgres; passthrough
+ *                                  for sqlite
+ *   resolveTables(sql)             rewrites bare unprefixed table names
+ *                                  in cluster mode (only the framework's
+ *                                  known tables are rewritten — operator
+ *                                  app-data SQL is unaffected)
+ */
+
+var cluster = require("./cluster");
+var frameworkSchema = require("./framework-schema");
+var externalDb = require("./external-db");
+var lazyRequire = require("./lazy-require");
+var { FrameworkError } = require("./framework-error");
+
+class ClusterStorageError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "ClusterStorageError";
+    this.code = code || "cluster-storage/invalid";
+    this.isClusterStorageError = true;
+  }
+}
+
+// ---- Lazy db ref to avoid circular require ----
+var _localDb = lazyRequire(function () { return require("./db"); });
+
+// ---- Table-name resolution ----
+
+function tableName(local) {
+  if (cluster.isClusterMode()) return frameworkSchema.tableName(local);
+  return local;
+}
+
+// Rewrite bare table names in SQL when running in cluster mode. We only
+// touch tokens that are exactly one of the framework's known table names
+// (audit_log, consent_log, …) — anything else passes through unchanged
+// so app-data SQL composed via this dispatcher (or operator-written
+// migrations) isn't rewritten by accident.
+function resolveTables(sql) {
+  if (!cluster.isClusterMode()) return sql;
+  var mapping = frameworkSchema.LOCAL_TO_EXTERNAL;
+  // Order longest-first so prefix matches don't collide (audit_log
+  // before audit). Match on word boundaries so we don't rewrite a
+  // suffix of a longer identifier.
+  var localNames = Object.keys(mapping).sort(function (a, b) { return b.length - a.length; });
+  var translated = sql;
+  for (var i = 0; i < localNames.length; i++) {
+    var local = localNames[i];
+    var external = mapping[local];
+    if (local === external) continue;          // identity mapping — no-op
+    var re = new RegExp("\\b" + local.replace(/[\\.-]/g, "\\$&") + "\\b", "g");
+    translated = translated.replace(re, external);
+  }
+  return translated;
+}
+
+// ---- Placeholder translation ----
+//
+// SQLite and Postgres both accept `?` in some contexts, but Postgres
+// only accepts `$N` for parameter binding. We translate at dispatch
+// time so callers always write `?` and the right thing happens per
+// dialect.
+
+function placeholderize(sql, dialect) {
+  if (dialect !== "postgres") return sql;
+  // Walk the SQL and replace `?` with $1, $2, … but skip ones inside
+  // single-quoted string literals.
+  var out = "";
+  var n = 0;
+  var inStr = false;
+  for (var i = 0; i < sql.length; i++) {
+    var c = sql.charAt(i);
+    if (c === "'" && !inStr) { inStr = true;  out += c; continue; }
+    if (c === "'" &&  inStr) {
+      // Handle escaped '' inside string
+      if (sql.charAt(i + 1) === "'") { out += "''"; i += 1; continue; }
+      inStr = false; out += c; continue;
+    }
+    if (!inStr && c === "?") { n += 1; out += "$" + n; continue; }
+    out += c;
+  }
+  return out;
+}
+
+// ---- execute() ----
+
+async function execute(sql, params) {
+  if (typeof sql !== "string") {
+    throw new ClusterStorageError("sql must be a string", "cluster-storage/bad-arg");
+  }
+  params = params || [];
+
+  if (cluster.isClusterMode()) {
+    var translated = placeholderize(resolveTables(sql), cluster.dialect());
+    var result = await externalDb.query(translated, params, {
+      backend: cluster.externalDbBackend(),
+    });
+    return result;
+  }
+
+  // Local SQLite path. node:sqlite is sync — wrap in a resolved Promise
+  // so callers always see the same shape regardless of mode.
+  var stmt = _localDb().prepare(sql);
+  // Heuristic: if the statement returns rows (SELECT or has RETURNING),
+  // use .all(); otherwise .run() and report changes as rowCount.
+  if (/^\s*SELECT\b/i.test(sql) || /\bRETURNING\b/i.test(sql)) {
+    var rows = stmt.all.apply(stmt, params);
+    return { rows: rows, rowCount: rows.length };
+  }
+  var info = stmt.run.apply(stmt, params);
+  return { rows: [], rowCount: info.changes };
+}
+
+// Convenience wrappers for the two common patterns.
+async function executeOne(sql, params) {
+  var result = await execute(sql, params);
+  return result.rows.length > 0 ? result.rows[0] : null;
+}
+
+async function executeAll(sql, params) {
+  var result = await execute(sql, params);
+  return result.rows;
+}
+
+module.exports = {
+  execute:               execute,
+  executeOne:            executeOne,
+  executeAll:            executeAll,
+  tableName:             tableName,
+  resolveTables:         resolveTables,
+  placeholderize:        placeholderize,
+  ClusterStorageError:   ClusterStorageError,
+};