@blamejs/core 0.5.11 → 0.5.12

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.11** (2026-04-30) — b.config: schema-validated environment configuration
 - **0.5.10** (2026-04-30) — b.middleware.sse: Server-Sent Events
 - **0.5.9** (2026-04-30) — b.csv: RFC 4180 parser + serializer
 - **0.5.8** (2026-04-30) — b.uuid: RFC 4122 v4 + RFC 9562 v7

package/lib/middleware/index.js

@@ -31,6 +31,7 @@ module.exports = {
   compression:     require("./compression").create,
   cspNonce:        require("./csp-nonce").create,
   sse:             require("./sse").create,
+  requestLog:      require("./request-log").create,
   apiEncrypt:      require("./api-encrypt"),
 
   // Module exports for advanced use (constants, raw factory access)
@@ -49,6 +50,7 @@ module.exports = {
     compression:     require("./compression"),
     cspNonce:        require("./csp-nonce"),
     sse:             require("./sse"),
+    requestLog:      require("./request-log"),
     apiEncrypt:      require("./api-encrypt"),
   },
 };

package/lib/middleware/request-log.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * request-log — HTTP access-log middleware. Captures method, path,
+ * status, duration, response bytes, requestId, actor IP, user-agent
+ * and emits one structured log entry per request via b.log.
+ *
+ *   router.use(b.middleware.requestLog({
+ *     logger:        b.log.boot("http"),     // any b.log instance
+ *     skipPaths:     ["/healthz", /^\/static/],
+ *     trustProxy:    true,                   // honors X-Forwarded-For
+ *     levelFn:       function (status) {     // default: 5xx=error, 4xx=warn, else info
+ *       return status >= 500 ? "error" : status >= 400 ? "warn" : "info";
+ *     },
+ *     fields:        ["method", "path", "status", "durationMs",
+ *                     "actorIp", "userAgent", "requestId", "bytes"],
+ *   }));
+ *
+ * The middleware adopts `b.requestHelpers.captureResponseStatus` to
+ * read the final status reliably (handlers that call `res.writeHead`
+ * vs `res.statusCode = ...` vs `res.status(...).send(...)` all work).
+ *
+ * trustProxy gates X-Forwarded-For consumption — same boundary as the
+ * rest of the framework. Default false; operators behind a sanitizing
+ * reverse proxy opt in.
+ *
+ * Emits at log-level keyed off response status by default. Operators
+ * who want one-level-fits-all pass a static string for `level` (e.g.
+ * "debug" to keep access logs out of production stdout) or a function
+ * for fully custom logic (e.g. "warn" only on slow-path requests).
+ */
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+
+var DEFAULT_FIELDS = [
+  "method", "path", "status", "durationMs", "bytes",
+  "actorIp", "userAgent", "requestId",
+];
+
+function _defaultLevel(status) {
+  if (status >= 500) return "error";
+  if (status >= 400) return "warn";
+  return "info";
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "logger", "skipPaths", "trustProxy", "level", "levelFn", "fields",
+  ], "middleware.requestLog");
+  var logger = opts.logger;
+  if (!logger || typeof logger.info !== "function") {
+    throw new Error("middleware.requestLog: opts.logger must be a b.log instance " +
+      "(call b.log.boot(...) or b.log.create({...}))");
+  }
+  var skipPaths = Array.isArray(opts.skipPaths) ? opts.skipPaths.slice() : [];
+  for (var i = 0; i < skipPaths.length; i++) {
+    if (typeof skipPaths[i] !== "string" && !(skipPaths[i] instanceof RegExp)) {
+      throw new Error("middleware.requestLog: skipPaths[" + i + "] must be a string prefix or RegExp");
+    }
+  }
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var levelFn;
+  if (typeof opts.levelFn === "function") {
+    levelFn = opts.levelFn;
+  } else if (typeof opts.level === "string") {
+    var fixedLevel = opts.level;
+    levelFn = function () { return fixedLevel; };
+  } else {
+    levelFn = _defaultLevel;
+  }
+  var fields = Array.isArray(opts.fields) && opts.fields.length > 0
+    ? opts.fields.slice()
+    : DEFAULT_FIELDS;
+
+  function _shouldSkip(req) {
+    var path = req.pathname || (req.url || "").split("?")[0];
+    for (var i = 0; i < skipPaths.length; i++) {
+      var entry = skipPaths[i];
+      if (typeof entry === "string") { if (path.indexOf(entry) === 0) return true; }
+      else if (entry.test(path)) return true;
+    }
+    return false;
+  }
+
+  return function requestLog(req, res, next) {
+    if (_shouldSkip(req)) return next();
+    var startedAt = process.hrtime ? process.hrtime() : null;
+    var startedMs = Date.now();
+    var bytes = 0;
+    var statusFromWriteHead = null;
+    var emitted = false;
+
+    // Tally bytes off res.write / res.end and read the final status
+    // when end fires. Inlined here (rather than composing
+    // captureResponseStatus + a separate byte-counter) so the log
+    // entry sees the fully-populated bytes counter — wrap order
+    // matters: bytes must be incremented BEFORE the log emit.
+    var origWrite     = res.write;
+    var origEnd       = res.end;
+    var origWriteHead = res.writeHead;
+    res.writeHead = function (s) {
+      statusFromWriteHead = s;
+      return origWriteHead.apply(res, arguments);
+    };
+    res.write = function (chunk, enc, cb) {
+      if (chunk != null) {
+        var len = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk), enc || "utf8");
+        bytes += len;
+      }
+      return origWrite.call(res, chunk, enc, cb);
+    };
+    res.end = function (chunk, enc, cb) {
+      if (chunk != null) {
+        var len = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk), enc || "utf8");
+        bytes += len;
+      }
+      _emit();
+      return origEnd.call(res, chunk, enc, cb);
+    };
+
+    function _emit() {
+      if (emitted) return;
+      emitted = true;
+      var statusCode = statusFromWriteHead != null
+        ? statusFromWriteHead
+        : (typeof res.statusCode === "number" ? res.statusCode : 200);
+      var durationMs;
+      if (startedAt && process.hrtime) {
+        var d = process.hrtime(startedAt);
+        durationMs = (d[0] * 1000) + (d[1] / 1e6);
+      } else {
+        durationMs = Date.now() - startedMs;
+      }
+      var entry = {};
+      var actor = requestHelpers.extractActorContext(req, {
+        ip: requestHelpers.clientIp(req, { trustProxy: trustProxy }),
+      });
+      var src = {
+        method:     req.method,
+        path:       req.pathname || (req.url || "").split("?")[0],
+        status:     statusCode,
+        durationMs: Math.round(durationMs * 100) / 100,
+        bytes:      bytes,
+        actorIp:    actor.ip,
+        userAgent:  actor.userAgent,
+        requestId:  actor.requestId,
+        sessionId:  actor.sessionId,
+        userId:     actor.userId,
+        route:      actor.route,
+      };
+      for (var fi = 0; fi < fields.length; fi++) {
+        var f = fields[fi];
+        if (Object.prototype.hasOwnProperty.call(src, f)) entry[f] = src[f];
+      }
+      var level = levelFn(statusCode, req, res);
+      var fn = typeof logger[level] === "function" ? logger[level] : logger.info;
+      try { fn.call(logger, "http", entry); } catch (_e) { /* never let log-emit failure crash the response */ }
+    }
+
+    return next();
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/package.json

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