@blamejs/core 0.14.17 → 0.14.18

package/lib/queue-local.js

@@ -28,6 +28,18 @@
  * before INSERT; lease unseals the leased rows before returning to
  * the caller. cluster-storage's RETURNING clause hands back sealed
  * blobs which we run through cryptoField.unsealRow explicitly.
+ *
+ * Bring-your-own database: the local backend defaults to the
+ * framework's main DB (single-node) / external-db (cluster) via
+ * cluster-storage, and to the table "_blamejs_jobs". An operator can
+ * point the backend at their own store, table, and schema through the
+ * protocol config — see create(config). The physical table reference
+ * is composed through b.safeSql identifier quoting (never raw string
+ * interpolation), so an operator-supplied table/schema cannot smuggle
+ * SQL through the identifier slot (SQL identifier injection, CWE-89).
+ * Sealing stays keyed off the logical column map registered for
+ * "_blamejs_jobs", so payload + lastError remain sealed regardless of
+ * which physical table the rows land in.
  */
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
@@ -37,11 +49,22 @@ var cryptoField = require("./crypto-field");
 var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var safeJson = require("./safe-json");
+var safeSql = require("./safe-sql");
 var scheduler = require("./scheduler");
 var { QueueError } = require("./framework-error");
 
 var _err = QueueError.factory;
 
+// Logical table name the field-crypto schema is keyed on. This is the
+// COLUMN→seal map registered in db.js's FRAMEWORK_SCHEMA, NOT the
+// physical table the SQL writes to. An operator who points the backend
+// at their own table still seals payload + lastError through this map,
+// so a bring-your-own table inherits the same at-rest protection.
+var SEAL_TABLE = "_blamejs_jobs";
+
+// Default physical table for the local backend.
+var DEFAULT_TABLE = "_blamejs_jobs";
+
 // vault is lazy-required because some flows (sealed lastError) only
 // touch it on retry-with-error paths, and the import order
 // (queue-local → vault → db → audit → cluster) tolerates the late bind.
