@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/itg/mongodb.js

@@ -0,0 +1,322 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// MongoDB Node driver (82 §8 ITG-142, ITG-143, ITG-033), through the driver's command monitoring.
+// `MongoClient` (the export of lib/mongo_client.js) is replaced by a Proxy whose construct trap
+// enables `monitorCommands` unless the app passed `monitorCommands: false` explicitly, and
+// observes `commandStarted` / `commandSucceeded` / `commandFailed` through the instance's `emit`
+// (no listener is added, so the client's listener APIs show only the app's own). The driver emits
+// these events synchronously in the async context of the operation, so a span's parent is the
+// span current when the app called the operation. Documented side effect (82 open issue 3): an app
+// listener registered for command events on a client created without the option now fires.
+// The Proxy keeps `name`, statics, `instanceof` and subclassing (`class X extends MongoClient`).
+
+const crypto = require('crypto')
+const c = require('./common')
+const dbc = require('./dbcomment')
+
+const MAX_STATEMENT = 2000
+const SKIPPED = new Set(['saslstart', 'saslcontinue', 'authenticate', 'getnonce', 'hello', 'ismaster',
+  'copydbsaslstart', 'createuser', 'updateuser'])
+const DROPPED = new Set(['lsid', '$clusterTime', '$db', 'txnNumber', 'signature', '$readPreference'])
+
+let ejson = null
+
+function isPlain (v) {
+  if (!v || typeof v !== 'object') return false
+  if (Array.isArray(v)) return false
+  if (v._bsontype) return false
+  if (v instanceof Date || v instanceof Uint8Array || v instanceof RegExp) return false
+  return true
+}
+
+function shape (v, depth) {
+  if (depth > 32) return '?'
+  if (Array.isArray(v)) {
+    if (v.length === 0) return []
+    const first = shape(v[0], depth + 1)
+    return v.length > 1 ? [first, '…'] : [first]
+  }
+  if (v instanceof Map) {
+    const o = {}
+    for (const [k, x] of v) if (!DROPPED.has(k)) o[String(k)] = shape(x, depth + 1)
+    return o
+  }
+  if (isPlain(v)) {
+    const o = {}
+    for (const k of Object.keys(v)) if (!DROPPED.has(k)) o[k] = shape(v[k], depth + 1)
+    return o
+  }
+  return '?'
+}
+
+function truncate (s) {
+  return s.length > MAX_STATEMENT ? s.slice(0, MAX_STATEMENT - 1) + '…' : s
+}
+
+/** ITG-033: the command document, values replaced by "?" (sanitized) or as extended JSON (raw). */
+function statement (command, mode) {
+  if (mode === 'off' || !command || typeof command !== 'object') return undefined
+  try {
+    if (mode === 'raw') {
+      const doc = {}
+      for (const k of Object.keys(command)) if (!DROPPED.has(k)) doc[k] = command[k]
+      const text = ejson ? ejson.stringify(doc, { relaxed: true }) : JSON.stringify(doc, (k, v) => (typeof v === 'bigint' ? String(v) : v))
+      return truncate(text)
+    }
+    return truncate(JSON.stringify(shape(command, 0)))
+  } catch (_) {
+    return undefined
+  }
+}
+
+function collectionOf (name, command) {
+  try {
+    const v = name === 'getMore' ? command.collection : command[name]
+    return typeof v === 'string' ? v : undefined
+  } catch (_) {
+    return undefined
+  }
+}
+
+function replyRows (reply) {
+  try {
+    const cur = reply && reply.cursor
+    if (cur && typeof cur === 'object') {
+      for (const k of ['firstBatch', 'nextBatch']) if (Array.isArray(cur[k])) return cur[k].length
+    }
+    if (reply && typeof reply.n === 'number') return reply.n
+  } catch (_) {}
+  return undefined
+}
+
+function peer (address) {
+  const tags = {}
+  if (typeof address !== 'string') return tags
+  const i = address.lastIndexOf(':')
+  if (address.startsWith('/') || i === -1) tags['net.peer.name'] = address
+  else {
+    tags['net.peer.name'] = address.slice(0, i).replace(/^\[|\]$/g, '')
+    tags['net.peer.port'] = address.slice(i + 1)
+  }
+  return tags
+}
+
+function keyOf (ev) {
+  return String(ev.requestId) + '|' + String(ev.connectionId) + '|' + String(ev.address)
+}
+
+/** Per client: open spans by (requestId, connectionId, address). */
+function observe (client) {
+  const open = new Map()
+  const emit = client.emit
+  if (typeof emit !== 'function') return
+  Object.defineProperty(client, 'emit', {
+    configurable: true,
+    writable: true,
+    enumerable: false,
+    value: function (event, ev) {
+      try {
+        if (event === 'commandStarted') started(open, ev)
+        else if (event === 'commandSucceeded') succeeded(open, ev)
+        else if (event === 'commandFailed') failed(open, ev)
+      } catch (_) {}
+      return emit.apply(this, arguments)
+    }
+  })
+}
+
+function started (open, ev) {
+  if (!ev || typeof ev.commandName !== 'string') return
+  const name = ev.commandName
+  if (SKIPPED.has(name.toLowerCase())) return
+  const t = c.dbTracer()
+  if (!t || c.suppressedLib('mongodb')) return
+  let command = ev.command || {}
+  // our trace comment (96 SVM-503): the span gets the id the comment carries, and the comment
+  // is not part of db.statement
+  let plan = null
+  if (typeof command.comment === 'string' && planned.has(command.comment)) {
+    plan = planned.get(command.comment)
+    planned.delete(command.comment)
+    const rest = {}
+    for (const k of Object.keys(command)) if (k !== 'comment') rest[k] = command[k]
+    command = rest
+  }
+  const coll = collectionOf(name, command)
+  const tags = { 'db.system': 'mongodb', 'db.operation': name }
+  if (ev.databaseName) tags['db.name'] = String(ev.databaseName)
+  if (coll) tags['db.mongodb.collection'] = coll
+  Object.assign(tags, peer(ev.address))
+  const st = statement(command, t.db.statement)
+  if (st !== undefined) tags['db.statement'] = st
+  const span = c.clientSpan(t, coll ? name + ' ' + coll : name, tags)
+  // only when the span belongs to the trace the comment names (else the comment stays unmatched)
+  if (span && plan && !t.bridge && typeof span.spanId === 'string' && span.traceId === plan.traceId) {
+    span.spanId = plan.spanId
+    span._ctx = null
+  }
+  if (span) open.set(keyOf(ev), span)
+}
+
+function succeeded (open, ev) {
+  const k = keyOf(ev)
+  const span = open.get(k)
+  if (!span) return
+  open.delete(k)
+  const reply = ev.reply
+  // a write the server answers with writeErrors succeeded at the protocol level (same as pmx-io)
+  const we = reply && Array.isArray(reply.writeErrors) && reply.writeErrors[0]
+  if (we) {
+    const code = we.code
+    const err = { name: code === 11000 ? 'DuplicateKeyError' : 'WriteError', message: String(we.errmsg || '') }
+    c.end(span, err, code)
+    return
+  }
+  const rows = replyRows(reply)
+  if (rows !== undefined) span.setAttribute('db.rows', String(rows))
+  c.end(span)
+}
+
+function failed (open, ev) {
+  const k = keyOf(ev)
+  const span = open.get(k)
+  if (!span) return
+  open.delete(k)
+  const err = ev.failure || new Error('command failed')
+  c.end(span, err, err && err.code !== undefined ? err.code : undefined)
+}
+
+// 96 SVM-503: comments added by the Connection.command wrapper → the span id they carry
+const planned = new Map()
+const PLANNED_MAX = 1024
+// commands that accept `comment` from MongoDB 4.4 (wire version 9); getMore inherits it
+const COMMENTED = new Set(['find', 'aggregate', 'count', 'distinct', 'insert', 'update', 'delete', 'findAndModify'])
+const WIRE_4_4 = 9
+
+function randomSpanId () {
+  let id
+  do id = crypto.randomBytes(8).toString('hex')
+  while (id === '0000000000000000')
+  return id
+}
+
+function maxWire (conn) {
+  const d = conn && (conn.description || conn.hello)
+  return d && typeof d.maxWireVersion === 'number' ? d.maxWireVersion : 0
+}
+
+/** The command document with the trace comment (a copy), or `cmd` unchanged. */
+function withComment (conn, cmd) {
+  const t = c.dbTracer()
+  if (!t || t.bridge || c.suppressedLib('mongodb')) return cmd
+  const mode = t.db.comment
+  if (mode !== 'on' && mode !== 'force') return cmd
+  if (!cmd || typeof cmd !== 'object' || cmd.comment !== undefined) return cmd
+  // auto-encryption connections pass an already encrypted document down: left alone
+  if (conn && conn.constructor && conn.constructor.name === 'CryptoConnection') return cmd
+  const proto = Object.getPrototypeOf(cmd)
+  if (proto !== Object.prototype && proto !== null) return cmd
+  const name = Object.keys(cmd)[0]
+  if (!COMMENTED.has(name) || maxWire(conn) < WIRE_4_4) return cmd
+  const parent = dbc.spanIds(c.currentSpan())
+  if (!parent) return cmd
+  const id = randomSpanId()
+  if (!dbc.validIds(parent.traceId, id)) return cmd
+  const comment = dbc.mongoComment(t, parent.traceId, id)
+  if (planned.size >= PLANNED_MAX) planned.clear()
+  planned.set(comment, { traceId: parent.traceId, spanId: id })
+  return Object.assign({}, cmd, { comment })
+}
+
+function wrapCommand (orig) {
+  return function command (ns, cmd) {
+    let next = cmd
+    try {
+      next = withComment(this, cmd)
+    } catch (_) {
+      next = cmd
+    }
+    if (next === cmd) return orig.apply(this, arguments)
+    const args = Array.prototype.slice.call(arguments)
+    args[1] = next
+    return orig.apply(this, args)
+  }
+}
+
+/** 96 SVM-505: appName = the pmx app name unless the options or the URL name one. */
+function withAppName (args, opts) {
+  const t = c.dbTracer()
+  const name = t && dbc.connectionAppName(t)
+  if (!name) return opts
+  if (opts && opts.appName !== undefined && opts.appName !== null) return opts
+  if (typeof args[0] === 'string' && /[?&]appname=/i.test(args[0])) return opts
+  return Object.assign({}, opts, { appName: name })
+}
+
+function proxyClient (MongoClient) {
+  return new Proxy(MongoClient, {
+    construct (target, args, newTarget) {
+      let a = args
+      try {
+        if (c.dbTracer()) {
+          const opts = args[1]
+          if (opts === undefined || opts === null || typeof opts === 'object') {
+            let next = opts || {}
+            if (next.monitorCommands === undefined) next = Object.assign({}, next, { monitorCommands: true })
+            next = withAppName(args, next)
+            if (next !== (opts || {})) {
+              a = args.slice()
+              a[1] = next
+            }
+          }
+        }
+      } catch (_) {
+        a = args
+      }
+      const client = Reflect.construct(target, a, newTarget)
+      try {
+        const o = client.options || {}
+        if (o.monitorCommands !== false) observe(client)
+      } catch (_) {}
+      return client
+    }
+  })
+}
+
+/** lib/mongo_client.js: exports.MongoClient. */
+function patchClient (exports, info) {
+  const MongoClient = exports && exports.MongoClient
+  if (typeof MongoClient !== 'function') {
+    c.disabled('mongodb', 'MongoClient not found')
+    return
+  }
+  if (MongoClient[c.WRAPPED]) return
+  // 85 OTX-020: OpenTelemetry's MongoDB instrumentation wraps the connection's `command` (pmx
+  // observes events and wraps nothing there); resolved on the first command in bridge mode
+  const dir = info && info.dir
+  if (dir) {
+    c.watch('mongodb', () => {
+      const m = require(require('path').join(dir, 'lib', 'cmap', 'connection.js'))
+      return m && m.Connection && m.Connection.prototype ? [m.Connection.prototype, 'command'] : null
+    })
+  }
+  if (dir) {
+    try {
+      const m = require(require('path').join(dir, 'lib', 'cmap', 'connection.js'))
+      if (m && m.Connection && m.Connection.prototype) c.wrap(m.Connection.prototype, 'command', wrapCommand)
+    } catch (err) {
+      c.disabled('mongodb', 'trace comment: ' + (err && err.message))
+    }
+  }
+  try {
+    const b = require(require('path').join(info.dir, 'lib', 'bson.js'))
+    if (b && b.EJSON && typeof b.EJSON.stringify === 'function') ejson = b.EJSON
+  } catch (_) {}
+  const P = proxyClient(MongoClient)
+  const d = Object.getOwnPropertyDescriptor(exports, 'MongoClient')
+  if (d && d.writable) exports.MongoClient = P
+  else Object.defineProperty(exports, 'MongoClient', { value: P, writable: true, enumerable: true, configurable: true })
+}
+
+module.exports = { patchClient, statement, wrapCommand, withAppName, planned }

