@blamejs/core 0.5.10 → 0.5.12

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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
 - **0.5.7** (2026-04-30) — defensive validation + queue closure capture + audit context

package/index.js

@@ -106,6 +106,7 @@ var forms = require("./lib/forms");
 var app = require("./lib/app");
 var jobs = require("./lib/jobs");
 var breakGlass = require("./lib/break-glass");
+var config = require("./lib/config");
 var csv = require("./lib/csv");
 var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
@@ -210,6 +211,7 @@ module.exports = {
   createApp:        app.createApp,
   jobs:             jobs,
   breakGlass:       breakGlass,
+  config:           config,
   csv:              csv,
   uuid:             uuid,
   mail:             mail,

package/lib/config.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * config — schema-validated environment configuration.
+ *
+ * Operators read process.env throughout their app code. A typo in the
+ * key name OR a value in the wrong shape (port="abc", flag="yas")
+ * surfaces three days later as a mysterious 500. This primitive validates
+ * env at boot via b.safeSchema so the app refuses to start with broken
+ * config.
+ *
+ *   var config = b.config.create({
+ *     schema: b.safeSchema.object({
+ *       NODE_ENV:        b.safeSchema.enum_(["development", "test", "production"]),
+ *       PORT:            b.config.coerce.number().default(3000),
+ *       LOG_LEVEL:       b.safeSchema.enum_(["debug", "info", "warn", "error"]).default("info"),
+ *       SESSION_SECRET:  b.safeSchema.string().min(32),
+ *       DATABASE_URL:    b.safeSchema.string().url(),
+ *       REDIS_URL:       b.safeSchema.string().url().optional(),
+ *       FEATURE_X:       b.config.coerce.boolean().default(false),
+ *     }),
+ *     // env: process.env (default) — operators in tests pass a fake object
+ *     // redactKeys: ["SESSION_SECRET", "DATABASE_URL"] — never log these
+ *   });
+ *
+ *   config.value          → the validated, typed value object
+ *   config.value.PORT     → 3000 (Number, not "3000")
+ *   config.boot()         → throws ConfigError on validation failure;
+ *                           returns the validated value otherwise
+ *
+ * The factory immediately runs validation — the throw at create() time
+ * is intentional. Operators want config errors at app boot, not at
+ * the first request that touches the broken value.
+ */
+var safeSchema = require("./safe-schema");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var REDACT_MASK = "[REDACTED]";
+
+var ConfigError = defineClass("ConfigError", { alwaysPermanent: true });
+
+// Coercion shapes most operators want for env values: number, integer,
+// boolean — env is always a string at the source so coerce. Operators
+// who want stricter parsing chain .refine() or use raw schemas.
+var coerce = {
+  number: function () {
+    return safeSchema.preprocess(function (v) {
+      if (v === undefined || v === null || v === "") return v;
+      var n = Number(v);
+      return isNaN(n) ? v : n;
+    }, safeSchema.number());
+  },
+  boolean: function () {
+    return safeSchema.preprocess(function (v) {
+      if (typeof v === "boolean") return v;
+      if (v === "1" || v === "true"  || v === "yes") return true;
+      if (v === "0" || v === "false" || v === "no")  return false;
+      return v;  // pass through — schema rejects non-boolean
+    }, safeSchema.boolean());
+  },
+};
+
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new ConfigError("config/bad-opts",
+      "create: opts is required (must include opts.schema)");
+  }
+  validateOpts(opts, ["schema", "env", "redactKeys"], "config.create");
+  if (!opts.schema || typeof opts.schema.parse !== "function") {
+    throw new ConfigError("config/bad-schema",
+      "create: opts.schema must be a b.safeSchema instance (built via b.safeSchema.object({...}))");
+  }
+  var env = opts.env || process.env;
+  if (env !== process.env && (typeof env !== "object" || env === null)) {
+    throw new ConfigError("config/bad-env",
+      "create: opts.env must be an object (default process.env)");
+  }
+  var redactKeys = Array.isArray(opts.redactKeys) ? opts.redactKeys.slice() : [];
+  for (var i = 0; i < redactKeys.length; i++) {
+    if (typeof redactKeys[i] !== "string" || redactKeys[i].length === 0) {
+      throw new ConfigError("config/bad-redact-keys",
+        "create: redactKeys[" + i + "] must be a non-empty string");
+    }
+  }
+  // Filter env to a plain object — process.env's prototype chain
+  // includes inherited Object.prototype keys we don't want to validate.
+  var input = {};
+  for (var k in env) {
+    if (Object.prototype.hasOwnProperty.call(env, k)) input[k] = env[k];
+  }
+
+  var result = opts.schema.safeParse(input);
+  if (!result.ok) {
+    var msg = "config validation failed:\n";
+    for (var ei = 0; ei < result.errors.length; ei++) {
+      var err = result.errors[ei];
+      msg += "  - " + err.path.join(".") + ": " + err.message + "\n";
+    }
+    throw new ConfigError("config/validation-failed", msg);
+  }
+
+  var value = result.value;
+
+  function redactedView() {
+    // For logging the validated config without leaking secrets — useful
+    // at boot ("loaded config: { NODE_ENV: 'production', PORT: 3000, ... }").
+    var out = {};
+    for (var k in value) {
+      if (!Object.prototype.hasOwnProperty.call(value, k)) continue;
+      out[k] = redactKeys.indexOf(k) !== -1 ? REDACT_MASK : value[k];
+    }
+    return out;
+  }
+
+  return {
+    value:    value,
+    get:      function (key) { return value[key]; },
+    has:      function (key) { return Object.prototype.hasOwnProperty.call(value, key); },
+    redacted: redactedView,
+  };
+}
+
+module.exports = {
+  create:      create,
+  ConfigError: ConfigError,
+  coerce:      coerce,
+};

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.10",
+  "version": "0.5.12",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",