@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/modules.js

@@ -0,0 +1,260 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Library instrumentation mechanism (80 NIO-210): libraries are wrapped when the app loads them,
+// never loaded by @aidra/pmx-io itself.
+//  * CommonJS (Node): Module.prototype._compile is observed; when a file of a target package has
+//    been compiled, the integration patches its exports (in place, or by replacing
+//    module.exports) before the caller receives them. This also covers CJS packages imported
+//    from ES modules (Node runs them through the same loader). Files already loaded when an
+//    integration is enabled are patched from require.cache.
+//  * CommonJS (Bun): Module.prototype.require is observed (Bun does not use _compile).
+//  * ES modules: hooks registered by preload.mjs when tracing is enabled at spawn (NIO-085,
+//    esm-hooks.mjs) replace a target module by a wrapper module that re-exports it with the
+//    patched exports (globalThis[Symbol.for('@pmx/io:esm')] below).
+// Integrations are declared in integrations.js: { pkg, files: { '<path in package>': patch } }.
+// A patch receives (exports, info) and returns undefined (patched in place) or a replacement.
+// Wrapping is transparent (82 ITG-003); a module that fails to patch is left untouched.
+
+const path = require('path')
+const debug = require('./debug')('axm:tracing')
+
+// The packages integrations.js patches (checked before loading the integrations themselves)
+const TARGET_PKGS = new Set(['express', 'router', 'koa', '@nestjs/core', 'h3', 'hono', 'pino', 'winston', 'bunyan',
+  // database and broker integrations (82, lib/itg/index.js)
+  'pg', 'pg-pool', 'postgres', 'ioredis', '@redis/client', 'mysql2', 'mongodb', 'nats', '@nats-io/nats-core',
+  '@nats-io/jetstream', 'kafkajs', 'amqplib', 'bullmq', 'pg-boss', 'graphile-worker'])
+
+const REGISTRY = Symbol.for('@pmx/io:modules')
+const ESM_KEY = Symbol.for('@pmx/io:esm')
+const PATCHED = Symbol.for('@pmx/io:patched')
+
+function registry () {
+  let r = globalThis[REGISTRY]
+  if (!r) {
+    r = { installed: false, integrations: null, wants: { errors: false, tracing: false }, tracing: null, done: new Set() }
+    Object.defineProperty(globalThis, REGISTRY, { value: r, enumerable: false, configurable: true })
+  }
+  return r
+}
+
+/** (pkg, file in package) of a path under node_modules, or null. */
+function packageOf (filename) {
+  if (typeof filename !== 'string') return null
+  const norm = filename.split(path.sep).join('/')
+  const i = norm.lastIndexOf('/node_modules/')
+  if (i === -1) return null
+  const rest = norm.slice(i + 14)
+  const parts = rest.split('/')
+  if (parts[0].startsWith('@')) {
+    if (parts.length < 3) return null
+    return { pkg: parts[0] + '/' + parts[1], file: parts.slice(2).join('/'), dir: norm.slice(0, i + 14) + parts[0] + '/' + parts[1] }
+  }
+  if (parts.length < 2) return null
+  return { pkg: parts[0], file: parts.slice(1).join('/'), dir: norm.slice(0, i + 14) + parts[0] }
+}
+
+function integrations () {
+  const r = registry()
+  if (!r.integrations) r.integrations = require('./integrations').list()
+  return r.integrations
+}
+
+function findPatch (pkg, file) {
+  for (const it of integrations()) {
+    if (it.pkg !== pkg) continue
+    const fn = it.files[file]
+    if (fn) return { it, fn }
+  }
+  return null
+}
+
+function wanted (it) {
+  const r = registry()
+  const w = r.wants
+  if (it.for === 'db' || it.for === 'messaging' || it.for === 'db+messaging') {
+    // 82 ITG-001: database / broker integrations only with tracing and their switch on
+    const t = w.tracing && r.tracing && r.tracing._tracer
+    if (!t) return false
+    return (it.for !== 'messaging' && Boolean(t.db)) || (it.for !== 'db' && Boolean(t.messaging))
+  }
+  return (it.for === 'errors' && (w.errors || w.tracing)) || (it.for === 'tracing' && w.tracing) || (it.for === 'both' && (w.errors || w.tracing))
+}
+
+/** Apply the patch for (pkg, file) to `exports`; returns the (possibly replaced) exports. */
+function applyPatch (pkg, file, exports, info) {
+  const found = findPatch(pkg, file)
+  if (!found || !wanted(found.it)) return exports
+  if (exports === null || exports === undefined) return exports
+  if ((typeof exports === 'object' || typeof exports === 'function') && exports[PATCHED]) return exports
+  try {
+    const out = found.fn(exports, Object.assign({ pkg, file }, info || {}))
+    const result = out === undefined ? exports : out
+    try {
+      Object.defineProperty(result, PATCHED, { value: true, enumerable: false, configurable: true })
+      if (result !== exports) Object.defineProperty(exports, PATCHED, { value: true, enumerable: false, configurable: true })
+    } catch (_) {}
+    debug('instrumented %s/%s', pkg, file)
+    return result
+  } catch (err) {
+    debug('could not instrument %s/%s: %s', pkg, file, err && err.message)
+    return exports
+  }
+}
+
+function onCompiled (mod, filename) {
+  const p = packageOf(filename)
+  if (!p || !TARGET_PKGS.has(p.pkg) || !findPatch(p.pkg, p.file)) return
+  const before = mod.exports
+  const after = applyPatch(p.pkg, p.file, before, { dir: p.dir, filename })
+  if (after !== before) mod.exports = after
+}
+
+function installNode (Module) {
+  const proto = Module.prototype
+  const orig = proto._compile
+  if (typeof orig !== 'function') return false
+  proto._compile = function _compile (content, filename) {
+    const ret = orig.apply(this, arguments)
+    if (typeof filename === 'string' && filename.indexOf('node_modules') !== -1) {
+      try {
+        onCompiled(this, filename)
+      } catch (_) {}
+    }
+    return ret
+  }
+  return true
+}
+
+function installBun (Module) {
+  const proto = Module.prototype
+  const orig = proto.require
+  proto.require = function require (id) {
+    const exports = orig.apply(this, arguments)
+    if (typeof id !== 'string' || id.startsWith('.') || id.startsWith('/') || id.startsWith('node:')) return exports
+    try {
+      return onBunRequire(id, exports, this)
+    } catch (_) {
+      return exports
+    }
+  }
+}
+
+/** Bun: a bare require of a target package patches its target files from the cache. */
+function onBunRequire (id, exports, parent) {
+  const parts = id.split('/')
+  const pkg = id.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]
+  if (!TARGET_PKGS.has(pkg)) return exports
+  const its = integrations().filter((it) => it.pkg === pkg && wanted(it))
+  if (its.length === 0) return exports
+  let mainFile
+  try {
+    mainFile = require('module').createRequire(parent && parent.filename ? parent.filename : path.join(process.cwd(), 'x.js')).resolve(id)
+  } catch (_) {
+    return exports
+  }
+  const p = packageOf(mainFile)
+  if (!p) return exports
+  let result = exports
+  for (const it of its) {
+    for (const file of Object.keys(it.files)) {
+      const full = path.join(p.dir, file)
+      if (full === mainFile) {
+        result = applyPatch(pkg, file, result, { dir: p.dir, filename: full })
+        continue
+      }
+      const cached = require.cache[full]
+      if (cached) {
+        const after = applyPatch(pkg, file, cached.exports, { dir: p.dir, filename: full })
+        if (after !== cached.exports) cached.exports = after
+      } else if (it.eager && it.eager.includes(file)) {
+        try {
+          const req = require('module').createRequire(full)
+          const ex = req(full)
+          applyPatch(pkg, file, ex, { dir: p.dir, filename: full })
+        } catch (_) {}
+      }
+    }
+  }
+  return result
+}
+
+/** Patch target files that were loaded before an integration became wanted. */
+function patchLoaded () {
+  const cache = require.cache || {}
+  for (const filename of Object.keys(cache)) {
+    if (filename.indexOf('node_modules') === -1) continue
+    const p = packageOf(filename)
+    if (!p || !TARGET_PKGS.has(p.pkg) || !findPatch(p.pkg, p.file)) continue
+    const mod = cache[filename]
+    if (!mod || !mod.loaded) continue
+    const after = applyPatch(p.pkg, p.file, mod.exports, { dir: p.dir, filename })
+    if (after !== mod.exports) mod.exports = after
+  }
+}
+
+function install () {
+  const r = registry()
+  if (r.installed) return
+  r.installed = true
+  const Module = require('./util').cjsModule()
+  if (typeof process.versions.bun === 'string') installBun(Module)
+  else installNode(Module)
+  // ES-module wrappers (esm-hooks.mjs) call this with the original namespace
+  Object.defineProperty(globalThis, ESM_KEY, {
+    configurable: true,
+    enumerable: false,
+    value: (pkg, file, ns) => {
+      const copy = {}
+      for (const k of Object.keys(ns)) copy[k] = ns[k]
+      return applyPatch(pkg, file, copy, { esm: true })
+    }
+  })
+  // CommonJS files evaluated by in-thread module hooks bypass _compile (esm-hooks.mjs trailer)
+  const cjs = function (mod, filename) {
+    try {
+      onCompiled(mod, filename)
+    } catch (_) {}
+  }
+  cjs.wants = (url) => {
+    const p = packageOf(require('url').fileURLToPath(url))
+    return Boolean(p && TARGET_PKGS.has(p.pkg) && findPatch(p.pkg, p.file))
+  }
+  cjs.read = (url) => require('fs').readFileSync(require('url').fileURLToPath(url), 'utf8')
+  Object.defineProperty(globalThis, Symbol.for('@pmx/io:cjs'), { configurable: true, enumerable: false, value: cjs })
+  // Fastify publishes each new instance; the integrations load only when one is created
+  try {
+    require('diagnostics_channel').subscribe('fastify.initialization', (msg) => require('./integrations').onFastify(msg && msg.fastify))
+  } catch (_) {}
+}
+
+function enableErrors () {
+  const r = registry()
+  r.wants.errors = true
+  install()
+  patchLoaded()
+}
+
+function enableTracing (feature) {
+  const r = registry()
+  r.wants.tracing = true
+  r.tracing = feature
+  install()
+  patchLoaded()
+}
+
+function disableTracing () {
+  const r = registry()
+  r.wants.tracing = false
+  r.tracing = null
+}
+
+function disableErrors () {
+  registry().wants.errors = false
+}
+
+function wants () {
+  return registry().wants
+}
+
+module.exports = { TARGET_PKGS, install, enableErrors, enableTracing, disableTracing, disableErrors, packageOf, applyPatch, wants, registry, ESM_KEY }

