@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/itg/pgqueue.js

@@ -0,0 +1,305 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// PostgreSQL-backed job queues (82 §11): pg-boss (ITG-222) and graphile-worker (ITG-223), with the
+// opt-in payload carrier of ITG-220 (`messaging.payloadCarrier`): the producer adds
+// `__pmx_trace__` = { traceparent, tracestate?, baggage? } to a copy of a job payload that is a
+// plain object (never to arrays or scalars) and lacks the key; the consumer wrapper removes the key
+// before the handler/task sees the payload, whatever the setting. Without the option producer and
+// consumer spans are still created and share `messaging.message.id` (the job id). The SQL these
+// libraries run inside a PRODUCER span is its children (the span is current during the call).
+
+const c = require('./common')
+
+const KEY = c.TRACE_KEY
+
+function isPlain (v) {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false
+  const p = Object.getPrototypeOf(v)
+  return p === Object.prototype || p === null
+}
+
+/** A payload copy carrying the span's context (ITG-220), or the payload unchanged. */
+function carry (payload, span) {
+  const t = c.msgTracer()
+  if (!span || !t || !t.messaging.payloadCarrier || !isPlain(payload) || Object.prototype.hasOwnProperty.call(payload, KEY)) return payload
+  return Object.assign({}, payload, { [KEY]: c.traceCarrier(span) })
+}
+
+/** The context in a payload's carrier, removing the key in place (the object is the library's). */
+function take (payload) {
+  if (!isPlain(payload) || !Object.prototype.hasOwnProperty.call(payload, KEY)) return null
+  const carrier = payload[KEY]
+  try {
+    delete payload[KEY]
+  } catch (_) {}
+  return carrier && typeof carrier === 'object' ? c.extract(carrier) : null
+}
+
+/** Run fn with the PRODUCER span current; `args(span)` builds the arguments (carrier). */
+function produce (system, destination, tags, fn, thisArg, args, idOf, origArgs) {
+  const span = c.producer(system, destination, tags)
+  if (!span) return { span: null, result: fn.apply(thisArg, origArgs) }
+  const a = args(span)
+  let r
+  try {
+    const store = require('../tracing/context').current()
+    r = require('../tracing/context').run({ span, bag: span.bag, server: store && store.server, itg: system }, fn, thisArg, a)
+  } catch (err) {
+    c.end(span, err)
+    throw err
+  }
+  if (!c.isThenable(r)) {
+    c.end(span)
+    return { span, result: r }
+  }
+  return { span, result: c.settle(r, span, (v) => {
+    const id = idOf ? idOf(v) : undefined
+    if (id !== undefined && id !== null) span.setAttribute('messaging.message.id', String(id))
+  }) }
+}
+
+function nestedIn (system) {
+  const s = require('../tracing/context').current()
+  return Boolean(s && s.itg === system)
+}
+
+// -- pg-boss ----------------------------------------------------------------------------------
+
+const PGBOSS = 'pg-boss'
+
+/** send(name, data, options) | send({ name, data, options }) → [name, data, rebuild(data')]. */
+function sendArgs (args) {
+  if (typeof args[0] === 'string') {
+    return { name: args[0], data: args[1], rebuild: (d) => { const a = args.slice(); a[1] = d; return a } }
+  }
+  if (args[0] && typeof args[0] === 'object') {
+    const req = args[0]
+    return { name: req.name, data: req.data, rebuild: (d) => { const a = args.slice(); a[0] = Object.assign({}, req, { data: d }); return a } }
+  }
+  return null
+}
+
+function wrapBossSend (orig) {
+  return function send () {
+    const args = Array.prototype.slice.call(arguments)
+    if (!c.msgTracer() || nestedIn(PGBOSS)) return orig.apply(this, args)
+    const s = sendArgs(args)
+    if (!s || internalQueue(s.name)) return orig.apply(this, args)
+    return produce(PGBOSS, s.name, {}, orig, this, (span) => s.rebuild(carry(s.data, span)), (id) => (typeof id === 'string' ? id : undefined), args).result
+  }
+}
+
+function wrapBossPublish (orig) {
+  return function publish (event, data) {
+    if (!c.msgTracer() || nestedIn(PGBOSS)) return orig.apply(this, arguments)
+    const args = Array.prototype.slice.call(arguments)
+    return produce(PGBOSS, event, {}, orig, this, (span) => { const a = args.slice(); a[1] = carry(data, span); return a }, undefined, args).result
+  }
+}
+
+function wrapBossInsert (orig) {
+  return function insert () {
+    const args = Array.prototype.slice.call(arguments)
+    if (!c.msgTracer() || nestedIn(PGBOSS)) return orig.apply(this, args)
+    // 9.x/10.x: insert(jobs); 11+: insert(name, jobs, options)
+    const named = typeof args[0] === 'string'
+    const jobs = named ? args[1] : args[0]
+    if (!Array.isArray(jobs)) return orig.apply(this, args)
+    const names = new Set(named ? [args[0]] : jobs.map((j) => j && j.name))
+    const tags = {}
+    if (jobs.length > 1) tags['messaging.batch.message_count'] = String(jobs.length)
+    return produce(PGBOSS, names.size === 1 ? Array.from(names)[0] : undefined, tags, orig, this, (span) => {
+      const copy = jobs.map((j) => (j && typeof j === 'object' ? Object.assign({}, j, { data: carry(j.data, span) }) : j))
+      const a = args.slice()
+      a[named ? 1 : 0] = copy
+      return a
+    }, undefined, args).result
+  }
+}
+
+function jobTags (job) {
+  const tags = {}
+  if (job && job.id !== undefined) tags['messaging.message.id'] = String(job.id)
+  const rc = job && (job.retryCount !== undefined ? job.retryCount : job.retrycount)
+  if (typeof rc === 'number') tags['messaging.pmx.attempt'] = String(rc + 1)
+  return tags
+}
+
+function wrapBossHandler (queue, handler) {
+  const w = function (arg) {
+    if (!c.msgTracer()) {
+      if (Array.isArray(arg)) arg.forEach((j) => take(j && j.data))
+      else take(arg && arg.data)
+      return handler.apply(this, arguments)
+    }
+    let span
+    if (Array.isArray(arg) && arg.length !== 1) {
+      const ctxs = arg.map((j) => take(j && j.data))
+      const tags = {}
+      if (arg.length > 1) tags['messaging.batch.message_count'] = String(arg.length)
+      span = c.batchConsumer(PGBOSS, queue, ctxs, tags, 'process')
+    } else {
+      const job = Array.isArray(arg) ? arg[0] : arg
+      span = c.consumer(PGBOSS, queue, take(job && job.data), jobTags(job))
+    }
+    return c.runConsumer(span, handler, this, arguments)
+  }
+  return c.copyMeta(w, handler)
+}
+
+const internalQueue = (name) => typeof name === 'string' && name.startsWith('__pgboss__')
+
+function wrapBossWork (orig) {
+  return function work (name) {
+    const args = Array.prototype.slice.call(arguments)
+    const i = args.length - 1
+    if (!c.tracer() || i < 1 || typeof args[i] !== 'function' || internalQueue(name)) return orig.apply(this, args)
+    args[i] = wrapBossHandler(typeof name === 'string' ? name : (name && name.name), args[i])
+    // the worker's own polling (fetch) runs in this context: marked, it makes no receive spans
+    const ctx = require('../tracing/context')
+    const store = ctx.current()
+    return ctx.run({ span: store && store.span, bag: store ? store.bag : [], server: store && store.server, itg: PGBOSS }, orig, this, args)
+  }
+}
+
+function wrapBossFetch (orig) {
+  return function fetch (name) {
+    if (!c.msgTracer() || nestedIn(PGBOSS) || internalQueue(name)) return orig.apply(this, arguments)
+    const span = c.batchConsumer(PGBOSS, typeof name === 'string' ? name : undefined, null, {}, 'receive')
+    let r
+    try {
+      r = orig.apply(this, arguments)
+    } catch (err) {
+      c.end(span, err)
+      throw err
+    }
+    if (!c.isThenable(r)) return r
+    return r.then((res) => {
+      try {
+        const jobs = Array.isArray(res) ? res : (res ? [res] : [])
+        for (const j of jobs) c.addLink(span, take(j && j.data))
+        if (jobs.length >= 2) span.setAttribute('messaging.batch.message_count', String(jobs.length))
+        if (jobs.length > 0) c.end(span)
+      } catch (_) {}
+      return res
+    }, (err) => {
+      c.end(span, err)
+      throw err
+    })
+  }
+}
+
+/** pg-boss manager (9.x/10.x `src/manager.js` CommonJS; 11+ `dist/manager.js` ES module). */
+function patchBoss (exports, info) {
+  const Manager = info && info.esm ? exports.default : (exports && (exports.default || exports))
+  const proto = Manager && Manager.prototype
+  if (!proto || typeof proto.send !== 'function' || typeof proto.work !== 'function') {
+    c.disabled('pg-boss', 'Manager.send/work not found')
+    return
+  }
+  for (const m of ['send', 'sendAfter', 'sendThrottled', 'sendDebounced']) {
+    if (typeof proto[m] === 'function') c.wrap(proto, m, wrapBossSend)
+  }
+  if (typeof proto.publish === 'function') c.wrap(proto, 'publish', wrapBossPublish)
+  if (typeof proto.insert === 'function') c.wrap(proto, 'insert', wrapBossInsert)
+  c.wrap(proto, 'work', wrapBossWork)
+  if (typeof proto.fetch === 'function') c.wrap(proto, 'fetch', wrapBossFetch)
+}
+
+// -- graphile-worker --------------------------------------------------------------------------
+
+const GRAPHILE = 'graphile-worker'
+
+function wrapAddJob (orig) {
+  if (typeof orig !== 'function' || orig[c.WRAPPED]) return orig
+  const w = function addJob (identifier, payload, spec) {
+    if (!c.msgTracer()) return orig.apply(this, arguments)
+    const tags = {}
+    if (spec && spec.queueName) tags['messaging.graphile_worker.queue_name'] = String(spec.queueName)
+    const args = Array.prototype.slice.call(arguments)
+    return produce(GRAPHILE, identifier, tags, orig, this, (span) => { const a = args.slice(); a[1] = carry(payload, span); return a }, (job) => job && job.id, args).result
+  }
+  return c.copyMeta(w, orig)
+}
+
+function wrapTask (identifier, task) {
+  const w = function (payload, helpers) {
+    const job = helpers && helpers.job
+    if (!c.msgTracer()) {
+      take(payload)
+      return task.apply(this, arguments)
+    }
+    const ctx = take(payload)
+    const tags = {}
+    if (job && job.id !== undefined) tags['messaging.message.id'] = String(job.id)
+    if (job && typeof job.attempts === 'number') tags['messaging.pmx.attempt'] = String(job.attempts)
+    if (job && job.queue_name) tags['messaging.graphile_worker.queue_name'] = String(job.queue_name)
+    const span = c.consumer(GRAPHILE, identifier, ctx, tags)
+    return c.runConsumer(span, task, this, arguments)
+  }
+  return c.copyMeta(w, task)
+}
+
+const taskCache = new WeakMap()
+
+function tasksProxy (tasks) {
+  if (!tasks || typeof tasks !== 'object') return tasks
+  return new Proxy(tasks, {
+    get (target, key, receiver) {
+      const v = Reflect.get(target, key, receiver)
+      if (typeof v !== 'function' || typeof key !== 'string') return v
+      let w = taskCache.get(v)
+      if (!w) {
+        w = wrapTask(key, v)
+        taskCache.set(v, w)
+      }
+      return w
+    }
+  })
+}
+
+/** helpers.js: makeAddJob(compiledSharedOptions, withPgClient) returns addJob. */
+function patchHelpers (exports) {
+  const make = exports && exports.makeAddJob
+  if (typeof make !== 'function') {
+    c.disabled('graphile-worker', 'makeAddJob not found')
+    return
+  }
+  const w = c.copyMeta(function makeAddJob () {
+    return wrapAddJob(make.apply(this, arguments))
+  }, make)
+  return replace(exports, 'makeAddJob', w)
+}
+
+/** worker.js: makeNewWorker(workerShared, params) with params.tasks. */
+function patchWorker (exports) {
+  const make = exports && exports.makeNewWorker
+  if (typeof make !== 'function') {
+    c.disabled('graphile-worker', 'makeNewWorker not found')
+    return
+  }
+  const w = c.copyMeta(function makeNewWorker (shared, params) {
+    if (!params || typeof params !== 'object' || !params.tasks || !c.tracer()) return make.apply(this, arguments)
+    const args = Array.prototype.slice.call(arguments)
+    args[1] = Object.assign({}, params, { tasks: tasksProxy(params.tasks) })
+    return make.apply(this, args)
+  }, make)
+  return replace(exports, 'makeNewWorker', w)
+}
+
+function replace (exports, name, value) {
+  const d = Object.getOwnPropertyDescriptor(exports, name)
+  if (d && d.writable) {
+    exports[name] = value
+    return
+  }
+  if (d && d.configurable) {
+    Object.defineProperty(exports, name, { value, writable: true, enumerable: d.enumerable, configurable: true })
+    return
+  }
+  // a getter-only (non-configurable) binding: return a copy with the replaced export
+  return require('../integrations').replaceExport(exports, name, value)
+}
+
+module.exports = { patchBoss, patchHelpers, patchWorker, carry, take }

