@blamejs/core 0.6.70 → 0.7.1

package/lib/log-stream-syslog.js

@@ -32,11 +32,17 @@ var net   = require("net");
 var os    = require("os");
 var tls   = require("tls");
 var C = require("./constants");
+var { boot } = require("./log");
+var safeAsync = require("./safe-async");
+var safeUrl = require("./safe-url");
 var { LogStreamError } = require("./framework-error");
 
 var _err = LogStreamError.factory;
+var log  = boot("log-stream-syslog");
 
-var DEFAULT_FACILITY    = 16;          // local0
+// RFC 5424 facility codes (0-23). 0x10 = 16 = local0 — the
+// conventional facility for app-emitted records.
+var DEFAULT_FACILITY    = 0x10;
 var DEFAULT_APP_NAME    = "blamejs";
 var DEFAULT_PROC_ID     = String(process.pid);
 var DEFAULT_MSG_ID      = "-";
@@ -46,8 +52,8 @@ var TLS_DEFAULT_PORT    = 6514;
 var UDP_DEFAULT_PORT    = 514;
 var DEFAULT_TIMEOUT_MS  = C.TIME.seconds(10);
 var DEFAULT_RECONNECT_BASE_MS = 250;
-var DEFAULT_RECONNECT_MAX_MS  = 30000;
-var DEFAULT_BUFFER_LIMIT = 10000;
+var DEFAULT_RECONNECT_MAX_MS  = C.TIME.seconds(30);
+var DEFAULT_BUFFER_LIMIT = C.BYTES.bytes(10000);
 
 // RFC 5424 severity codes from the framework's level names.
 var LEVEL_TO_SEVERITY = {
@@ -64,7 +70,8 @@ function _toRfc3339(tsMs) {
 function _formatRfc5424(record, cfg) {
   var severity = LEVEL_TO_SEVERITY[record.level] != null
     ? LEVEL_TO_SEVERITY[record.level] : 6;
-  var pri = (cfg.facility * 8) + severity;
+  // RFC 5424 §6.2.1: PRI = facility << 3 | severity (severity is 3 bits).
+  var pri = (cfg.facility << 3) + severity;
   var ts  = _toRfc3339(record.ts || Date.now());
   // Body — JSON-encode meta + message together so the structured
   // payload survives the wire as a single MSG token. Operators with
@@ -86,21 +93,18 @@ function create(config) {
   if (typeof url !== "string" || url.length === 0) {
     throw _err("BAD_OPT", "log-stream syslog requires { url } (string)");
   }
-  // Parse URL — accept udp://, tcp://, tls://. safeUrl rejects http://
-  // by default; allow these explicit transports.
+  // Parse URL — accept udp://, tcp://, tls:// only.
   var parsed;
   try {
-    parsed = new URL(url);
+    parsed = safeUrl.parse(url, {
+      allowedProtocols: ["udp:", "tcp:", "tls:"],
+      errorClass:       LogStreamError,
+    });
   } catch (e) {
     throw _err("BAD_URL", "log-stream syslog: bad url '" + url + "': " +
       ((e && e.message) || String(e)));
   }
   var transport = parsed.protocol.replace(/:$/, "").toLowerCase();
-  if (transport !== "udp" && transport !== "tcp" && transport !== "tls") {
-    throw _err("BAD_URL",
-      "log-stream syslog: protocol must be udp / tcp / tls, got " +
-      JSON.stringify(parsed.protocol));
-  }
   var defaultPort = transport === "tls" ? TLS_DEFAULT_PORT
                   : transport === "tcp" ? TCP_DEFAULT_PORT
                   : UDP_DEFAULT_PORT;
@@ -135,11 +139,8 @@ function create(config) {
   }
   // Track the operator's onDrop so dropped events surface.
   var onDrop = typeof config.onDrop === "function" ? config.onDrop : null;
-  function _emitDrop(reason, batch, err) {
-    if (!onDrop) return;
-    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
-    catch (_e) {}
-  }
+  var _emitDrop = safeAsync.makeDropCallback(onDrop,
+    function (e) { log.warn("onDrop-callback-failed: " + e.message); });
 
   // ---- UDP transport ----
   if (transport === "udp") {
@@ -167,7 +168,8 @@ function create(config) {
       },
       close: function () {
         udpClosed = true;
-        try { udpSock.close(); } catch (_e) {}
+        try { udpSock.close(); }
+        catch (e) { log.warn("udp-close-failed: " + e.message); }
         return Promise.resolve();
       },
     };
@@ -222,7 +224,8 @@ function create(config) {
     sock.on("close", function () {
       sockReady = false;
       connecting = false;
-      try { sock.destroy(); } catch (_e) {}
+      try { sock.destroy(); }
+      catch (e) { log.warn("sock-destroy-failed: " + e.message); }
       sock = null;
       if (closed) return;
       reconnectAttempt += 1;
@@ -263,15 +266,17 @@ function create(config) {
       // shutdown race the slower TLS handshake and surface as
       // "sink-closed" drops even though the framework had a viable
       // connection in progress.
-      var DRAIN_TIMEOUT_MS = 3000;
+      var DRAIN_TIMEOUT_MS = C.TIME.seconds(3);
       var started = Date.now();
       return new Promise(function (resolve) {
         function _finish() {
           closed = true;
           var pending = queue.splice(0, queue.length);
           if (pending.length > 0) _emitDrop("sink-closed", pending, null);
-          try { if (sock) sock.end(); } catch (_e) {}
-          try { if (sock) sock.destroy(); } catch (_e) {}
+          try { if (sock) sock.end(); }
+          catch (e) { log.warn("sock-end-failed: " + e.message); }
+          try { if (sock) sock.destroy(); }
+          catch (e) { log.warn("sock-destroy-failed: " + e.message); }
           sock = null;
           resolve();
         }

package/lib/log-stream-webhook.js

@@ -33,6 +33,7 @@ var C = require("./constants");
 var retryHelper = require("./retry");
 var { LogStreamError } = require("./framework-error");
 var httpClient = require("./http-client");
+var safeAsync = require("./safe-async");
 var safeUrl = require("./safe-url");
 var authHeader = require("./auth-header");
 
@@ -46,7 +47,7 @@ var DEFAULTS = {
   contentType:   "application/json",
   bodyShape:     "array",
   timeoutMs:     C.TIME.seconds(30),
-  bufferLimit:   10000,
+  bufferLimit:   C.BYTES.bytes(10000),
 };
 
 var _err = LogStreamError.factory;
@@ -105,28 +106,18 @@ function create(config) {
   // would otherwise lose drops silently. The callback is invoked
   // best-effort — a throw inside it is swallowed.
   var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
-  function _emitDrop(reason, batch, err) {
-    if (!onDrop) return;
-    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
-    catch (_e) { /* drop callback is best-effort by design */ }
-  }
+  var _emitDrop = safeAsync.makeDropCallback(onDrop);
   var buffer = [];
   var dropCount = 0;
-  var flushTimer = null;
   var inFlight = false;
   var closed = false;
-
-  function _scheduleFlush() {
-    if (flushTimer) return;
-    flushTimer = setTimeout(function () { flushTimer = null; _flush(); }, cfg.maxBatchAgeMs);
-    flushTimer.unref();
-  }
+  var flushScheduler = safeAsync.makeScheduledFlush(cfg.maxBatchAgeMs, function () { return _flush(); });
 
   // Track the in-flight flush as a promise so close() can await it.
   // Without this, a record arriving mid-flush gets buffered, the
   // emit-time _flush() early-returns on `if (inFlight) return`, and
   // the buffered record is stranded if shutdown fires before
-  // _scheduleFlush() drains it.
+  // flushScheduler.schedule() drains it.
   var inFlightPromise = null;
   async function _flush() {
     if (inFlight) return inFlightPromise;
@@ -154,7 +145,7 @@ function create(config) {
       } finally {
         inFlight = false;
         inFlightPromise = null;
-        if (buffer.length > 0) _scheduleFlush();
+        if (buffer.length > 0) flushScheduler.schedule();
       }
     })();
     return inFlightPromise;
@@ -172,7 +163,7 @@ function create(config) {
       // Don't await — non-blocking flush. Caller's emit returns immediately.
       _flush().catch(function () {});
     } else {
-      _scheduleFlush();
+      flushScheduler.schedule();
     }
     return Promise.resolve({ accepted: true, queued: buffer.length });
   }
@@ -184,7 +175,7 @@ function create(config) {
     // calling shutdown(). Order: stop the timer, await any in-flight
     // flush so its records POST before we touch the buffer, drain
     // anything still queued, THEN refuse new enqueues.
-    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    flushScheduler.cancel();
     if (inFlightPromise) {
       try { await inFlightPromise; } catch (_e) { /* surfaced via onDrop */ }
     }

package/lib/log-stream.js

@@ -58,11 +58,14 @@ var otlpProto       = require("./log-stream-otlp");
 var otlpGrpcProto   = require("./log-stream-otlp-grpc");
 var cloudwatchProto = require("./log-stream-cloudwatch");
 var syslogProto     = require("./log-stream-syslog");
+var { boot }        = require("./log");
 var redactor        = require("./redact");
 var lazyRequire     = require("./lazy-require");
 var protocolDispatcher = require("./protocol-dispatcher");
 var { LogStreamError } = require("./framework-error");
 
+var _log = boot("log-stream");
+
 var dispatcher = protocolDispatcher.create({
   name:       "log-stream",
   errorClass: LogStreamError,
@@ -79,7 +82,10 @@ var dispatcher = protocolDispatcher.create({
 });
 
 var LEVELS = ["debug", "info", "warn", "error"];
-var LEVEL_PRIORITY = { debug: 10, info: 20, warn: 30, error: 40 };
+// Ordinal priority — higher = more severe. Values are spaced (1..4)
+// only so future intermediate levels (e.g. 'notice' between info/warn)
+// could slot in without renumbering the existing four.
+var LEVEL_PRIORITY = { debug: 1, info: 2, warn: 3, error: 4 };
 
 var _err = LogStreamError.factory;
 
@@ -292,7 +298,12 @@ function bootFromEnv(opts) {
 
 function _resetForTest() {
   Object.keys(sinks).forEach(function (n) {
-    try { if (sinks[n].raw.close) sinks[n].raw.close(); } catch (_e) {}
+    try { if (sinks[n].raw.close) sinks[n].raw.close(); }
+    catch (e) {
+      // Test-reset path; best-effort — surface for diagnosability via
+      // the framework's boot logger so flaky teardown doesn't go silent.
+      _log.debug("reset-close-failed: " + (e && e.message || e));
+    }
   });
   sinks = {};
   incomingHandlers = [];

package/lib/log.js

@@ -60,11 +60,31 @@
  */
 
 var { AsyncLocalStorage } = require("node:async_hooks");
-var nodeCrypto = require("node:crypto");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
 var redact = require("./redact");
+var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
+// Lazy resolves to break load-order cycles:
+//   - parsers/safe-env requires log (boot logger for env-read errors).
+//     log can't require safe-env at top because safe-env's top-level
+//     `var log = boot("env")` would see log's exports half-built.
+//   - crypto requires constants + framework-error + vendor; it does NOT
+//     require log, so a top-of-file require would technically work, but
+//     keeping crypto lazy keeps log loadable from anywhere without
+//     pulling the whole crypto bundle into the framework's earliest
+//     boot path (request-id middleware needs only generateToken).
+var safeEnv = lazyRequire(function () { return require("./parsers/safe-env"); });
+var crypto  = lazyRequire(function () { return require("./crypto"); });
+
+// Request-id correlation token — 8 bytes hex-encoded (16 chars). Short
+// enough to read in a log line, long enough to keep collisions far below
+// audible-noise even at 1M req/s sustained. Routed through C.BYTES so
+// the file's byte arithmetic has a single source of truth.
+var REQUEST_ID_BYTES = C.BYTES.bytes(8);
+
 var LEVELS = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 };
 var LEVEL_NAMES = Object.keys(LEVELS);
 
@@ -185,7 +205,10 @@ function create(opts) {
   ], "b.log");
 
   // Resolve initial level: env > opts > default
-  var envLevel = process.env.LOG_LEVEL;
+  // safeEnv enforces the size cap + missing/empty handling; LEVELS lookup
+  // gates an unrecognised value (silently falls through to opts/default
+  // rather than throwing — bad LOG_LEVEL on the env should not crash boot).
+  var envLevel = safeEnv().readVar("LOG_LEVEL");
   var level;
   if (envLevel && LEVELS[envLevel] !== undefined) {
     level = LEVELS[envLevel];
@@ -315,8 +338,10 @@ function create(opts) {
       var generate   = typeof mwOpts.generate === "function"
         ? mwOpts.generate
         : function () {
-          // 16 random hex chars — short, sufficient correlation entropy
-          return nodeCrypto.randomBytes(8).toString("hex");
+          // 16 random hex chars — short, sufficient correlation entropy.
+          // Routes through the framework token primitive so the entropy
+          // source matches the rest of the codebase.
+          return crypto().generateToken(REQUEST_ID_BYTES);
         };
       return function logRequestIdMiddleware(req, res, next) {
         var inbound = req.headers && req.headers[headerName];
@@ -324,7 +349,7 @@ function create(opts) {
           ? inbound
           : generate();
         // Strip CRLF defensively before reflecting back into a header
-        id = String(id).replace(/[\r\n]/g, "");
+        id = safeBuffer.stripCrlf(String(id));
         req.id = id;
         if (setOnRes && typeof res.setHeader === "function") {
           try { res.setHeader("X-Request-Id", id); } catch (_e) { /* header may be locked */ }
@@ -397,12 +422,25 @@ function boot(name) {
     sink(JSON.stringify(entry));
   }
 
+  function debug(msg, fields) {
+    // Boot-time debug entries route through console.log unless LOG_LEVEL
+    // suppresses them. fields (when present) get JSON-appended so
+    // operators see the structured context.
+    if (LEVELS.debug < _bootMinLevel()) return;
+    var rendered = msg;
+    if (fields !== undefined) {
+      try { rendered = msg + " " + JSON.stringify(fields); }
+      catch (_e) { rendered = msg; }
+    }
+    _emit("debug", rendered);
+  }
   function info(msg)  { _emit("info",  msg); }
   function warn(msg)  { _emit("warn",  msg); }
   function error(msg) { _emit("error", msg); }
 
   // The returned function is the info path so `log(msg)` matches the
   // existing call shape across the codebase.
+  info.debug = debug;
   info.info  = info;
   info.warn  = warn;
   info.error = error;
@@ -410,9 +448,49 @@ function boot(name) {
   return info;
 }
 
+// makeViaOrFallback — closure factory for operator-log routing. Used by
+// bundler / dev / error-page / pqc-gate (and similar primitives) that
+// accept opts.log but must keep emitting through a per-module fallback
+// when the operator didn't pass one. Replaces the per-file
+// `function _logVia(log, level, message, fields) { if (log && typeof
+// log[level] === "function") { try { log[level](message, fields); }
+// catch ... } return; } ... fallback;` boilerplate.
+//
+//   var _logVia = log.makeViaOrFallback(opts.log, log.boot("bundler"));
+//   _logVia("error", "build-failed", { reason: "..." });
+//
+// The operator log call is best-effort: a misbehaving log[level] swallows
+// internally rather than crash the caller. Fallback is invoked only when
+// the operator log is absent or doesn't expose the requested level.
+function makeViaOrFallback(operatorLog, fallbackLog) {
+  return function (level, message, fields) {
+    if (operatorLog && typeof operatorLog[level] === "function") {
+      try { operatorLog[level](message, fields); }
+      catch (_e) { /* operator log best-effort */ }
+      return;
+    }
+    var line = message + (fields ? " " + JSON.stringify(fields) : "");
+    var fb = (level === "error" || level === "fatal") ? fallbackLog.error
+           : (level === "warn") ? fallbackLog.warn
+           : fallbackLog.info;
+    if (typeof fb === "function") fb(line);
+  };
+}
+
+// Boot-time minimum level (debug suppressed unless explicitly enabled).
+// Uses raw process.env per the documented load-cycle exception: log.js
+// runs before safeEnv on the boot path; safeEnv requires log, so log
+// can't go through safeEnv to read its own level.
+function _bootMinLevel() {
+  // allow:raw-process-env — see header comment above
+  var raw = process.env.BLAMEJS_BOOT_LOG_LEVEL || process.env.LOG_LEVEL || "info";
+  return LEVELS[raw] != null ? LEVELS[raw] : LEVELS.info;
+}
+
 module.exports = {
   create:           create,
   boot:             boot,
+  makeViaOrFallback: makeViaOrFallback,
   LEVELS:           LEVELS,
   LogError:         LogError,
   // Module-level helpers for code paths that don't have a logger

package/lib/mail-bounce.js

@@ -66,10 +66,14 @@
 var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var audit = lazyRequire(function () { return require("./audit"); });
+var safeBuffer = require("./safe-buffer");
 var safeJson = require("./safe-json");
 var C = require("./constants");
+var requestHelpers = require("./request-helpers");
 var { defineClass } = require("./framework-error");
 
+var HTTP = requestHelpers.HTTP_STATUS;
+
 var MailBounceError = defineClass("MailBounceError", { withStatusCode: true });
 
 // Cap on inbound webhook bodies — any vendor bigger than this is
@@ -441,27 +445,30 @@ function handler(opts) {
   }
 
   return function mailBounceMiddleware(req, res) {
-    var chunks = [];
-    var size = 0;
+    var collector = safeBuffer.boundedChunkCollector({
+      maxBytes:    maxBytes,
+      errorClass:  MailBounceError,
+      sizeCode:    "mailBounce/too-large",
+      sizeMessage: "payload exceeds maxBytes",
+    });
     var aborted = false;
 
     req.on("data", function (chunk) {
       if (aborted) return;
-      size += chunk.length;
-      if (size > maxBytes) {
+      try { collector.push(chunk); }
+      catch (_e) {
         aborted = true;
-        return _send(res, 413, { error: "payload too large" });
+        return _send(res, HTTP.PAYLOAD_TOO_LARGE, { error: "payload too large" });
       }
-      chunks.push(chunk);
     });
 
     req.on("end", function () {
       if (aborted) return;
-      var raw = Buffer.concat(chunks);
+      var raw = collector.result();
       var body;
       try { body = safeJson.parse(raw, { maxBytes: maxBytes }); }
       catch (e) {
-        return _send(res, 400, { error: "invalid JSON: " + e.message });
+        return _send(res, HTTP.BAD_REQUEST, { error: "invalid JSON: " + e.message });
       }
 
       // Verification hook — operator decides what counts as authentic.
@@ -472,15 +479,15 @@ function handler(opts) {
       if (verify) {
         var ok;
         try { ok = verify(req, body, raw); }
-        catch { return _send(res, 401, { error: "verification error" }); }
-        if (!ok) return _send(res, 401, { error: "verification failed" });
+        catch { return _send(res, HTTP.UNAUTHORIZED, { error: "verification error" }); }
+        if (!ok) return _send(res, HTTP.UNAUTHORIZED, { error: "verification failed" });
       }
 
       var event;
       try {
         event = customParser ? _customParser(customParser)(body) : VENDORS[vendor](body);
       } catch (e) {
-        return _send(res, 400, {
+        return _send(res, HTTP.BAD_REQUEST, {
           error: e.message || "parse failed",
           code:  e.code   || "parse-failed",
         });
@@ -488,20 +495,20 @@ function handler(opts) {
 
       _emit(event);
 
-      if (!onBounce) return _send(res, 200, { ok: true });
+      if (!onBounce) return _send(res, HTTP.OK, { ok: true });
 
       Promise.resolve()
         .then(function () { return onBounce(event); })
-        .then(function () { _send(res, 200, { ok: true }); },
+        .then(function () { _send(res, HTTP.OK, { ok: true }); },
               function (e) {
-                _send(res, 500, {
+                _send(res, HTTP.INTERNAL_SERVER_ERROR, {
                   error: "onBounce threw: " + (e && e.message),
                 });
               });
     });
 
     req.on("error", function () {
-      if (!aborted) _send(res, 400, { error: "request error" });
+      if (!aborted) _send(res, HTTP.BAD_REQUEST, { error: "request error" });
     });
   };
 }

package/lib/mail-dkim.js

@@ -41,6 +41,7 @@
 var lazyRequire = require("./lazy-require");
 var audit       = lazyRequire(function () { return require("./audit"); });
 var nodeCrypto  = require("crypto");
+var safeBuffer  = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
@@ -85,7 +86,7 @@ function _canonBodyRelaxed(body) {
   var normalized = body.replace(/\r?\n/g, "\r\n");
   var lines = normalized.split("\r\n");
   for (var i = 0; i < lines.length; i++) {
-    lines[i] = lines[i].replace(/[ \t]+/g, " ").replace(/[ \t]+$/, "");
+    lines[i] = safeBuffer.stripTrailingHspace(lines[i].replace(/[ \t]+/g, " "));
   }
   // Drop trailing empty lines.
   while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
@@ -240,11 +241,7 @@ function create(opts) {
         "headersToSign[" + i + "] must be a non-empty string");
     }
   }
-  if (opts.bodyLength !== undefined &&
-      (typeof opts.bodyLength !== "number" || !isFinite(opts.bodyLength) || opts.bodyLength < 0)) {
-    throw new DkimError("dkim/bad-body-length",
-      "bodyLength must be a non-negative finite number");
-  }
+  validateOpts.optionalFiniteNonNegative(opts.bodyLength, "bodyLength", DkimError, "dkim/bad-body-length");
 
   var auditOn = opts.audit !== false;
   // Try to parse the private key once at create time so misconfigured