package/lib/node-options.js

@@ -0,0 +1,62 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// NODE_OPTIONS tokenising that keeps each token's original text (quoting included), so the
+// preload can remove its own `--require`/`--import` tokens and leave the rest intact (NIO-021).
+
+/**
+ * Split NODE_OPTIONS into tokens: [{ raw, value }]. Double quotes group, and backslash escapes
+ * the next character inside quotes (Node's NODE_OPTIONS rules).
+ */
+function tokenize (str) {
+  const tokens = []
+  let i = 0
+  const n = str.length
+  while (i < n) {
+    while (i < n && /\s/.test(str[i])) i++
+    if (i >= n) break
+    const start = i
+    let value = ''
+    let inQuotes = false
+    while (i < n && (inQuotes || !/\s/.test(str[i]))) {
+      const c = str[i]
+      if (c === '"') {
+        inQuotes = !inQuotes
+        i++
+        continue
+      }
+      if (c === '\\' && inQuotes && i + 1 < n) {
+        value += str[i + 1]
+        i += 2
+        continue
+      }
+      value += c
+      i++
+    }
+    tokens.push({ raw: str.slice(start, i), value })
+  }
+  return tokens
+}
+
+/**
+ * Remove `--require <p>` / `-r <p>` / `--require=<p>` / `--import <p>` / `--import=<p>` where
+ * `isOurs(p)` is true. Returns the new NODE_OPTIONS string ('' when nothing remains).
+ */
+function stripPreloads (str, isOurs) {
+  const tokens = tokenize(str || '')
+  const kept = []
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]
+    const v = t.value
+    if ((v === '--require' || v === '-r' || v === '--import') && i + 1 < tokens.length && isOurs(tokens[i + 1].value)) {
+      i++
+      continue
+    }
+    const eq = /^(--require|-r|--import)=(.*)$/s.exec(v)
+    if (eq && isOurs(eq[2])) continue
+    kept.push(t.raw)
+  }
+  return kept.join(' ')
+}
+
+module.exports = { tokenize, stripPreloads }