@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/bun.js

@@ -0,0 +1,155 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Bun.serve (80 NIO-101, NIO-220, NIO-221, NIO-223): HTTP/HTTPS metrics, SERVER spans (route =
+// the `routes` key that matched) and handler exceptions for every Bun.serve server. Bun.serve is
+// a writable property, so the function is wrapped at activation; the app's options object is
+// copied, never changed.
+
+const inbound = require('./inbound')
+const context = require('./tracing/context')
+
+let wrapped = false
+
+function serverState (protocol, req, route) {
+  let url
+  try {
+    url = new URL(req.url)
+  } catch (_) {
+    url = { pathname: '/', search: '' }
+  }
+  const target = url.pathname + (url.search || '')
+  return {
+    protocol,
+    req: { url: target, method: req.method, headers: req.headers, path: url.pathname },
+    res: null,
+    span: null,
+    store: undefined,
+    route,
+    routeFn: null,
+    error: null,
+    info: null,
+    done: false,
+    bun: true
+  }
+}
+
+function wrapHandler (fn, protocol, route) {
+  const w = function (req) {
+    const c = inbound.consumers
+    if (!c.metrics && !c.tracing && !c.errors) return fn.apply(this, arguments)
+    const doneMetric = c.metrics && c.metrics.start ? c.metrics.start(protocol) : null
+    const st = serverState(protocol, req, route)
+    if (c.tracing) {
+      try {
+        const host = (req.headers && req.headers.get && req.headers.get('host')) || 'localhost'
+        const span = c.tracing.tracer.serverSpan({
+          method: req.method,
+          target: st.req.url,
+          scheme: protocol,
+          host,
+          userAgent: req.headers && req.headers.get ? req.headers.get('user-agent') : undefined,
+          headers: req.headers,
+          request: req
+        })
+        if (span) {
+          st.span = span
+          inbound.attach(span, st)
+          st.store = { span, bag: span.bag, server: span }
+        } else {
+          st.store = context.EMPTY_STORE
+        }
+      } catch (_) {}
+    }
+    const finish = (status) => {
+      if (st.done) return
+      st.done = true
+      if (doneMetric) {
+        try {
+          doneMetric()
+        } catch (_) {}
+      }
+      if (st.route === undefined && st.routeFn) {
+        try {
+          st.route = st.routeFn()
+        } catch (_) {}
+      }
+      if (c.errors && status >= 500 && st.error) {
+        try {
+          c.errors.report(st, status)
+        } catch (_) {}
+      }
+      if (st.span && c.tracing) {
+        try {
+          c.tracing.finishServerSpan(st.span, status, st.route, st.error)
+        } catch (_) {}
+      }
+    }
+    let r
+    try {
+      r = st.store ? context.run(st.store, fn, this, arguments) : fn.apply(this, arguments)
+    } catch (err) {
+      st.error = err
+      finish(500)
+      throw err
+    }
+    if (r && typeof r.then === 'function') {
+      return r.then((res) => {
+        finish(res && res.status)
+        return res
+      }, (err) => {
+        st.error = err
+        finish(500)
+        throw err
+      })
+    }
+    finish(r && r.status)
+    return r
+  }
+  try {
+    Object.defineProperty(w, 'length', { value: fn.length })
+    Object.defineProperty(w, 'name', { value: fn.name })
+  } catch (_) {}
+  return w
+}
+
+function wrapRoutes (routes, protocol) {
+  const out = {}
+  for (const key of Object.keys(routes)) {
+    const v = routes[key]
+    if (typeof v === 'function') {
+      out[key] = wrapHandler(v, protocol, key)
+    } else if (v && typeof v === 'object' && !(typeof Response === 'function' && v instanceof Response)) {
+      const per = {}
+      for (const m of Object.keys(v)) per[m] = typeof v[m] === 'function' ? wrapHandler(v[m], protocol, key) : v[m]
+      out[key] = per
+    } else {
+      out[key] = v
+    }
+  }
+  return out
+}
+
+function install () {
+  if (wrapped || typeof globalThis.Bun !== 'object' || !globalThis.Bun || typeof globalThis.Bun.serve !== 'function') return
+  wrapped = true
+  const Bun = globalThis.Bun
+  const orig = Bun.serve
+  const serve = function serve (options) {
+    if (!options || typeof options !== 'object') return orig.apply(this, arguments)
+    const protocol = options.tls ? 'https' : 'http'
+    const o = Object.assign({}, options)
+    if (typeof o.fetch === 'function') o.fetch = wrapHandler(o.fetch, protocol, undefined)
+    if (o.routes && typeof o.routes === 'object') o.routes = wrapRoutes(o.routes, protocol)
+    const args = Array.prototype.slice.call(arguments)
+    args[0] = o
+    return orig.apply(this, args)
+  }
+  try {
+    Bun.serve = serve
+  } catch (_) {
+    wrapped = false
+  }
+}
+
+module.exports = { install, wrapHandler }

package/lib/config.js

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Configuration defaulting and the configuration report (80 A.2, A.8.3).
+
+const { DEFAULT_CONFIG, VERSION } = require('./constants')
+const { autocast, isPlainObject } = require('./util')
+
+/** Shallow defaulting: keys given by the caller replace the default value wholesale. */
+function normalizeConfig (config) {
+  const base = JSON.parse(JSON.stringify(DEFAULT_CONFIG)) // apmOptions (undefined) is dropped
+  if (!isPlainObject(config)) return base
+  return Object.assign(base, config)
+}
+
+function apmInfo () {
+  return { type: 'node', version: VERSION, impl: 'pmx' }
+}
+
+function redact (moduleConf) {
+  for (const key of ['password', 'passwd']) {
+    if (moduleConf[key] !== undefined && moduleConf[key] !== null && moduleConf[key] !== '') {
+      moduleConf[key] = 'Password hidden'
+    }
+  }
+}
+
+/**
+ * Add apm / module_* keys and merge package.json `config` and the env var named after the
+ * module (A.8.3). Mutates and returns `conf`.
+ */
+function decorate (conf, pkg, moduleName) {
+  conf.module_conf = {}
+  conf.apm = apmInfo()
+  conf.module_name = moduleName
+  if (pkg && typeof pkg.version === 'string') conf.module_version = pkg.version
+  if (pkg && isPlainObject(pkg.config)) {
+    Object.assign(conf, pkg.config)
+    Object.assign(conf.module_conf, pkg.config)
+  }
+  const raw = moduleName !== undefined ? process.env[moduleName] : undefined
+  if (typeof raw === 'string') {
+    let parsed
+    try {
+      parsed = JSON.parse(raw)
+    } catch (_) {
+      parsed = undefined
+    }
+    if (isPlainObject(parsed)) {
+      const cast = autocast(parsed)
+      Object.assign(conf, cast)
+      const forModule = Object.assign({}, cast)
+      delete forModule.probes
+      Object.assign(conf.module_conf, forModule)
+    }
+  }
+  redact(conf.module_conf)
+  return conf
+}
+
+const DEFAULT_WIDGET = {
+  type: 'generic',
+  logo: 'https://app.keymetrics.io/img/logo/keymetrics-300.png',
+  theme: ['#111111', '#1B2228', '#807C7C', '#807C7C']
+}
+
+module.exports = { normalizeConfig, decorate, apmInfo, DEFAULT_WIDGET }

package/lib/constants.js

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+const VERSION = require('../package.json').version
+
+module.exports = {
+  VERSION,
+  GLOBAL_SYMBOL: Symbol.for('@pm2/io'),
+  METRIC_PUSH_INTERVAL: 990,
+  DEFAULT_CONFIG: Object.freeze({
+    catchExceptions: true,
+    profiling: true,
+    metrics: { v8: true, network: false, eventLoop: true, runtime: true, http: true, httpOutbound: true },
+    standalone: false,
+    apmOptions: undefined
+  })
+}

package/lib/debug.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Minimal DEBUG namespace support (80 NIO-012): `*` wildcards, comma/space separated
+// patterns, `-` prefix to exclude. Lines are `<namespace> <message>` on stderr.
+
+
+let cachedSource
+let include = []
+let exclude = []
+
+function toRegExp (pattern) {
+  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, '\\$&').replace(/\*/g, '.*?')
+  return new RegExp('^' + escaped + '$')
+}
+
+function parse () {
+  const src = process.env.DEBUG || ''
+  if (src === cachedSource) return
+  cachedSource = src
+  include = []
+  exclude = []
+  for (const part of src.split(/[\s,]+/)) {
+    if (!part) continue
+    if (part[0] === '-') exclude.push(toRegExp(part.slice(1)))
+    else include.push(toRegExp(part))
+  }
+}
+
+function enabled (ns) {
+  parse()
+  if (exclude.some((r) => r.test(ns))) return false
+  return include.some((r) => r.test(ns))
+}
+
+function createDebug (ns) {
+  const log = function (...args) {
+    if (!enabled(ns)) return
+    try {
+      process.stderr.write(ns + ' ' + require('util').format(...args) + '\n')
+    } catch (_) { /* never break the app */ }
+  }
+  log.namespace = ns
+  Object.defineProperty(log, 'enabled', { get: () => enabled(ns) })
+  return log
+}
+
+module.exports = createDebug

