@blamejs/core 0.5.15 → 0.5.17

package/lib/restore.js

@@ -52,9 +52,9 @@
  */
 
 var fs = require("fs");
-var nodeCrypto = require("node:crypto");
 var os = require("os");
 var path = require("path");
+var crypto = require("./crypto");
 var restoreBundle = require("./restore-bundle");
 var restoreRollback = require("./restore-rollback");
 var lazyRequire = require("./lazy-require");
@@ -128,7 +128,7 @@ function create(opts) {
         "inspect: bundle '" + bundleId + "' not in storage");
     }
     var pullDir = path.join(os.tmpdir(),
-      "blamejs-restore-inspect-" + nodeCrypto.randomBytes(4).toString("hex"));
+      "blamejs-restore-inspect-" + crypto.generateToken(4));
     try {
       await storage.readBundle(bundleId, pullDir);
       return restoreBundle.inspect({ bundleDir: pullDir });
@@ -150,7 +150,7 @@ function create(opts) {
         "run: bundle '" + bundleId + "' not in storage");
     }
 
-    var pullId = nodeCrypto.randomBytes(4).toString("hex");
+    var pullId = crypto.generateToken(4);
     var pullDir    = path.join(os.tmpdir(), "blamejs-restore-pull-"    + pullId);
     var stagingDir = path.join(os.tmpdir(), "blamejs-restore-staging-" + pullId);
 

package/lib/safe-async.js

@@ -494,6 +494,126 @@ class Once {
   hasInvoked() { return this._promise !== null; }
 }
 
+// ---- repeating ----
+//
+// Bounded-cadence interval timer with consistent unref + cancel semantics.
+// Replaces the scattered setInterval ceremony where each caller hand-rolled
+// `var t = setInterval(...); t.unref();` and a corresponding clearInterval
+// in shutdown — easy to forget the unref and silently block process exit.
+//
+//   var sweep = b.safeAsync.repeating(function () {
+//     return cleanup();
+//   }, b.constants.TIME.seconds(30), { name: "cache-sweep" });
+//   ...
+//   sweep.stop();
+//
+// fn may be sync or async. If fn returns a Promise, the next tick fires
+// `intervalMs` after the prior fn() *started* (matching setInterval's
+// fixed-rate semantics, not after-completion). Promise rejections are
+// captured by the optional onError callback; if none provided, they're
+// silently dropped — a repeating timer is by definition fire-and-forget,
+// and an unhandled rejection here would crash the process.
+//
+// opts.unref defaults true: most repeating timers are background sweepers
+// that should NOT keep the process alive. Cluster heartbeat etc. set
+// `unref: false` so the lease keeps the leader from exiting silently.
+
+function repeating(fn, intervalMs, opts) {
+  if (typeof fn !== "function") {
+    throw new SafeAsyncError("repeating: fn must be a function", "async/bad-arg");
+  }
+  if (typeof intervalMs !== "number" || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new SafeAsyncError("repeating: intervalMs must be a positive finite number, got " + intervalMs,
+      "async/bad-arg");
+  }
+  opts = opts || {};
+  var unref = opts.unref !== false;     // default true
+  var onError = typeof opts.onError === "function" ? opts.onError : null;
+
+  var stopped = false;
+  var timer = setInterval(function () {
+    if (stopped) return;
+    var result;
+    try { result = fn(); }
+    catch (e) { if (onError) { try { onError(e); } catch (_e) { /* swallow */ } } return; }
+    if (result && typeof result.then === "function") {
+      result.then(null, function (e) {
+        if (onError) { try { onError(e); } catch (_e) { /* swallow */ } }
+      });
+    }
+  }, intervalMs);
+  if (unref && typeof timer.unref === "function") timer.unref();
+
+  return {
+    stop: function () {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    },
+  };
+}
+
+// ---- flushLoop ----
+//
+// Schedule fn(), wait for it to settle (resolve or reject), then schedule
+// the next fn() `intervalMs` later. Differs from `repeating` (fixed-rate,
+// fire-and-forget) — flushLoop is the after-completion pattern most
+// background flushers want: never overlap two flushes, and don't accumulate
+// backlog if a flush is slow.
+//
+//   var loop = b.safeAsync.flushLoop(function () {
+//     return otelExporter.flush();
+//   }, b.constants.TIME.seconds(15), { name: "otel-flush" });
+//   ...
+//   loop.stop();
+//
+// Always unref'd — a pending flush should never keep the process alive
+// (the operator's b.appShutdown drives the final drain explicitly).
+// onError catches rejections; without one, they're silently dropped.
+
+function flushLoop(fn, intervalMs, opts) {
+  if (typeof fn !== "function") {
+    throw new SafeAsyncError("flushLoop: fn must be a function", "async/bad-arg");
+  }
+  if (typeof intervalMs !== "number" || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new SafeAsyncError("flushLoop: intervalMs must be a positive finite number, got " + intervalMs,
+      "async/bad-arg");
+  }
+  opts = opts || {};
+  var onError = typeof opts.onError === "function" ? opts.onError : null;
+
+  var stopped = false;
+  var timer = null;
+
+  function _schedule() {
+    if (stopped) return;
+    timer = setTimeout(function () {
+      timer = null;
+      if (stopped) return;
+      var settled;
+      try { settled = Promise.resolve(fn()); }
+      catch (e) {
+        if (onError) { try { onError(e); } catch (_e) { /* swallow */ } }
+        _schedule();
+        return;
+      }
+      settled.then(null, function (e) {
+        if (onError) { try { onError(e); } catch (_e) { /* swallow */ } }
+      }).then(_schedule);
+    }, intervalMs);
+    if (typeof timer.unref === "function") timer.unref();
+  }
+  _schedule();
+
+  return {
+    stop: function () {
+      if (stopped) return;
+      stopped = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+    },
+  };
+}
+
 // ---- Re-exports of resilience primitives from lib/retry.js ----
 //
 // withRetry + CircuitBreaker live in lib/retry.js (the canonical home).
