@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/itg/noderedis.js

@@ -0,0 +1,236 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// node-redis (`redis` 4.x/5.x/6.x through `@redis/client`; 82 §6 ITG-122, ITG-123, ITG-032; streams
+// §10 ITG-210). Every command the client sends is one CLIENT span:
+//  * @redis/client ≥ 5 (`redis` ≥ 5): `RedisClient.prototype.sendCommand(args, options)` — the
+//    typed command methods, scripts and raw `sendCommand` all go through it; `_executeMulti`
+//    (`multi().exec()`, MULTI span) and `_executePipeline` (`multi().execAsPipeline()`, PIPELINE
+//    span) queue their commands directly.
+//  * @redis/client 1.x (`redis` 4.x): `commandsExecutor(command, args)` (typed methods) and
+//    `sendCommand(args, options)`; `multiExecutor(commands, selectedDB, chainId)` (MULTI when a
+//    chain id is given, PIPELINE otherwise).
+// `duplicate()`, pool/isolation clients and the node clients of `createCluster` are instances of
+// the same class. Subscriptions do not go through these methods and make no span.
+
+const c = require('./common')
+const r = require('./redis-common')
+
+function peerTags (client) {
+  const tags = {}
+  try {
+    const o = client.options || {}
+    const s = o.socket || {}
+    if (s.path) tags['net.peer.name'] = String(s.path)
+    else if (s.host || o.url) {
+      let host = s.host
+      let port = s.port
+      if (!host && o.url) {
+        try {
+          const u = new URL(o.url)
+          host = u.hostname
+          port = u.port || 6379
+        } catch (_) {}
+      }
+      if (host) tags['net.peer.name'] = String(host)
+      if (port) tags['net.peer.port'] = String(port)
+    } else {
+      tags['net.peer.name'] = 'localhost'
+      tags['net.peer.port'] = String(s.port || 6379)
+    }
+  } catch (_) {}
+  return tags
+}
+
+function dbTags (client) {
+  const tags = Object.assign({ 'db.system': 'redis' }, peerTags(client))
+  try {
+    const db = client.options && client.options.database
+    tags['db.redis.database_index'] = String(db || 0)
+  } catch (_) {}
+  return tags
+}
+
+/** Start the span of one command given its Redis arguments (name first); returns a finisher. */
+function startCommand (client, redisArgs) {
+  if (!Array.isArray(redisArgs) || redisArgs.length === 0) return null
+  const name = r.text(redisArgs[0]).toUpperCase()
+  const args = redisArgs.slice(1)
+  if (r.STREAM_COMMANDS.has(name) && c.msgTracer()) {
+    const call = r.streamCall(name, args, peerTags(client))
+    if (!call || !call.span) return { extra: [], done () {} }
+    return { extra: call.extra, done: (v, err) => call.done(v, err) }
+  }
+  const t = c.dbTracer()
+  if (!t) return null
+  const tags = dbTags(client)
+  tags['db.operation'] = name
+  const st = r.statement(name, args, t.db.statement)
+  if (st !== undefined) tags['db.statement'] = st
+  const span = c.clientSpan(t, name, tags)
+  if (!span) return null
+  return { extra: [], done: (v, err) => c.end(span, err, err ? r.errorCode(err) : undefined) }
+}
+
+function finishWith (p, done) {
+  if (!c.isThenable(p)) {
+    done(p)
+    return p
+  }
+  return p.then((v) => {
+    done(v)
+    return v
+  }, (err) => {
+    done(undefined, err)
+    throw err
+  })
+}
+
+function wrapSendCommand (orig) {
+  return function sendCommand (args, options) {
+    if (!c.tracer() || c.nested() || !Array.isArray(args)) return orig.apply(this, arguments)
+    let call = null
+    try {
+      call = startCommand(this, args)
+    } catch (_) {
+      call = null
+    }
+    if (!call) return orig.apply(this, arguments)
+    const a = Array.prototype.slice.call(arguments)
+    if (call.extra.length) a[0] = args.concat(call.extra)
+    let p
+    try {
+      p = c.outer(orig, this, a)
+    } catch (err) {
+      call.done(undefined, err)
+      throw err
+    }
+    return finishWith(p, call.done)
+  }
+}
+
+/**
+ * @redis/client 1.x typed commands: commandsExecutor(command, args). The executor sends through
+ * the client's private send, so an XADD whose entry gets the trace fields (ITG-210,
+ * `redisStreamFields`) is sent here through the public `sendCommand` with the extended arguments
+ * and its reply transformed as the executor would (`commander.transformCommandReply`).
+ */
+function wrapCommandsExecutor (orig, transform, transformReply) {
+  return function commandsExecutor (command, args) {
+    if (!c.tracer() || c.nested()) return orig.apply(this, arguments)
+    let call = null
+    let t = null
+    try {
+      t = transform ? transform(command, args) : { args: command.transformArguments.apply(command, args) }
+      call = startCommand(this, Array.from(t.args))
+    } catch (_) {
+      call = null
+    }
+    if (!call) return c.outer(orig, this, arguments)
+    if (call.extra.length) {
+      if (transformReply && typeof this.sendCommand === 'function') {
+        let p
+        try {
+          const a = Array.from(t.args).concat(call.extra)
+          if (t.args.preserve !== undefined) a.preserve = t.args.preserve
+          p = c.outer(this.sendCommand, this, [a, t.options])
+        } catch (err) {
+          call.done(undefined, err)
+          throw err
+        }
+        return finishWith(p, call.done).then((reply) => transformReply(command, reply, t.args.preserve))
+      }
+      call.extra.length = 0 // no reply transform available: the span without the fields
+    }
+    let p
+    try {
+      p = c.outer(orig, this, arguments)
+    } catch (err) {
+      call.done(undefined, err)
+      throw err
+    }
+    return finishWith(p, call.done)
+  }
+}
+
+function batchSpan (client, commands, multi) {
+  const t = c.dbTracer()
+  if (!t || !Array.isArray(commands) || commands.length === 0) return null
+  const cmds = []
+  for (const cmd of commands) {
+    const a = Array.isArray(cmd) ? cmd : cmd && cmd.args
+    if (!Array.isArray(a) || a.length === 0) continue
+    const name = r.text(a[0]).toUpperCase()
+    if (multi && (name === 'MULTI' || name === 'EXEC')) continue // 1.x queues them with the commands
+    cmds.push([name, a.slice(1)])
+  }
+  const name = multi ? 'MULTI' : 'PIPELINE'
+  const tags = dbTags(client)
+  tags['db.operation'] = name
+  const st = r.pipelineStatement(cmds, t.db.statement)
+  if (st !== undefined) tags['db.statement'] = st
+  tags['db.batch_size'] = String(cmds.length)
+  return c.clientSpan(t, name, tags)
+}
+
+function wrapBatch (multiFromArgs) {
+  return (orig) => function (commands) {
+    if (!c.tracer() || c.nested()) return orig.apply(this, arguments)
+    let span = null
+    try {
+      span = batchSpan(this, commands, multiFromArgs(arguments))
+    } catch (_) {
+      span = null
+    }
+    if (!span) return orig.apply(this, arguments)
+    let p
+    try {
+      p = c.outer(orig, this, arguments)
+    } catch (err) {
+      c.end(span, err)
+      throw err
+    }
+    return finishWith(p, (v, err) => c.end(span, err, err ? r.errorCode(err) : undefined))
+  }
+}
+
+/** dist/lib/client/index.js: the RedisClient class (default export). */
+function patchClient (exports, info) {
+  const Client = exports && (exports.default || exports.RedisClient || exports)
+  const proto = Client && Client.prototype
+  if (!proto || typeof proto.sendCommand !== 'function') {
+    c.disabled('@redis/client', 'RedisClient.prototype.sendCommand not found')
+    return
+  }
+  c.wrap(proto, 'sendCommand', wrapSendCommand)
+  if (typeof proto._executeMulti === 'function') c.wrap(proto, '_executeMulti', wrapBatch(() => true))
+  if (typeof proto._executePipeline === 'function') c.wrap(proto, '_executePipeline', wrapBatch(() => false))
+  if (typeof proto.multiExecutor === 'function') {
+    // 1.x: a chain id (third argument) marks a transaction
+    c.wrap(proto, 'multiExecutor', wrapBatch((args) => args.length >= 3 && args[2] !== undefined))
+  }
+  if (typeof proto.commandsExecutor === 'function') {
+    let transform = null
+    let transformReply = null
+    try {
+      const commander = require(require('path').join(info.dir, 'dist/lib/commander.js'))
+      if (typeof commander.transformCommandArguments === 'function') transform = commander.transformCommandArguments
+      if (typeof commander.transformCommandReply === 'function') transformReply = commander.transformCommandReply
+    } catch (_) {}
+    c.wrap(proto, 'commandsExecutor', (orig) => wrapCommandsExecutor(orig, transform, transformReply))
+    // 1.x binds the typed command methods to the executor it had when the module was evaluated
+    // (attachCommands); attaching them again with the wrapped executor routes them through it
+    try {
+      const path = require('path')
+      const commander = require(path.join(info.dir, 'dist/lib/commander.js'))
+      const commands = require(path.join(info.dir, 'dist/lib/client/commands.js'))
+      if (typeof commander.attachCommands === 'function' && commands && commands.default) {
+        commander.attachCommands({ BaseClass: Client, commands: commands.default, executor: proto.commandsExecutor })
+      }
+    } catch (err) {
+      c.disabled('@redis/client', 'typed commands not re-attached: ' + (err && err.message))
+    }
+  }
+}
+
+module.exports = { patchClient }