package/lib/esm-hooks.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+
+// Module customization hooks (80 NIO-085, NIO-210), registered by preload.mjs only when tracing is
+// enabled at spawn: `module.registerHooks` (in-thread, Node ≥ 22.15 / ≥ 23.5) or `module.register`
+// (off-thread, Node ≥ 18.19 / ≥ 20.6). For an ES-module file of a target library the `load` hook
+// returns a wrapper module instead:
+//
+//   import * as ns from '<url>?pmx-io-orig'
+//   export * from '<url>?pmx-io-orig'
+//   const r = globalThis[Symbol.for('@pmx/io:esm')]?.('<pkg>', '<file>', ns) ?? ns
+//   const x0 = r['Name']; export { x0 as Name }
+//
+// Explicit exports take precedence over `export *`, so only the patched names change; the
+// original module is evaluated once (under the `?pmx-io-orig` URL). Patching itself happens on
+// the main thread (modules.js / integrations.js).
+
+// [package, file in package, exported names to patch]
+export const TARGETS = [
+  ['hono', 'dist/hono.js', ['Hono']],
+  ['h3', 'dist/index.mjs', ['createApp']],
+  // database and broker integrations (82, lib/itg): classes are patched in place through the
+  // namespace; replaced exports are listed by name ('default' re-exports the default export)
+  ['postgres', 'src/index.js', ['default']],
+  ['postgres', 'src/query.js', []],
+  ['bullmq', 'dist/esm/classes/queue.js', []],
+  ['bullmq', 'dist/esm/classes/worker.js', ['Worker']],
+  ['pg-boss', 'dist/manager.js', ['default']],
+  ['graphile-worker', 'dist/helpers.js', ['makeAddJob']],
+  ['graphile-worker', 'dist/worker.js', ['makeNewWorker']]
+]
+
+const MARK = 'pmx-io-orig'
+
+function match (url) {
+  if (typeof url !== 'string' || !url.startsWith('file:') || url.includes(MARK)) return null
+  const i = url.lastIndexOf('/node_modules/')
+  if (i === -1) return null
+  const rest = decodeURI(url.slice(i + 14)).split('?')[0]
+  for (const t of TARGETS) {
+    if (rest === t[0] + '/' + t[1]) return t
+  }
+  return null
+}
+
+function wrapper (url, t, hasDefault) {
+  const orig = JSON.stringify(url + (url.includes('?') ? '&' : '?') + MARK)
+  const lines = [
+    `import * as ns from ${orig};`,
+    `export * from ${orig};`,
+    `const f = globalThis[Symbol.for('@pmx/io:esm')];`,
+    `const r = typeof f === 'function' ? f(${JSON.stringify(t[0])}, ${JSON.stringify(t[1])}, ns) : ns;`
+  ]
+  // `export *` never re-exports `default`: carry it explicitly when the original has one
+  if (hasDefault && !t[2].includes('default')) lines.push('export default ns.default;')
+  t[2].forEach((name, i) => {
+    lines.push(`const x${i} = r[${JSON.stringify(name)}]; export { x${i} as ${name} };`)
+  })
+  // keep the module evaluated (and patched) even when only re-exported names are used
+  if (t[2].length === 0) lines.push('void r;')
+  return lines.join('\n')
+}
+
+const DEFAULT_RE = /\bexport\s+default\b|\bas\s+default\b/
+
+function sourceText (r) {
+  const src = r && r.source
+  if (typeof src === 'string') return src
+  if (src && typeof src === 'object' && typeof src.byteLength === 'number') return Buffer.from(src.buffer || src, src.byteOffset || 0, src.byteLength).toString('utf8')
+  return ''
+}
+
+// In-thread hooks (module.registerHooks) make Node evaluate CommonJS files reached from `import`
+// without Module.prototype._compile, where modules.js patches them. For those files of instrumented
+// packages (asked through a main-thread predicate; off-thread hooks have none and need nothing) the
+// source gets a trailer that hands `module` to the same patch, at the end of its evaluation.
+const CJS_KEY = Symbol.for('@pmx/io:cjs')
+const TRAILER = "\n;(function(){try{var f=globalThis[Symbol.for('@pmx/io:cjs')];if(typeof f==='function')f(module,__filename)}catch(e){}})();\n"
+
+function cjsTarget (url) {
+  const f = globalThis[CJS_KEY]
+  if (typeof f !== 'function' || typeof url !== 'string' || !url.startsWith('file:') || !url.includes('/node_modules/')) return false
+  try {
+    return f.wants(url)
+  } catch (_) {
+    return false
+  }
+}
+
+function decide (url, t, r) {
+  // a target is wrapped only when it is an ES module (a package may ship the same path as
+  // CommonJS in older versions, e.g. graphile-worker 0.16)
+  if (t && r && r.format === 'module') return { format: 'module', shortCircuit: true, source: wrapper(url, t, DEFAULT_RE.test(sourceText(r))) }
+  if (r && r.format === 'commonjs' && cjsTarget(url)) {
+    let source = r.source
+    if (source === null || source === undefined) source = globalThis[CJS_KEY].read(url)
+    if (source !== null && source !== undefined) return Object.assign({}, r, { source: String(source) + TRAILER })
+  }
+  return r
+}
+
+// Synchronous for module.registerHooks, a promise for module.register (nextLoad decides)
+export function load (url, context, nextLoad) {
+  const t = match(url)
+  const r = nextLoad(url, context)
+  if (r && typeof r.then === 'function') return t ? r.then((res) => decide(url, t, res)) : r
+  return decide(url, t, r)
+}
+
+export function resolve (specifier, context, nextResolve) {
+  return nextResolve(specifier, context)
+}

