@blamejs/core 0.5.15 → 0.5.16

package/CHANGELOG.md

@@ -8,6 +8,7 @@ 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

package/index.js

@@ -145,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");
@@ -251,6 +252,7 @@ module.exports = {
   metrics:          metrics,
   tracing:          tracing,
   observability:    observability,
+  otelExport:       otelExport,
   protocolDispatcher: protocolDispatcher,
   requestHelpers:   requestHelpers,
   appShutdown:      appShutdown,

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