package/lib/itg/postgres.js

@@ -0,0 +1,252 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// postgres.js (82 §5.4, ITG-115–118). Every way a postgres.js query runs — awaiting it (`then`,
+// `catch`, `finally`), `execute()`, `forEach()`, `cursor()` iteration, `describe()`, `simple()`,
+// `values()`, `raw()`, `sql.unsafe`, `sql.file`, transactions and reserved connections — goes
+// through `Query.prototype.handle`, called once when execution starts. Wrapping that one method
+// (instead of the `sql` function) keeps every query object lazy and every property of `sql`
+// untouched: a query object that is never awaited never calls it and creates no span. The span
+// ends when the query's `resolve`/`reject` runs (also when postgres.js replaces them for cursor
+// iteration). The BEGIN/COMMIT/ROLLBACK/SAVEPOINT statements that `sql.begin` issues itself make no
+// span (ITG-117: the transaction has no span of its own); queries inside it do.
+
+const c = require('./common')
+const sql = require('./sql')
+const dbc = require('./dbcomment')
+
+const SPAN = Symbol('pmx-pgjs-span')
+const PREFIX = Symbol('pmx-pgjs-comment')
+const TX_OPS = new Set(['BEGIN', 'COMMIT', 'ROLLBACK', 'SAVEPOINT'])
+
+function optionTags (options) {
+  const tags = { 'db.system': 'postgresql' }
+  if (!options || typeof options !== 'object') return tags
+  if (options.database) tags['db.name'] = String(options.database)
+  if (options.user) tags['db.user'] = String(options.user)
+  const host = Array.isArray(options.host) ? options.host[0] : options.host
+  const port = Array.isArray(options.port) ? options.port[0] : options.port
+  if (options.path) {
+    tags['net.peer.name'] = String(options.path)
+  } else {
+    if (host) tags['net.peer.name'] = String(host)
+    if (port) tags['net.peer.port'] = String(port)
+  }
+  return tags
+}
+
+function templateText (q) {
+  const strings = q.strings
+  if (!Array.isArray(strings)) return ''
+  let s = String(strings[0] === undefined ? '' : strings[0])
+  for (let i = 1; i < strings.length; i++) s += '$' + i + strings[i]
+  return s
+}
+
+/** Keep `prop` of `q` wrapped by `make(current)` even when postgres.js assigns a new value. */
+function intercept (q, prop, make) {
+  let current = q[prop]
+  let wrapped = typeof current === 'function' ? make(current) : current
+  Object.defineProperty(q, prop, {
+    configurable: true,
+    enumerable: Object.prototype.propertyIsEnumerable.call(q, prop),
+    get () {
+      return wrapped
+    },
+    set (v) {
+      current = v
+      wrapped = typeof v === 'function' ? make(v) : v
+    }
+  })
+}
+
+function instrument (q, span, t) {
+  let delivered = 0
+  let streaming = false
+  const finish = (err, result) => {
+    if (span.ended) return
+    try {
+      let st = q.statement && typeof q.statement.string === 'string' ? q.statement.string : null
+      // the trace comment is never part of db.statement (96 SVM-504)
+      const prefix = q[PREFIX]
+      if (st !== null && prefix && st.startsWith(prefix)) st = st.slice(prefix.length)
+      if (st !== null) {
+        const tag = sql.statementTag(st, t.db.statement, false)
+        if (tag !== undefined) span.setAttribute('db.statement', tag)
+        if (!span.attributes['db.operation']) {
+          // sql.file(): the text was read after execution started
+          const op = sql.operation(st)
+          if (op) {
+            span.setAttribute('db.operation', op)
+            const db = span.attributes['db.name']
+            span.updateName(db ? op + ' ' + db : op)
+          }
+        }
+      }
+      if (!err) {
+        if (streaming) span.setAttribute('db.rows', String(delivered))
+        else if (result && typeof result.count === 'number') span.setAttribute('db.rows', String(result.count))
+      }
+    } catch (_) {}
+    c.end(span, err, err && typeof err.code === 'string' ? err.code : undefined)
+  }
+  const onResolve = (fn) => function (x) {
+    finish(undefined, x)
+    return fn.apply(this, arguments)
+  }
+  const onReject = (fn) => function (err) {
+    finish(err || new Error('query failed'))
+    return fn.apply(this, arguments)
+  }
+  const count = (fn) => function (v) {
+    delivered += Array.isArray(v) ? v.length : 1
+    return fn.apply(this, arguments)
+  }
+  if (q.cursorRows || typeof q.cursorFn === 'function') {
+    // cursor iteration assigns new resolve/reject/cursorFn at every next(): keep them wrapped
+    streaming = true
+    intercept(q, 'resolve', onResolve)
+    intercept(q, 'reject', onReject)
+    intercept(q, 'cursorFn', count)
+    return
+  }
+  // every other path: the functions present now are the ones postgres.js calls (cheaper)
+  if (typeof q.resolve === 'function') q.resolve = onResolve(q.resolve)
+  if (typeof q.reject === 'function') q.reject = onReject(q.reject)
+  if (typeof q.forEachFn === 'function') {
+    streaming = true
+    q.forEachFn = count(q.forEachFn)
+  }
+}
+
+/**
+ * 96 SVM-501/502: prepend the trace comment to the query's first string. postgres.js prepares
+ * (and caches by text) every non-simple query unless `prepare: false` (instance or query option):
+ * those are skipped with `on`; with `force` the query is sent unprepared.
+ */
+function comment (q, t, span, text) {
+  try {
+    const strings = q.strings
+    if (!Array.isArray(strings) || typeof strings[0] !== 'string') return
+    const qo = q.options && typeof q.options === 'object' ? q.options : {}
+    const io = optionsOf(q) || {}
+    const prepared = !qo.simple && io.prepare !== false && !('prepare' in qo && !qo.prepare)
+    if (!dbc.wants(t, span, text, prepared)) return
+    const prefix = dbc.sqlPrefix(t, span)
+    const next = Array.prototype.slice.call(strings)
+    next[0] = prefix + next[0]
+    q.strings = next
+    q[PREFIX] = prefix
+    if (prepared) q.options = Object.assign({}, qo, { prepare: false })
+  } catch (_) {}
+}
+
+function wrapHandle (orig) {
+  return function handle () {
+    if (this.executed || this[SPAN] !== undefined) return orig.apply(this, arguments)
+    const t = c.dbTracer()
+    if (t && !c.nested()) {
+      try {
+        const text = templateText(this)
+        const op = sql.operation(text)
+        const isTx = TX_OPS.has(op) || (op === 'PREPARE' && /^\s*prepare\s+transaction\b/i.test(text))
+        if (!isTx) {
+          const base = optionTags(optionsOf(this))
+          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
+          const name = op ? (base['db.name'] ? op + ' ' + base['db.name'] : op) : (base['db.name'] || 'postgresql')
+          const span = c.clientSpan(t, name, tags)
+          this[SPAN] = span
+          if (span) {
+            instrument(this, span, t)
+            comment(this, t, span, text)
+          }
+        }
+      } catch (_) {}
+    }
+    return orig.apply(this, arguments)
+  }
+}
+
+// The instance options (database, user, host, port) are not reachable from a query object, only
+// its `handler` is. The wrapped factory learns the handler of each instance by creating (never
+// executing) one query object, and maps it to the instance's options; queries of transactions and
+// reserved connections have their own handlers and use the options of the instance created last.
+const OPTIONS = new WeakMap()
+let lastOptions = null
+
+function remember (sqlFn) {
+  if (typeof sqlFn !== 'function' || !sqlFn.options) return
+  lastOptions = sqlFn.options
+  const probe = sqlFn`select 1`
+  if (probe && typeof probe.handler === 'function') OPTIONS.set(probe.handler, sqlFn.options)
+}
+
+function optionsOf (q) {
+  return (q.handler && OPTIONS.get(q.handler)) || lastOptions
+}
+
+/**
+ * 96 SVM-505: `connection.application_name` = the pmx app name unless the app set one (options,
+ * URL query or PGAPPNAME); postgres.js's own default ('postgres.js') counts as not set.
+ */
+function withAppName (argsIn) {
+  const t = c.dbTracer()
+  const name = t && dbc.connectionAppName(t)
+  if (!name || process.env.PGAPPNAME) return argsIn
+  const args = Array.prototype.slice.call(argsIn)
+  const url = typeof args[0] === 'string' ? args[0] : ''
+  if (/[?&]application_name=/i.test(url)) return argsIn
+  const i = url || args[0] === undefined ? 1 : 0
+  const opts = args[i]
+  if (opts !== undefined && (opts === null || typeof opts !== 'object')) return argsIn
+  const conn = opts && opts.connection
+  if (conn && typeof conn === 'object' && conn.application_name) return argsIn
+  args[i] = Object.assign({}, opts || {}, { connection: Object.assign({}, conn || {}, { application_name: name }) })
+  return args
+}
+
+function wrapFactory (Postgres) {
+  if (typeof Postgres !== 'function' || Postgres[c.WRAPPED]) return Postgres
+  const wrapped = function postgres () {
+    let args = arguments
+    try {
+      args = withAppName(arguments)
+    } catch (_) {}
+    const sqlFn = Postgres.apply(this, args)
+    try {
+      remember(sqlFn)
+    } catch (_) {}
+    return sqlFn
+  }
+  return c.copyMeta(wrapped, Postgres)
+}
+
+/** Patch query.js (CommonJS `cjs/src/query.js`, ESM `src/query.js`): Query.prototype.handle. */
+function patchQuery (exports) {
+  const Query = exports && exports.Query
+  if (!Query || !Query.prototype || typeof Query.prototype.handle !== 'function') {
+    c.disabled('postgres', 'Query.prototype.handle not found')
+    return
+  }
+  c.wrap(Query.prototype, 'handle', wrapHandle)
+}
+
+/** Wrap the default export (the factory) so instance options can be found for tags. */
+function patchIndex (exports, info) {
+  const fn = info && info.esm ? exports.default : exports
+  if (typeof fn !== 'function') {
+    c.disabled('postgres', 'default export is not a function')
+    return
+  }
+  const w = wrapFactory(fn)
+  if (info && info.esm) {
+    exports.default = w
+    return
+  }
+  return w
+}
+
+module.exports = { patchQuery, patchIndex, optionTags, templateText }