package/lib/exit.js

@@ -0,0 +1,79 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// onExit hooks (80 NIO-075): cb(code, signal) once, at normal exit or on SIGINT/SIGTERM/SIGHUP;
+// after signal-triggered callbacks settle (max 5 s) the process exits with code 0.
+// Hooks are process-wide and survive init()/destroy() (apps commonly register
+// `onExit(() => io.destroy())`).
+
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP']
+const SIGNAL_GRACE_MS = 5000
+
+const callbacks = [] // { fn, called }
+let installed = false
+let signalled = false
+
+function runSync (code, signal) {
+  for (const entry of callbacks.slice()) {
+    if (entry.called) continue
+    entry.called = true
+    try {
+      entry.fn(code, signal)
+    } catch (err) {
+      try {
+        console.error(err)
+      } catch (_) {}
+    }
+  }
+}
+
+async function runSignal (signal) {
+  const deadline = Date.now() + SIGNAL_GRACE_MS
+  for (const entry of callbacks.slice()) {
+    if (entry.called) continue
+    entry.called = true
+    try {
+      const ret = entry.fn(null, signal)
+      if (ret && typeof ret.then === 'function') {
+        const left = Math.max(0, deadline - Date.now())
+        let timer
+        await Promise.race([
+          Promise.resolve(ret).catch(() => {}),
+          new Promise((resolve) => { timer = setTimeout(resolve, left) })
+        ])
+        clearTimeout(timer)
+      }
+    } catch (err) {
+      try {
+        console.error(err)
+      } catch (_) {}
+    }
+  }
+}
+
+function onSignal (signal) {
+  if (signalled) return
+  signalled = true
+  runSignal(signal).then(() => process.exit(0), () => process.exit(0))
+}
+
+function install () {
+  if (installed) return
+  installed = true
+  process.on('exit', (code) => runSync(code, null))
+  for (const sig of SIGNALS) {
+    try {
+      process.on(sig, onSignal)
+    } catch (_) { /* signal not supported on this platform */ }
+  }
+}
+
+/** Register an exit callback. Returns undefined (non-functions are ignored). */
+function onExit (fn) {
+  if (typeof fn !== 'function') return undefined
+  callbacks.push({ fn, called: false })
+  install()
+  return undefined
+}
+
+module.exports = { onExit }