@blamejs/core 0.4.1

package/lib/handlers.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * Async handler primitive — buffered emit + resilient drain.
+ *
+ * The framework has many "fire something off, don't block the request"
+ * surfaces: audit emissions from middleware/log-stream/external-db
+ * hooks, webhook deliveries, log lines being shipped to an external
+ * sink. Without a shared primitive, each surface tends toward a
+ * fire-and-forget Promise pattern, which has well-known failure modes:
+ *
+ *   - Errors disappear silently
+ *   - Promises leak across test/shutdown boundaries
+ *   - In cyclic dispatchers (storage emits about its own writes), the
+ *     pattern is the only thing preventing infinite recursion, but at
+ *     the cost of introducing a race
+ *   - "Did the work complete?" is unanswerable
+ *
+ * AsyncHandler replaces the pattern with a uniform contract that bakes
+ * resilience in by default — operators don't opt in to robustness; it
+ * is the framework's posture and surfaces only what the operator
+ * actively configures (DLQ destination, retry policy adjustments, etc).
+ *
+ * Public API:
+ *
+ *   handler.emit(item)           sync; buffers; never throws (errors go
+ *                                to onError); never returns a Promise
+ *   handler.drain(opts?)         async; flushes buffer to storage with
+ *                                retry + circuit breaker + DLQ;
+ *                                resolves when current backlog is done
+ *                                or breaker is open. opts.signal aborts.
+ *   handler.shutdown(opts?)      async; final drain with timeout (default
+ *                                30s); subsequent emit() drops with
+ *                                onError notification
+ *   handler.getStats()           snapshot of operational metrics
+ *
+ * Resilience layers (all on by default):
+ *
+ *   Retry — batches that fail flush() are retried with exponential
+ *           backoff + jitter (safeAsync.asyncRetry). Default 3 attempts.
+ *           Transient external-db hiccups recover automatically.
+ *
+ *   Circuit breaker — if `failureThreshold` consecutive batches fail
+ *           after retry exhaustion, the breaker OPENS. Subsequent
+ *           emit() calls fast-fail (item goes to DLQ via onError);
+ *           drain() returns immediately with a CIRCUIT_OPEN reason.
+ *           After `cooldownMs` the breaker enters HALF_OPEN and one
+ *           probe batch is allowed; success closes it, failure
+ *           re-opens with another cooldown. Bounded recovery.
+ *
+ *   Dead-letter queue — items that fail every retry land in DLQ via
+ *           the operator-supplied `deadLetter(items, error)` callback.
+ *           If no DLQ is configured, items go to onError with a
+ *           handler/dropped error. The DLQ is fire-and-forget from
+ *           the handler's perspective — the operator can write to a
+ *           file, an external queue, an audit row, anywhere durable.
+ *
+ *   Backpressure — buffer capped at `maxBufferSize` (default 10000);
+ *           emit() over the cap goes to onError + DLQ. Operators
+ *           sizing for high-throughput audit emit larger; default is
+ *           sized for "audit emissions piggyback on request handling."
+ *
+ *   AbortSignal — drain(opts?) accepts opts.signal; aborting cancels
+ *           the in-flight drain (current batch finishes; remaining
+ *           items stay in buffer for next drain).
+ *
+ *   Bounded shutdown — shutdown(opts?) drains with a timeout (default
+ *           30s). Items that don't flush in time go to DLQ or
+ *           onError; the call resolves so process exit isn't blocked.
+ *
+ * Recursion safety: when a handler is flushing, downstream code MAY
+ * emit MORE items into the same handler (e.g. audit.flush writes to
+ * external-db, which would normally audit-emit). Those additional
+ * items land in the buffer for the NEXT cycle (NOT the current batch),
+ * keeping batch sizes bounded. The flush function can mark its own
+ * writes with a sentinel (e.g. `{ skipAudit: true }`) so downstream
+ * emitters know to skip — caller-controlled, not handler concern.
+ *
+ * Metrics (handler.getStats()):
+ *   bufferSize, totalEmitted, totalFlushed, totalRetried,
+ *   totalDeadLettered, lastFlushDurationMs, breakerState.
+ *   Operators wire these to their monitoring; the handler does not
+ *   ship metrics anywhere on its own.
+ */
+
+var safeAsync = require("./safe-async");
+var C = require("./constants");
+var validateOpts = require("./validate-opts");
+var { HandlerError } = require("./framework-error");
+var { boot } = require("./log");
+
+var DEFAULTS = {
+  maxBatch:           100,
+  maxAgeMs:           C.TIME.seconds(1),
+  maxBufferSize:      10000,
+  shutdownTimeoutMs:  C.TIME.seconds(30),
+  retry: {
+    maxAttempts:    3,
+    baseDelayMs:    100,
+    maxDelayMs:     C.TIME.seconds(5),
+    jitterFactor:   0.5,
+  },
+  breaker: {
+    failureThreshold: 5,
+    cooldownMs:       C.TIME.seconds(30),
+    successThreshold: 1,
+  },
+};
+
+var _err = HandlerError.factory;
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "name", "flush",
+    "maxBatch", "maxAgeMs", "maxBufferSize", "shutdownTimeoutMs",
+    "retry", "breaker",
+    "deadLetter", "onError",
+  ], "b.handlers");
+  if (typeof opts.flush !== "function") {
+    throw _err("handlers/invalid", "create requires { flush } async function");
+  }
+
+  var name              = opts.name || "anonymous";
+  var flush             = opts.flush;
+  var maxBatch          = (opts.maxBatch          != null) ? opts.maxBatch          : DEFAULTS.maxBatch;
+  var maxAgeMs          = (opts.maxAgeMs          != null) ? opts.maxAgeMs          : DEFAULTS.maxAgeMs;
+  var maxBufferSize     = (opts.maxBufferSize     != null) ? opts.maxBufferSize     : DEFAULTS.maxBufferSize;
+  var shutdownTimeoutMs = (opts.shutdownTimeoutMs != null) ? opts.shutdownTimeoutMs : DEFAULTS.shutdownTimeoutMs;
+  // Handler retry: any thrown error from operator-supplied flush() is
+  // retried until exhaustion. The default isRetryable classifier is
+  // network-shaped and would skip generic Errors; override to retry-
+  // anything since flush failures are caller-defined, not network errors.
+  var retryConfig = Object.assign(
+    { isRetryable: function () { return true; } },
+    DEFAULTS.retry,
+    opts.retry || {}
+  );
+  var breakerConfig     = Object.assign({}, DEFAULTS.breaker, opts.breaker || {});
+  var deadLetter        = (typeof opts.deadLetter === "function") ? opts.deadLetter : null;
+  var handlerLog = boot("handlers/" + name);
+  var onError           = (typeof opts.onError    === "function") ? opts.onError    : function (err) {
+    handlerLog.error(err && err.message ? err.message : String(err));
+  };
+
+  // Buffer + drain coordination.
+  var _buffer = [];
+  var _drainPromise = null;
+  var _ageTimer = null;
+  var _oldestEnqueueAt = null;
+  var _shutdown = false;
+  var _drainMutex = new safeAsync.Mutex();
+  var _breaker = new safeAsync.CircuitBreaker("handler:" + name, breakerConfig);
+
+  // Metrics.
+  var _totalEmitted = 0;
+  var _totalFlushed = 0;
+  var _totalRetried = 0;
+  var _totalDeadLettered = 0;
+  var _lastFlushDurationMs = 0;
+
+  function _scheduleAgeFlush() {
+    if (_ageTimer) return;
+    _ageTimer = setTimeout(function () {
+      _ageTimer = null;
+      drain().catch(function (e) { onError(e, []); });
+    }, maxAgeMs);
+    if (typeof _ageTimer.unref === "function") _ageTimer.unref();
+  }
+
+  function _cancelAgeFlush() {
+    if (_ageTimer) { clearTimeout(_ageTimer); _ageTimer = null; }
+  }
+
+  function _toDeadLetter(items, err) {
+    _totalDeadLettered += items.length;
+    if (deadLetter) {
+      try { deadLetter(items, err); }
+      catch (dlqErr) { onError(_err("handlers/dlq-failed",
+        "DLQ callback for handler '" + name + "' threw", dlqErr), items); }
+    } else {
+      onError(_err("handlers/dropped",
+        items.length + " item(s) dropped from handler '" + name + "' after retry exhaustion: " +
+        (err && err.message ? err.message : String(err)), err), items);
+    }
+  }
+
+  function emit(item) {
+    if (_shutdown) {
+      onError(_err("handlers/shutdown",
+        "emit on shut-down handler '" + name + "' — item dropped"), [item]);
+      _toDeadLetter([item], _err("handlers/shutdown", "handler is shutting down"));
+      return;
+    }
+    if (_buffer.length >= maxBufferSize) {
+      var dropErr = _err("handlers/buffer-full",
+        "buffer for handler '" + name + "' exceeded maxBufferSize=" +
+        maxBufferSize + " — flush is too slow / failing");
+      onError(dropErr, [item]);
+      _toDeadLetter([item], dropErr);
+      return;
+    }
+    _totalEmitted += 1;
+    _buffer.push(item);
+    if (_oldestEnqueueAt === null) _oldestEnqueueAt = Date.now();
+
+    if (_buffer.length >= maxBatch) {
+      _cancelAgeFlush();
+      drain().catch(function (e) { onError(e, []); });
+    } else {
+      _scheduleAgeFlush();
+    }
+  }
+
+  // Drain the buffer with retry + breaker + DLQ. Items emitted DURING
+  // a drain land in the buffer for the NEXT drain cycle (NOT the
+  // current call) — see the recursion-safety note in this module's
+  // header. Without this bound, a handler whose flush() emits MORE
+  // items into the same handler (cluster-mode audit: writing an
+  // audit row goes through externalDb.query, which emits a
+  // system.externaldb.query audit event back into the buffer)
+  // produces an unbounded loop where the buffer refills as fast as
+  // it drains.
+  //
+  // Implementation: snapshot _buffer.length at start; process exactly
+  // that many items (in batches of maxBatch). Items emitted during
+  // the drain accrue at the tail of _buffer and are visible to the
+  // next drain() call. Concurrent drain() calls share the in-flight
+  // Promise.
+  function drain(drainOpts) {
+    if (_drainPromise) return _drainPromise;
+    drainOpts = drainOpts || {};
+    var signal = drainOpts.signal || null;
+
+    _drainPromise = _drainMutex.runExclusive(async function () {
+      _cancelAgeFlush();
+      var remaining = _buffer.length;
+      while (remaining > 0) {
+        if (signal && signal.aborted) break;
+        var take = Math.min(maxBatch, remaining);
+        var batch = _buffer.splice(0, take);
+        remaining -= batch.length;
+        _oldestEnqueueAt = _buffer.length > 0 ? Date.now() : null;
+
+        var t0 = Date.now();
+        try {
+          await _breaker.wrap(async function () {
+            // Retry the entire batch on transient failures. Each retry
+            // re-enters the operator's flush() with the same items; the
+            // operator's flush() should be idempotent within a batch
+            // (or accept the duplicate-write trade-off).
+            //
+            // The operator flush() receives an isShutdown() probe in its
+            // second arg so it can early-exit between items if the
+            // handler was shut down mid-batch (e.g. by a test reset).
+            // Without that check, an in-flight flush keeps processing
+            // batch[i++] items even after shutdown — and audit's
+            // flush in particular writes those into whatever database
+            // is currently bound, leaking rows into the next test's db.
+            var attempts = 0;
+            await safeAsync.asyncRetry(async function () {
+              if (attempts > 0) _totalRetried += 1;
+              attempts += 1;
+              await flush(batch, { isShutdown: function () { return _shutdown; } });
+            }, retryConfig);
+          });
+          _totalFlushed += batch.length;
+        } catch (e) {
+          // Retry exhausted OR breaker open. Items go to DLQ; loop
+          // continues so other batches still attempt — unless the
+          // breaker is open, in which case the next iteration's
+          // _breaker.wrap will fail-fast immediately.
+          _toDeadLetter(batch, e);
+          if (e && e.code === "CIRCUIT_OPEN") {
+            // Stop the drain; remaining buffered items will be tried
+            // again on the next emit() / drain() call.
+            break;
+          }
+        }
+        _lastFlushDurationMs = Date.now() - t0;
+      }
+    }).then(function (v) { _drainPromise = null; return v; },
+            function (e) { _drainPromise = null; throw e; });
+    return _drainPromise;
+  }
+
+  async function shutdown(shutdownOpts) {
+    shutdownOpts = shutdownOpts || {};
+    var timeoutMs = (shutdownOpts.timeoutMs != null) ? shutdownOpts.timeoutMs : shutdownTimeoutMs;
+    _shutdown = true;
+    _cancelAgeFlush();
+    try {
+      await safeAsync.withTimeout(drain(), timeoutMs, { name: "handler:" + name + ".shutdown" });
+    } catch (e) {
+      // Timeout or breaker fail — DLQ whatever's left, then return.
+      var leftover = _buffer.splice(0);
+      if (leftover.length > 0) {
+        _toDeadLetter(leftover, e);
+      }
+    }
+  }
+
+  // Synchronous "stop and drop" — for test resets and other cases
+  // where draining buffered items would write to a stale or changing
+  // backing store. Sets the shutdown flag, cancels the age timer, and
+  // drops every buffered item to the DLQ. After this returns, no
+  // setTimeout from this handler can fire and emit() drops every
+  // future item with handlers/shutdown.
+  function shutdownSync(reason) {
+    _shutdown = true;
+    _cancelAgeFlush();
+    var dropped = _buffer.splice(0);
+    if (dropped.length > 0) {
+      _toDeadLetter(
+        dropped,
+        _err("handlers/shutdown-drop",
+          "handler '" + name + "' shut down with " + dropped.length +
+          " buffered item(s); items dropped: " + (reason || "no-drain shutdown"))
+      );
+    }
+  }
+
+  function getStats() {
+    return {
+      bufferSize:            _buffer.length,
+      totalEmitted:          _totalEmitted,
+      totalFlushed:          _totalFlushed,
+      totalRetried:          _totalRetried,
+      totalDeadLettered:     _totalDeadLettered,
+      lastFlushDurationMs:   _lastFlushDurationMs,
+      breakerState:          _breaker.getState ? _breaker.getState() : null,
+      isShutdown:            _shutdown,
+    };
+  }
+
+  function size() { return _buffer.length; }
+
+  return {
+    name:         name,
+    emit:         emit,
+    drain:        drain,
+    shutdown:     shutdown,
+    shutdownSync: shutdownSync,
+    getStats:     getStats,
+    size:         size,
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/html-balance.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * html-balance — minimal HTML structural sanity check.
+ *
+ * Scans an HTML fragment looking for unbalanced container tags
+ * (unclosed `<div>`, mismatched `<table>`/`</tr>`, etc.). Returns
+ * `null` when balanced; an object `{ code, message, line, column }`
+ * when not. The intent is operator-side feedback at save time —
+ * "you forgot to close this tag" — not security validation.
+ *
+ * What this catches:
+ *   - container tag opened but never closed at the same nesting depth
+ *   - close tag with no matching open
+ *   - close tag mismatched with the most recent open tag
+ *   - unterminated comment `<!-- ... ` (no `-->`)
+ *
+ * What this does NOT catch:
+ *   - bad attribute syntax (browsers are tolerant)
+ *   - unknown tag names (custom elements / shadow DOM)
+ *   - script content (skipped between `<script>` / `</script>`)
+ *   - style content (skipped between `<style>` / `</style>`)
+ *   - XSS or sanitization concerns — that's a separate primitive
+ *
+ * Usage:
+ *
+ *   var problem = b.htmlBalance.check(operatorSubmittedHtml);
+ *   if (problem) return res.status(400).render({ error: problem.message });
+ */
+
+// Tags that are NEVER closed (HTML5 void elements).
+var VOID_TAGS = Object.freeze({
+  area: 1, base: 1, br: 1, col: 1, embed: 1, hr: 1, img: 1, input: 1,
+  link: 1, meta: 1, param: 1, source: 1, track: 1, wbr: 1,
+});
+
+// Tags whose content is treated as raw text (skipped by this checker).
+var RAW_TEXT_TAGS = Object.freeze({ script: 1, style: 1, textarea: 1, title: 1 });
+
+function _posToLineColumn(src, pos) {
+  var line = 1, col = 1;
+  for (var i = 0; i < pos && i < src.length; i++) {
+    if (src.charCodeAt(i) === 10) { line++; col = 1; }
+    else col++;
+  }
+  return { line: line, column: col };
+}
+
+function check(html) {
+  if (typeof html !== "string" || html.length === 0) return null;
+  var stack = [];   // [{ tag, openPos }]
+  var i = 0;
+  var len = html.length;
+
+  while (i < len) {
+    // Comment skip: <!-- ... -->
+    if (html.charCodeAt(i) === 0x3C /* < */ &&
+        html.charCodeAt(i + 1) === 0x21 /* ! */ &&
+        html.charCodeAt(i + 2) === 0x2D &&
+        html.charCodeAt(i + 3) === 0x2D) {
+      var endComment = html.indexOf("-->", i + 4);
+      if (endComment === -1) {
+        var pos = _posToLineColumn(html, i);
+        return {
+          code:    "html/unterminated-comment",
+          message: "unterminated <!-- comment (no closing -->) at line " +
+            pos.line + " col " + pos.column,
+          line:    pos.line,
+          column:  pos.column,
+        };
+      }
+      i = endComment + 3;
+      continue;
+    }
+
+    // CDATA / doctype / processing-instructions are passed over.
+    if (html.charCodeAt(i) === 0x3C /* < */ &&
+        html.charCodeAt(i + 1) === 0x21 /* ! */) {
+      var gt = html.indexOf(">", i);
+      if (gt === -1) break;
+      i = gt + 1;
+      continue;
+    }
+
+    // Tag scan: `<` starts an element open or close.
+    if (html.charCodeAt(i) === 0x3C /* < */) {
+      var isClose = html.charCodeAt(i + 1) === 0x2F /* / */;
+      var nameStart = i + (isClose ? 2 : 1);
+      // Tag name: ASCII letters, digits, hyphen.
+      var nameEnd = nameStart;
+      while (nameEnd < len) {
+        var c = html.charCodeAt(nameEnd);
+        if ((c >= 0x41 && c <= 0x5A) || (c >= 0x61 && c <= 0x7A) ||
+            (c >= 0x30 && c <= 0x39) || c === 0x2D /* - */) nameEnd++;
+        else break;
+      }
+      if (nameEnd === nameStart) {
+        // Looks like a stray `<` not starting a tag — skip past it.
+        i++;
+        continue;
+      }
+      var tag = html.slice(nameStart, nameEnd).toLowerCase();
+      // Find the matching `>` for this tag (skip over quoted attribute values).
+      var j = nameEnd;
+      var inQuote = 0;
+      while (j < len) {
+        var ch = html.charCodeAt(j);
+        if (inQuote) {
+          if (ch === inQuote) inQuote = 0;
+        } else if (ch === 0x22 /* " */ || ch === 0x27 /* ' */) {
+          inQuote = ch;
+        } else if (ch === 0x3E /* > */) {
+          break;
+        }
+        j++;
+      }
+      if (j >= len) {
+        var p = _posToLineColumn(html, i);
+        return {
+          code:    "html/unterminated-tag",
+          message: "unterminated tag '<" + (isClose ? "/" : "") + tag +
+            "' (no closing >) at line " + p.line + " col " + p.column,
+          line:    p.line,
+          column:  p.column,
+        };
+      }
+      // Self-closing: `<foo />` or `<foo/>` or HTML5 void elements.
+      var selfClose = html.charCodeAt(j - 1) === 0x2F /* / */;
+      if (isClose) {
+        if (VOID_TAGS[tag]) {
+          // Stray closer for a void tag — surface as error.
+          var pcv = _posToLineColumn(html, i);
+          return {
+            code:    "html/void-close",
+            message: "closing tag </" + tag + "> for a void element at line " +
+              pcv.line + " col " + pcv.column,
+            line:    pcv.line,
+            column:  pcv.column,
+          };
+        }
+        var top = stack[stack.length - 1];
+        if (!top) {
+          var pco = _posToLineColumn(html, i);
+          return {
+            code:    "html/orphan-close",
+            message: "</" + tag + "> with no matching open tag at line " +
+              pco.line + " col " + pco.column,
+            line:    pco.line,
+            column:  pco.column,
+          };
+        }
+        if (top.tag !== tag) {
+          var pcm = _posToLineColumn(html, i);
+          var pop = _posToLineColumn(html, top.openPos);
+          return {
+            code:    "html/mismatched-close",
+            message: "</" + tag + "> at line " + pcm.line + " col " + pcm.column +
+              " does not match open <" + top.tag + "> at line " + pop.line +
+              " col " + pop.column,
+            line:    pcm.line,
+            column:  pcm.column,
+          };
+        }
+        stack.pop();
+      } else {
+        // Open tag (or self-closing).
+        if (selfClose || VOID_TAGS[tag]) {
+          // No push.
+        } else if (RAW_TEXT_TAGS[tag]) {
+          // Skip raw-text content AND its closing tag entirely. Inside
+          // <script>/<style>/<textarea>/<title> the `<` characters are
+          // text, not markup — re-entering the tag scanner on
+          // `</script>` would otherwise treat it as an orphan close.
+          var rawClose = "</" + tag;
+          var found = -1;
+          var search = j + 1;
+          var lower = html.toLowerCase();
+          while (search < len) {
+            var idx = lower.indexOf(rawClose, search);
+            if (idx === -1) break;
+            var afterIdx = idx + rawClose.length;
+            var ac = html.charCodeAt(afterIdx);
+            if (afterIdx >= len || ac === 0x3E || ac <= 0x20) {
+              found = idx;
+              break;
+            }
+            search = idx + 1;
+          }
+          if (found === -1) {
+            var pcr = _posToLineColumn(html, i);
+            return {
+              code:    "html/unclosed-raw-text",
+              message: "unclosed <" + tag + "> raw-text element at line " +
+                pcr.line + " col " + pcr.column,
+              line:    pcr.line,
+              column:  pcr.column,
+            };
+          }
+          // Advance past the closing `>` of the close tag.
+          var closeGt = html.indexOf(">", found);
+          if (closeGt === -1) closeGt = len - 1;
+          i = closeGt + 1;
+          continue;
+        } else {
+          stack.push({ tag: tag, openPos: i });
+        }
+      }
+      i = j + 1;
+      continue;
+    }
+    i++;
+  }
+
+  if (stack.length > 0) {
+    var leftover = stack[stack.length - 1];
+    var pl = _posToLineColumn(html, leftover.openPos);
+    return {
+      code:    "html/unclosed-tag",
+      message: "unclosed <" + leftover.tag + "> at line " + pl.line +
+        " col " + pl.column + " (no matching </" + leftover.tag + ">)",
+      line:    pl.line,
+      column:  pl.column,
+    };
+  }
+  return null;
+}
+
+module.exports = { check: check };