@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/itg/common.js

@@ -0,0 +1,657 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Common rules of the database and broker integrations (82 §1, §2, §4; the Node counterpart of
+// pmx-io's _msg.py / _db.py helpers): switches, CLIENT/PRODUCER/CONSUMER/receive span creation
+// and parenting, error marking, promise/callback completion, header carriers, links for batches,
+// iterator-style consumer spans and the exit flush of open iterator spans. The per-library modules
+// (lib/itg/<library>.js) only map library calls onto these helpers.
+//
+// Everything here is defensive: a failure in pmx code is logged under `axm:tracing` and never
+// reaches the app (ITG-003). Loaded only when an instrumented library is loaded with tracing on.
+
+const ctx = require('../tracing/context')
+const w3c = require('../tracing/w3c')
+const debug = require('../debug')('axm:tracing')
+
+const MODULES = Symbol.for('@pmx/io:modules')
+const ERROR_MAX = 500
+const TRACE_KEY = '__pmx_trace__' // pmx payload carrier (ITG-220)
+const WRAPPED = Symbol.for('@pmx/io:itg-wrapped')
+const ORIGINAL = Symbol.for('@pmx/io:itg-original')
+
+// ---------------------------------------------------------------------------------------------
+// switches (ITG-001)
+
+/** The tracer while tracing is enabled, else null (wrappers then pass straight through). */
+function tracer () {
+  const r = globalThis[MODULES]
+  if (!r || !r.wants.tracing) return null
+  const f = r.tracing
+  if (!f || !f._enabled) return null
+  const t = f._tracer
+  return t && t.enabled ? t : null
+}
+
+/** The tracer when database spans are wanted now, else null. */
+function dbTracer () {
+  const t = tracer()
+  return t && t.db ? t : null
+}
+
+/** The tracer when broker spans are wanted now, else null. */
+function msgTracer () {
+  const t = tracer()
+  return t && t.messaging ? t : null
+}
+
+/** The current span (a span of this process or, in bridge mode, of the app's SDK), or undefined. */
+function currentSpan () {
+  const s = ctx.current()
+  return s ? s.span : undefined
+}
+
+// One logical operation, one span (ITG-005): an outer wrapper that created a span runs the inner
+// layers with `depth` raised (synchronous nesting); asynchronous nesting is marked per library on
+// the objects that pass between the layers.
+let depth = 0
+
+function nested () {
+  return depth > 0
+}
+
+/** Call fn with the nesting marker raised (inner wrappers then do nothing). */
+function outer (fn, thisArg, args) {
+  depth++
+  try {
+    return fn.apply(thisArg, args)
+  } finally {
+    depth--
+  }
+}
+
+function disabled (lib, why) {
+  debug('%s: instrumentation disabled (%s)', lib, why)
+}
+
+// ---------------------------------------------------------------------------------------------
+// spans
+
+/** A CLIENT span under the current span, or null (no root CLIENT spans, ITG-010). */
+function clientSpan (t, name, tags, kind) {
+  const parent = currentSpan()
+  if (!parent) return null
+  try {
+    return t.childOf(parent, name, kind || 'CLIENT', tags)
+  } catch (err) {
+    debug('span failed: %s', err && err.message)
+    return null
+  }
+}
+
+function msgTags (system, destination, operation, extra) {
+  const tags = { 'messaging.system': system }
+  if (destination) tags['messaging.destination.name'] = destination
+  if (operation) tags['messaging.operation'] = operation
+  if (extra) {
+    for (const k of Object.keys(extra)) {
+      if (extra[k] !== undefined && extra[k] !== null) tags[k] = extra[k]
+    }
+  }
+  return tags
+}
+
+/**
+ * ITG-020/021: `publish <destination>` (`request <destination>` for request/reply, kind CLIENT),
+ * a child of the current span; without one only with `messaging.rootProducers`. null when no span
+ * is to be created (nothing is injected then).
+ */
+function producer (system, destination, tags, kind, verb) {
+  const t = msgTracer()
+  if (!t) return null
+  kind = kind || 'PRODUCER'
+  try {
+    const name = (verb || 'publish') + ' ' + (destination || 'multiple')
+    const attrs = msgTags(system, destination, kind === 'PRODUCER' ? 'publish' : undefined, tags)
+    const parent = currentSpan()
+    if (parent) return t.childOf(parent, name, kind, attrs)
+    if (t.messaging.rootProducers) return t.startSpan(name, { kind, attributes: attrs, parent: w3c.NEW_TRACE })
+  } catch (err) {
+    debug('producer span failed: %s', err && err.message)
+  }
+  return null
+}
+
+/**
+ * ITG-021: a CONSUMER `process <destination>` entry span; parent = the message's context, else
+ * the current span, else a new trace.
+ */
+function consumer (system, destination, context, tags) {
+  const t = msgTracer()
+  if (!t) return null
+  try {
+    const name = 'process ' + (destination || 'multiple')
+    const attrs = msgTags(system, destination, 'process', tags)
+    if (w3c.isSpanContext(context)) return t.startSpan(name, { kind: 'CONSUMER', attributes: attrs, parent: context })
+    const cur = currentSpan()
+    return t.startSpan(name, { kind: 'CONSUMER', attributes: attrs, parent: cur || w3c.NEW_TRACE })
+  } catch (err) {
+    debug('consumer span failed: %s', err && err.message)
+    return null
+  }
+}
+
+/**
+ * ITG-023/024: a CONSUMER span handling several messages (`process` for a batch callback,
+ * `receive` for a batch pull): parent = the current span, else a new trace; one link per message
+ * carrying a context, at most `messaging.maxLinks`.
+ */
+function batchConsumer (system, destination, contexts, tags, operation) {
+  const t = msgTracer()
+  if (!t) return null
+  operation = operation || 'process'
+  try {
+    const name = operation + ' ' + (destination || 'multiple')
+    const attrs = msgTags(system, destination, operation, tags)
+    const cur = currentSpan()
+    const span = t.startSpan(name, { kind: 'CONSUMER', attributes: attrs, parent: cur || w3c.NEW_TRACE })
+    span.maxLinks = t.messaging.maxLinks
+    if (contexts) for (const c of contexts) addLink(span, c)
+    return span
+  } catch (err) {
+    debug('batch span failed: %s', err && err.message)
+    return null
+  }
+}
+
+function addLink (span, c) {
+  if (span && w3c.isSpanContext(c)) span.addLink(c)
+}
+
+/** ITG-013: `<error.name>: <first line of error.message>`, at most 500 characters. */
+function errorText (err) {
+  let name
+  let msg
+  if (err && typeof err === 'object') {
+    name = typeof err.name === 'string' && err.name ? err.name : (err.constructor && err.constructor.name) || 'Error'
+    msg = typeof err.message === 'string' ? err.message : ''
+  } else {
+    name = 'Error'
+    msg = String(err)
+  }
+  const first = msg.split(/\r?\n/)[0]
+  const text = first ? name + ': ' + first : name
+  return text.length > ERROR_MAX ? text.slice(0, ERROR_MAX) : text
+}
+
+function fail (span, err, code) {
+  if (!span) return
+  try {
+    span.setStatus('ERROR', errorText(err))
+    if (code !== undefined && code !== null && code !== '') span.setAttribute('db.response.status_code', String(code))
+  } catch (_) {}
+}
+
+function end (span, err, code) {
+  if (!span) return
+  try {
+    if (err !== undefined && err !== null) fail(span, err, code)
+    span.end()
+  } catch (e) {
+    debug('span end failed: %s', e && e.message)
+  }
+}
+
+function isThenable (v) {
+  return v !== null && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function'
+}
+
+/**
+ * Ends `span` when `p` settles; returns a promise settling like `p` (a derived promise: an app
+ * that ignores a rejection still gets its unhandled-rejection report). `onValue(v)` may tag rows,
+ * `codeOf(err)` gives the server error code.
+ */
+function settle (p, span, onValue, codeOf) {
+  return p.then((v) => {
+    if (onValue) {
+      try {
+        onValue(v)
+      } catch (_) {}
+    }
+    end(span)
+    return v
+  }, (err) => {
+    end(span, err, codeOf ? safe(codeOf, err) : undefined)
+    throw err
+  })
+}
+
+function safe (fn, arg) {
+  try {
+    return fn(arg)
+  } catch (_) {
+    return undefined
+  }
+}
+
+/** Run fn with `span` current (and its baggage); returns fn's result. */
+function withSpan (span, fn, thisArg, args) {
+  if (!span) return fn.apply(thisArg, args || [])
+  const store = ctx.current()
+  return ctx.run({ span, bag: span.bag, server: store && store.server }, fn, thisArg, args)
+}
+
+/**
+ * Callback style (ITG-023): run fn with `span` current; the span ends when fn returns, throws,
+ * or (for a thenable result) when that settles; errors mark it ERROR and propagate unchanged.
+ */
+function runConsumer (span, fn, thisArg, args) {
+  if (!span) return fn.apply(thisArg, args || [])
+  let r
+  try {
+    r = withSpan(span, fn, thisArg, args)
+  } catch (err) {
+    end(span, err)
+    throw err
+  }
+  if (isThenable(r)) {
+    try {
+      r.then(() => end(span), (err) => end(span, err))
+    } catch (err) {
+      end(span)
+    }
+    return r
+  }
+  end(span)
+  return r
+}
+
+/** Bind a callback to the context current now (callbacks a library calls later, NIO-203). */
+function bind (fn) {
+  return typeof fn === 'function' ? ctx.bind(fn) : fn
+}
+
+// ---------------------------------------------------------------------------------------------
+// carriers (ITG-022, ITG-220)
+
+/**
+ * [[name, value]] of `traceparent` (+ `tracestate`, `baggage` when non-empty) of `span`; in 85
+ * bridge mode the headers the app's OpenTelemetry propagator writes (OTX-012, as pmx-io does).
+ */
+function traceHeaders (span) {
+  if (!span || !span.context) return []
+  try {
+    const b = bridgeNow()
+    if (b !== null) {
+      const pairs = b.headersFor(span)
+      if (pairs) return pairs
+    }
+    return w3c.headersFor(span.context, span.bag)
+  } catch (err) {
+    debug('trace headers failed: %s', err && err.message)
+    return []
+  }
+}
+
+/** A new plain object: `base` (never modified) plus the trace headers the app did not set. */
+function headersObject (span, base, asBytes) {
+  const out = Object.assign({}, base || {})
+  const present = new Set(Object.keys(out).map((k) => k.toLowerCase()))
+  for (const [k, v] of traceHeaders(span)) {
+    if (!present.has(k)) out[k] = asBytes ? Buffer.from(v, 'utf8') : v
+  }
+  return out
+}
+
+/** The `__pmx_trace__` / `pmxTrace` carrier value of `span` (ITG-212, ITG-220). */
+function traceCarrier (span) {
+  const o = {}
+  for (const [k, v] of traceHeaders(span)) o[k] = v
+  return o
+}
+
+/**
+ * The remote context in a carrier (object, Map, headers object, pairs), or null; in 85 bridge
+ * mode the app's OpenTelemetry propagator reads it (OTX-012, as pmx-io does).
+ */
+function extract (carrier) {
+  if (!carrier) return null
+  try {
+    const b = bridgeNow()
+    if (b !== null) {
+      const sc = b.extract(carrier)
+      if (sc !== undefined) return sc
+    }
+    return w3c.extract(carrier)
+  } catch (_) {
+    return null
+  }
+}
+
+/** ITG-025: bytes of a payload that already is bytes or a string (never serialised to measure). */
+function bodySize (body) {
+  if (typeof body === 'string') return Buffer.byteLength(body, 'utf8')
+  if (body instanceof Uint8Array || body instanceof ArrayBuffer) return body.byteLength
+  return undefined
+}
+
+// ---------------------------------------------------------------------------------------------
+// iterator style (ITG-023)
+
+const openIters = new Set()
+let exitHooked = false
+
+function hookExit () {
+  if (exitHooked) return
+  exitHooked = true
+  // before the span sink's own exit flush, which was registered when tracing started
+  process.prependListener('exit', endOpenIterators)
+}
+
+/**
+ * Per-iterator state: a CONSUMER span starts when a message is handed to the app, is current while
+ * the loop body runs (an AsyncLocalStorage store entered synchronously inside the wrapped `next()`
+ * and filled in at delivery), and ends at the next request on the same iterator, at close or at
+ * exit flush (`pmx.end_inferred` for the last two). When iteration ends, the context of the code
+ * before the loop is restored.
+ */
+class IterState {
+  constructor () {
+    this.span = null
+    this.store = null
+    this.prev = undefined
+    this.started = false
+  }
+
+  /** The app asks for the next message (synchronously inside next()). */
+  nextRequested () {
+    this._finish(false)
+    if (!ctx.active()) return
+    const cur = ctx.current()
+    if (!this.started) {
+      this.started = true
+      this.prev = cur
+    }
+    const base = this.prev
+    const store = { span: base && base.span, bag: base ? base.bag : w3c.EMPTY_BAG, server: base && base.server }
+    try {
+      ctx.enter(store)
+      this.store = store
+    } catch (_) {
+      this.store = null
+    }
+  }
+
+  /** A message is handed to the app: `span` becomes current for the loop body. */
+  delivered (span) {
+    if (!span) return
+    this.span = span
+    if (this.store) {
+      this.store.span = span
+      this.store.bag = span.bag
+    }
+    openIters.add(this)
+    hookExit()
+  }
+
+  /** Iteration finished (done, return(), close): end the span and restore the earlier context. */
+  closed (inferred) {
+    this._finish(inferred !== false)
+    if (this.started) {
+      try {
+        ctx.enter(this.prev)
+      } catch (_) {}
+    }
+  }
+
+  _finish (inferred) {
+    const span = this.span
+    this.span = null
+    if (this.store) {
+      // the loop body's store no longer names the span (late callbacks see the parent)
+      this.store.span = this.prev && this.prev.span
+      this.store.bag = this.prev ? this.prev.bag : w3c.EMPTY_BAG
+    }
+    openIters.delete(this)
+    if (span) {
+      if (inferred) span.setAttribute('pmx.end_inferred', 'true')
+      end(span)
+    }
+  }
+
+  atExit () {
+    const span = this.span
+    this.span = null
+    if (span) {
+      span.setAttribute('pmx.end_inferred', 'true')
+      end(span)
+    }
+  }
+}
+
+function endOpenIterators () {
+  for (const it of Array.from(openIters)) {
+    try {
+      it.atExit()
+    } catch (_) {}
+  }
+  openIters.clear()
+}
+
+const ITER = Symbol('pmx-iter')
+
+/** The IterState attached to a library iterator/subscription object (created on demand). */
+function iterState (obj) {
+  if (!obj || (typeof obj !== 'object' && typeof obj !== 'function')) return null
+  let st = obj[ITER]
+  if (st instanceof IterState) return st
+  st = new IterState()
+  try {
+    Object.defineProperty(obj, ITER, { value: st, configurable: true, enumerable: false, writable: true })
+  } catch (_) {
+    return null
+  }
+  return st
+}
+
+// ---------------------------------------------------------------------------------------------
+// wrapping (ITG-003)
+
+function copyMeta (fn, orig) {
+  try {
+    Object.defineProperty(fn, 'length', { value: orig.length, configurable: true })
+    Object.defineProperty(fn, 'name', { value: orig.name, configurable: true })
+  } catch (_) {}
+  try {
+    Object.defineProperty(fn, ORIGINAL, { value: orig })
+    Object.defineProperty(fn, WRAPPED, { value: true })
+  } catch (_) {}
+  // static properties (e.g. util.promisify.custom) stay reachable
+  try {
+    for (const k of Reflect.ownKeys(orig)) {
+      if (k === 'length' || k === 'name' || k === 'prototype' || k === WRAPPED || k === ORIGINAL) continue
+      if (!Object.prototype.hasOwnProperty.call(fn, k)) {
+        const d = Object.getOwnPropertyDescriptor(orig, k)
+        if (d) Object.defineProperty(fn, k, d)
+      }
+    }
+  } catch (_) {}
+  if (orig.prototype !== undefined) {
+    try {
+      fn.prototype = orig.prototype
+    } catch (_) {}
+  }
+  return fn
+}
+
+/**
+ * Replace obj[name] (a function) by make(original) once. The replacement keeps `name`, `length`
+ * and the property's enumerability; pmx marks it with a private symbol (never `__wrapped`, which
+ * OpenTelemetry's shimmer uses, 85 OTX-020). Returns true when wrapped (or already wrapped).
+ * `opts.lib` names the package (default: the one being patched), `opts.track: false` keeps a
+ * wrapper of a per-instance object out of the per-library list.
+ */
+function wrap (obj, name, make, opts) {
+  if (!obj) return false
+  let desc
+  let owner = obj
+  while (owner && !(desc = Object.getOwnPropertyDescriptor(owner, name))) owner = Object.getPrototypeOf(owner)
+  if (!desc || typeof desc.value !== 'function') return false
+  const orig = desc.value
+  if (orig[WRAPPED]) return true
+  try {
+    const made = make(orig)
+    // objects wrapped at run time (kafkajs producers) name their library and are not tracked
+    const lib = (opts && opts.lib) || currentLib
+    // 85 OTX-020: in bridge mode, when an OpenTelemetry instrumentation covers this library (its
+    // shimmer wrapper, marked `__wrapped`, sits on this or another function pmx hooks in the
+    // library), pass straight through
+    const w = copyMeta(function () {
+      const b = bridgeNow()
+      if (b !== null && !b.disabledMarkerCheck && coveredByOtel(lib, this, name, w)) {
+        b.suppress(lib)
+        return orig.apply(this, arguments)
+      }
+      return made.apply(this, arguments)
+    }, orig)
+    Object.defineProperty(obj, name, { value: w, writable: desc.writable !== false, enumerable: desc.enumerable, configurable: true })
+    if (!(opts && opts.track === false)) hook(lib, obj, name, w, orig)
+    return true
+  } catch (err) {
+    debug('cannot wrap %s: %s', name, err && err.message)
+    return false
+  }
+}
+
+// 85 OTX-020 per library: the functions pmx hooked (and functions pmx watches without hooking
+// them, e.g. the MongoDB driver's Connection.command), by package name. An OpenTelemetry
+// instrumentation rarely wraps exactly the functions pmx wraps (amqplib: `publish` but not
+// `sendToQueue`; node-redis: commands but not `MULTI`; MongoDB: the connection, not the events
+// pmx observes), so one OTel-wrapped function suppresses all of the library's pmx spans.
+const hooks = new Map()
+
+function hook (lib, obj, name, w, orig) {
+  let list = hooks.get(lib)
+  if (!list) hooks.set(lib, (list = []))
+  list.push({ obj, name, w, orig, get: null })
+}
+
+/** Watch a function pmx does not wrap: `get()` returns [obj, name] (resolved lazily), or null. */
+function watch (lib, get) {
+  let list = hooks.get(lib)
+  if (!list) hooks.set(lib, (list = []))
+  list.push({ obj: null, name: null, w: null, orig: null, get })
+}
+
+function otelWrapped (fn, own) {
+  return Boolean(fn && fn !== own && fn.__wrapped === true)
+}
+
+/**
+ * True when an OpenTelemetry instrumentation wrapped a function of `lib` that pmx hooks or
+ * watches: the method as the receiver sees it (OTel may wrap a subclass's prototype), the
+ * property pmx replaced (OTel wrapped pmx's wrapper), or the function pmx wrapped (OTel came first).
+ */
+function coveredByOtel (lib, self, name, w) {
+  if (self !== null && self !== undefined && name !== undefined) {
+    try {
+      if (otelWrapped(self[name], w)) return true
+    } catch (_) {}
+  }
+  const list = hooks.get(lib)
+  if (!list) return false
+  for (const h of list) {
+    try {
+      if (h.get) {
+        // a watched function is resolved once
+        const get = h.get
+        h.get = null
+        const r = get()
+        if (r) {
+          h.obj = r[0]
+          h.name = r[1]
+        }
+      }
+      if (!h.obj) continue
+      if (otelWrapped(h.obj[h.name], h.w) || otelWrapped(h.orig, null)) return true
+    } catch (_) {}
+  }
+  return false
+}
+
+/** In bridge mode: true (and `lib` reported in `suppressed`) when OpenTelemetry covers `lib`. */
+function suppressedLib (lib) {
+  const b = bridgeNow()
+  if (b === null || b.disabledMarkerCheck || !coveredByOtel(lib)) return false
+  b.suppress(lib)
+  return true
+}
+
+/** The 85 bridge while tracing runs in bridge mode, else null. */
+function bridgeNow () {
+  const r = globalThis[MODULES]
+  const t = r && r.tracing && r.tracing._tracer
+  return t && t.bridge ? t.bridge : null
+}
+
+// the package being patched (set by lib/itg/index.js), reported in `suppressed` (OTX-004)
+let currentLib = 'unknown'
+function setLib (name) {
+  currentLib = name || 'unknown'
+}
+
+function isWrapped (fn) {
+  return Boolean(fn && fn[WRAPPED])
+}
+
+/** The library version from its package.json next to `dir`, or '?'. */
+function versionOf (dir) {
+  try {
+    return require(require('path').join(dir, 'package.json')).version || '?'
+  } catch (_) {
+    return '?'
+  }
+}
+
+module.exports = {
+  tracer,
+  dbTracer,
+  msgTracer,
+  currentSpan,
+  nested,
+  outer,
+  disabled,
+  clientSpan,
+  producer,
+  consumer,
+  batchConsumer,
+  addLink,
+  errorText,
+  fail,
+  end,
+  isThenable,
+  settle,
+  withSpan,
+  runConsumer,
+  bind,
+  traceHeaders,
+  headersObject,
+  traceCarrier,
+  extract,
+  bodySize,
+  IterState,
+  iterState,
+  endOpenIterators,
+  wrap,
+  watch,
+  suppressedLib,
+  coveredByOtel,
+  setLib,
+  bridgeNow,
+  copyMeta,
+  isWrapped,
+  versionOf,
+  TRACE_KEY,
+  WRAPPED,
+  ORIGINAL
+}