package/lib/itg/mysql2.js

@@ -0,0 +1,205 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// mysql2 (82 §7 ITG-133, ITG-134, ITG-031). `query` and `execute` of the connection class are one
+// CLIENT span per call, in callback form, event form (`query(…).on(…)`, `.stream()`) and through
+// the promise wrapper (`mysql2/promise` calls the callback API, so it adds no span). The span ends
+// at the command's `end` event, observed through the command's own `emit` (no listener is added,
+// so an unhandled `error` event still behaves as without pmx). The statement is the text the app
+// passed — before mysql2 interpolates the values client-side — sanitised per ITG-031. Pools bind
+// the `getConnection` callback to the caller's context (the query a pool issues after a checkout
+// belongs to the right request) and, with `db.poolSpans`, make a `pool.acquire` span when the
+// checkout has to wait.
+
+const c = require('./common')
+const sql = require('./sql')
+const dbc = require('./dbcomment')
+
+const TAGS = Symbol('pmx-mysql2-tags')
+
+function connTags (conn) {
+  let tags = conn[TAGS]
+  if (tags) return tags
+  tags = { 'db.system': 'mysql' }
+  const cfg = conn.config || {}
+  if (cfg.database) tags['db.name'] = String(cfg.database)
+  if (cfg.user) tags['db.user'] = String(cfg.user)
+  if (cfg.socketPath) tags['net.peer.name'] = String(cfg.socketPath)
+  else {
+    tags['net.peer.name'] = String(cfg.host || 'localhost')
+    if (cfg.port) tags['net.peer.port'] = String(cfg.port)
+  }
+  try {
+    Object.defineProperty(conn, TAGS, { value: tags, configurable: true })
+  } catch (_) {}
+  return tags
+}
+
+function textOf (s) {
+  if (typeof s === 'string') return s
+  if (s && typeof s === 'object' && typeof s.sql === 'string') return s.sql
+  return ''
+}
+
+function rowsOf (rows) {
+  if (Array.isArray(rows)) return rows.length
+  if (rows && typeof rows === 'object' && typeof rows.affectedRows === 'number') return rows.affectedRows
+  return undefined
+}
+
+/** Observe the command's completion through its own emit/onResult (instance properties). */
+function observe (cmd, span) {
+  let err
+  let rows
+  let streamed = 0
+  const finish = () => {
+    if (span.ended) return
+    if (!err) {
+      const n = rows !== undefined ? rows : (streamed || undefined)
+      if (n !== undefined) span.setAttribute('db.rows', String(n))
+    }
+    c.end(span, err, err && err.errno !== undefined ? err.errno : undefined)
+  }
+  // callback mode: the result is delivered after `end` (on the next tick); the span ends then
+  const byCallback = typeof cmd.onResult === 'function'
+  const emit = cmd.emit
+  Object.defineProperty(cmd, 'emit', {
+    configurable: true,
+    writable: true,
+    enumerable: false,
+    value: function (ev, a) {
+      try {
+        if (ev === 'error') err = err || a
+        else if (ev === 'result') {
+          if (a && typeof a === 'object' && !Array.isArray(a) && typeof a.affectedRows === 'number') rows = a.affectedRows
+          else streamed++
+        } else if (ev === 'end' && !byCallback) finish()
+      } catch (_) {}
+      return emit.apply(this, arguments)
+    }
+  })
+  const onResult = cmd.onResult
+  if (typeof onResult === 'function') {
+    cmd.onResult = function (e, r) {
+      try {
+        if (e) err = e
+        else rows = rowsOf(r)
+        finish()
+      } catch (_) {}
+      return onResult.apply(this, arguments)
+    }
+  }
+}
+
+/**
+ * 96 SVM-501/502: prepend the trace comment (args[0] replaced by a copy). `execute()` uses
+ * mysql2's prepared-statement cache keyed by the text: skipped with `on`, commented with `force`.
+ */
+function comment (t, span, s, args, prepared) {
+  const text = textOf(s)
+  if (!dbc.wants(t, span, text, prepared)) return
+  const prefix = dbc.sqlPrefix(t, span)
+  if (typeof s === 'string') args[0] = prefix + s
+  else {
+    const proto = Object.getPrototypeOf(s)
+    if (proto === Object.prototype || proto === null) args[0] = Object.assign({}, s, { sql: prefix + s.sql })
+  }
+}
+
+function wrapCall (op) {
+  return (orig) => function (s, values, cb) {
+    const t = c.dbTracer()
+    if (!t || c.nested() || s === null || s === undefined) return orig.apply(this, arguments)
+    let span = null
+    try {
+      const text = textOf(s)
+      const base = connTags(this)
+      const operation = sql.operation(text)
+      const tags = Object.assign({}, base)
+      if (operation) tags['db.operation'] = operation
+      const st = sql.statementTag(text, t.db.statement, true)
+      if (st !== undefined) tags['db.statement'] = st
+      const name = operation ? (base['db.name'] ? operation + ' ' + base['db.name'] : operation) : (base['db.name'] || 'mysql')
+      span = c.clientSpan(t, name, tags)
+    } catch (_) {
+      span = null
+    }
+    if (!span) return orig.apply(this, arguments)
+    const args = Array.prototype.slice.call(arguments)
+    try {
+      comment(t, span, s, args, op === 'execute')
+    } catch (_) {}
+    // callbacks run later from the socket: give them the caller's context
+    for (let i = 1; i < args.length; i++) if (typeof args[i] === 'function') args[i] = c.bind(args[i])
+    let cmd
+    try {
+      cmd = c.outer(orig, this, args)
+    } catch (err) {
+      c.end(span, err)
+      throw err
+    }
+    try {
+      if (cmd && typeof cmd.emit === 'function') observe(cmd, span)
+      else c.end(span)
+    } catch (_) {
+      c.end(span)
+    }
+    return cmd
+  }
+}
+
+function wrapGetConnection (orig) {
+  return function getConnection (cb) {
+    const t = c.tracer()
+    if (!t || typeof cb !== 'function') return orig.apply(this, arguments)
+    let span = null
+    try {
+      const cfg = this.config || {}
+      const limit = cfg.connectionLimit
+      const free = this._freeConnections
+      const all = this._allConnections
+      const freeCount = free ? (typeof free.length === 'number' ? free.length : 0) : 0
+      const allCount = all ? (typeof all.length === 'number' ? all.length : 0) : 0
+      if (t.db && t.db.poolSpans && c.currentSpan() && freeCount === 0 && limit > 0 && allCount >= limit) {
+        const q = this._connectionQueue
+        span = c.clientSpan(t, 'pool.acquire', {
+          'db.system': 'mysql',
+          'db.pool.size': String(allCount),
+          'db.pool.max_size': String(limit),
+          'db.pool.waiting': String(q && typeof q.length === 'number' ? q.length : 0)
+        }, 'INTERNAL')
+      }
+    } catch (_) {
+      span = null
+    }
+    const bound = c.bind(cb)
+    return orig.call(this, function (err) {
+      c.end(span, err || undefined)
+      return bound.apply(this, arguments)
+    })
+  }
+}
+
+/** lib/base/connection.js (≥ 3.10) or lib/connection.js (older 3.x): query and execute. */
+function patchConnection (exports) {
+  const Conn = exports && (exports.default || exports)
+  const proto = Conn && Conn.prototype
+  if (!proto || typeof proto.query !== 'function') {
+    c.disabled('mysql2', 'Connection.prototype.query not found')
+    return
+  }
+  if (!Object.prototype.hasOwnProperty.call(proto, 'query')) return // inherited from base/connection.js
+  c.wrap(proto, 'query', wrapCall('query'))
+  if (typeof proto.execute === 'function') c.wrap(proto, 'execute', wrapCall('execute'))
+}
+
+/** lib/base/pool.js or lib/pool.js: getConnection. */
+function patchPool (exports) {
+  const Pool = exports && (exports.default || exports)
+  const proto = Pool && Pool.prototype
+  if (!proto || typeof proto.getConnection !== 'function') return
+  if (!Object.prototype.hasOwnProperty.call(proto, 'getConnection')) return
+  c.wrap(proto, 'getConnection', wrapGetConnection)
+}
+
+module.exports = { patchConnection, patchPool }