@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/standalone/activate.js

@@ -0,0 +1,307 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Standalone mode (80 B.15): activation (NIO-260), roots and relays (NIO-263), the root's setup
+// (hub, capture, prodman connection, NIO-262..NIO-267), shutdown reasons (NIO-268) and isolation
+// (NIO-269). Everything here is caught and logged under `axm:standalone`; nothing throws into the
+// app and the app always runs.
+
+const path = require('path')
+const { PKG_DIR } = require('../util')
+const debug = require('../debug')('axm:standalone')
+
+const MISSING_LINE = '[@pm2/io] not reporting to prodman: %s not set (standalone mode needs PM2_PUBLIC_KEY, PM2_SECRET_KEY and PM2_APP_NAME)'
+const UNREACHABLE_LINE = '[@pm2/io] not reporting: the standalone root (pid %s) is not reachable; start the server with exec'
+const TREE_ENV = ['PMX_IO_STANDALONE', 'PMX_IO_ROOT_PID', 'PMX_IO_ROOT_PPID', 'PMX_IO_HUB', 'PMX_IO_HUB_TOKEN', 'PMX_IO_CAPTURE_LOGS']
+const STANDALONE_CJS = path.join(PKG_DIR, 'standalone.cjs')
+const GLOBAL = Symbol.for('@pmx/io:standalone')
+const SIGNAL_MEMORY_MS = 10 * 60 * 1000
+const SIGNAL_NUMBERS = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGTERM: 15 }
+
+const printed = new Set()
+function printOnce (line) {
+  if (printed.has(line)) return
+  printed.add(line)
+  try {
+    process.stderr.write(line + '\n')
+  } catch (_) {}
+}
+
+/** A process started by pmx/pm2 (or a descendant of one): the keys are the agent's (APM-001). */
+function underPmx (env) {
+  return env.pm_id !== undefined && env.PMX_IO_STANDALONE !== '1'
+}
+
+function daemonChannel (env) {
+  return env.PMX_IO === '1' && typeof process.send === 'function'
+}
+
+function scrubTreeEnv (env) {
+  for (const k of TREE_ENV) delete env[k]
+}
+
+/** NIO-263: is this process the root of its tree? */
+function isRoot (env) {
+  const pid = String(process.pid)
+  if (env.PMX_IO_ROOT_PID === pid) return true
+  if (env.PMX_IO_ROOT_PPID && env.PMX_IO_ROOT_PPID === String(process.ppid)) return true
+  return !env.PMX_IO_ROOT_PID && !env.PMX_IO_ROOT_PPID && !env.PMX_IO_HUB
+}
+
+/** Adds `--require <abs standalone.cjs>` to NODE_OPTIONS once (NIO-261). */
+function ensureNodeOptions (env) {
+  const cur = env.NODE_OPTIONS || ''
+  if (cur.includes(STANDALONE_CJS)) return
+  const token = `--require "${STANDALONE_CJS.replace(/"/g, '\\"')}"`
+  env.NODE_OPTIONS = cur ? token + ' ' + cur : token
+}
+
+function childrenWanted (config) {
+  try {
+    return require('../tracing/options').childrenEnabled(config, process.env)
+  } catch (_) {
+    return true
+  }
+}
+
+/**
+ * Decide what this process is (NIO-260, NIO-263). Returns
+ *   { role: 'root', transport, handle } | { role: 'relay', factory } | null (inert).
+ */
+function decide (config) {
+  const env = process.env
+  if (daemonChannel(env)) return null
+  if (underPmx(env)) {
+    debug('started by pmx (pm_id set): standalone mode not used')
+    return null
+  }
+  if (!isRoot(env)) {
+    const hub = env.PMX_IO_HUB
+    const rootPid = env.PMX_IO_ROOT_PID || env.PMX_IO_ROOT_PPID
+    if (!hub) {
+      if (rootPid) printOnce(UNREACHABLE_LINE.replace('%s', rootPid))
+      return null
+    }
+    const token = env.PMX_IO_HUB_TOKEN || ''
+    const { HubRelayTransport } = require('../relay/transport')
+    const factory = () => new HubRelayTransport(hub, token, {
+      onUnreachable: () => {
+        if (rootPid) printOnce(UNREACHABLE_LINE.replace('%s', rootPid))
+      }
+    })
+    return { role: 'relay', factory }
+  }
+  const container = require('./container')
+  const { resolveConfig } = require('./transport')
+  const info = container.globalInfo()
+  const cfg = resolveConfig(config && config.apmOptions, env, info)
+  if (cfg.missing.length) {
+    printOnce(MISSING_LINE.replace('%s', cfg.missing.join(', ')))
+    scrubTreeEnv(env)
+    return null
+  }
+  return { role: 'root', handle: setupRoot(cfg, info, config) }
+}
+
+// -- the root ---------------------------------------------------------------------------------------
+
+let ROOT = null
+
+function setupRoot (cfg, info, config) {
+  if (ROOT) return ROOT
+  const env = process.env
+  const { ProdmanTransport } = require('./transport')
+  env.PMX_IO_ROOT_PID = String(process.pid)
+  delete env.PMX_IO_ROOT_PPID
+  env.PMX_IO_STANDALONE = '1'
+  // NIO-262: descendants report through the hub and never need the bucket keys
+  delete env.PM2_SECRET_KEY
+  delete env.PM2_PUBLIC_KEY
+  const handle = {
+    transport: null,
+    hub: null,
+    capture: null,
+    closeThreads: null,
+    instance: null,
+    signal: null,
+    signalAt: 0,
+    crashed: false,
+    observers: new Map(),
+    destroyed: false
+  }
+  const children = childrenWanted(config)
+  if (children) {
+    ensureNodeOptions(env)
+    try {
+      const { Hub } = require('../relay/hub')
+      const hub = new Hub((msg) => onRelay(handle, msg))
+      env.PMX_IO_HUB = hub.start()
+      env.PMX_IO_HUB_TOKEN = hub.token
+      handle.hub = hub
+    } catch (err) {
+      debug('hub not started: %s', err && err.message)
+    }
+    try {
+      handle.closeThreads = require('../relay/transport').listenThreads((msg) => onRelay(handle, msg))
+    } catch (_) {}
+  } else {
+    delete env.PMX_IO_HUB
+    delete env.PMX_IO_HUB_TOKEN
+  }
+  env.PMX_IO_CAPTURE_LOGS = cfg.captureLogs
+  const transport = new ProdmanTransport(cfg, info, { relayPids: () => (handle.hub ? handle.hub.relayPids() : []) })
+  handle.transport = transport
+  if (cfg.captureLogs === 'stdio') {
+    try {
+      const { Capture } = require('./capture')
+      handle.capture = new Capture((stream, text) => transport.onLogChunk(stream, text))
+      handle.capture.start()
+    } catch (err) {
+      debug('log capture failed: %s', err && err.message)
+    }
+  }
+  installShutdown(handle)
+  handle.destroy = () => destroyRoot(handle)
+  Object.defineProperty(globalThis, GLOBAL, {
+    configurable: true,
+    enumerable: false,
+    value: { onUncaught: () => { handle.crashed = true }, handle }
+  })
+  transport.start()
+  ROOT = handle
+  return handle
+}
+
+function onRelay (handle, msg) {
+  const inst = handle.instance
+  if (inst && typeof inst._onRelayMessage === 'function') {
+    inst._onRelayMessage(msg)
+  } else if (msg && msg.__pmx_relay__ === 'log' && typeof msg.d === 'string') {
+    handle.transport.onLogChunk(msg.s === 'err' ? 'err' : 'out', msg.d)
+  }
+}
+
+// -- shutdown (NIO-268) -----------------------------------------------------------------------------
+
+function exitReason (handle, code) {
+  if (handle.crashed) return { reason: 'crash', signal: null, planned: false }
+  if (handle.signal && Date.now() - handle.signalAt < SIGNAL_MEMORY_MS) return { reason: 'signal', signal: handle.signal, planned: true }
+  if (typeof code === 'number' && code !== 0) return { reason: 'crash', signal: null, planned: false }
+  return { reason: 'exit', signal: null, planned: true }
+}
+
+function installShutdown (handle) {
+  for (const sig of ['SIGTERM', 'SIGINT']) {
+    const observer = function pmxIoSignalObserver () {
+      if (handle.destroyed || process.pid !== Number(process.env.PMX_IO_ROOT_PID || process.pid)) return
+      handle.signal = sig
+      handle.signalAt = Date.now()
+      // the app's own exit hooks (onExit) run through exit.js's listener; ours only reports
+      const others = process.listeners(sig).filter((l) => l !== observer)
+      handle.transport.shutdown('signal', sig, true, 1000).then(() => {
+        if (others.length || process.listeners(sig).some((l) => l !== observer)) return
+        process.removeListener(sig, observer)
+        handle.observers.delete(sig)
+        if (process.pid === 1) process.exit(128 + SIGNAL_NUMBERS[sig])
+        else process.kill(process.pid, sig)
+      }, () => {})
+    }
+    try {
+      process.on(sig, observer)
+      handle.observers.set(sig, observer)
+    } catch (_) {}
+  }
+  handle.onExit = (code) => {
+    if (handle.destroyed) return
+    const r = exitReason(handle, code)
+    try {
+      handle.transport.shutdown(r.reason, r.signal, r.planned, 0)
+    } catch (_) {}
+  }
+  process.on('exit', handle.onExit)
+}
+
+function destroyRoot (handle) {
+  if (handle.destroyed) return
+  handle.destroyed = true
+  for (const [sig, fn] of handle.observers) process.removeListener(sig, fn)
+  handle.observers.clear()
+  if (handle.onExit) process.removeListener('exit', handle.onExit)
+  if (handle.capture) handle.capture.stop()
+  if (handle.hub) handle.hub.stop()
+  if (handle.closeThreads) handle.closeThreads()
+  try {
+    handle.transport.destroyAll()
+  } catch (_) {}
+  if (ROOT === handle) ROOT = null
+}
+
+// -- entry points -----------------------------------------------------------------------------------
+
+/** Called from PMX.init when standalone mode is wanted (NIO-260 a/c). Returns a transport or null. */
+function fromInit (instance, config) {
+  try {
+    const d = decide(config)
+    if (!d) return null
+    if (d.role === 'root') {
+      instance._mode = 'standalone'
+      instance._standalone = d.handle
+      d.handle.instance = instance
+      return d.handle.transport
+    }
+    instance._mode = 'relay'
+    instance._relayFactory = d.factory
+    startRelayCapture(instance)
+    return d.factory()
+  } catch (err) {
+    debug('activation failed: %s', err && err.message)
+    try {
+      process.stderr.write('[@pm2/io] standalone mode disabled: ' + (err && err.message) + '\n')
+    } catch (_) {}
+    return null
+  }
+}
+
+/** NIO-267: relays capture too (their chunks go to the root) when the root captures. */
+function startRelayCapture (instance) {
+  if (process.env.PMX_IO_CAPTURE_LOGS !== 'stdio' || instance._relayCapture) return
+  const { Capture } = require('./capture')
+  instance._relayCapture = new Capture((stream, text) => {
+    const t = instance._transport
+    if (t && typeof t.sendLog === 'function') t.sendLog(stream, text)
+  })
+  instance._relayCapture.start()
+}
+
+/** The standalone preload entries (NIO-261 b): `@aidra/pmx-io/standalone` and `standalone.mjs`. */
+function fromPreload () {
+  const env = process.env
+  const activate = require('../activate')
+  const s = activate.state()
+  if (s.active) return s
+  if (daemonChannel(env) || underPmx(env)) return null
+  if (env.pmx === 'false' || env.automation === 'false') return null
+  env.PMX_IO_STANDALONE = '1'
+  if (!env.PMX_IO_ROOT_PID && !env.PMX_IO_ROOT_PPID) env.PMX_IO_ROOT_PID = String(process.pid)
+  ensureNodeOptions(env)
+  const { GLOBAL_SYMBOL } = require('../constants')
+  if (Object.prototype.hasOwnProperty.call(globalThis, GLOBAL_SYMBOL)) return null
+  const { PMX } = require('../pmx')
+  let instance
+  if (!activate.isMainThread()) {
+    instance = new PMX({ mode: 'thread' })
+    s.role = 'thread'
+  } else {
+    instance = new PMX()
+    s.role = 'standalone'
+  }
+  s.instance = instance
+  s.active = true
+  activate.claimSingleton(instance)
+  instance.init({ standalone: true })
+  const conf = activate.secondInitConfig(env)
+  if (conf) instance.init(Object.assign({ standalone: true }, conf))
+  return s
+}
+
+module.exports = { decide, fromInit, fromPreload, isRoot, underPmx, ensureNodeOptions, exitReason, MISSING_LINE, UNREACHABLE_LINE, STANDALONE_CJS, TREE_ENV }

