@blamejs/core 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.3** (2026-05-01) — externalDb pool tuning + role-aware connect + read-replica routing
+- **0.6.2** (2026-05-01) — input validation + identifier-quoting consistency
 - **0.6.1** (2026-05-01) — security tightenings + operator-facing jargon sweep
 - **0.6.0** (2026-05-01) — wiki restructured into 22 focused pages + missing-primitive coverage
 

package/README.md

@@ -17,7 +17,7 @@ The modern Node app is a 1,200-package supply-chain liability with no LTS calend
 
 ## Status
 
-Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.2** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
+Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.3** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
 
 ```js
 var b = require("@blamejs/core");
@@ -63,6 +63,7 @@ Full primitive-by-primitive docs live at [blamejs.com](https://blamejs.com), whi
 - **Validation** — [Safe Parsers](https://blamejs.com/safe-parsers)
 - **Communication** — [WebSockets](https://blamejs.com/websockets) · [Mail](https://blamejs.com/mail) · [Notifications](https://blamejs.com/notifications)
 - **Tools** — [Observability](https://blamejs.com/observability) · [Testing](https://blamejs.com/testing) · [i18n & Locale](https://blamejs.com/i18n-locale) · [Format Helpers](https://blamejs.com/format-helpers)
+- **Compliance** — [Compliance Patterns](https://blamejs.com/compliance-patterns)
 - **Production** — [Cluster Mode](https://blamejs.com/cluster) · [Reliability](https://blamejs.com/reliability) · [Backup & Restore](https://blamejs.com/backup-restore)
 
 ## CLI

package/lib/external-db.js

@@ -54,6 +54,7 @@ var retryHelper = require("./retry");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
+var safeSql = require("./safe-sql");
 var { ExternalDbError } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
@@ -187,6 +188,9 @@ function init(opts) {
       residencyTag:    cfg.residencyTag || "unrestricted",
       breaker:         new retryHelper.CircuitBreaker("externalDb:" + name, cfg.breaker),
       retryConfig:     cfg.retry || null,
+      replicas:        _buildReplicas(name, cfg),
+      replicaIdx:      0,    // round-robin cursor
+      replicaFallbackToPrimary: cfg.replicaFallbackToPrimary !== false,
     };
   }
 
@@ -380,6 +384,12 @@ async function shutdown() {
   if (!initialized) return;
   for (var name in backends) {
     try { await backends[name].pool.drain(); } catch (_e) { /* best effort */ }
+    var bk = backends[name];
+    if (bk && bk.replicas) {
+      for (var i = 0; i < bk.replicas.length; i++) {
+        try { await bk.replicas[i].pool.drain(); } catch (_e) { /* best effort */ }
+      }
+    }
   }
   backends = {};
   defaultBackend = null;
@@ -400,9 +410,173 @@ function _requireInit() {
   if (!initialized) throw _err("NOT_INITIALIZED", "externalDb.init() must be called first", true);
 }
 
+// ---- Read-replica routing ----
+//
+// Operators with a primary + replicas declare replicas alongside the
+// primary backend config:
+//
+//   externalDb.init({
+//     backends: {
+//       main: {
+//         connect, query,                          // primary
+//         replicas: [
+//           { connect: replica1, query, weight: 1 },
+//           { connect: replica2, query, weight: 2 },
+//         ],
+//         replicaFallbackToPrimary: true,          // default; on all-replicas-unhealthy,
+//                                                  //   read.query falls back to primary
+//       },
+//     },
+//   });
+//
+//   await externalDb.read.query("SELECT * FROM users");      // → replica
+//   await externalDb.write.query("INSERT INTO users ...");    // → primary
+//   await externalDb.query("...");                            // → primary (legacy, unchanged)
+//
+// Load balancing: weighted round-robin (default weight 1). Weights
+// expand into a static plan at init — a [w1, w2, w3] vector becomes a
+// pre-built index sequence, then read.query() advances replicaIdx.
+//
+// Health: each replica tracks `lastFailureAt`. After UNHEALTHY_COOLDOWN_MS
+// since the last failure, the replica re-enters the rotation. Operators
+// observing all-replicas-down see read.query() fall back to primary
+// (overridable via replicaFallbackToPrimary: false).
+
+var REPLICA_UNHEALTHY_COOLDOWN_MS = C.TIME.seconds(30);
+
+function _buildReplicas(backendName, cfg) {
+  if (!cfg.replicas) return null;
+  if (!Array.isArray(cfg.replicas) || cfg.replicas.length === 0) {
+    throw _err("INVALID_CONFIG",
+      "backend '" + backendName + "': replicas must be a non-empty array", true);
+  }
+  var out = [];
+  for (var i = 0; i < cfg.replicas.length; i++) {
+    var r = cfg.replicas[i];
+    if (!r || typeof r.connect !== "function") {
+      throw _err("INVALID_CONFIG",
+        "backend '" + backendName + "': replicas[" + i + "].connect must be a function", true);
+    }
+    if (typeof r.query !== "function") {
+      throw _err("INVALID_CONFIG",
+        "backend '" + backendName + "': replicas[" + i + "].query must be a function", true);
+    }
+    var weight = r.weight !== undefined ? r.weight : 1;
+    if (typeof weight !== "number" || !isFinite(weight) || weight <= 0 ||
+        Math.floor(weight) !== weight) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + backendName + "': replicas[" + i + "].weight must be a positive integer", true);
+    }
+    out.push({
+      index:           i,
+      pool:            new Pool(backendName + ":replica:" + i, r),
+      query:           r.query,
+      weight:          weight,
+      lastFailureAt:   0,
+      consecutiveFailures: 0,
+    });
+  }
+  return out;
+}
+
+function _pickReplica(b) {
+  if (!b.replicas || b.replicas.length === 0) return null;
+  var now = Date.now();
+  // Build a healthy candidate set.
+  var healthy = [];
+  for (var i = 0; i < b.replicas.length; i++) {
+    var r = b.replicas[i];
+    if (now - r.lastFailureAt >= REPLICA_UNHEALTHY_COOLDOWN_MS) healthy.push(r);
+  }
+  if (healthy.length === 0) return null;
+  // Weighted round-robin: walk by weight, advancing replicaIdx by 1 each
+  // call and modding by total weight. Each replica's "slot" in the
+  // sequence repeats `weight` times.
+  var totalWeight = 0;
+  for (var w = 0; w < healthy.length; w++) totalWeight += healthy[w].weight;
+  var cursor = (b.replicaIdx++) % totalWeight;
+  var acc = 0;
+  for (var c = 0; c < healthy.length; c++) {
+    acc += healthy[c].weight;
+    if (cursor < acc) return healthy[c];
+  }
+  return healthy[0];   // unreachable; defensive
+}
+
+async function _readQuery(sql, params, opts) {
+  _requireInit();
+  opts = opts || {};
+  var b = _pickBackend(opts);
+  if (!b.replicas || b.replicas.length === 0) {
+    // No replicas configured — read.query() returns primary.
+    return query(sql, params, opts);
+  }
+  var replica = _pickReplica(b);
+  if (!replica) {
+    if (b.replicaFallbackToPrimary) return query(sql, params, opts);
+    throw _err("ALL_REPLICAS_UNHEALTHY",
+      "backend '" + b.name + "': all replicas unhealthy and fallback disabled", true);
+  }
+  var t0 = Date.now();
+  try {
+    var client = await replica.pool.acquire();
+    try {
+      var res = await replica.query(client, sql, params || []);
+      replica.pool.release(client);
+      replica.consecutiveFailures = 0;
+      _emit("system.externaldb.read", "success", {
+        backend:    b.name,
+        replicaIdx: replica.index,
+        durationMs: Date.now() - t0,
+        rowCount:   res && res.rowCount,
+      });
+      return res;
+    } catch (e) {
+      // Connection-shape errors mark unhealthy + destroy.
+      if (e && (e.code === "ECONNRESET" || e.code === "ECONNREFUSED" ||
+                e.code === "ETIMEDOUT" || e.code === "ENOTFOUND" ||
+                e.code === "EPIPE")) {
+        await replica.pool.destroy(client);
+        replica.lastFailureAt = Date.now();
+        replica.consecutiveFailures += 1;
+      } else {
+        replica.pool.release(client);
+      }
+      throw e;
+    }
+  } catch (e) {
+    _emit("system.externaldb.read", "failure", {
+      backend:    b.name,
+      replicaIdx: replica.index,
+      durationMs: Date.now() - t0,
+      errorCode:  e.code || null,
+    }, (e && e.message) || String(e));
+    // Fallback to primary on a failed replica read when allowed.
+    if (b.replicaFallbackToPrimary) {
+      return query(sql, params, opts);
+    }
+    throw e;
+  }
+}
+
+var read = {
+  query: _readQuery,
+};
+
+// write namespace — alias for the primary path. Lets operators express
+// intent symmetrically with read.query without a magic-comment hint.
+var write = {
+  query:       function (sql, params, opts) { return query(sql, params, opts); },
+  transaction: function (fn, opts) { return transaction(fn, opts); },
+};
+
 function _resetForTest() {
   Object.keys(backends).forEach(function (n) {
     try { backends[n].pool.drain(); } catch (_e) {}
+    var bk = backends[n];
+    if (bk && bk.replicas) {
+      bk.replicas.forEach(function (r) { try { r.pool.drain(); } catch (_e) {} });
+    }
   });
   backends = {};
   defaultBackend = null;
@@ -411,6 +585,198 @@ function _resetForTest() {
   db.reset();
 }
 
+// ---- configurePool — runtime resize of an existing backend's pool ----
+//
+// Operators tune pool sizing without restarting the app. Existing idle
+// clients are kept; new acquisitions respect the new max. min is honored
+// the next time the pool refills. idleTimeoutMs takes effect on the next
+// reaper tick.
+function configurePool(backendName, opts) {
+  _requireInit();
+  if (typeof backendName !== "string" || backendName.length === 0) {
+    throw _err("INVALID_CONFIG", "configurePool: backendName must be a non-empty string", true);
+  }
+  var bk = backends[backendName];
+  if (!bk) throw _err("UNKNOWN_BACKEND", "configurePool: no backend named '" + backendName + "'", true);
+  if (!opts || typeof opts !== "object") {
+    throw _err("INVALID_CONFIG", "configurePool: opts must be an object", true);
+  }
+  var allowed = ["min", "max", "idleTimeoutMs"];
+  for (var k in opts) {
+    if (!Object.prototype.hasOwnProperty.call(opts, k)) continue;
+    if (allowed.indexOf(k) === -1) {
+      throw _err("INVALID_CONFIG",
+        "configurePool: unknown option '" + k + "'. Allowed: " + allowed.join(", "), true);
+    }
+  }
+  function _requirePosInt(name, value) {
+    if (typeof value !== "number" || !isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+      throw _err("INVALID_CONFIG",
+        "configurePool: " + name + " must be a positive integer, got " + JSON.stringify(value), true);
+    }
+  }
+  if (opts.min           !== undefined) _requirePosInt("min", opts.min);
+  if (opts.max           !== undefined) _requirePosInt("max", opts.max);
+  if (opts.idleTimeoutMs !== undefined) _requirePosInt("idleTimeoutMs", opts.idleTimeoutMs);
+  if (opts.min !== undefined && opts.max !== undefined && opts.min > opts.max) {
+    throw _err("INVALID_CONFIG", "configurePool: min must be <= max", true);
+  }
+  Object.assign(bk.pool.config, opts);
+}
+
+// ---- adapters.connectAs — Postgres role-aware connect wrapper ----
+//
+// Wraps an operator's connect() so that every fresh client runs
+// `SET ROLE`, `SET search_path`, `SET application_name`, and any other
+// operator-supplied GUCs at acquire time. The pattern enables the
+// search_path-views shape: the same SQL `SELECT * FROM sessions`
+// resolves to `public.sessions` for app_user and to
+// `analytics.sessions` (a view with PHI redacted) for analytics_user.
+// See the "Compliance Patterns" wiki page.
+//
+// Identifier inputs (role, schemas in searchPath) are validated via
+// safeSql.validateIdentifier — bad shapes throw at the call site. String
+// values (applicationName, statement_timeout) are quoted as SQL string
+// literals with single-quote escaping per the SQL standard.
+//
+//   connect: b.externalDb.adapters.connectAs(rawConnect, {
+//     role:               "analytics_user",
+//     searchPath:         ["analytics", "public"],
+//     applicationName:    "wiki:analytics",
+//     statementTimeoutMs: C.TIME.seconds(30),
+//     gucs: {
+//       idle_in_transaction_session_timeout: "60s",
+//     },
+//   })
+//
+// `query` is the same query function the backend declares; the wrapper
+// uses it to issue the SET statements.
+function _connectAs(rawConnect, query, opts) {
+  if (typeof rawConnect !== "function") {
+    throw _err("INVALID_CONFIG", "connectAs: connect must be a function", true);
+  }
+  if (typeof query !== "function") {
+    throw _err("INVALID_CONFIG", "connectAs: query must be a function", true);
+  }
+  opts = opts || {};
+  var allowed = ["role", "searchPath", "applicationName", "statementTimeoutMs", "gucs"];
+  for (var k in opts) {
+    if (!Object.prototype.hasOwnProperty.call(opts, k)) continue;
+    if (allowed.indexOf(k) === -1) {
+      throw _err("INVALID_CONFIG",
+        "connectAs: unknown option '" + k + "'. Allowed: " + allowed.join(", "), true);
+    }
+  }
+
+  // Validate inputs at config time so a malformed name surfaces at
+  // boot rather than on the first connection.
+  if (opts.role !== undefined) {
+    safeSql.validateIdentifier(String(opts.role), { allowReserved: false });
+  }
+  var pathSegments = null;
+  if (opts.searchPath !== undefined) {
+    var raw = Array.isArray(opts.searchPath) ? opts.searchPath : [opts.searchPath];
+    if (raw.length === 0) {
+      throw _err("INVALID_CONFIG", "connectAs: searchPath must have at least one schema", true);
+    }
+    pathSegments = [];
+    for (var pi = 0; pi < raw.length; pi++) {
+      safeSql.validateIdentifier(String(raw[pi]), { allowReserved: false });
+      pathSegments.push(String(raw[pi]));
+    }
+  }
+  if (opts.applicationName !== undefined && typeof opts.applicationName !== "string") {
+    throw _err("INVALID_CONFIG", "connectAs: applicationName must be a string", true);
+  }
+  if (opts.statementTimeoutMs !== undefined) {
+    if (typeof opts.statementTimeoutMs !== "number" || !isFinite(opts.statementTimeoutMs) ||
+        opts.statementTimeoutMs <= 0 || Math.floor(opts.statementTimeoutMs) !== opts.statementTimeoutMs) {
+      throw _err("INVALID_CONFIG",
+        "connectAs: statementTimeoutMs must be a positive integer", true);
+    }
+  }
+  if (opts.gucs !== undefined && (typeof opts.gucs !== "object" || opts.gucs === null)) {
+    throw _err("INVALID_CONFIG", "connectAs: gucs must be an object", true);
+  }
+  if (opts.gucs) {
+    for (var gname in opts.gucs) {
+      // GUC names: Postgres NAMEDATALEN-shaped identifiers.
+      safeSql.validateIdentifier(gname, { allowReserved: true });
+    }
+  }
+
+  // Pre-compute the SET statements once — every fresh client runs the
+  // same list, so building it per-connect would burn microbenchmarks.
+  var stmts = [];
+  if (opts.role) {
+    stmts.push('SET ROLE "' + opts.role + '"');
+  }
+  if (pathSegments) {
+    var pathSql = pathSegments.map(function (s) { return '"' + s + '"'; }).join(", ");
+    stmts.push("SET search_path TO " + pathSql);
+  }
+  if (opts.applicationName !== undefined) {
+    // Single-quoted string literal — SQL-standard escape doubles embedded
+    // single quotes.
+    var an = String(opts.applicationName).replace(/'/g, "''");
+    stmts.push("SET application_name TO '" + an + "'");
+  }
+  if (opts.statementTimeoutMs !== undefined) {
+    stmts.push("SET statement_timeout TO " + opts.statementTimeoutMs);
+  }
+  if (opts.gucs) {
+    for (var gn in opts.gucs) {
+      var gv = opts.gucs[gn];
+      if (typeof gv === "number") {
+        stmts.push('SET "' + gn + '" TO ' + gv);
+      } else {
+        var gvs = String(gv).replace(/'/g, "''");
+        stmts.push('SET "' + gn + '" TO \'' + gvs + "'");
+      }
+    }
+  }
+
+  return async function wrappedConnect() {
+    var client = await rawConnect();
+    try {
+      for (var i = 0; i < stmts.length; i++) {
+        await query(client, stmts[i], []);
+      }
+    } catch (e) {
+      // Initialization failed — the operator's close hook isn't visible
+      // here, so we throw and let the pool's catch destroy the partial
+      // client.
+      throw e;
+    }
+    return client;
+  };
+}
+
+// Operators import the helper as `b.externalDb.adapters.connectAs(connect, opts)`
+// — declarative wrapping with shared input validation.
+function _adaptersConnectAs(connect, opts) {
+  // The backend's query function is needed to issue SET statements on a
+  // freshly-acquired client. Operators pass it via opts.query — same
+  // function they declare on the backend itself.
+  if (!opts || typeof opts !== "object") {
+    throw _err("INVALID_CONFIG",
+      "adapters.connectAs: opts must be an object", true);
+  }
+  if (typeof opts.query !== "function") {
+    throw _err("INVALID_CONFIG",
+      "adapters.connectAs: opts.query is required (the backend's query function)", true);
+  }
+  // Pull query off and pass the remaining role-aware opts.
+  var query = opts.query;
+  var roleOpts = {};
+  for (var k in opts) {
+    if (Object.prototype.hasOwnProperty.call(opts, k) && k !== "query") {
+      roleOpts[k] = opts[k];
+    }
+  }
+  return _connectAs(connect, query, roleOpts);
+}
+
 module.exports = {
   init:           init,
   query:          query,
@@ -418,6 +784,12 @@ module.exports = {
   healthCheck:    healthCheck,
   listBackends:   listBackends,
   shutdown:       shutdown,
+  configurePool:  configurePool,
+  read:           read,
+  write:          write,
+  adapters: {
+    connectAs:    _adaptersConnectAs,
+  },
   Pool:           Pool,
   _resetForTest:  _resetForTest,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",