@blamejs/core 0.4.14 → 0.4.16

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.15** (2026-04-30) — b.httpClient: redirect-following + outbound multipart
+- **0.4.14** (2026-04-30) — b.i18n: lazy locales + ordinal plurals + onMissingKey hook
 - **0.4.13** (2026-04-30) — b.db: streaming query results
 - **0.4.12** (2026-04-30) — b.log: multi-sink output with per-sink level filtering
 - **0.4.11** (2026-04-30) — b.cache: bytes-cap eviction, sliding TTL, tag invalidation

package/lib/http-client.js

@@ -292,10 +292,256 @@ function _fromH2Headers(h2Headers) {
 
 // ---- request() ----
 
+var REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+// Build a multipart/form-data body from { fields, files } shape.
+// Mirrors the wire format that lib/middleware/body-parser.js's multipart
+// parser accepts so round-trip from one blamejs app's outbound to
+// another's inbound is exact.
+function _buildMultipartBody(spec) {
+  var nodeCrypto = require("node:crypto");
+  var boundary = "----blamejs-mp-" + nodeCrypto.randomBytes(16).toString("hex");
+  var CRLF = "\r\n";
+  var parts = [];
+
+  function _pushField(name, value) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new Error("multipart: field name must be a non-empty string");
+    }
+    var head = "--" + boundary + CRLF +
+               'Content-Disposition: form-data; name="' + name + '"' + CRLF + CRLF;
+    parts.push(Buffer.from(head, "utf8"));
+    parts.push(Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8"));
+    parts.push(Buffer.from(CRLF, "utf8"));
+  }
+
+  function _pushFile(file) {
+    if (!file || typeof file !== "object") throw new Error("multipart: file entries must be objects");
+    if (typeof file.field !== "string" || file.field.length === 0) {
+      throw new Error("multipart: file.field must be a non-empty string");
+    }
+    var filename = typeof file.filename === "string" && file.filename.length > 0
+      ? file.filename : "blob";
+    var mimeType = file.contentType || file.mimeType || "application/octet-stream";
+    var content = file.content;
+    if (typeof content === "string") content = Buffer.from(content, "utf8");
+    if (!Buffer.isBuffer(content)) {
+      throw new Error("multipart: file.content must be a Buffer or string");
+    }
+    var head = "--" + boundary + CRLF +
+               'Content-Disposition: form-data; name="' + file.field + '"' +
+                 '; filename="' + filename.replace(/"/g, "%22") + '"' + CRLF +
+               "Content-Type: " + mimeType + CRLF + CRLF;
+    parts.push(Buffer.from(head, "utf8"));
+    parts.push(content);
+    parts.push(Buffer.from(CRLF, "utf8"));
+  }
+
+  if (spec && spec.fields && typeof spec.fields === "object") {
+    var keys = Object.keys(spec.fields);
+    for (var i = 0; i < keys.length; i++) {
+      var k = keys[i];
+      var v = spec.fields[k];
+      if (Array.isArray(v)) {
+        for (var j = 0; j < v.length; j++) _pushField(k, v[j]);
+      } else {
+        _pushField(k, v);
+      }
+    }
+  }
+  if (spec && Array.isArray(spec.files)) {
+    for (var fi = 0; fi < spec.files.length; fi++) _pushFile(spec.files[fi]);
+  }
+  parts.push(Buffer.from("--" + boundary + "--" + CRLF, "utf8"));
+  return { boundary: boundary, body: Buffer.concat(parts) };
+}
+
+// Headers stripped on cross-origin redirect to defend against accidental
+// credential exfiltration. Lower-case for header-map comparison.
+var SENSITIVE_HEADERS_LC = ["authorization", "cookie", "proxy-authorization"];
+
+function _stripCrossOriginAuth(headers) {
+  var out = {};
+  var keys = Object.keys(headers);
+  for (var i = 0; i < keys.length; i++) {
+    if (SENSITIVE_HEADERS_LC.indexOf(keys[i].toLowerCase()) !== -1) continue;
+    out[keys[i]] = headers[keys[i]];
+  }
+  return out;
+}
+
 function request(opts) {
   if (!opts || !opts.url) {
     return Promise.reject(_makeError(opts && opts.errorClass, "BAD_ARG", "url is required", true));
   }
+
+  // Validate before/after shapes early — Tier-A throw if the operator
+  // passed something un-callable so the bug surfaces at the call site
+  // rather than inside the request loop.
+  if (opts.before !== undefined) {
+    if (!Array.isArray(opts.before) || !opts.before.every(function (f) { return typeof f === "function"; })) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+        "before must be an array of functions", true));
+    }
+  }
+  if (opts.after !== undefined) {
+    if (!Array.isArray(opts.after) || !opts.after.every(function (f) { return typeof f === "function"; })) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+        "after must be an array of functions", true));
+    }
+  }
+  if (opts.onUploadProgress !== undefined && typeof opts.onUploadProgress !== "function") {
+    return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+      "onUploadProgress must be a function", true));
+  }
+  if (opts.onDownloadProgress !== undefined && typeof opts.onDownloadProgress !== "function") {
+    return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+      "onDownloadProgress must be a function", true));
+  }
+
+  // before interceptors — run in array order. Each may return a modified
+  // opts object (or return nothing to leave the running opts as-is).
+  // Caller-set defaults / observability / auth header injection lands
+  // here. Synchronous to keep the request hot path simple; async
+  // pre-flight work (e.g. token refresh) belongs in the route handler
+  // before httpClient.request is even called.
+  if (Array.isArray(opts.before) && opts.before.length > 0) {
+    var working = opts;
+    for (var bi = 0; bi < opts.before.length; bi++) {
+      var ret;
+      try { ret = opts.before[bi](working); }
+      catch (e) {
+        return Promise.reject(_makeError(opts.errorClass, "BEFORE_THREW",
+          "before[" + bi + "] threw: " + ((e && e.message) || String(e)), true));
+      }
+      if (ret && typeof ret === "object") working = ret;
+    }
+    opts = working;
+  }
+
+  // Multipart shorthand: { multipart: { fields, files } } expands to
+  // body + Content-Type with the boundary parameter. Mutually exclusive
+  // with caller-supplied body / Content-Type.
+  if (opts.multipart) {
+    if (opts.body !== undefined) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+        "request: pass either { body } or { multipart }, not both", true));
+    }
+    var built;
+    try { built = _buildMultipartBody(opts.multipart); }
+    catch (e) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG", e.message, true));
+    }
+    opts = Object.assign({}, opts, {
+      method: opts.method || "POST",
+      body:   built.body,
+      headers: Object.assign({}, opts.headers || {}, {
+        "Content-Type":   "multipart/form-data; boundary=" + built.boundary,
+        "Content-Length": String(built.body.length),
+      }),
+      multipart: undefined,
+    });
+  }
+
+  // maxRedirects:
+  //   undefined → today's behavior (no follow). Caller inspects 3xx.
+  //   null      → today's behavior (explicit). Same as undefined.
+  //   0         → no follow, but 3xx returned to caller (alias of null).
+  //   N         → follow up to N hops; 3xx with no Location returned as-is.
+  var maxRedirects = (opts.maxRedirects === undefined || opts.maxRedirects === null)
+    ? null : opts.maxRedirects;
+  if (maxRedirects !== null) {
+    if (typeof maxRedirects !== "number" || !isFinite(maxRedirects) || maxRedirects < 0 ||
+        Math.floor(maxRedirects) !== maxRedirects) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+        "maxRedirects must be a non-negative integer or null", true));
+    }
+  }
+  var afterChain = (Array.isArray(opts.after) && opts.after.length > 0) ? opts.after : null;
+  function _runAfter(finalOpts, res) {
+    if (!afterChain) return res;
+    for (var ai = 0; ai < afterChain.length; ai++) {
+      try { afterChain[ai](finalOpts, res); }
+      catch (_e) { /* after hooks are best-effort — never break the response */ }
+    }
+    return res;
+  }
+
+  if (maxRedirects === null || maxRedirects === 0) {
+    return _requestSingle(opts).then(function (res) { return _runAfter(opts, res); });
+  }
+
+  return _requestWithRedirects(opts, maxRedirects).then(function (boxed) {
+    return _runAfter(boxed.finalOpts, boxed.res);
+  });
+}
+
+function _requestWithRedirects(opts, hopsLeft) {
+  var originalUrl = opts.url;
+  var originalOrigin = null;
+  try {
+    var u0 = new URL(opts.url);
+    originalOrigin = u0.protocol + "//" + u0.host;
+  } catch (_e) { /* request() will reject on next hop's parse */ }
+
+  var current = Object.assign({}, opts, { _resolveOnRedirect: true });
+  function _follow() {
+    return _requestSingle(current).then(function (res) {
+      if (!REDIRECT_STATUSES.has(res.statusCode) || hopsLeft <= 0) {
+        return { finalOpts: current, res: res };
+      }
+      var loc = res.headers && (res.headers.location || res.headers.Location);
+      if (!loc) return { finalOpts: current, res: res };  // 3xx with no Location — operator handles
+      hopsLeft -= 1;
+
+      // Resolve relative Location against the just-fetched URL (the URL
+      // of the request that produced the redirect, which may itself be a
+      // post-redirect URL).
+      var nextUrl;
+      try { nextUrl = new URL(loc, current.url).toString(); }
+      catch (_e) {
+        return Promise.reject(_makeError(opts.errorClass, "BAD_REDIRECT",
+          "Location header invalid URL: " + loc, true));
+      }
+
+      // Cross-origin auth-header strip.
+      var nextHeaders = current.headers || {};
+      var nextOrigin;
+      try {
+        var nu = new URL(nextUrl);
+        nextOrigin = nu.protocol + "//" + nu.host;
+      } catch (_e) { /* request() will reject when it tries to parse */ }
+      if (originalOrigin && nextOrigin && nextOrigin !== originalOrigin) {
+        nextHeaders = _stripCrossOriginAuth(nextHeaders);
+      }
+
+      // 303 → always GET; body dropped. 301/302 → historical clients
+      // also coerce non-GET bodies (we follow that convention). 307/308
+      // → preserve method + body.
+      var nextMethod = current.method || "GET";
+      var nextBody = current.body;
+      if (res.statusCode === 303 ||
+          ((res.statusCode === 301 || res.statusCode === 302) &&
+           nextMethod !== "GET" && nextMethod !== "HEAD")) {
+        nextMethod = "GET";
+        nextBody = undefined;
+      }
+
+      current = Object.assign({}, current, {
+        url:                 nextUrl,
+        method:              nextMethod,
+        body:                nextBody,
+        headers:             nextHeaders,
+        _resolveOnRedirect:  true,
+      });
+      return _follow();
+    });
+  }
+  void originalUrl;
+  return _follow();
+}
+
+function _requestSingle(opts) {
   // Validate scheme + shape via url-safe. Default is HTTPS-only — the
   // framework refuses to silently drop bytes on the wire as cleartext.
   // Callers with cleartext endpoints (h2c, internal services, test
@@ -374,9 +620,26 @@ function _requestH1(transport, u, opts) {
     function _resolve(value) { if (!settled) { settled = true; resolve(value); } }
     function _reject(err)    { if (!settled) { settled = true; reject(err); } }
 
+    var onUploadProgress   = typeof opts.onUploadProgress === "function" ? opts.onUploadProgress : null;
+    var onDownloadProgress = typeof opts.onDownloadProgress === "function" ? opts.onDownloadProgress : null;
+
     var req = transport.lib.request(reqOpts, function (res) {
       if (observer) observer("response:headers", { statusCode: res.statusCode, headers: res.headers });
 
+      // Download total: Content-Length when present, null otherwise.
+      var dlTotal = null;
+      if (res.headers && typeof res.headers["content-length"] === "string") {
+        var cl = parseInt(res.headers["content-length"], 10);
+        if (!isNaN(cl) && cl >= 0) dlTotal = cl;
+      }
+      var dlLoaded = 0;
+      function _emitDownload(chunkBytes) {
+        if (!onDownloadProgress) return;
+        dlLoaded += chunkBytes;
+        try { onDownloadProgress({ loaded: dlLoaded, total: dlTotal }); }
+        catch (_e) { /* progress hooks are best-effort */ }
+      }
+
       if (responseMode === "stream") {
         if (res.statusCode >= 400) {
           res.resume();
@@ -384,6 +647,17 @@ function _requestH1(transport, u, opts) {
             "HTTP " + res.statusCode + " " + (res.statusMessage || ""),
             _isPermanentStatus(res.statusCode), res.statusCode));
         }
+        if (onDownloadProgress) {
+          // Wrap the stream so chunks emit progress to the operator.
+          // The framework's contract is to hand back the response stream
+          // unmodified; fix-up via a passthrough keeps that contract while
+          // observing the chunk sizes.
+          var passthrough = new (require("node:stream").PassThrough)();
+          res.on("data", function (chunk) { _emitDownload(chunk.length); passthrough.write(chunk); });
+          res.on("end",  function () { passthrough.end(); });
+          res.on("error", function (e) { passthrough.destroy(e); });
+          return _resolve({ statusCode: res.statusCode, headers: res.headers, body: passthrough });
+        }
         return _resolve({ statusCode: res.statusCode, headers: res.headers, body: res });
       }
 
@@ -398,7 +672,9 @@ function _requestH1(transport, u, opts) {
           req.destroy();
           _reject(_makeError(opts.errorClass, "RESPONSE_TOO_LARGE",
             "response body exceeds " + maxResponseBytes + " bytes", true));
+          return;
         }
+        _emitDownload(chunk.length);
       });
       res.on("end", function () {
         if (capExceeded) return;
@@ -410,6 +686,12 @@ function _requestH1(transport, u, opts) {
         });
         if (res.statusCode >= 200 && res.statusCode < 300) {
           _resolve({ statusCode: res.statusCode, headers: res.headers, body: buf });
+        } else if (opts._resolveOnRedirect && REDIRECT_STATUSES.has(res.statusCode)) {
+          // Redirect-following layer needs the response object intact so
+          // it can inspect Location and re-issue. The caller-facing
+          // request() never sets _resolveOnRedirect — operator code that
+          // didn't ask for redirect-following keeps seeing 3xx as errors.
+          _resolve({ statusCode: res.statusCode, headers: res.headers, body: buf });
         } else {
           var msg = "HTTP " + res.statusCode + ": " + buf.toString("utf8").slice(0, 500);
           _reject(_makeError(opts.errorClass, "HTTP_ERROR", msg,
@@ -445,17 +727,47 @@ function _requestH1(transport, u, opts) {
       signal.addEventListener("abort", onAbort, { once: true });
     }
 
+    // Upload progress: emit { loaded, total } as body bytes go to the
+    // wire. Buffer / string bodies are sliced into chunks ourselves so
+    // operators see incremental progress; Readable bodies emit on each
+    // 'data' event from the source stream.
+    var ulTotal = null;
+    if (Buffer.isBuffer(opts.body)) ulTotal = opts.body.length;
+    else if (typeof opts.body === "string") ulTotal = Buffer.byteLength(opts.body, "utf8");
+    var ulLoaded = 0;
+    function _emitUpload(chunkBytes) {
+      if (!onUploadProgress) return;
+      ulLoaded += chunkBytes;
+      try { onUploadProgress({ loaded: ulLoaded, total: ulTotal }); }
+      catch (_e) { /* progress hooks are best-effort */ }
+    }
+
     if (opts.body && typeof opts.body.pipe === "function") {
+      if (onUploadProgress) {
+        opts.body.on("data", function (c) { _emitUpload(c.length); });
+      }
       opts.body.on("error", function (e) {
         try { req.destroy(); } catch (_) {}
         _reject(_makeError(opts.errorClass, "REQ_BODY_ERROR",
           "request body stream error: " + e.message, false));
       });
       opts.body.pipe(req);
-    } else if (Buffer.isBuffer(opts.body)) {
-      req.end(opts.body);
-    } else if (typeof opts.body === "string") {
-      req.end(Buffer.from(opts.body, "utf8"));
+    } else if (Buffer.isBuffer(opts.body) || typeof opts.body === "string") {
+      var bodyBuf = Buffer.isBuffer(opts.body) ? opts.body : Buffer.from(opts.body, "utf8");
+      if (onUploadProgress) {
+        // Chunked write so progress reports land before req.end().
+        var CHUNK = 64 * 1024;
+        var off = 0;
+        while (off < bodyBuf.length) {
+          var slice = bodyBuf.slice(off, Math.min(off + CHUNK, bodyBuf.length));
+          req.write(slice);
+          _emitUpload(slice.length);
+          off += slice.length;
+        }
+        req.end();
+      } else {
+        req.end(bodyBuf);
+      }
     } else {
       req.end();
     }

package/package.json

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