@@ -84,7 +107,7 @@ function _shapeLeasedRow(raw) {
   // raw is a row coming back from RETURNING — payload is sealed if
   // present. Run through cryptoField's unseal pipeline so the caller
   // gets cleartext.
-  var unsealed = cryptoField.unsealRow("_blamejs_jobs", raw);
+  var unsealed = cryptoField.unsealRow(SEAL_TABLE, raw);
   return {
     jobId:          unsealed._id,
     queueName:      unsealed.queueName,
@@ -102,9 +125,78 @@ function _shapeLeasedRow(raw) {
   };
 }
 
-function create(_config) {
-  // No protocol-level config — uses cluster-storage which dispatches
-  // to the framework's main DB (single-node) or external-db (cluster).
+// Validate a bring-your-own store handle at config time. It must expose
+// the execute / executeOne / executeAll trio that cluster-storage does,
+// since every method here dispatches through that surface.
+var _REQUIRED_STORE_METHODS = ["execute", "executeOne", "executeAll"];
+function _resolveStore(handle) {
+  if (handle === undefined || handle === null) return clusterStorage;
+  if (typeof handle !== "object") {
+    throw _err("INVALID_DB_HANDLE",
+      "queue local config.db must be a storage handle exposing execute/executeOne/executeAll, got " +
+        typeof handle, true);
+  }
+  for (var i = 0; i < _REQUIRED_STORE_METHODS.length; i++) {
+    var m = _REQUIRED_STORE_METHODS[i];
+    if (typeof handle[m] !== "function") {
+      throw _err("INVALID_DB_HANDLE",
+        "queue local config.db is missing required method '" + m + "()'", true);
+    }
+  }
+  return handle;
+}
+
+// Compose the physical table reference from config.table + config.schema,
+// quoting each identifier through b.safeSql so an operator-supplied name
+// cannot interpolate SQL through the identifier slot (CWE-89). Returns
+// the bare default name unquoted when no custom table/schema is given so
+// the framework's cluster-mode table rewrite (resolveTables) still fires
+// on the default jobs table; any custom name is fully validated + quoted.
+function _resolveTableRef(config) {
+  var table = config.table !== undefined && config.table !== null
+    ? config.table : DEFAULT_TABLE;
+  if (typeof table !== "string") {
+    throw _err("INVALID_TABLE",
+      "queue local config.table must be a string identifier, got " + typeof table, true);
+  }
+  var schema = config.schema;
+  if (schema !== undefined && schema !== null && typeof schema !== "string") {
+    throw _err("INVALID_SCHEMA",
+      "queue local config.schema must be a string identifier, got " + typeof schema, true);
+  }
+  var usingDefault = (table === DEFAULT_TABLE) &&
+    (schema === undefined || schema === null);
+  if (usingDefault) {
+    // Byte-identical default SQL — unquoted bare name so cluster-mode
+    // resolveTables continues to recognize and rewrite the jobs table.
+    return DEFAULT_TABLE;
+  }
+  // Any custom table/schema is validated + dialect-quoted. validateIdentifier
+  // / quoteQualified THROW (SafeSqlError) on a bad identifier; surface that
+  // as the queue's config-time error so the operator catches the typo at
+  // boot rather than on first enqueue.
+  try {
+    if (schema !== undefined && schema !== null && schema !== "") {
+      return safeSql.quoteQualified([schema, table]);
+    }
+    return safeSql.quoteIdentifier(table);
+  } catch (e) {
+    throw _err("INVALID_TABLE",
+      "queue local table/schema failed identifier validation: " + e.message, true);
+  }
+}
+
+function create(config) {
+  config = config || {};
+  // Bring-your-own store + table. Defaults preserve the prior behavior
+  // exactly: cluster-storage dispatch to the framework's main DB
+  // (single-node) / external-db (cluster), table "_blamejs_jobs".
+  var store = _resolveStore(config.db);
+  // qTable holds the physical table reference already validated +
+  // dialect-quoted by _resolveTableRef (via safeSql.quoteIdentifier /
+  // quoteQualified, or the framework's bare default name). The `q` prefix
+  // marks it as a safe-to-interpolate identifier so it is never re-quoted.
+  var qTable = _resolveTableRef(config);
 
   async function enqueue(queueName, payload, opts) {
     cluster.requireLeader();
@@ -171,11 +263,11 @@ function create(_config) {
       flowChildName:   flowChildName,
       dependsOn:       dependsOn,
     };
-    var sealed = cryptoField.sealRow("_blamejs_jobs", row);
+    var sealed = cryptoField.sealRow(SEAL_TABLE, row);
     var values = JOB_COLS.map(function (c) { return c in sealed ? sealed[c] : null; });
 
-    await clusterStorage.execute(
-      "INSERT INTO _blamejs_jobs (" + _quotedList(JOB_COLS) + ") " +
+    await store.execute(
+      "INSERT INTO " + qTable + " (" + _quotedList(JOB_COLS) + ") " +
       "VALUES (" + _placeholders(JOB_COLS) + ")",
       values
     );
@@ -201,16 +293,16 @@ function create(_config) {
     // can't be picked twice). RETURNING hands back the leased columns
     // so we don't need a separate SELECT after the UPDATE.
     var sql =
-      "UPDATE _blamejs_jobs " +
+      "UPDATE " + qTable + " " +
       "SET status = 'inflight', leasedAt = ?, leaseExpiresAt = ?, attempts = attempts + 1 " +
       "WHERE _id IN (" +
-      "  SELECT _id FROM _blamejs_jobs " +
+      "  SELECT _id FROM " + qTable + " " +
       "  WHERE queueName = ? AND status = 'pending' AND availableAt <= ? " +
       "  ORDER BY priority DESC, availableAt ASC, enqueuedAt ASC " +
       "  LIMIT ?" +
       ") " +
       "RETURNING " + _quotedList(LEASE_RETURN_COLS);
-    var result = await clusterStorage.execute(
+    var result = await store.execute(
       sql,
       [nowMs, leaseExpiresAt, queueName, nowMs, maxRows]
     );
@@ -232,8 +324,8 @@ function create(_config) {
         "extendLease: additionalMs must be a positive number", true);
     }
     var newExpiry = Date.now() + additionalMs;
-    var result = await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET leaseExpiresAt = ? " +
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET leaseExpiresAt = ? " +
       "WHERE _id = ? AND status = 'inflight'",
       [newExpiry, jobId]
     );
@@ -247,16 +339,16 @@ function create(_config) {
     // the status flip. Single SELECT + UPDATE pair under the same
     // jobId — race-free under SQLite (single-writer); cluster-storage
     // dispatches both calls to the same backend.
-    var rowRes = await clusterStorage.execute(
+    var rowRes = await store.execute(
       "SELECT _id, queueName, payload, repeatCron, repeatTimezone, " +
       "       flowId, flowChildName, priority, classification, traceId " +
-      "FROM _blamejs_jobs WHERE _id = ?",
+      "FROM " + qTable + " WHERE _id = ?",
       [jobId]
     );
     var row = (rowRes && rowRes.rows && rowRes.rows[0]) || null;
 
-    await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET status = 'done', finishedAt = ?, leaseExpiresAt = NULL " +
+    await store.execute(
+      "UPDATE " + qTable + " SET status = 'done', finishedAt = ?, leaseExpiresAt = NULL " +
       "WHERE _id = ? AND status = 'inflight'",
       [nowMs, jobId]
     );
@@ -266,7 +358,7 @@ function create(_config) {
     // re-enqueue — operators investigate before the cron resumes.
     if (row && row.repeatCron) {
       try {
-        var unsealedRow = cryptoField.unsealRow("_blamejs_jobs", row);
+        var unsealedRow = cryptoField.unsealRow(SEAL_TABLE, row);
         var cron = scheduler.parseCron(unsealedRow.repeatCron);
         var nextMs = scheduler.nextCronFire(cron, new Date(nowMs), unsealedRow.repeatTimezone || null);
         await enqueue(unsealedRow.queueName,
@@ -296,8 +388,8 @@ function create(_config) {
   }
 
   async function _maybeReleaseFlowChildren(flowId, completedJobId, completedChildName, nowMs) {
-    var siblingsRes = await clusterStorage.execute(
-      "SELECT _id, dependsOn, flowChildName, status, availableAt FROM _blamejs_jobs " +
+    var siblingsRes = await store.execute(
+      "SELECT _id, dependsOn, flowChildName, status, availableAt FROM " + qTable + " " +
       "WHERE flowId = ? AND status = 'pending' AND availableAt > ?",
       [flowId, nowMs]
     );
@@ -317,16 +409,16 @@ function create(_config) {
         // Quick path: just-completed job matches by id or child name.
         if (dep === completedJobId || (completedChildName && dep === completedChildName)) continue;
         // Otherwise SELECT to confirm done.
-        var depRes = await clusterStorage.execute(
-          "SELECT 1 FROM _blamejs_jobs WHERE flowId = ? AND status = 'done' AND " +
+        var depRes = await store.execute(
+          "SELECT 1 FROM " + qTable + " WHERE flowId = ? AND status = 'done' AND " +
           "  (_id = ? OR flowChildName = ?) LIMIT 1",
           [flowId, dep, dep]
         );
         if (!depRes || !depRes.rows || depRes.rows.length === 0) { allDone = false; break; }
       }
       if (allDone) {
-        await clusterStorage.execute(
-          "UPDATE _blamejs_jobs SET availableAt = ? WHERE _id = ?",
+        await store.execute(
+          "UPDATE " + qTable + " SET availableAt = ? WHERE _id = ?",
           [nowMs, sib._id]
         );
       }
@@ -345,8 +437,8 @@ function create(_config) {
     // status / availableAt / finishedAt updates per branch — same
     // semantics as the previous SELECT-then-UPDATE-in-transaction
     // path, but no cross-dialect transaction primitive needed.
-    await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET " +
+    await store.execute(
+      "UPDATE " + qTable + " SET " +
       "  status = CASE WHEN attempts < maxAttempts THEN 'pending' ELSE 'failed' END, " +
       "  lastError = ?, " +
       "  leaseExpiresAt = NULL, " +
@@ -360,8 +452,8 @@ function create(_config) {
 
   async function sweepExpired() {
     cluster.requireLeader();
-    var result = await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET status = 'pending', leaseExpiresAt = NULL " +
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET status = 'pending', leaseExpiresAt = NULL " +
       "WHERE status = 'inflight' AND leaseExpiresAt < ?",
       [Date.now()]
     );
@@ -369,8 +461,8 @@ function create(_config) {
   }
 
   async function size(queueName) {
-    var row = await clusterStorage.executeOne(
-      "SELECT COUNT(*) AS n FROM _blamejs_jobs " +
+    var row = await store.executeOne(
+      "SELECT COUNT(*) AS n FROM " + qTable + " " +
       "WHERE queueName = ? AND (status = 'pending' OR status = 'inflight')",
       [queueName]
     );
@@ -395,16 +487,16 @@ function create(_config) {
       }
       limit = opts.limit;
     }
-    var rows = await clusterStorage.executeAll(
+    var rows = await store.executeAll(
       "SELECT _id, queueName, payload, status, enqueuedAt, finishedAt, " +
       "       attempts, maxAttempts, lastError, traceId, classification " +
-      "FROM _blamejs_jobs " +
+      "FROM " + qTable + " " +
       "WHERE queueName = ? AND status = 'failed' " +
       "ORDER BY finishedAt DESC LIMIT ?",
       [queueName, limit]
     );
     return rows.map(function (row) {
-      var unsealed = cryptoField.unsealRow("_blamejs_jobs", row);
+      var unsealed = cryptoField.unsealRow(SEAL_TABLE, row);
       return {
         jobId:       row._id,
         queueName:   row.queueName,
@@ -424,8 +516,8 @@ function create(_config) {
   async function dlqRetry(jobId) {
     cluster.requireLeader();
     var nowMs = Date.now();
-    var result = await clusterStorage.execute(
-      "UPDATE _blamejs_jobs SET " +
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET " +
       "  status = 'pending', " +
       "  attempts = 0, " +
       "  availableAt = ?, " +
@@ -440,8 +532,8 @@ function create(_config) {
   }
 
   async function dlqSize(queueName) {
-    var row = await clusterStorage.executeOne(
-      "SELECT COUNT(*) AS n FROM _blamejs_jobs " +
+    var row = await store.executeOne(
+      "SELECT COUNT(*) AS n FROM " + qTable + " " +
       "WHERE queueName = ? AND status = 'failed'",
       [queueName]
     );
@@ -450,13 +542,30 @@ function create(_config) {
 
   async function purge(queueName) {
     cluster.requireLeader();
-    var result = await clusterStorage.execute(
-      "DELETE FROM _blamejs_jobs WHERE queueName = ?",
+    var result = await store.execute(
+      "DELETE FROM " + qTable + " WHERE queueName = ?",
       [queueName]
     );
     return result.rowCount || 0;
   }
 
+  // patchFlowDeps — the second pass of enqueueFlow. Writes the resolved
+  // dependsOn jobIds and parks availableAt at MAX_SAFE_INTEGER for a flow
+  // child that has dependencies. Lives on the backend (not in queue.js)
+  // so it targets THIS backend's configured store + table — a
+  // bring-your-own table receives the flow graph the same way the
+  // first-pass enqueue did, instead of the dispatcher writing to the
+  // default jobs table behind the backend's back. depIds is serialized
+  // to JSON for the dependsOn column.
+  async function patchFlowDeps(jobId, depIds) {
+    cluster.requireLeader();
+    var result = await store.execute(
+      "UPDATE " + qTable + " SET dependsOn = ?, availableAt = ? WHERE _id = ?",
+      [JSON.stringify(depIds), FLOW_BLOCKED_AVAILABLE_AT, jobId]
+    );
+    return (result.rowCount || 0) > 0;
+  }
+
   return {
     protocol:       "local",
     enqueue:        enqueue,
@@ -470,6 +579,7 @@ function create(_config) {
     dlqList:        dlqList,
     dlqRetry:       dlqRetry,
     dlqSize:        dlqSize,
+    patchFlowDeps:  patchFlowDeps,
   };
 }
 

package/lib/queue.js

@@ -13,7 +13,9 @@
  *   backend declares a `protocol` plus protocol-specific options. The
  *   built-in `local` protocol is SQLite-backed (rows live in the
  *   framework's main DB so persistence survives crashes / restarts
- *   without external infrastructure). `redis` and `sqs` ship; `amqp`
+ *   without external infrastructure), and can be pointed at an
+ *   operator's own database handle, table, and schema via the `local`
+ *   config (`db` / `table` / `schema`). `redis` and `sqs` ship; `amqp`
  *   and `nats` are listed as deferred and surface a clear error if
  *   selected.
  *
@@ -54,7 +56,6 @@
  *   Durable, pluggable job queue with priority-aware leasing, retry + deterministic backoff, graceful shutdown, parent/child flows, and a dead-letter surface for jobs that exhaust their retries.
  */
 var C = require("./constants");
-var clusterStorage = require("./cluster-storage");
 var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
@@ -107,13 +108,29 @@ var sweepTimer = null;
  * Throws when `opts.backends` is missing — operators catch the typo
  * at boot rather than discovering it on first enqueue.
  *
+ * The `local` protocol defaults to the framework's own database (the
+ * main SQLite in single-node mode, the operator-supplied external DB in
+ * cluster mode) and the `_blamejs_jobs` table. An operator who wants the
+ * queue rows to live in their own database, table, or schema supplies
+ * `db` / `table` / `schema` in the `local` backend config. The `db`
+ * handle must expose the same `execute` / `executeOne` / `executeAll`
+ * surface as `b.clusterStorage`; `table` / `schema` are validated as SQL
+ * identifiers and quoted through `b.safeSql` (an identifier that isn't a
+ * safe name is refused at `init` time, not interpolated into SQL).
+ * Sealed columns (`payload`, `lastError`) stay sealed regardless of
+ * where the rows land.
+ *
  * @opts
  *   backends: {
  *     [name: string]: {
  *       protocol:  "local" | "redis" | "sqs",
  *       breaker?:  { ... },   // see b.retry.CircuitBreaker opts
  *       retry?:    { ... },   // see b.retry.withRetry opts
- *       // ...protocol-specific opts (e.g. redis url, sqs queueUrl)
+ *       // local protocol — bring-your-own database (all optional):
+ *       db?:       object,    // store handle (execute/executeOne/executeAll); default cluster-storage
+ *       table?:    string,    // table name (validated + quoted); default "_blamejs_jobs"
+ *       schema?:   string,    // schema/namespace qualifier (validated + quoted)
+ *       // ...other protocol-specific opts (e.g. redis url, sqs queueUrl)
  *     },
  *   },
  *   defaultBackend?: string,  // name to use when enqueue/consume omit { backend }
@@ -122,11 +139,12 @@ var sweepTimer = null;
  *   b.queue.init({
  *     backends: {
  *       primary: { protocol: "local" },
+ *       app:     { protocol: "local", table: "app_jobs", schema: "work" },
  *     },
  *     defaultBackend: "primary",
  *   });
  *   b.queue.listBackends();
- *   // → [{ name: "primary", protocol: "local", breakerState: "closed" }]
+ *   // → [{ name: "primary", protocol: "local", breakerState: "closed" }, ...]
  */
 function init(opts) {
   if (initialized) return;
@@ -183,6 +201,7 @@ function init(opts) {
       dlqList:       raw.dlqList ? wrapWithRetry(raw.dlqList) : null,
       dlqRetry:      raw.dlqRetry ? wrapWithRetry(raw.dlqRetry) : null,
       dlqSize:       raw.dlqSize ? wrapWithRetry(raw.dlqSize) : null,
+      patchFlowDeps: raw.patchFlowDeps ? wrapWithRetry(raw.patchFlowDeps) : null,
     };
   });
 
@@ -897,6 +916,17 @@ function enqueueFlow(spec) {
 
   var flowId = "flow-" + bCrypto.generateToken(C.BYTES.bytes(8));
 
+  // Resolve the backend up front so the second-pass dependsOn patch
+  // targets the SAME backend (and its configured store + table) that the
+  // first-pass enqueue wrote to. A backend pointed at a bring-your-own
+  // table must receive the flow graph through its own writer, not a
+  // dispatcher-level write to the default jobs table.
+  var flowBackend = _backendFor(spec);
+  if (typeof flowBackend.patchFlowDeps !== "function") {
+    return Promise.reject(_err("FLOW_UNSUPPORTED",
+      "queue backend '" + flowBackend.name + "' does not support enqueueFlow", true));
+  }
+
   return observability.tap("queue.enqueueFlow",
     { queueName: spec.queueName, flowId: flowId, childCount: spec.children.length },
     async function () {
@@ -910,6 +940,7 @@ function enqueueFlow(spec) {
         var ch = spec.children[p];
         // Hold off setting dependsOn until we know all sibling jobIds.
         var enqOpts = {
+          backend:       flowBackend.name,
           flowId:        flowId,
           flowChildName: ch.name,
           priority:      ch.priority || 0,
@@ -917,9 +948,9 @@ function enqueueFlow(spec) {
           traceId:       ch.traceId || null,
           maxAttempts:   ch.maxAttempts,
           // dependsOn intentionally omitted on first pass — will be patched
-          // in via direct UPDATE after all jobIds are known. This means
-          // root children (no deps) are immediately leaseable; deps-bearing
-          // children get patched to MAX_SAFE_INTEGER via second pass.
+          // in via the backend's patchFlowDeps after all jobIds are known.
+          // Root children (no deps) are immediately leaseable; deps-bearing
+          // children get parked at MAX_SAFE_INTEGER via the second pass.
         };
         var result = await enqueue(spec.queueName, ch.payload, enqOpts);
         nameToJobId[ch.name] = result.jobId;
@@ -927,14 +958,13 @@ function enqueueFlow(spec) {
       }
       // Second pass: write dependsOn (translated to jobIds) for children
       // that need it, and parking-lot their availableAt to MAX_SAFE_INTEGER.
+      // Routed through the backend's writer so it lands in the backend's
+      // configured store + table (bring-your-own DB safe).
       for (var q = 0; q < jobs.length; q++) {
         var j = jobs[q];
         if (j.dependsOn.length === 0) continue;
         var depIds = j.dependsOn.map(function (n2) { return nameToJobId[n2]; });
-        await clusterStorage.execute(
-          "UPDATE _blamejs_jobs SET dependsOn = ?, availableAt = ? WHERE _id = ?",
-          [JSON.stringify(depIds), Number.MAX_SAFE_INTEGER, j.jobId]
-        );
+        await flowBackend.patchFlowDeps(j.jobId, depIds);
       }
       _emit("system.queue.flow.enqueue", {
         metadata: {

package/lib/render.js

@@ -82,17 +82,35 @@ var DEFAULT_DYNAMIC_CACHE_CONTROL = "private, no-cache, must-revalidate";
  * without losing Content-Type. Returns `undefined` — the response
  * is fully written by the time the call returns.
  *
+ * `opts.replacer` is forwarded to `JSON.stringify` (ECMA-262 §25.5.2,
+ * the second argument) so handlers can serialize values that have no
+ * native JSON form — `BigInt` (which otherwise throws), `Date` in a
+ * custom shape, `Map` / `Set`, or a redaction filter over secret-
+ * shaped keys — without pre-walking the body. Accepts the same
+ * function or property-name array `JSON.stringify` does; a non-
+ * function / non-array value is a config typo and throws.
+ *
  * @opts
- *   status:  200,   // numeric HTTP status (200/201/202/4xx/5xx)
- *   headers: {},    // merged over defaults; later wins
+ *   status:   200,                  // numeric HTTP status (200/201/202/4xx/5xx)
+ *   headers:  {},                   // merged over defaults; later wins
+ *   replacer: function|string[],    // JSON.stringify replacer (BigInt/Date/redaction)
  *
  * @example
  *   b.render.json(res, { ok: true, id: 42 }, { status: 201 });
  *   // → response: 201, application/json, body `{"ok":true,"id":42}`
+ *
+ *   b.render.json(res, { total: 9007199254740993n }, {
+ *     replacer: function (k, v) { return typeof v === "bigint" ? v.toString() : v; },
+ *   });
+ *   // → body `{"total":"9007199254740993"}`
  */
 function json(res, body, opts) {
   opts = opts || {};
-  var encoded = JSON.stringify(body);
+  if (opts.replacer !== undefined && opts.replacer !== null &&
+      typeof opts.replacer !== "function" && !Array.isArray(opts.replacer)) {
+    throw new TypeError("render.json: opts.replacer must be a function or an array of keys");
+  }
+  var encoded = JSON.stringify(body, opts.replacer);
   var headers = _mergedHeaders({
     "Content-Type":   "application/json; charset=utf-8",
     "Content-Length": Buffer.byteLength(encoded, "utf8"),

package/lib/safe-buffer.js

@@ -321,6 +321,60 @@ function boundedChunkCollector(opts) {
   };
 }
 
+/**
+ * @primitive b.safeBuffer.collectStream
+ * @signature b.safeBuffer.collectStream(stream, opts)
+ * @since     0.14.18
+ * @related   b.safeBuffer.boundedChunkCollector, b.safeBuffer.toBuffer
+ *
+ * Read a Node Readable (an `http.IncomingMessage` request body, a file
+ * stream, an upstream response) fully into one Buffer with the byte cap
+ * enforced at every chunk — the streaming sibling of
+ * `boundedChunkCollector`. `boundedChunkCollector` is a push-based
+ * collector object; `collectStream` is the pump around it, so callers
+ * compose the stream case instead of reaching for a `(stream, opts)`
+ * overload that does not exist.
+ *
+ * Resolves with the concatenated Buffer when the stream ends. Rejects
+ * (and destroys the stream) the moment a chunk would overflow
+ * `maxBytes`, so a hostile sender cannot force unbounded buffering. A
+ * bad `maxBytes` (missing / non-finite / `Infinity`) rejects rather than
+ * throwing synchronously.
+ *
+ * @opts
+ *   maxBytes:    number,     // REQUIRED positive finite int; total byte cap
+ *   errorClass:  Function,   // caller Error subclass for the too-large reject
+ *   sizeCode:    string,     // default "buffer/too-large"
+ *   sizeMessage: string,     // override the too-large message
+ *
+ * @example
+ *   var body = await b.safeBuffer.collectStream(req, { maxBytes: 65536 });
+ *   var json = b.safeJson.parse(body.toString("utf8"));
+ *   // → the parsed request body, never more than 64 KiB buffered
+ */
+function collectStream(stream, opts) {
+  return new Promise(function (resolve, reject) {
+    var collector;
+    try { collector = boundedChunkCollector(opts || {}); }
+    catch (e) { reject(e); return; }
+    var done = false;
+    function fail(e) {
+      if (done) return;
+      done = true;
+      try { if (stream && typeof stream.destroy === "function") stream.destroy(); }
+      catch (_e) { /* socket already closed */ }
+      reject(e);
+    }
+    stream.on("data", function (chunk) {
+      if (done) return;
+      try { collector.push(chunk); }
+      catch (e) { fail(e); }
+    });
+    stream.on("end", function () { if (!done) { done = true; resolve(collector.result()); } });
+    stream.on("error", fail);
+  });
+}
+
 /**
  * @primitive b.safeBuffer.secureZero
  * @signature b.safeBuffer.secureZero(buf)
@@ -552,6 +606,7 @@ module.exports = {
   normalizeText:         normalizeText,
   toBuffer:              toBuffer,
   boundedChunkCollector: boundedChunkCollector,
+  collectStream: collectStream,
   secureZero:            secureZero,
   isHex:                 isHex,
   hasCrlf:               hasCrlf,