package/lib/standalone/capture.js

@@ -0,0 +1,55 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Log capture for standalone mode (80 NIO-267, `captureLogs: 'stdio'`): process.stdout.write and
+// process.stderr.write are wrapped in the root and in relays. Output written by native addons or
+// by child processes with inherited stdio directly to fds 1/2 is not captured (Node has no dup2,
+// so Python's `fd` mode has no equivalent, Part G.1). Capture never throws, never blocks the
+// writer and is re-entrancy guarded; the app's output is always written unchanged.
+
+class Capture {
+  /** @param {(stream: 'out'|'err', text: string) => void} sink */
+  constructor (sink) {
+    this._sink = sink
+    this._restore = null
+  }
+
+  start () {
+    if (this._restore) return
+    const originals = {}
+    let busy = false
+    const sink = this._sink
+    for (const [type, stream] of [['out', process.stdout], ['err', process.stderr]]) {
+      if (!stream || typeof stream.write !== 'function') continue
+      const orig = stream.write
+      originals[type] = { stream, orig }
+      stream.write = function write (chunk, encoding) {
+        if (!busy) {
+          busy = true
+          try {
+            let text
+            if (typeof chunk === 'string') text = chunk
+            // the encoding argument applies to strings only: bytes are written as they are
+            else if (chunk instanceof Uint8Array) text = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength).toString('utf8')
+            else text = String(chunk)
+            if (text) sink(type, text)
+          } catch (_) {
+          } finally {
+            busy = false
+          }
+        }
+        return orig.apply(this, arguments)
+      }
+    }
+    this._restore = () => {
+      for (const k of Object.keys(originals)) originals[k].stream.write = originals[k].orig
+    }
+  }
+
+  stop () {
+    if (this._restore) this._restore()
+    this._restore = null
+  }
+}
+
+module.exports = { Capture }