@@ -510,6 +630,8 @@ module.exports = {
   withSignal:         withSignal,
   withTimeoutSignal:  withTimeoutSignal,
   sleep:              sleep,
+  repeating:          repeating,
+  flushLoop:          flushLoop,
   safeAwait:          safeAwait,
   Mutex:              Mutex,
   Semaphore:          Semaphore,

package/lib/tracing.js

@@ -81,7 +81,7 @@
  *     async-context, which is fine for the surfaces we instrument.
  */
 
-var nodeCrypto = require("node:crypto");
+var crypto = require("./crypto");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 var { resolveRoute, captureResponseStatus } = require("./request-helpers");
@@ -134,10 +134,10 @@ function _formatTraceparent(traceId, spanId, flags) {
 }
 
 function _newTraceId() {
-  return nodeCrypto.randomBytes(16).toString("hex");
+  return crypto.generateToken(16);   // 32 hex chars (W3C trace-context)
 }
 function _newSpanId() {
-  return nodeCrypto.randomBytes(8).toString("hex");
+  return crypto.generateToken(8);    // 16 hex chars (W3C trace-context)
 }
 
 // ---- Pass-through span (used when OTel isn't installed) ----

package/lib/webhook.js

@@ -225,10 +225,10 @@ function _pqcVerify(publicKeyPem, data, expectedHex) {
 // a kid → signature pair. Whitespace tolerated around commas.
 
 function _parseSignatureHeader(headerValue) {
-  var parts = headerValue.split(",");
+  var segs = requestHelpers.parseListHeader(headerValue);
   var t = null, id = null, sigs = {};
-  for (var i = 0; i < parts.length; i++) {
-    var seg = parts[i].trim();
+  for (var i = 0; i < segs.length; i++) {
+    var seg = segs[i];
     var eq = seg.indexOf("=");
     if (eq <= 0) continue;            // skip malformed segments rather than failing whole header
     var name = seg.slice(0, eq);

package/lib/websocket.js

@@ -84,6 +84,8 @@
 var nodeCrypto = require("crypto");
 var { EventEmitter } = require("events");
 var C = require("./constants");
+var requestHelpers = require("./request-helpers");
+var safeAsync = require("./safe-async");
 var safeBuffer = require("./safe-buffer");
 var { FrameworkError } = require("./framework-error");
 var { boot } = require("./log");
@@ -192,7 +194,7 @@ function validateUpgradeRequest(req) {
 function negotiateSubprotocol(req, supported) {
   if (!supported || supported.length === 0) return null;
   var raw = (req.headers || {})["sec-websocket-protocol"] || "";
-  var offered = raw.split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+  var offered = requestHelpers.parseListHeader(raw);
   for (var i = 0; i < offered.length; i++) {
     if (supported.indexOf(offered[i]) !== -1) return offered[i];
   }
@@ -417,8 +419,8 @@ class WebSocketConnection extends EventEmitter {
     this._lastPongAt = Date.now();
 
     var self = this;
-    this._pingTimer = setInterval(function () { self._heartbeat(pongMs); }, pingMs);
-    this._pingTimer.unref();
+    this._pingTimer = safeAsync.repeating(function () { self._heartbeat(pongMs); },
+      pingMs, { name: "websocket-ping" });
 
     socket.on("data",  function (chunk) { self._onData(chunk); });
     socket.on("error", function (err)   {
@@ -446,7 +448,7 @@ class WebSocketConnection extends EventEmitter {
     if (this._state === STATE_CLOSED) return;
     this._state = STATE_CLOSED;
     if (error) this.lastError = error;
-    if (this._pingTimer)  { clearInterval(this._pingTimer);  this._pingTimer  = null; }
+    if (this._pingTimer)  { this._pingTimer.stop();  this._pingTimer  = null; }
     if (this._closeTimer) { clearTimeout(this._closeTimer);  this._closeTimer = null; }
     // Surface diagnosable errors via 'error' first — but only if the
     // operator is listening AND this is a real diagnosable case.

package/package.json

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

package/lib/parsers/safe-csv.js

@@ -1,224 +0,0 @@
-"use strict";
-/**
- * Security-focused CSV parser + writer.
- *
- * RFC 4180 compliant parsing + the operator-friendly defaults that the
- * RFC doesn't address:
- *
- *   - Size + row-count + field-length limits (DoS prevention)
- *   - BOM stripping
- *   - Configurable delimiter (',' default; '\t' for TSV; ';' for European)
- *   - Configurable quote char
- *   - CRLF / LF / CR line endings all accepted
- *
- * SECURITY: writer prevents CSV/Excel formula injection. Excel and other
- * spreadsheet apps execute cells starting with '=', '+', '-', '@', or
- * tab/CR characters. By default the writer prefixes such cells with a
- * single quote so the formula doesn't execute when the file is opened.
- * Toggle with { preventFormulaInjection: false } for true RFC 4180 output.
- *
- * Public API:
- *   csv.parse(input, opts?)          → array of arrays | array of objects
- *   csv.stringify(rows, opts?)       → string (RFC 4180 + injection-safe)
- *   csv.SafeCsvError                 → error class
- *
- * Defaults (parse):
- *   maxBytes:        16 MiB
- *   maxRows:         1,000,000
- *   maxFieldBytes:   1 MiB
- *   delimiter:       ','
- *   quote:           '"'
- *   header:          true   (first row is column names; rows returned as objects)
- *   trim:            false  (don't trim cell whitespace by default)
- */
-
-var C = require("../constants");
-var safeBuffer = require("../safe-buffer");
-var { FrameworkError } = require("../framework-error");
-
-class SafeCsvError extends FrameworkError {
-  constructor(message, code, position) {
-    super(message);
-    this.name = "SafeCsvError";
-    this.code = code || "csv/invalid";
-    this.position = position || null;
-    this.isSafeCsvError = true;
-  }
-}
-
-var DEFAULTS_PARSE = {
-  maxBytes:      C.BYTES.mib(16),
-  maxRows:       1000000,
-  maxFieldBytes: C.BYTES.mib(1),
-  delimiter:     ",",
-  quote:         '"',
-  header:        true,
-  trim:          false,
-};
-
-var DEFAULTS_STRINGIFY = {
-  delimiter:                ",",
-  quote:                    '"',
-  preventFormulaInjection:  true,
-  formulaPrefixChars:       ["=", "+", "-", "@", "\t", "\r"],
-  always_quote:             false,   // quote every field; default only quotes when needed
-  newline:                  "\r\n",  // RFC 4180
-  header:                   null,    // explicit array; null → derive from first object's keys
-};
-
-// ---- parse ----
-
-function parse(input, opts) {
-  opts = Object.assign({}, DEFAULTS_PARSE, opts || {});
-
-  input = safeBuffer.normalizeText(input, {
-    maxBytes:   opts.maxBytes,
-    errorClass: SafeCsvError,
-    typeCode:   "csv/wrong-input-type",
-    sizeCode:   "csv/too-large",
-  });
-
-  var len = input.length;
-  var pos = 0;
-  var rows = [];
-  var row = [];
-  var field = "";
-  var inQuote = false;
-
-  function pushField() {
-    if (Buffer.byteLength(field, "utf8") > opts.maxFieldBytes) {
-      throw new SafeCsvError("field exceeds maxFieldBytes at row " + (rows.length + 1), "csv/field-too-large");
-    }
-    row.push(opts.trim ? field.trim() : field);
-    field = "";
-  }
-  function pushRow() {
-    pushField();
-    rows.push(row);
-    if (rows.length > opts.maxRows) {
-      throw new SafeCsvError("row count exceeds maxRows", "csv/too-many-rows");
-    }
-    row = [];
-  }
-
-  while (pos < len) {
-    var ch = input.charAt(pos);
-    if (inQuote) {
-      if (ch === opts.quote) {
-        // Possible escaped quote (double-quote inside quoted field)
-        if (pos + 1 < len && input.charAt(pos + 1) === opts.quote) {
-          field += opts.quote;
-          pos += 2;
-          continue;
-        }
-        // End of quoted field
-        inQuote = false;
-        pos += 1;
-        continue;
-      }
-      field += ch;
-      pos += 1;
-    } else {
-      if (ch === opts.delimiter) {
-        pushField();
-        pos += 1;
-      } else if (ch === "\r") {
-        // CR or CRLF — both end the row
-        pushRow();
-        pos += 1;
-        if (pos < len && input.charAt(pos) === "\n") pos += 1;
-      } else if (ch === "\n") {
-        pushRow();
-        pos += 1;
-      } else if (ch === opts.quote && field === "") {
-        inQuote = true;
-        pos += 1;
-      } else {
-        field += ch;
-        pos += 1;
-      }
-    }
-  }
-  if (inQuote) throw new SafeCsvError("unterminated quoted field", "csv/unterminated-quote");
-  // Final row (no trailing newline)
-  if (field.length > 0 || row.length > 0) {
-    pushRow();
-  }
-
-  if (opts.header) {
-    if (rows.length === 0) return [];
-    var header = rows[0];
-    return rows.slice(1).map(function (r) {
-      var obj = {};
-      for (var i = 0; i < header.length; i++) obj[header[i]] = r[i] !== undefined ? r[i] : null;
-      return obj;
-    });
-  }
-  return rows;
-}
-
-// ---- stringify ----
-
-function stringify(rows, opts) {
-  opts = Object.assign({}, DEFAULTS_STRINGIFY, opts || {});
-  if (!Array.isArray(rows)) {
-    throw new SafeCsvError("stringify expects an array of rows", "csv/wrong-input-type");
-  }
-  if (rows.length === 0) return "";
-
-  // Determine header + row shape
-  var header;
-  var isObjectRows = false;
-  if (Array.isArray(rows[0])) {
-    isObjectRows = false;
-    header = opts.header || null;
-  } else if (typeof rows[0] === "object" && rows[0] !== null) {
-    isObjectRows = true;
-    header = opts.header || Object.keys(rows[0]);
-  } else {
-    throw new SafeCsvError("rows must be arrays or objects", "csv/wrong-input-type");
-  }
-
-  function escapeCell(value) {
-    var s = value == null ? "" : String(value);
-    if (opts.preventFormulaInjection && s.length > 0) {
-      var first = s.charAt(0);
-      if (opts.formulaPrefixChars.indexOf(first) !== -1) {
-        s = "'" + s;   // Excel-safe prefix
-      }
-    }
-    var needsQuote = opts.always_quote ||
-      s.indexOf(opts.delimiter) !== -1 ||
-      s.indexOf(opts.quote) !== -1 ||
-      s.indexOf("\n") !== -1 ||
-      s.indexOf("\r") !== -1;
-    if (needsQuote) {
-      s = opts.quote + s.split(opts.quote).join(opts.quote + opts.quote) + opts.quote;
-    }
-    return s;
-  }
-
-  var out = [];
-  if (header) {
-    out.push(header.map(escapeCell).join(opts.delimiter));
-  }
-  for (var i = 0; i < rows.length; i++) {
-    var r = rows[i];
-    var cells;
-    if (isObjectRows) {
-      cells = header.map(function (k) { return escapeCell(r[k]); });
-    } else {
-      cells = r.map(escapeCell);
-    }
-    out.push(cells.join(opts.delimiter));
-  }
-  return out.join(opts.newline);
-}
-
-module.exports = {
-  parse:                parse,
-  stringify:            stringify,
-  SafeCsvError:         SafeCsvError,
-  DEFAULTS_PARSE:       DEFAULTS_PARSE,
-  DEFAULTS_STRINGIFY:   DEFAULTS_STRINGIFY,
-};