@blamejs/core 0.5.11 → 0.5.13

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.12** (2026-04-30) — b.middleware.requestLog: HTTP access-log middleware
+- **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/lib/testing.js

@@ -547,6 +547,165 @@ function listenOnRandomPort(server, host) {
 // Standalone fake of @opentelemetry/api's minimal subset that
 // b.tracing actually consumes. No framework primitive owns this.
 
+// ---- request(target) — supertest-style chainable HTTP test helper ----
+//
+//   var res = await b.testing.request(router)
+//     .post("/api/widget")
+//     .set("X-Request-Id", "abc")
+//     .send({ name: "alpha" })
+//     .expect(200);
+//
+//   res.status, res.headers, res.body (Buffer), res.json (parsed if applicable)
+//
+// Accepts:
+//   - a b.router instance (uses .handle(req, res))
+//   - a request listener function (req, res) => void
+//   - an http.Server / https.Server (used as-is)
+//
+// The framework spins up a real http.Server on an ephemeral port so
+// the request flows through the full Node http stack — same code path
+// production traffic takes. Server is closed automatically when the
+// promise resolves or rejects.
+function request(target) {
+  var http = require("node:http");
+  // Resolve target → request listener
+  var server;
+  var ownsServer = false;
+  if (target && typeof target.handle === "function") {
+    server = http.createServer(function (req, res) {
+      Promise.resolve(target.handle(req, res)).catch(function (err) {
+        if (!res.headersSent) res.writeHead(500, { "Content-Type": "text/plain" });
+        try { res.end((err && err.message) || "Internal Server Error"); } catch (_e) { /* response may already be ended */ }
+      });
+    });
+    ownsServer = true;
+  } else if (typeof target === "function") {
+    server = http.createServer(target);
+    ownsServer = true;
+  } else if (target && typeof target.listen === "function" && typeof target.close === "function") {
+    server = target;
+    ownsServer = false;
+  } else {
+    throw new Error("b.testing.request: target must be a b.router, a (req,res)=>void function, or an http.Server");
+  }
+
+  function _start(method, path) {
+    var headers = {};
+    var body = null;
+    var expectations = [];
+
+    var chain = {
+      set: function (k, v) {
+        if (typeof k === "object" && k !== null) Object.assign(headers, k);
+        else headers[k] = v;
+        return chain;
+      },
+      send: function (b) {
+        if (b == null) { body = null; return chain; }
+        if (Buffer.isBuffer(b) || typeof b === "string") {
+          body = b;
+        } else {
+          body = JSON.stringify(b);
+          if (!headers["Content-Type"] && !headers["content-type"]) {
+            headers["Content-Type"] = "application/json";
+          }
+        }
+        return chain;
+      },
+      expect: function (statusOrAssertion) {
+        expectations.push(statusOrAssertion);
+        return chain;
+      },
+      then: function (onFulfilled, onRejected) {
+        return _execute().then(onFulfilled, onRejected);
+      },
+      catch: function (onRejected) {
+        return _execute().catch(onRejected);
+      },
+    };
+
+    function _execute() {
+      return new Promise(function (resolve, reject) {
+        var listenP;
+        if (ownsServer) listenP = listenOnRandomPort(server);
+        else listenP = Promise.resolve(server.address() ? server.address().port : null);
+
+        listenP.then(function (port) {
+          var reqOpts = {
+            host:    "127.0.0.1",
+            port:    port,
+            method:  method,
+            path:    path,
+            headers: headers,
+          };
+          var nodeReq = http.request(reqOpts, function (nodeRes) {
+            var chunks = [];
+            nodeRes.on("data", function (c) { chunks.push(c); });
+            nodeRes.on("end", function () {
+              var bodyBuf = Buffer.concat(chunks);
+              var bodyText = bodyBuf.toString("utf8");
+              var json = null;
+              var ct = nodeRes.headers["content-type"] || "";
+              if (ct.indexOf("application/json") !== -1) {
+                try { json = JSON.parse(bodyText); } catch (_e) { /* leave json null */ }
+              }
+              var result = {
+                status:  nodeRes.statusCode,
+                headers: nodeRes.headers,
+                body:    bodyBuf,
+                text:    bodyText,
+                json:    json,
+              };
+              try {
+                for (var i = 0; i < expectations.length; i++) {
+                  var exp = expectations[i];
+                  if (typeof exp === "number") {
+                    if (result.status !== exp) {
+                      throw new Error("expect(" + exp + ") got status " + result.status +
+                        " body: " + bodyText.slice(0, 200));
+                    }
+                  } else if (typeof exp === "function") {
+                    exp(result);
+                  } else {
+                    throw new Error("expect: argument must be a number or function");
+                  }
+                }
+                resolve(result);
+              } catch (e) {
+                reject(e);
+              } finally {
+                if (ownsServer) try { server.close(); } catch (_e) { /* server may already be closed */ }
+              }
+            });
+            nodeRes.on("error", function (err) {
+              if (ownsServer) try { server.close(); } catch (_e) { /* */ }
+              reject(err);
+            });
+          });
+          nodeReq.on("error", function (err) {
+            if (ownsServer) try { server.close(); } catch (_e) { /* */ }
+            reject(err);
+          });
+          if (body != null) nodeReq.write(body);
+          nodeReq.end();
+        }, reject);
+      });
+    }
+
+    return chain;
+  }
+
+  return {
+    get:    function (p) { return _start("GET",    p); },
+    post:   function (p) { return _start("POST",   p); },
+    put:    function (p) { return _start("PUT",    p); },
+    patch:  function (p) { return _start("PATCH",  p); },
+    delete: function (p) { return _start("DELETE", p); },
+    head:   function (p) { return _start("HEAD",   p); },
+    options:function (p) { return _start("OPTIONS",p); },
+  };
+}
+
 function makeFakeOtelApi() {
   var spans = [];
   var activeSpan = null;
@@ -615,6 +774,8 @@ module.exports = {
   // Async test helpers
   runMiddleware:          runMiddleware,
   waitFor:                waitFor,
+  // Chainable HTTP request helper (supertest-style)
+  request:                request,
   // Class + constants
   TestingError:           TestingError,
   DEFAULTS:               DEFAULTS,

package/package.json

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