@blamejs/core 0.5.14 → 0.5.16

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.15** (2026-04-30) — b.archive: ZIP creation
+- **0.5.14** (2026-04-30) — b.time: timezone-aware datetime arithmetic + formatting
 - **0.5.13** (2026-04-30) — b.testing.request: supertest-style chainable HTTP test helper
 - **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

package/index.js

@@ -105,6 +105,7 @@ var staticServe = require("./lib/static");
 var forms = require("./lib/forms");
 var app = require("./lib/app");
 var jobs = require("./lib/jobs");
+var archive = require("./lib/archive");
 var breakGlass = require("./lib/break-glass");
 var config = require("./lib/config");
 var csv = require("./lib/csv");
@@ -144,6 +145,7 @@ var pagination = require("./lib/pagination");
 var metrics = require("./lib/metrics");
 var tracing = require("./lib/tracing");
 var observability = require("./lib/observability");
+var otelExport = require("./lib/otel-export");
 var protocolDispatcher = require("./lib/protocol-dispatcher");
 var requestHelpers = require("./lib/request-helpers");
 var appShutdown = require("./lib/app-shutdown");
@@ -211,6 +213,7 @@ module.exports = {
   forms:            forms,
   createApp:        app.createApp,
   jobs:             jobs,
+  archive:          archive,
   breakGlass:       breakGlass,
   config:           config,
   csv:              csv,
@@ -249,6 +252,7 @@ module.exports = {
   metrics:          metrics,
   tracing:          tracing,
   observability:    observability,
+  otelExport:       otelExport,
   protocolDispatcher: protocolDispatcher,
   requestHelpers:   requestHelpers,
   appShutdown:      appShutdown,

package/lib/archive.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * archive — ZIP creation. Operator-data-export shape ("download my
+ * data as a zip"), log archives, plain-zip exports for users.
+ *
+ *   var archive = b.archive.zip();
+ *   archive.addFile("readme.txt",     "Hello\n");
+ *   archive.addFile("data/users.csv", csvBytes, { method: "deflate" });
+ *   archive.addFile("avatars/me.png", pngBuf,   { method: "store" });   // already-compressed
+ *   var zipBytes = archive.toBuffer();
+ *
+ *   // OR write directly to disk:
+ *   archive.writeTo("/tmp/export.zip");
+ *
+ * Format support:
+ *   - Stored (no compression — for already-compressed inputs like
+ *     PNG / JPEG / mp4)
+ *   - Deflate via node:zlib's deflateRawSync (default for everything else)
+ *   - File names with / are honored — directory entries are implicit;
+ *     extractors create the directory structure on demand
+ *   - UTF-8 file names (sets the EFS bit per APPNOTE 6.3.4)
+ *   - Modification time defaults to "now"; operators override per file
+ *
+ * v1 scope cuts (deferred):
+ *   - ZIP64 (>4 GiB archives, >65535 files) — operators with that
+ *     scale bring their own
+ *   - Encryption — `b.crypto.encryptPacked` produces a sealed bundle
+ *     for the operator's encryption-at-rest needs; ZIP-native
+ *     password encryption is broken-by-design
+ *   - Streaming write (toStream) — toBuffer() is enough for the
+ *     "download my data" shape; operators streaming gigabytes
+ *     have a different toolset
+ *   - Reading / extraction — write-only for now
+ */
+var zlib = require("node:zlib");
+var fs   = require("node:fs");
+var nodeCrypto = require("node:crypto");
+var { defineClass } = require("./framework-error");
+
+var ArchiveError = defineClass("ArchiveError", { alwaysPermanent: true });
+
+// ZIP signatures
+var SIG_LFH = 0x04034b50;   // local file header
+var SIG_CFH = 0x02014b50;   // central directory file header
+var SIG_EOCD = 0x06054b50;  // end of central directory
+
+// Compression methods
+var METHOD_STORE   = 0;
+var METHOD_DEFLATE = 8;
+
+// CRC-32 — IEEE 802.3 polynomial. node:crypto has no native CRC32, so
+// we vendor the standard table-driven implementation.
+var CRC32_TABLE = (function () {
+  var t = new Uint32Array(256);
+  for (var i = 0; i < 256; i++) {
+    var c = i;
+    for (var j = 0; j < 8; j++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    t[i] = c >>> 0;
+  }
+  return t;
+})();
+
+function _crc32(buf) {
+  var crc = 0xffffffff;
+  for (var i = 0; i < buf.length; i++) {
+    crc = CRC32_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+// MS-DOS date/time encoding — APPNOTE 4.4.6
+function _msdosDateTime(date) {
+  var d = date instanceof Date ? date : new Date(date);
+  if (isNaN(d.getTime())) d = new Date();
+  var dosTime = ((d.getHours() & 0x1f) << 11) |
+                ((d.getMinutes() & 0x3f) << 5) |
+                ((Math.floor(d.getSeconds() / 2)) & 0x1f);
+  var dosDate = (((d.getFullYear() - 1980) & 0x7f) << 9) |
+                (((d.getMonth() + 1) & 0xf) << 5) |
+                (d.getDate() & 0x1f);
+  return { time: dosTime, date: dosDate };
+}
+
+function zip() {
+  var entries = [];
+
+  function addFile(name, content, opts) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new ArchiveError("archive/bad-name", "addFile: name must be a non-empty string");
+    }
+    if (name.indexOf("\0") !== -1) {
+      throw new ArchiveError("archive/bad-name", "addFile: name contains null byte");
+    }
+    // No path traversal — relative paths only, no leading slash, no ".." segments.
+    var normalized = name.replace(/\\/g, "/").replace(/^\/+/, "");
+    var segs = normalized.split("/");
+    for (var si = 0; si < segs.length; si++) {
+      if (segs[si] === "..") {
+        throw new ArchiveError("archive/bad-name", "addFile: name contains '..' segment");
+      }
+    }
+    var bodyBuf;
+    if (Buffer.isBuffer(content)) bodyBuf = content;
+    else if (typeof content === "string") bodyBuf = Buffer.from(content, "utf8");
+    else throw new ArchiveError("archive/bad-content",
+      "addFile: content must be a Buffer or string, got " + typeof content);
+
+    opts = opts || {};
+    var method = opts.method === "store" ? METHOD_STORE : METHOD_DEFLATE;
+    var mtime = opts.mtime instanceof Date ? opts.mtime : new Date();
+
+    var crc = _crc32(bodyBuf);
+    var stored = bodyBuf;
+    if (method === METHOD_DEFLATE) {
+      stored = zlib.deflateRawSync(bodyBuf);
+      // If deflate didn't shrink it (small/already-compressed inputs),
+      // fall back to STORE to save the operator a few bytes.
+      if (stored.length >= bodyBuf.length) {
+        stored = bodyBuf;
+        method = METHOD_STORE;
+      }
+    }
+
+    entries.push({
+      name:           normalized,
+      method:         method,
+      mtime:          mtime,
+      crc:            crc,
+      stored:         stored,
+      uncompressedSize: bodyBuf.length,
+    });
+  }
+
+  function _buildLocalFileHeader(entry) {
+    var nameBuf = Buffer.from(entry.name, "utf8");
+    var dt = _msdosDateTime(entry.mtime);
+    var hdr = Buffer.alloc(30);
+    hdr.writeUInt32LE(SIG_LFH, 0);
+    hdr.writeUInt16LE(20, 4);         // version needed
+    hdr.writeUInt16LE(0x0800, 6);     // flags: bit 11 = UTF-8 name
+    hdr.writeUInt16LE(entry.method, 8);
+    hdr.writeUInt16LE(dt.time, 10);
+    hdr.writeUInt16LE(dt.date, 12);
+    hdr.writeUInt32LE(entry.crc, 14);
+    hdr.writeUInt32LE(entry.stored.length, 18);
+    hdr.writeUInt32LE(entry.uncompressedSize, 22);
+    hdr.writeUInt16LE(nameBuf.length, 26);
+    hdr.writeUInt16LE(0, 28);         // extra field length
+    return Buffer.concat([hdr, nameBuf]);
+  }
+
+  function _buildCentralDirectoryEntry(entry, lfhOffset) {
+    var nameBuf = Buffer.from(entry.name, "utf8");
+    var dt = _msdosDateTime(entry.mtime);
+    var hdr = Buffer.alloc(46);
+    hdr.writeUInt32LE(SIG_CFH, 0);
+    hdr.writeUInt16LE(0x033f, 4);     // version made by (UNIX | 6.3)
+    hdr.writeUInt16LE(20, 6);         // version needed
+    hdr.writeUInt16LE(0x0800, 8);     // flags: bit 11 = UTF-8
+    hdr.writeUInt16LE(entry.method, 10);
+    hdr.writeUInt16LE(dt.time, 12);
+    hdr.writeUInt16LE(dt.date, 14);
+    hdr.writeUInt32LE(entry.crc, 16);
+    hdr.writeUInt32LE(entry.stored.length, 20);
+    hdr.writeUInt32LE(entry.uncompressedSize, 24);
+    hdr.writeUInt16LE(nameBuf.length, 28);
+    hdr.writeUInt16LE(0, 30);         // extra field length
+    hdr.writeUInt16LE(0, 32);         // file comment length
+    hdr.writeUInt16LE(0, 34);         // disk number start
+    hdr.writeUInt16LE(0, 36);         // internal file attributes
+    hdr.writeUInt32LE(0, 38);         // external file attributes
+    hdr.writeUInt32LE(lfhOffset, 42);
+    return Buffer.concat([hdr, nameBuf]);
+  }
+
+  function toBuffer() {
+    if (entries.length > 65535) {
+      throw new ArchiveError("archive/too-many-entries",
+        "ZIP archive cannot contain more than 65535 entries (ZIP64 unsupported in v1)");
+    }
+    var pieces = [];
+    var offsets = [];
+    var totalLocalBytes = 0;
+    for (var i = 0; i < entries.length; i++) {
+      offsets.push(totalLocalBytes);
+      var lfh = _buildLocalFileHeader(entries[i]);
+      pieces.push(lfh);
+      pieces.push(entries[i].stored);
+      totalLocalBytes += lfh.length + entries[i].stored.length;
+    }
+    var cdStart = totalLocalBytes;
+    var cdSize = 0;
+    for (var j = 0; j < entries.length; j++) {
+      var cdh = _buildCentralDirectoryEntry(entries[j], offsets[j]);
+      pieces.push(cdh);
+      cdSize += cdh.length;
+    }
+    // End of Central Directory
+    var eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(SIG_EOCD, 0);
+    eocd.writeUInt16LE(0, 4);                    // disk number
+    eocd.writeUInt16LE(0, 6);                    // disk where CD starts
+    eocd.writeUInt16LE(entries.length, 8);       // entries on this disk
+    eocd.writeUInt16LE(entries.length, 10);      // total entries
+    eocd.writeUInt32LE(cdSize, 12);              // size of central directory
+    eocd.writeUInt32LE(cdStart, 16);             // offset of central directory
+    eocd.writeUInt16LE(0, 20);                   // comment length
+    pieces.push(eocd);
+    return Buffer.concat(pieces);
+  }
+
+  function writeTo(filepath) {
+    var buf = toBuffer();
+    fs.writeFileSync(filepath, buf);
+    return buf.length;
+  }
+
+  function digest() {
+    // SHA-256 of the produced archive bytes — useful for operator-side
+    // integrity logging on exported bundles. Not vendor-locked to any
+    // particular hash; SHA-256 is universally recognized for content
+    // addressing.
+    return nodeCrypto.createHash("sha256").update(toBuffer()).digest("hex");
+  }
+
+  return {
+    addFile:    addFile,
+    toBuffer:   toBuffer,
+    writeTo:    writeTo,
+    digest:     digest,
+    get entryCount() { return entries.length; },
+  };
+}
+
+module.exports = {
+  zip:           zip,
+  ArchiveError:  ArchiveError,
+  // Test-only export — operators don't call this; it's here for unit-testing
+  // the CRC implementation against known vectors.
+  _crc32ForTest: _crc32,
+};

package/lib/otel-export.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * otel-export — OTLP/HTTP-JSON exporter for `b.observability` events.
+ *
+ * Bridges the framework's `observability.event(name, value, attrs)`
+ * surface to any OTel-compatible backend (Honeycomb, Datadog, Jaeger
+ * Collector, AWS Distro, Grafana, NewRelic — anything that speaks
+ * OTLP/HTTP). Spec: opentelemetry.io/docs/specs/otlp.
+ *
+ *   var otel = b.otelExport.create({
+ *     endpoint:     "https://otel.honeycomb.io/v1/metrics",
+ *     headers:      { "X-Honeycomb-Team": env("HONEYCOMB_API_KEY") },
+ *     serviceName:  "wiki",
+ *     intervalMs:   b.constants.TIME.seconds(15),  // auto-flush cadence
+ *     httpClient:   b.httpClient,                  // for testing
+ *   });
+ *
+ *   // Counter — accumulates per (name, attrs) tuple, flushed in batches.
+ *   otel.recordCounter("http.requests", 1, { method: "GET", status: 200 });
+ *
+ *   // Histogram — operator-bucketed observation. Less common; operators
+ *   // wanting full histogram support build on top.
+ *   otel.recordObservation("http.duration_ms", 142, { route: "/api/x" });
+ *
+ *   await otel.flush();   // manual flush
+ *   otel.close();         // cancels interval, final flush
+ *
+ * Wiring with `b.observability`:
+ *
+ *   // Option A: replace the metrics tap entirely
+ *   b.observability._setTap(otel.tapHandler);
+ *
+ *   // Option B: alongside b.metrics — operators write their own
+ *   // multi-tap fan-out (or pick one or the other for v1).
+ *
+ * Endpoint must accept OTLP/HTTP with Content-Type: application/json
+ * (the JSON variant of the OTLP protobuf — every modern collector
+ * supports it). The framework refuses to ship the binary protobuf
+ * encoding because it requires either a vendored proto runtime or
+ * hand-rolled wire format with no compelling benefit at this scope.
+ */
+var C = require("./constants");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var OtelExportError = defineClass("OtelExportError", { alwaysPermanent: false });
+
+var DEFAULT_INTERVAL_MS = C.TIME.seconds(15);
+
+// OTLP aggregation temporality:
+//   1 = DELTA      — counters report deltas since last export
+//   2 = CUMULATIVE — counters report running totals
+// DELTA is what most exporters do for short-lived processes; the
+// receiving backend handles the running sum.
+var TEMPORALITY_DELTA = 1;
+
+// ---- attribute encoding ----
+// OTLP attributes are KeyValue with typed `value` fields:
+//   { key, value: { stringValue | intValue | doubleValue | boolValue } }
+function _attrsToOtlp(attrs) {
+  if (!attrs || typeof attrs !== "object") return [];
+  var out = [];
+  for (var k in attrs) {
+    if (!Object.prototype.hasOwnProperty.call(attrs, k)) continue;
+    var v = attrs[k];
+    var kv;
+    if (typeof v === "string")  kv = { stringValue: v };
+    else if (typeof v === "number") {
+      kv = Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+    }
+    else if (typeof v === "boolean") kv = { boolValue: v };
+    else if (v == null) continue;
+    else kv = { stringValue: String(v) };
+    out.push({ key: k, value: kv });
+  }
+  return out;
+}
+
+// Stable key per (name, attrs) so tap calls aggregate.
+function _bucketKey(name, attrs) {
+  if (!attrs) return name + "|";
+  var ks = Object.keys(attrs).sort();
+  var parts = [name];
+  for (var i = 0; i < ks.length; i++) parts.push(ks[i] + "=" + String(attrs[ks[i]]));
+  return parts.join("|");
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "endpoint", "headers", "serviceName", "intervalMs",
+    "httpClient", "resourceAttributes", "scope",
+  ], "otelExport.create");
+  if (typeof opts.endpoint !== "string" || opts.endpoint.length === 0) {
+    throw new OtelExportError("otel-export/bad-endpoint",
+      "create: endpoint must be a non-empty URL");
+  }
+  if (typeof opts.serviceName !== "string" || opts.serviceName.length === 0) {
+    throw new OtelExportError("otel-export/bad-service-name",
+      "create: serviceName must be a non-empty string");
+  }
+  var endpoint = opts.endpoint;
+  var serviceName = opts.serviceName;
+  var headers = opts.headers || {};
+  var intervalMs = opts.intervalMs != null ? opts.intervalMs : DEFAULT_INTERVAL_MS;
+  if (typeof intervalMs !== "number" || !isFinite(intervalMs) || intervalMs < 0) {
+    throw new OtelExportError("otel-export/bad-interval",
+      "create: intervalMs must be a non-negative finite number");
+  }
+  var httpClient = opts.httpClient || require("./http-client");
+  var scopeName = (opts.scope && opts.scope.name) || "blamejs";
+  var scopeVersion = (opts.scope && opts.scope.version) || "0.5.x";
+  var resourceAttrs = Object.assign({ "service.name": serviceName },
+    opts.resourceAttributes || {});
+
+  // Buckets: counters and observations keyed by (name, sorted-attrs).
+  var counters = new Map();          // bucketKey → { name, attrs, value, startUnixNano }
+  var observations = new Map();      // bucketKey → { name, attrs, sum, count, min, max, startUnixNano }
+  var startUnixNano = String(Date.now() * 1e6);
+  var timer = null;
+  var closed = false;
+
+  function recordCounter(name, value, attrs) {
+    if (closed) return;
+    if (typeof name !== "string" || name.length === 0) return;
+    var v = typeof value === "number" && isFinite(value) ? value : 1;
+    var key = _bucketKey(name, attrs);
+    var b = counters.get(key);
+    if (!b) {
+      b = { name: name, attrs: attrs || {}, value: 0, startUnixNano: startUnixNano };
+      counters.set(key, b);
+    }
+    b.value += v;
+  }
+
+  function recordObservation(name, value, attrs) {
+    if (closed) return;
+    if (typeof name !== "string" || name.length === 0) return;
+    if (typeof value !== "number" || !isFinite(value)) return;
+    var key = _bucketKey(name, attrs);
+    var b = observations.get(key);
+    if (!b) {
+      b = { name: name, attrs: attrs || {}, sum: 0, count: 0, min: value, max: value, startUnixNano: startUnixNano };
+      observations.set(key, b);
+    }
+    b.sum   += value;
+    b.count += 1;
+    if (value < b.min) b.min = value;
+    if (value > b.max) b.max = value;
+  }
+
+  // Operators wire this as the observability tap. event(name, value, labels)
+  // → recordCounter for value=1 fire-and-forget shapes.
+  function tapHandler(name, value, labels) {
+    recordCounter(name, value, labels);
+  }
+
+  function _drainAndEncode() {
+    var nowUnixNano = String(Date.now() * 1e6);
+    var metrics = [];
+    var c, o;
+
+    counters.forEach(function (entry) {
+      metrics.push({
+        name: entry.name,
+        sum: {
+          dataPoints: [{
+            attributes:        _attrsToOtlp(entry.attrs),
+            startTimeUnixNano: entry.startUnixNano,
+            timeUnixNano:      nowUnixNano,
+            asDouble:          entry.value,
+          }],
+          aggregationTemporality: TEMPORALITY_DELTA,
+          isMonotonic:            true,
+        },
+      });
+    });
+    void c;
+    observations.forEach(function (entry) {
+      metrics.push({
+        name: entry.name,
+        summary: {
+          dataPoints: [{
+            attributes:        _attrsToOtlp(entry.attrs),
+            startTimeUnixNano: entry.startUnixNano,
+            timeUnixNano:      nowUnixNano,
+            count:             String(entry.count),
+            sum:               entry.sum,
+            quantileValues: [
+              { quantile: 0,   value: entry.min },
+              { quantile: 1,   value: entry.max },
+            ],
+          }],
+        },
+      });
+    });
+    void o;
+
+    // Reset buckets (DELTA temporality — each export is the delta).
+    counters.clear();
+    observations.clear();
+    startUnixNano = nowUnixNano;
+    if (metrics.length === 0) return null;
+    return {
+      resourceMetrics: [{
+        resource: { attributes: _attrsToOtlp(resourceAttrs) },
+        scopeMetrics: [{
+          scope:   { name: scopeName, version: scopeVersion },
+          metrics: metrics,
+        }],
+      }],
+    };
+  }
+
+  async function flush() {
+    var payload = _drainAndEncode();
+    if (!payload) return { sent: false, reason: "no-data" };
+    var body = JSON.stringify(payload);
+    try {
+      var res = await httpClient.request({
+        method:  "POST",
+        url:     endpoint,
+        headers: Object.assign({ "Content-Type": "application/json" }, headers),
+        body:    body,
+      });
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        throw new OtelExportError("otel-export/upstream-rejected",
+          "OTLP endpoint returned " + res.statusCode);
+      }
+      return { sent: true, statusCode: res.statusCode, bodyLength: body.length };
+    } catch (e) {
+      if (e && e.isOtelExportError) throw e;
+      throw new OtelExportError("otel-export/send-failed",
+        "OTLP send failed: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  function _scheduleFlush() {
+    if (intervalMs === 0 || closed) return;
+    timer = setTimeout(function () {
+      flush().catch(function (_e) { /* never let a flush error crash the timer */ });
+      _scheduleFlush();
+    }, intervalMs);
+    if (typeof timer.unref === "function") timer.unref();
+  }
+  _scheduleFlush();
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    if (timer) { clearTimeout(timer); timer = null; }
+    return flush().catch(function (_e) { /* close path swallows final-flush errors */ });
+  }
+
+  return {
+    recordCounter:     recordCounter,
+    recordObservation: recordObservation,
+    tapHandler:        tapHandler,
+    flush:             flush,
+    close:             close,
+    get bufferedCounters()     { return counters.size; },
+    get bufferedObservations() { return observations.size; },
+  };
+}
+
+module.exports = {
+  create:           create,
+  OtelExportError:  OtelExportError,
+  // Test-only encoders for unit-testing the OTLP shape without an HTTP client.
+  _attrsToOtlpForTest: _attrsToOtlp,
+  _bucketKeyForTest:   _bucketKey,
+};

package/package.json

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