package/lib/itg/pg.js

@@ -0,0 +1,253 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// node-postgres (82 §5.3, ITG-110–113): `Client.prototype.query` in every form (text, text +
+// values, config object, callback or promise, submittables such as pg-cursor / pg-query-stream)
+// is one CLIENT span; `Pool.prototype.connect` binds its callback to the caller's context (so the
+// query that `Pool.query` issues after a checkout belongs to the right request) and, with
+// `db.poolSpans`, creates a `pool.acquire` span when the checkout has to wait. The native client
+// (`pg.native`) is wrapped the same way.
+
+const c = require('./common')
+const sql = require('./sql')
+const dbc = require('./dbcomment')
+
+const TAGS = Symbol('pmx-pg-tags')
+// a submittable (Query, Cursor, QueryStream) pmx tagged in place: { target, prefix }
+const TAGGED = Symbol('pmx-pg-tagged')
+
+function connTags (client) {
+  let tags = client[TAGS]
+  if (tags) return tags
+  tags = { 'db.system': 'postgresql' }
+  const p = client.connectionParameters || client
+  const db = client.database || p.database
+  const user = client.user || p.user
+  const host = client.host || p.host
+  const port = client.port || p.port
+  if (db) tags['db.name'] = String(db)
+  if (user) tags['db.user'] = String(user)
+  if (typeof host === 'string' && host.startsWith('/')) {
+    tags['net.peer.name'] = host.replace(/\/$/, '') + '/.s.PGSQL.' + (port || 5432)
+  } else {
+    if (host) tags['net.peer.name'] = String(host)
+    if (port) tags['net.peer.port'] = String(port)
+  }
+  try {
+    Object.defineProperty(client, TAGS, { value: tags, configurable: true })
+  } catch (_) {}
+  return tags
+}
+
+function makeSpan (t, client, text, name) {
+  const base = connTags(client)
+  const op = sql.operation(text)
+  const tags = Object.assign({}, base)
+  if (op) tags['db.operation'] = op
+  const st = sql.statementTag(text, t.db.statement, false)
+  if (st !== undefined) tags['db.statement'] = st
+  if (name) tags['db.statement.name'] = String(name)
+  const spanName = op ? (base['db.name'] ? op + ' ' + base['db.name'] : op) : (base['db.name'] || 'postgresql')
+  return c.clientSpan(t, spanName, tags)
+}
+
+const rows = (span) => (res) => {
+  if (res && typeof res.rowCount === 'number') span.setAttribute('db.rows', String(res.rowCount))
+}
+
+const codeOf = (err) => (err && typeof err.code === 'string' ? err.code : undefined)
+
+/** Submittables (ITG-112): one span until ReadyForQuery or an error; db.rows = rows read. */
+function traceSubmittable (span, q) {
+  let n = 0
+  const done = (err) => {
+    if (span.ended) return
+    span.setAttribute('db.rows', String(n))
+    c.end(span, err, codeOf(err))
+  }
+  const hook = (name, after) => {
+    const orig = q[name]
+    if (typeof orig !== 'function') return
+    Object.defineProperty(q, name, {
+      configurable: true,
+      writable: true,
+      enumerable: Object.prototype.propertyIsEnumerable.call(q, name),
+      value: function () {
+        try {
+          after.apply(null, arguments)
+        } catch (_) {}
+        return orig.apply(this, arguments)
+      }
+    })
+  }
+  hook('handleDataRow', () => { n++ })
+  hook('handleError', (err) => done(err || new Error('query failed')))
+  hook('handleReadyForQuery', () => done())
+}
+
+function wrapQuery (orig) {
+  return function query (config, values, callback) {
+    const t = c.dbTracer()
+    if (!t || config === null || config === undefined || c.nested()) return orig.apply(this, arguments)
+    let span = null
+    let text
+    try {
+      if (typeof config === 'object') untag(config)
+      text = typeof config === 'string' ? config : config.text
+      if (typeof text !== 'string' && typeof config.submit === 'function') text = config.text || (config.cursor && config.cursor.text)
+      span = makeSpan(t, this, typeof text === 'string' ? text : '', typeof config === 'object' ? config.name : undefined)
+    } catch (_) {
+      span = null
+    }
+    if (!span) return orig.apply(this, arguments)
+    const args = Array.prototype.slice.call(arguments)
+    try {
+      comment(t, span, config, text, args)
+    } catch (_) {}
+    try {
+      if (typeof config.submit === 'function') {
+        traceSubmittable(span, config)
+        return orig.apply(this, args)
+      }
+      // callback forms: (text, cb), (text, values, cb), (config, cb), config.callback
+      let cbIndex = -1
+      if (typeof values === 'function') cbIndex = 1
+      else if (typeof callback === 'function') cbIndex = 2
+      if (cbIndex !== -1) {
+        const cb = c.bind(args[cbIndex])
+        args[cbIndex] = function (err, res) {
+          if (!err) rows(span)(res)
+          c.end(span, err || undefined, codeOf(err))
+          return cb.apply(this, arguments)
+        }
+        return orig.apply(this, args)
+      }
+      if (typeof config === 'object' && typeof config.callback === 'function') {
+        const cb = c.bind(config.callback)
+        args[0] = Object.assign(Object.create(Object.getPrototypeOf(args[0])), args[0], {
+          callback (err, res) {
+            if (!err) rows(span)(res)
+            c.end(span, err || undefined, codeOf(err))
+            return cb.apply(this, arguments)
+          }
+        })
+        return orig.apply(this, args)
+      }
+    } catch (err) {
+      c.end(span)
+      return orig.apply(this, arguments)
+    }
+    let result
+    try {
+      result = orig.apply(this, args)
+    } catch (err) {
+      c.end(span, err, codeOf(err))
+      throw err
+    }
+    if (c.isThenable(result)) return c.settle(result, span, rows(span), codeOf)
+    c.end(span)
+    return result
+  }
+}
+
+/**
+ * 96 SVM-501/502: prepend the trace comment to the statement (args[0] replaced by a copy; a
+ * submittable's own text is set in place). Named statements (`name`) are prepared and cached by
+ * name: skipped with `on`; with `force` the copy is sent unnamed (parsed every time).
+ */
+function comment (t, span, config, text, args) {
+  const named = typeof config === 'object' && config.name !== undefined && config.name !== null && config.name !== ''
+  if (!dbc.wants(t, span, text, named)) return
+  const prefix = dbc.sqlPrefix(t, span)
+  if (typeof config === 'string') {
+    args[0] = prefix + config
+  } else if (typeof config.submit === 'function') {
+    if (named) return // the app's object would have to be renamed
+    // tagged in place (the app holds the object); untag() removes it before a re-execution
+    const target = config.cursor && typeof config.cursor.text === 'string' && config.text === undefined ? config.cursor : config
+    if (typeof target.text !== 'string') return
+    target.text = prefix + target.text
+    try {
+      Object.defineProperty(config, TAGGED, { value: { target, prefix }, configurable: true, writable: true })
+    } catch (_) {}
+  } else if (typeof config.text === 'string') {
+    const copy = Object.assign(Object.create(Object.getPrototypeOf(config)), config, { text: prefix + config.text })
+    if (named) copy.name = undefined
+    args[0] = copy
+  }
+}
+
+/** A submittable reused by the app: remove the comment pmx added at its previous execution. */
+function untag (config) {
+  const tag = config[TAGGED]
+  if (!tag) return
+  config[TAGGED] = undefined
+  const { target, prefix } = tag
+  if (typeof target.text === 'string' && target.text.startsWith(prefix)) target.text = target.text.slice(prefix.length)
+}
+
+/** 96 SVM-505: application_name = the pmx app name when the app set none (or PGAPPNAME). */
+function wrapClientConnect (orig) {
+  return function connect () {
+    try {
+      const p = this.connectionParameters
+      const t = p && c.dbTracer()
+      if (t && !p.application_name && !p.fallback_application_name) {
+        const name = dbc.connectionAppName(t)
+        if (name) p.fallback_application_name = name
+      }
+    } catch (_) {}
+    return orig.apply(this, arguments)
+  }
+}
+
+function wrapConnect (orig) {
+  return function connect (cb) {
+    const t = c.tracer()
+    if (!t) return orig.apply(this, arguments)
+    let span = null
+    try {
+      const max = this.options && this.options.max
+      if (t.db && t.db.poolSpans && c.currentSpan() &&
+          this.idleCount === 0 && typeof max === 'number' && this.totalCount >= max) {
+        span = c.clientSpan(t, 'pool.acquire', {
+          'db.system': 'postgresql',
+          'db.pool.size': String(this.totalCount),
+          'db.pool.max_size': String(max),
+          'db.pool.waiting': String(this.waitingCount)
+        }, 'INTERNAL')
+      }
+    } catch (_) {
+      span = null
+    }
+    if (typeof cb === 'function') {
+      const bound = c.bind(cb)
+      return orig.call(this, function (err) {
+        c.end(span, err || undefined)
+        return bound.apply(this, arguments)
+      })
+    }
+    const p = orig.apply(this, arguments)
+    if (span && c.isThenable(p)) return c.settle(p, span)
+    return p
+  }
+}
+
+function patchClient (Client) {
+  if (!Client || !Client.prototype || typeof Client.prototype.query !== 'function') {
+    c.disabled('pg', 'Client.prototype.query not found')
+    return
+  }
+  c.wrap(Client.prototype, 'query', wrapQuery)
+  if (typeof Client.prototype.connect === 'function') c.wrap(Client.prototype, 'connect', wrapClientConnect)
+}
+
+function patchPool (Pool) {
+  if (!Pool || !Pool.prototype || typeof Pool.prototype.connect !== 'function') {
+    c.disabled('pg-pool', 'Pool.prototype.connect not found')
+    return
+  }
+  c.wrap(Pool.prototype, 'connect', wrapConnect)
+}
+
+module.exports = { patchClient, patchPool, connTags }