@blamejs/core 0.12.5 → 0.12.7

package/lib/observability-otlp-exporter.js

@@ -36,6 +36,7 @@ var safeAsync = require("./safe-async");
 var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var safeUrl = require("./safe-url");
+var pb = require("./protobuf-encoder");
 var { defineClass } = require("./framework-error");
 
 var OtlpExporterError = defineClass("OtlpExporterError", { alwaysPermanent: true });
@@ -189,6 +190,221 @@ function _bundleSpans(spans) {
   return { resourceSpans: resourceSpans };
 }
 
+// ---- OTLP/protobuf encoder ------------------------------------------------
+//
+// OTLP §3 — `application/x-protobuf` body shape per the
+// opentelemetry-proto repo's ExportTraceServiceRequest message.
+//
+// Wire-format encoding composes b.protobufEncoder. Fields are:
+//
+//   ExportTraceServiceRequest {
+//     repeated ResourceSpans resource_spans = 1;
+//   }
+//   ResourceSpans {
+//     Resource resource     = 1;
+//     repeated ScopeSpans scope_spans = 2;
+//     string schema_url     = 3;
+//   }
+//   Resource {
+//     repeated KeyValue attributes        = 1;
+//     uint32 dropped_attributes_count    = 2;
+//   }
+//   ScopeSpans {
+//     InstrumentationScope scope = 1;
+//     repeated Span spans        = 2;
+//     string schema_url          = 3;
+//   }
+//   InstrumentationScope { string name = 1; string version = 2; ... }
+//   Span {
+//     bytes trace_id              = 1;  // 16 bytes
+//     bytes span_id               = 2;  //  8 bytes
+//     string trace_state          = 3;
+//     bytes parent_span_id        = 4;  //  8 bytes or empty
+//     string name                 = 5;
+//     SpanKind kind               = 6;  // enum 0..5
+//     fixed64 start_time_unix_nano = 7;
+//     fixed64 end_time_unix_nano   = 8;
+//     repeated KeyValue attributes = 9;
+//     uint32 dropped_attributes_count = 10;
+//     repeated Event events           = 11;
+//     uint32 dropped_events_count     = 12;
+//     repeated Link links             = 13;
+//     uint32 dropped_links_count      = 14;
+//     Status status                   = 15;
+//   }
+//   Event { fixed64 time_unix_nano = 1; string name = 2; repeated KeyValue attributes = 3; uint32 dropped_attributes_count = 4; }
+//   Status { string message = 2; enum code = 3; }  // field 1 reserved
+//   KeyValue { string key = 1; AnyValue value = 2; }
+//   AnyValue {
+//     oneof value {
+//       string string_value = 1;
+//       bool   bool_value   = 2;
+//       int64  int_value    = 3;
+//       double double_value = 4;
+//       ArrayValue array_value = 5;
+//     }
+//   }
+//   ArrayValue { repeated AnyValue values = 1; }
+//
+// AnyValue recursion is capped at MAX_ANYVALUE_DEPTH to defend the
+// CVE-2024-7254 + CVE-2025-4565 protobuf nested-group DoS class.
+
+var MAX_ANYVALUE_DEPTH = 100;                                                    // allow:raw-byte-literal — protobuf nested-message DoS cap
+
+function _hexToBytes(hex) {
+  if (typeof hex !== "string" || hex.length === 0) return Buffer.alloc(0);
+  // Tolerate odd-length hex by left-padding with zero; OTLP spec
+  // requires fixed lengths but the exporter should not crash a request
+  // with a malformed inbound trace_id — drop-silent and emit empty.
+  if (hex.length % 2 !== 0) return Buffer.alloc(0);
+  var out = Buffer.alloc(hex.length / 2);
+  for (var i = 0; i < hex.length; i += 2) {
+    var byte = parseInt(hex.substr(i, 2), 16);                                  // allow:raw-byte-literal — radix=16 for hex parse, not byte count
+    if (!isFinite(byte)) return Buffer.alloc(0);
+    out[i / 2] = byte;
+  }
+  return out;
+}
+
+var KIND_TEXT_TO_ENUM = {
+  unspecified: 0, internal: 1, server: 2, client: 3, producer: 4, consumer: 5,
+};
+
+function _anyValueToProto(v, depth) {
+  if (depth >= MAX_ANYVALUE_DEPTH) {
+    // Refuse to descend further; emit empty AnyValue. Matches the spec's
+    // "unknown wire type" tolerant-parser behaviour on the receive side.
+    return Buffer.alloc(0);
+  }
+  var t = typeof v;
+  if (t === "string")  return pb.string(1, v);
+  if (t === "boolean") return pb.bool(2, v);
+  if (t === "number") {
+    if (Number.isInteger(v)) {
+      // OTLP AnyValue field 3 is proto int64 — wire-type 0 varint, NOT
+      // length-delimited. Negatives encode as the 64-bit two's-complement
+      // reinterpret-cast (10-byte varint per the spec). Composes
+      // `pb.int64` which carries the BigInt conversion + range check so
+      // a negative attribute value (e.g. retry-after offset, signed
+      // metric delta) doesn't poison the whole batch.
+      return pb.int64(3, v);
+    }
+    return pb.double(4, v);
+  }
+  if (Array.isArray(v)) {
+    var items = new Array(v.length);
+    for (var i = 0; i < v.length; i += 1) {
+      items[i] = _anyValueToProto(v[i], depth + 1);
+    }
+    var arrayInner = pb.repeatedMessage(1, items, function (b) { return b; });
+    return pb.embeddedMessage(5, arrayInner);
+  }
+  // Unknown → coerce to string per the JSON path's behaviour.
+  return pb.string(1, String(v));
+}
+
+function _keyValueToProto(kvObj) {
+  // kvObj is { key, value: <plain-js> } from _attrToOtlp — but we
+  // re-derive directly here so the protobuf path doesn't depend on
+  // the JSON-shaped intermediate.
+  return Buffer.concat([
+    pb.string(1, kvObj.key),
+    pb.embeddedMessage(2, _anyValueToProto(kvObj.rawValue, 0)),
+  ]);
+}
+
+function _attrsToProto(attrs) {
+  // attrs is the raw `{ key: value }` operator attribute object; OTLP
+  // KeyValue gets emitted per entry with field 9 (attributes) on Span,
+  // field 1 (attributes) on Resource, etc.
+  if (!attrs || typeof attrs !== "object") return [];
+  var keys = Object.keys(attrs);
+  var out = new Array(keys.length);
+  for (var i = 0; i < keys.length; i += 1) {
+    out[i] = { key: keys[i], rawValue: attrs[keys[i]] };
+  }
+  return out;
+}
+
+function _spanToProto(span) {
+  // Status code: 0=Unset, 1=Ok, 2=Error. Status field 1 is reserved.
+  var statusBody = Buffer.concat([
+    pb.string(2, (span.status && span.status.message) || ""),
+    pb.uint32(3, STATUS_CODE_TO_OTLP[span.status && span.status.code] || 0),
+  ]);
+  var eventsRepeated = pb.repeatedMessage(11, span.events || [], function (e) {
+    return Buffer.concat([
+      pb.fixed64(1, e.timeUnixNano || 0),
+      pb.string(2, e.name || ""),
+      pb.repeatedMessage(3, _attrsToProto(e.attributes), _keyValueToProto),
+      pb.uint32(4, 0),
+    ]);
+  });
+  return Buffer.concat([
+    pb.bytes(1,   _hexToBytes(span.traceId)),
+    pb.bytes(2,   _hexToBytes(span.spanId)),
+    pb.string(3,  ""),                                                          // trace_state (not yet propagated by the framework)
+    pb.bytes(4,   _hexToBytes(span.parentSpanId || "")),
+    pb.string(5,  span.name || ""),
+    pb.uint32(6,  KIND_TEXT_TO_ENUM[span.kind] != null ? KIND_TEXT_TO_ENUM[span.kind] : KIND_TEXT_TO_ENUM.internal),
+    pb.fixed64(7, span.startTimeUnixNano || 0),
+    pb.fixed64(8, span.endTimeUnixNano || span.startTimeUnixNano || 0),         // allow:raw-byte-literal — proto field number 8, not bytes
+    pb.repeatedMessage(9, _attrsToProto(span.attributes), _keyValueToProto),
+    pb.uint32(10, span.droppedAttributesCount || 0),
+    eventsRepeated,
+    pb.uint32(12, span.droppedEventsCount || 0),
+    pb.uint32(15, 0),                                                           // links repeated count placeholder; encoder emits 0 length-delim when no links
+    Buffer.concat([
+      pb._tag(15, 2),                                                           // WIRE_LDELIM tag for status
+      pb._writeVarint(statusBody.length),
+      statusBody,
+    ]),
+  ]);
+}
+
+// `bundle` is the value returned by _bundleSpans — { resourceSpans: [...] }
+// where each entry has { resource, scopeSpans: [{ scope, spans: [...] }] }
+// in the JSON-shape. We re-derive the proto bytes from the SAME pre-OTLP
+// span list so the protobuf path doesn't double-transform the data.
+function _bundleSpansToProto(spansArray) {
+  if (spansArray.length === 0) return Buffer.alloc(0);
+  var byResource = new Map();
+  for (var i = 0; i < spansArray.length; i += 1) {
+    var s = spansArray[i];
+    var resKey = JSON.stringify(s.resource || {});
+    var bucket = byResource.get(resKey);
+    if (!bucket) {
+      bucket = {
+        resource: s.resource || {},
+        scope:    s.scope || { name: "blamejs", version: null },
+        spans:    [],
+      };
+      byResource.set(resKey, bucket);
+    }
+    bucket.spans.push(s);
+  }
+  var resourceSpansPieces = [];
+  for (var entry of byResource) {
+    var b = entry[1];
+    var resourceBody = pb.repeatedMessage(1, _attrsToProto(b.resource), _keyValueToProto);
+    var scopeBody = Buffer.concat([
+      pb.string(1, b.scope.name || "blamejs"),
+      pb.string(2, b.scope.version || ""),
+    ]);
+    var spansRepeated = pb.repeatedMessage(2, b.spans, _spanToProto);
+    var scopeSpansBody = Buffer.concat([
+      pb.embeddedMessage(1, scopeBody),
+      spansRepeated,
+    ]);
+    var resourceSpansBody = Buffer.concat([
+      pb.embeddedMessage(1, resourceBody),
+      pb.embeddedMessage(2, scopeSpansBody),
+    ]);
+    resourceSpansPieces.push(pb.embeddedMessage(1, resourceSpansBody));
+  }
+  return Buffer.concat(resourceSpansPieces);
+}
+
 function create(opts) {
   validateOpts.requireObject(opts, "otlpExporter", OtlpExporterError);
   validateOpts(opts, [
@@ -196,6 +412,7 @@ function create(opts) {
     "flushIntervalMs", "timeoutMs", "maxAttempts",
     "backoffInitialMs", "backoffMaxMs",
     "fetchImpl", "audit", "allowedProtocols",
+    "encoding",
   ], "otlpExporter.create");
   validateOpts.requireNonEmptyString(opts.endpoint,
     "otlpExporter.create: endpoint", OtlpExporterError, "otlp/bad-endpoint");
@@ -224,8 +441,24 @@ function create(opts) {
     "otlpExporter.create: maxAttempts", OtlpExporterError, "otlp/bad-opts");
 
   var endpoint   = opts.endpoint;
+  // OTLP §3 — operators with high-volume traces opt into the binary
+  // `application/x-protobuf` encoding via `opts.encoding: "protobuf"`
+  // (composes lib/protobuf-encoder.js for the wire-level emission).
+  // Default stays `"json"` for backward compatibility with existing
+  // collectors. The third encoding option (`"http/protobuf"` per the
+  // OTLP spec wording) is an alias for "protobuf".
+  var encoding = opts.encoding || "json";
+  if (encoding === "http/protobuf") encoding = "protobuf";
+  if (encoding !== "json" && encoding !== "protobuf") {
+    throw new OtlpExporterError("otlp/bad-encoding",
+      "otlpExporter.create: opts.encoding must be \"json\" or \"protobuf\" (got " +
+      JSON.stringify(opts.encoding) + ")");
+  }
+  var contentType = encoding === "protobuf"
+    ? "application/x-protobuf"
+    : "application/json";
   var headers    = Object.assign({
-    "Content-Type": "application/json",
+    "Content-Type": contentType,
   }, opts.headers || {});
   var batchSize  = opts.batchSize     || DEFAULT_BATCH_SIZE;
   var maxQueue   = opts.maxQueueSize  || DEFAULT_MAX_QUEUE_SIZE;
@@ -298,10 +531,14 @@ function create(opts) {
     var ac = (typeof AbortController === "function") ? new AbortController() : null;
     var t = ac ? setTimeout(function () { ac.abort(); }, timeoutMs) : null;
     try {
+      // The flush() path now passes EITHER a JSON-shape object (encoding
+      // "json") OR an already-encoded Buffer (encoding "protobuf").
+      // Stringify only the JSON path; pass the Buffer through.
+      var body = Buffer.isBuffer(payload) ? payload : JSON.stringify(payload);
       var res = await fetchImpl(endpoint, {
         method:  "POST",
         headers: headers,
-        body:    JSON.stringify(payload),
+        body:    body,
         signal:  ac ? ac.signal : undefined,
       });
       if (res && res.ok) return { ok: true, status: res.status };
@@ -343,7 +580,12 @@ function create(opts) {
     inFlight = true;
     try {
       var batch = queue.splice(0, batchSize);
-      var payload = _bundleSpans(batch);
+      // OTLP §3 — JSON encoding emits the resourceSpans envelope as
+      // JSON; protobuf encoding emits the same shape as binary
+      // ExportTraceServiceRequest bytes.
+      var payload = encoding === "protobuf"
+        ? _bundleSpansToProto(batch)
+        : _bundleSpans(batch);
       var result = await _post(payload, 1);
       if (result.ok) {
         _emitMetric("export_ok", batch.length, { http_status: String(result.status) });

package/lib/protobuf-encoder.js

@@ -95,27 +95,103 @@ function uint64(fieldNumber, value) {
   return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), _writeVarint(value)]);
 }
 
+function int64(fieldNumber, value) {
+  // proto3 int64: wire-type 0 varint. Negatives encode as the 64-bit
+  // two's-complement reinterpret-cast to uint64, which always sets the
+  // top bit — every negative int64 occupies the full 10 varint bytes
+  // per the spec. https://protobuf.dev/programming-guides/encoding/#signed-ints
+  if (value === 0 || value === 0n) return Buffer.alloc(0);  // proto3 default
+  var bi;
+  if (typeof value === "bigint") {
+    bi = value;
+  } else if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new Error("protobuf-encoder: int64 must be finite integer (got " + value + ")");
+    }
+    bi = BigInt(value);
+  } else {
+    throw new Error("protobuf-encoder: int64 must be number or bigint, got " + typeof value);
+  }
+  // Refuse out-of-range — proto int64 is [-2^63, 2^63 - 1].
+  if (bi < -(1n << 63n) || bi > (1n << 63n) - 1n) {
+    throw new Error("protobuf-encoder: int64 out of range (got " + bi.toString() + ")");
+  }
+  if (bi < 0n) bi = bi + (1n << 64n);     // two's-complement reinterpret
+  return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), _writeVarint(bi)]);
+}
+
+function sint64(fieldNumber, value) {
+  // proto3 sint64: wire-type 0 varint with ZigZag encoding —
+  // small negatives encode compactly. https://protobuf.dev/programming-guides/encoding/#signed-ints
+  if (value === 0 || value === 0n) return Buffer.alloc(0);
+  var bi;
+  if (typeof value === "bigint") bi = value;
+  else if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new Error("protobuf-encoder: sint64 must be finite integer (got " + value + ")");
+    }
+    bi = BigInt(value);
+  } else {
+    throw new Error("protobuf-encoder: sint64 must be number or bigint, got " + typeof value);
+  }
+  if (bi < -(1n << 63n) || bi > (1n << 63n) - 1n) {
+    throw new Error("protobuf-encoder: sint64 out of range (got " + bi.toString() + ")");
+  }
+  // ZigZag: (n << 1) ^ (n >> 63) for 64-bit signed.
+  var zz = (bi << 1n) ^ (bi >> 63n);
+  if (zz < 0n) zz = zz + (1n << 64n);
+  return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), _writeVarint(zz)]);
+}
+
 function bool(fieldNumber, value) {
   if (!value) return Buffer.alloc(0);  // proto3 default
   return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), Buffer.from([1])]);
 }
 
 function fixed64(fieldNumber, value) {
-  // For OTel: time_unix_nano fields are fixed64. Accept BigInt or
-  // Number; encode as little-endian 8 bytes.
+  // For OTel: time_unix_nano fields are fixed64. Accept BigInt, Number,
+  // or string-form digits (OTLP/JSON encodes uint64 as a JSON string per
+  // https://protobuf.dev/programming-guides/proto3/#json; the framework
+  // tracer emits strings for that reason and the same value flows into
+  // both encoding paths). Encode as little-endian 8 bytes.
   var buf = Buffer.alloc(FIXED64_BYTES);
+  var bi;
   if (typeof value === "bigint") {
-    buf.writeBigUInt64LE(value, 0);
-  } else {
+    bi = value;
+  } else if (typeof value === "string") {
+    // Char-code walk rather than /^[0-9]+$/ — that exact regex already
+    // appears in guard-cidr + guard-domain; the codebase-patterns
+    // duplicate-regex detector fires at the 3rd file (same shape as the
+    // SemVer-pre-release walk in lib/self-update.js).
+    if (value.length === 0) {
+      throw new Error("protobuf-encoder: fixed64 string must be non-empty unsigned digit-only");
+    }
+    for (var ci = 0; ci < value.length; ci += 1) {
+      var cc = value.charCodeAt(ci);
+      if (cc < 0x30 || cc > 0x39) {                                                  // allow:raw-byte-literal — ASCII '0' (0x30) .. '9' (0x39)
+        throw new Error("protobuf-encoder: fixed64 string must be unsigned digit-only (got " + JSON.stringify(value) + ")");
+      }
+    }
+    bi = BigInt(value);
+  } else if (typeof value === "number") {
     if (value < 0 || !Number.isFinite(value)) {
       throw new Error("protobuf-encoder: fixed64 must be non-negative finite (got " + value + ")");
     }
-    // Number path — split into low/high 32-bit halves.
-    var low  = value % 0x100000000;
-    var high = Math.floor(value / 0x100000000);
-    buf.writeUInt32LE(low,  0);
-    buf.writeUInt32LE(high, 4);
+    // Refuse silently-rounded values beyond Number.MAX_SAFE_INTEGER —
+    // the caller MUST pass a BigInt or string in that range. JS doubles
+    // lose precision past 2^53 so a Number 1779518164402000000 isn't
+    // actually that exact value once it touches Number arithmetic.
+    if (value > Number.MAX_SAFE_INTEGER) {
+      throw new Error("protobuf-encoder: fixed64 Number above MAX_SAFE_INTEGER loses precision; pass a BigInt or digit-string (got " + value + ")");
+    }
+    bi = BigInt(value);
+  } else {
+    throw new Error("protobuf-encoder: fixed64 must be bigint, number, or digit-string (got " + typeof value + ")");
+  }
+  if (bi < 0n || bi > (1n << 64n) - 1n) {
+    throw new Error("protobuf-encoder: fixed64 out of uint64 range (got " + bi.toString() + ")");
   }
+  buf.writeBigUInt64LE(bi, 0);
   return Buffer.concat([_tag(fieldNumber, WIRE_64BIT), buf]);
 }
 
@@ -177,6 +253,8 @@ function repeatedMessage(fieldNumber, items, perItemBodyEncoder) {
 module.exports = {
   uint32:           uint32,
   uint64:           uint64,
+  int64:            int64,
+  sint64:           sint64,
   bool:             bool,
   fixed64:          fixed64,
   double:           double,