@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/actions.js

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Custom, internal and scoped actions (80 A.8.1, A.8.2, NIO-040..042; 40 §7.4, §7.5, §7.8, §8.3).
+
+const debug = require('./debug')('axm:services:actions')
+
+function actionType (name) {
+  return name.startsWith('km:') || name.startsWith('internal:') ? 'internal' : 'custom'
+}
+
+class ActionService {
+  /**
+   * @param {object} transport
+   * @param {(err: any) => void} notifyError used for rejected async handlers (NIO-042)
+   */
+  constructor (transport, notifyError) {
+    this._transport = transport
+    this._notifyError = notifyError
+    this._actions = new Map()
+    transport.onMessage((msg) => this.dispatch(msg))
+  }
+
+  register (name, opts, handler) {
+    if (typeof name !== 'string') {
+      console.error('You must define an name when registering an action')
+      return false
+    }
+    if (typeof handler !== 'function') {
+      console.error('You must define an callback when registering an action')
+      return false
+    }
+    const arity = handler.length
+    this._actions.set(name, { name, handler, arity, scoped: false })
+    const data = { action_name: name, action_type: actionType(name), arity }
+    if (opts !== undefined) data.opts = opts
+    this._transport.send('axm:action', data)
+    return true
+  }
+
+  registerScoped (name, handler) {
+    if (typeof name !== 'string') {
+      console.error('You must define an name when registering an action')
+      return false
+    }
+    if (typeof handler !== 'function') {
+      console.error('You must define an callback when registering an action')
+      return false
+    }
+    this._actions.set(name, { name, handler, arity: handler.length, scoped: true })
+    this._transport.send('axm:action', { action_name: name, action_type: 'scoped', arity: handler.length, opts: null })
+    return true
+  }
+
+  has (name) {
+    return this._actions.has(name)
+  }
+
+  list () {
+    return Array.from(this._actions.values()).map((a) => ({
+      action_name: a.name,
+      action_type: a.scoped ? 'scoped' : actionType(a.name),
+      arity: a.arity
+    }))
+  }
+
+  /** Handle a daemon → app message (40 §8.3). Unknown names are ignored silently. */
+  dispatch (msg) {
+    let name
+    let opts
+    let uuid
+    if (typeof msg === 'string') {
+      name = msg
+    } else if (msg && typeof msg === 'object') {
+      name = msg.msg || msg.action_name
+      opts = msg.opts
+      uuid = msg.uuid
+    }
+    if (typeof name !== 'string') return
+    const action = this._actions.get(name)
+    if (!action) return
+    debug('invoking action %s', name)
+
+    if (action.scoped) {
+      if (!uuid) return
+      const send = (type) => (data) => this._transport.send(type, { data, uuid, action_name: name })
+      const stream = {
+        send: send('axm:scoped_action:stream'),
+        error: send('axm:scoped_action:error'),
+        end: send('axm:scoped_action:end')
+      }
+      action.handler(opts || {}, stream)
+      return
+    }
+
+    let replied = false
+    const reply = (data) => {
+      replied = true
+      this._transport.send('axm:reply', { at: Date.now(), action_name: name, return: data })
+    }
+    const params = opts === undefined || opts === null ? {} : opts // NIO-041
+    const ret = action.arity === 2 ? action.handler(params, reply) : action.handler(reply)
+    if (ret && typeof ret.then === 'function') {
+      ret.then((value) => {
+        if (!replied) reply(value)
+      }, (err) => {
+        if (!replied) reply({ success: false, err: err && err.message !== undefined ? err.message : String(err) })
+        try {
+          this._notifyError(err)
+        } catch (_) {}
+      })
+    }
+  }
+
+  destroy () {
+    this._actions.clear()
+  }
+}
+
+module.exports = { ActionService, actionType }

package/lib/activate.js

@@ -0,0 +1,402 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Preload activation (80 B.3 NIO-020..NIO-025, B.16 NIO-290..NIO-296) and coexistence with an
+// app's own @pm2/io (B.4 NIO-030..NIO-036, 02 D-05).
+//
+// A process that loads the preload becomes one of:
+//  * the root (env PMX_IO=1 from the daemon, IPC channel, main thread): reports over IPC and,
+//    with `children` (default true), opens the local hub for its Node descendants (NIO-291);
+//  * a daemon-mode relay (PMX_IO unset, PMX_IO_HUB set, PMX_IO_STANDALONE unset): reports
+//    through the root's hub;
+//  * a thread relay (a worker thread of an instrumented process): reports through the main
+//    thread (NIO-293).
+
+const path = require('path')
+const fs = require('fs')
+const { fileURLToPath } = require('url')
+const { GLOBAL_SYMBOL } = require('./constants')
+const { PKG_DIR } = require('./util')
+const debug = require('./debug')('axm:main')
+
+const STATE = Symbol.for('@pmx/io:preload-state')
+
+function state () {
+  let s = globalThis[STATE]
+  if (!s) {
+    s = { active: false, instance: null, joined: false, conflict: false, esmHooked: false, role: null, hub: null, caps: [], closeThreads: null }
+    Object.defineProperty(globalThis, STATE, { value: s, enumerable: false, configurable: true })
+  }
+  return s
+}
+
+const OWN_PRELOADS = ['preload.cjs', 'preload.mjs', 'standalone.cjs', 'standalone.mjs'].map((f) => path.join(PKG_DIR, f))
+
+function realpath (p) {
+  try {
+    return fs.realpathSync(p)
+  } catch (_) {
+    return p
+  }
+}
+
+function isOurPreload (spec) {
+  if (typeof spec !== 'string' || spec === '') return false
+  let file = spec
+  if (file.startsWith('file:')) {
+    try {
+      file = fileURLToPath(file)
+    } catch (_) {
+      return false
+    }
+  }
+  const abs = path.resolve(file)
+  if (OWN_PRELOADS.includes(abs)) return true
+  const real = realpath(abs)
+  return OWN_PRELOADS.some((own) => realpath(own) === real)
+}
+
+function isMainThread () {
+  // A worker thread's bootstrap always loads worker_threads: when it is not loaded yet this is
+  // the main thread, without paying for loading the module (start-up cost, NIO-024).
+  const list = process.moduleLoadList
+  if (Array.isArray(list) && !list.includes('NativeModule worker_threads')) return true
+  try {
+    return require('worker_threads').isMainThread !== false
+  } catch (_) {
+    return true
+  }
+}
+
+function optedOut (env) {
+  return env.pmx === 'false' || env.automation === 'false'
+}
+
+/** NIO-020 activation conditions (the root under the daemon). */
+function shouldActivate (env) {
+  env = env || process.env
+  return env.PMX_IO === '1' &&
+    !optedOut(env) &&
+    isMainThread() &&
+    typeof process.send === 'function'
+}
+
+/** NIO-291: a descendant of an instrumented root, under the daemon. */
+function isDaemonRelay (env) {
+  env = env || process.env
+  return !env.PMX_IO && Boolean(env.PMX_IO_HUB) && env.PMX_IO_STANDALONE !== '1' && !optedOut(env)
+}
+
+/** INJ-024: the capabilities the daemon advertised (read once, then removed). */
+function readCaps (env) {
+  const raw = env.PMX_IO_CAPS
+  if (typeof raw !== 'string') return []
+  return raw.split(',').map((s) => s.trim()).filter((s) => s)
+}
+
+/**
+ * NIO-021 (amended by NIO-291): PMX_IO and PMX_IO_CAPS are never inherited; the preload tokens
+ * leave NODE_OPTIONS only when descendants are not instrumented (`children: false`).
+ */
+function scrubEnvironment (keepPreloads) {
+  delete process.env.PMX_IO
+  delete process.env.PMX_IO_CAPS
+  if (keepPreloads) return
+  const opts = process.env.NODE_OPTIONS
+  if (typeof opts === 'string') {
+    const stripped = require('./node-options').stripPreloads(opts, isOurPreload)
+    if (stripped.trim() === '') delete process.env.NODE_OPTIONS
+    else process.env.NODE_OPTIONS = stripped
+  }
+}
+
+function sendOption (instance, data) {
+  try {
+    if (instance._transport && instance._initialized) instance._transport.send('axm:option:configuration', data)
+    else if (typeof process.send === 'function' && process.connected !== false && instance._mode === 'managed') {
+      process.send({ type: 'axm:option:configuration', data }, () => {})
+    }
+  } catch (_) {}
+}
+
+/** NIO-030/031: define the global symbol as an accessor so foreign reads/writes are observable. */
+function claimSingleton (instance) {
+  const s = state()
+  Object.defineProperty(globalThis, GLOBAL_SYMBOL, {
+    configurable: true,
+    enumerable: false,
+    get () {
+      if (!s.joined) {
+        s.joined = true
+        debug('an app copy of @pm2/io joined the injected instance')
+        sendOption(instance, { pm2_io_joined: true })
+      }
+      return instance
+    },
+    set (value) {
+      if (value === instance) return
+      if (!s.conflict) {
+        s.conflict = true
+        sendOption(instance, { pm2_io_conflict: true })
+        try {
+          process.stderr.write('[pmx] another @pm2/io instance tried to replace the injected one; it was ignored\n')
+        } catch (_) {}
+      }
+    }
+  })
+}
+
+/** NIO-034: warn once when the legacy `pmx` module is required. Never alters it. */
+function watchLegacyPmx () {
+  let Module
+  try {
+    Module = require('./util').cjsModule()
+  } catch (_) {
+    return
+  }
+  const proto = Module.prototype
+  if (!proto || typeof proto.require !== 'function') return
+  const orig = proto.require
+  let warned = false
+  proto.require = function require (id) {
+    if (!warned && id === 'pmx') {
+      warned = true
+      try {
+        process.stderr.write("[pmx] legacy 'pmx' module detected: start the app with --no-pmx to avoid duplicate metrics\n")
+      } catch (_) {}
+    }
+    return orig.apply(this, arguments)
+  }
+}
+
+/**
+ * A.2: the second init from env `io`. (Env `trace` and the sampling variables are applied by
+ * every init, NIO-201, so `trace=true` alone needs no second init.)
+ */
+function secondInitConfig (env) {
+  const { envIoConf } = require('./tracing/options')
+  const conf = envIoConf(env)
+  return conf ? Object.assign({}, conf) : null
+}
+
+/** NIO-291: open the hub and export its variables before the app can start children. */
+function openHub (s, instanceRef) {
+  const { Hub } = require('./relay/hub')
+  const hub = new Hub((msg) => {
+    const inst = instanceRef()
+    if (inst) inst._onRelayMessage(msg)
+  })
+  process.env.PMX_IO_HUB = hub.start()
+  process.env.PMX_IO_HUB_TOKEN = hub.token
+  process.env.PMX_IO_ROOT_PID = String(process.pid)
+  s.hub = hub
+  // worker threads start after the app's first line: listen for them off the start-up path
+  const t = setImmediate(() => {
+    s.closeThreads = require('./relay/transport').listenThreads((msg) => {
+      const inst = instanceRef()
+      if (inst) inst._onRelayMessage(msg)
+    })
+  })
+  if (t.unref) t.unref()
+  return hub
+}
+
+function activateRoot (s) {
+  const { childrenEnabled } = require('./tracing/options')
+  s.caps = readCaps(process.env)
+  const children = childrenEnabled(null, process.env)
+  scrubEnvironment(children)
+  if (Object.prototype.hasOwnProperty.call(globalThis, GLOBAL_SYMBOL)) {
+    debug('global @pm2/io instance already present; not injecting')
+    return null
+  }
+  // (a) node_version (40 §7.1)
+  try {
+    process.send({ node_version: process.versions.node }, () => {})
+  } catch (_) {}
+  // (b) claim the singleton
+  const { PMX } = require('./pmx')
+  const instance = new PMX({ managed: true, caps: s.caps })
+  s.instance = instance
+  s.active = true
+  s.role = 'root'
+  claimSingleton(instance)
+  watchLegacyPmx()
+  if (children) {
+    try {
+      openHub(s, () => s.instance)
+    } catch (err) {
+      debug('hub not started: %s', err && err.message)
+    }
+  } else {
+    delete process.env.PMX_IO_HUB
+    delete process.env.PMX_IO_HUB_TOKEN
+  }
+  // (c) default init, (d) second init from env
+  instance.init()
+  const conf = secondInitConfig(process.env)
+  if (conf) instance.init(conf)
+  return s
+}
+
+function activateRelay (s, kind) {
+  if (Object.prototype.hasOwnProperty.call(globalThis, GLOBAL_SYMBOL)) return null
+  const { PMX } = require('./pmx')
+  let instance
+  if (kind === 'thread') {
+    instance = new PMX({ mode: 'thread' })
+  } else {
+    const env = process.env
+    const hub = env.PMX_IO_HUB
+    const token = env.PMX_IO_HUB_TOKEN || ''
+    const { HubRelayTransport } = require('./relay/transport')
+    instance = new PMX({ mode: 'relay', relayFactory: () => new HubRelayTransport(hub, token) })
+  }
+  s.instance = instance
+  s.active = true
+  s.role = kind
+  claimSingleton(instance)
+  instance.init()
+  const conf = secondInitConfig(process.env)
+  if (conf) instance.init(conf)
+  return s
+}
+
+/**
+ * Activate instrumentation from a preload. Idempotent. Returns the state, or null when the
+ * activation conditions do not hold (then nothing at all is done).
+ */
+function activate () {
+  const s = state()
+  if (s.active) return s
+  const env = process.env
+  if (!isMainThread()) {
+    // NIO-293: a worker thread of an instrumented process (daemon root with children, or a
+    // standalone tree) becomes a thread relay
+    if (optedOut(env) || !(env.PMX_IO_HUB || env.PMX_IO_STANDALONE === '1')) return null
+    if (require('./tracing/options').childrenEnabled(null, env) === false) return null
+    return activateRelay(s, 'thread')
+  }
+  if (shouldActivate(env)) return activateRoot(s)
+  if (isDaemonRelay(env)) {
+    if (require('./tracing/options').childrenEnabled(null, env) === false) return null
+    return activateRelay(s, 'relay')
+  }
+  return null
+}
+
+const ESM_SYNTAX = /^[ \t]*(?:import[ \t]*[\w*{'"]|export[ \t]+(?:\{|\*|default\b|const\b|let\b|var\b|function\b|class\b|async\b))/m
+
+/** The `type` of the package.json nearest to `dir`, or undefined. */
+function packageType (dir) {
+  for (let i = 0; i < 64; i++) {
+    let text = null
+    try {
+      text = fs.readFileSync(path.join(dir, 'package.json'), 'utf8')
+    } catch (_) {}
+    if (text !== null) {
+      try {
+        const t = JSON.parse(text).type
+        return typeof t === 'string' ? t : undefined
+      } catch (_) {
+        return undefined
+      }
+    }
+    const up = path.dirname(dir)
+    if (up === dir) return undefined
+    dir = up
+  }
+  return undefined
+}
+
+/**
+ * Whether the app's entry point is (or may be) an ES module: `.mjs`/`.mts`; `.js`/`.ts`/no
+ * extension under a package.json with `"type": "module"`, or containing import/export syntax
+ * (Node's syntax detection); `--input-type=module` / `--experimental-default-type=module`. Errs
+ * towards true: a wrong "true" only costs the hooks thread, a wrong "false" leaves ES-module
+ * builds of hono/h3 unwrapped (their CommonJS builds are always covered).
+ */
+function entryIsEsm (argv, execArgv) {
+  argv = argv || process.argv
+  const flags = (execArgv || process.execArgv || []).concat(String(process.env.NODE_OPTIONS || '').split(/\s+/))
+  if (flags.some((f) => f === '--input-type=module' || f === '--experimental-default-type=module')) return true
+  const entry = argv[1]
+  if (typeof entry !== 'string' || entry === '') return false
+  let file = path.resolve(entry)
+  const ext = path.extname(file).toLowerCase()
+  if (ext === '.mjs' || ext === '.mts') return true
+  if (ext === '.cjs' || ext === '.cts') return false
+  if (ext === '' && !fs.existsSync(file) && fs.existsSync(file + '.js')) file += '.js'
+  try {
+    file = fs.realpathSync(file)
+  } catch (_) {}
+  if (packageType(path.dirname(file)) === 'module') return true
+  try {
+    const fd = fs.openSync(file, 'r')
+    try {
+      const buf = Buffer.alloc(64 * 1024)
+      const n = fs.readSync(fd, buf, 0, buf.length, 0)
+      return ESM_SYNTAX.test(buf.toString('utf8', 0, n))
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch (_) {
+    return false
+  }
+}
+
+/**
+ * NIO-085 / NIO-210: register the module customization hooks that wrap ES-module libraries,
+ * only when tracing is enabled (called from preload.mjs / standalone.mjs).
+ */
+function registerEsmHooks () {
+  const s = state()
+  if (!s.active || s.esmHooked || !s.instance || !s.instance._tracingEnabled()) return false
+  let mod
+  try {
+    mod = require('module')
+  } catch (_) {
+    return false
+  }
+  const file = path.join(__dirname, 'esm-hooks.mjs')
+  try {
+    if (typeof mod.registerHooks === 'function') {
+      const hooks = require(file)
+      mod.registerHooks({ load: hooks.load })
+    } else if (typeof mod.register === 'function') {
+      // off-thread hooks (Node < 22.15 / < 23.5) start a worker thread, ~100 ms of start-up on
+      // Node 18/20: only when the entry point is an ES module (a CommonJS app loads the
+      // CommonJS builds, which the require interception covers)
+      if (!entryIsEsm()) {
+        debug('CommonJS entry point: module hooks not registered (ES-module libraries imported later are not instrumented)')
+        return false
+      }
+      mod.register(require('url').pathToFileURL(file).href)
+    } else {
+      debug('module hooks unavailable on this Node: ES-module libraries are not instrumented')
+      return false
+    }
+  } catch (err) {
+    debug('module hooks failed: %s', err && err.message)
+    return false
+  }
+  s.esmHooked = true
+  return true
+}
+
+module.exports = {
+  activate,
+  registerEsmHooks,
+  shouldActivate,
+  isDaemonRelay,
+  scrubEnvironment,
+  isOurPreload,
+  secondInitConfig,
+  state,
+  readCaps,
+  openHub,
+  claimSingleton,
+  isMainThread,
+  entryIsEsm,
+  OWN_PRELOADS
+}

package/lib/application.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Applications (pmx 97 PAP-001/002/050/051, prodman 02 §6.20): the application this process
+// belongs to. Under a pmx daemon the daemon decides (`PMX_APPLICATION`, PAP-022) and an init
+// value that differs is ignored with one warning; standalone, init({ application }) >
+// PMX_APPLICATION > `default`, an invalid value giving `default` and one warning.
+
+const DEFAULT = 'default'
+const ENV = 'PMX_APPLICATION'
+
+const NAME = /^[a-z0-9](?:[a-z0-9._-]{0,61}[a-z0-9])?$/
+
+/**
+ * PAP-001/002: `{ value }` with the normalised name (`null` = unset: empty after trimming), or
+ * `{ error }` with the failing rule: 'type', 'charset', 'length' or 'reserved'.
+ */
+function normalize (raw) {
+  if (raw === undefined || raw === null) return { value: null }
+  if (typeof raw !== 'string') return { error: 'type' }
+  const n = raw.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, '').replace(/[A-Z]/g, (c) => c.toLowerCase())
+  if (n === '') return { value: null }
+  if (!/^[a-z0-9._-]+$/.test(n) || !/^[a-z0-9]/.test(n) || !/[a-z0-9]$/.test(n)) return { error: 'charset' }
+  if (n.length > 63) return { error: 'length' }
+  if (!NAME.test(n)) return { error: 'charset' }
+  if (n === 'all' || n === 'none' || n.startsWith('pmx')) return { error: 'reserved' }
+  return { value: n }
+}
+
+/** PAP-004 wording. */
+function message (raw, reason) {
+  const shown = typeof raw === 'string' ? raw : JSON.stringify(raw)
+  if (reason === 'reserved') return `Application name "${shown}" is reserved`
+  return `Invalid application name "${shown}": use 1-63 lower-case letters, digits, '.', '_' or '-', starting and ending with a letter or digit`
+}
+
+function warnDefault (line) {
+  try {
+    process.stderr.write(line + '\n')
+  } catch (_) {}
+}
+
+let resolved = null
+const warned = new Set()
+
+function warnOnce (warn, line) {
+  if (warned.has(line)) return
+  warned.add(line)
+  ;(warn || warnDefault)(line)
+}
+
+/**
+ * PAP-050: resolve and remember the application. `opts`: { managed (under a pmx daemon), env,
+ * warn (line printer) }. Returns the name (`default` included).
+ */
+function resolve (initValue, opts) {
+  opts = opts || {}
+  const env = opts.env || process.env
+  const warn = opts.warn
+  const fromEnv = normalize(env[ENV])
+  if (opts.managed) {
+    const a = fromEnv.value || DEFAULT
+    if (initValue !== undefined && initValue !== null) {
+      const n = normalize(initValue)
+      if (n.error || (n.value || DEFAULT) !== a) {
+        warnOnce(warn, `[pmx-io] application is set by pmx (${a}); ignoring init application ${typeof initValue === 'string' ? initValue : JSON.stringify(initValue)}`)
+      }
+    }
+    resolved = a
+    return a
+  }
+  resolved = DEFAULT
+  for (const raw of [initValue, env[ENV]]) {
+    const n = normalize(raw)
+    if (n.error) {
+      warnOnce(warn, `[pmx-io] ${message(raw, n.error)}; using application ${DEFAULT}`)
+      break
+    }
+    if (n.value) {
+      resolved = n.value
+      break
+    }
+  }
+  return resolved
+}
+
+/** The application resolved by the last init, else the environment's (`default` when unset). */
+function current (env) {
+  if (resolved !== null) return resolved
+  return normalize((env || process.env)[ENV]).value || DEFAULT
+}
+
+/** PAP-051: the `service.namespace` value, or null: the application, else a non-default pm2 namespace. */
+function serviceNamespace (application, namespace) {
+  if (application && application !== DEFAULT) return application
+  if (typeof namespace === 'string' && namespace !== '' && namespace !== DEFAULT) return namespace
+  return null
+}
+
+/** Tests only. */
+function _reset () {
+  resolved = null
+  warned.clear()
+}
+
+module.exports = { DEFAULT, ENV, normalize, message, resolve, current, serviceNamespace, _reset }