@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/features/notify.js

@@ -0,0 +1,358 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Errors: notifyError, framework handlers, uncaught capture (80 A.5.1–A.5.4, NIO-070..072).
+
+const fs = require('fs')
+const path = require('path')
+const { fileURLToPath } = require('url')
+const { PKG_DIR, isPlainObject } = require('../util')
+const debug = require('../debug')('axm:features:notify')
+
+const MAX_MESSAGE = 1000
+const CACHE_TTL_MS = 30 * 60 * 1000
+const REPORTED = Symbol.for('@pmx/io:reported')
+const REJECTION_PREFIX = 'You have triggered an unhandledRejection, you may have forgotten to catch a Promise rejection:'
+
+// ---- non-Error conversion (A.5.1) ----
+
+function toError (value) {
+  if (value instanceof Error) return value
+  if (value && typeof value === 'object' && typeof value.message === 'string' && typeof value.stack === 'string') return value
+  let message
+  try {
+    message = 'Non-error value: ' + JSON.stringify(value)
+  } catch (err) {
+    try {
+      message = 'Unserializable non-error value: ' + String(err)
+    } catch (_) {
+      message = 'Unserializable non-error value that cannot be converted to a string'
+    }
+  }
+  if (message.length > MAX_MESSAGE) message = message.slice(0, MAX_MESSAGE) + '...'
+  const e = new Error(message)
+  return e
+}
+
+// ---- source excerpt (A.5.4) ----
+
+const fileCache = new Map() // path -> { at, lines }
+
+function readLines (file) {
+  const now = Date.now()
+  const hit = fileCache.get(file)
+  if (hit && now - hit.at < CACHE_TTL_MS) return hit.lines
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/)
+  fileCache.set(file, { at: now, lines })
+  if (fileCache.size > 100) fileCache.delete(fileCache.keys().next().value)
+  return lines
+}
+
+const FRAME_RES = [
+  /\(([^()]*):(\d+):\d+\)$/, // at fn (/path/file.js:1:2)
+  /^at (.*):(\d+):\d+$/, // at /path/file.js:1:2
+  /^(\/.*|file:\/\/.*):(\d+)$/ // header line of a fatal exception: /path/file.js:3
+]
+
+function frames (stack) {
+  const out = []
+  for (const raw of String(stack).split('\n')) {
+    const line = raw.trim()
+    let m = null
+    for (const re of FRAME_RES) {
+      m = re.exec(line)
+      if (m) break
+    }
+    if (!m) continue
+    let file = m[1]
+    if (file.startsWith('async ')) file = file.slice(6)
+    if (file.startsWith('file://')) {
+      try {
+        file = fileURLToPath(file)
+      } catch (_) {
+        continue
+      }
+    }
+    out.push({ file, line: Number(m[2]) })
+  }
+  return out
+}
+
+const LIB_DIR = path.join(PKG_DIR, 'lib') + path.sep
+const LIB_ENTRIES = ['index.js', 'index.mjs', 'preload.cjs', 'preload.mjs'].map((f) => path.join(PKG_DIR, f))
+
+function isLibraryFile (abs) {
+  return abs.startsWith(LIB_DIR) || LIB_ENTRIES.includes(abs)
+}
+
+function sourceExcerpt (err) {
+  if (!err || typeof err.stack !== 'string') return null
+  for (const f of frames(err.stack)) {
+    if (!(path.isAbsolute(f.file) || f.file.startsWith('.'))) continue
+    if (f.file.includes('node_modules')) continue
+    const abs = path.resolve(f.file)
+    if (isLibraryFile(abs)) continue
+    let lines
+    try {
+      lines = readLines(abs)
+    } catch (_) {
+      return null
+    }
+    const idx = f.line - 1
+    if (idx < 0 || idx >= lines.length) return null
+    const before = lines.slice(Math.max(0, idx - 5), idx)
+    const current = lines[idx].replace(/\t/g, '  ').replace('  ', '>>')
+    const afterL = lines.slice(idx + 1, idx + 6)
+    return { callsite: `${f.file}:${f.line}`, context: before.concat([current], afterL).join('\n') }
+  }
+  return null
+}
+
+function addExcerpt (payload, err) {
+  try {
+    const ex = sourceExcerpt(err)
+    if (ex) {
+      payload.callsite = ex.callsite
+      payload.context = ex.context
+    }
+  } catch (e) {
+    debug('excerpt failed: %s', e && e.message)
+  }
+  return payload
+}
+
+function markReported (err) {
+  if (err && (typeof err === 'object' || typeof err === 'function')) {
+    try {
+      Object.defineProperty(err, REPORTED, { value: true, enumerable: false, configurable: true })
+    } catch (_) {}
+  }
+}
+
+/** NIO-259: the current span's ids, or null. */
+function currentTraceIds () {
+  const r = globalThis[Symbol.for('@pmx/io:context')]
+  if (!r || !r.als) return null
+  const store = r.als.getStore()
+  const span = store && store.span
+  if (!span || typeof span.traceId !== 'string' || typeof span.spanId !== 'string') return null
+  return { trace_id: span.traceId, span_id: span.spanId }
+}
+
+function addTraceIds (payload) {
+  const ids = currentTraceIds()
+  if (!ids) return payload
+  const meta = payload.metadata && typeof payload.metadata === 'object' ? payload.metadata : {}
+  if (meta.trace_id === undefined) meta.trace_id = ids.trace_id
+  if (meta.span_id === undefined) meta.span_id = ids.span_id
+  payload.metadata = meta
+  return payload
+}
+
+/** notifyError payload (A.5.1). */
+function notifyPayload (value, context) {
+  const err = toError(value)
+  const payload = {
+    message: err.message,
+    stack: err.stack,
+    name: err.name,
+    metadata: isPlainObject(context) ? context : {}
+  }
+  return addExcerpt(payload, err)
+}
+
+/** Uncaught payload (NIO-070): all JSON-serialisable own properties plus name/message/stack. */
+function uncaughtPayload (value) {
+  const err = toError(value)
+  const payload = {}
+  for (const key of Object.getOwnPropertyNames(err)) {
+    let v
+    try {
+      v = err[key]
+      if (typeof v === 'function' || typeof v === 'symbol' || v === undefined) continue
+      if (typeof v === 'bigint') continue
+      JSON.stringify(v)
+    } catch (_) {
+      continue
+    }
+    payload[key] = v
+  }
+  payload.name = err.name
+  payload.message = err.message
+  payload.stack = err.stack
+  return addExcerpt(payload, err)
+}
+
+class NotifyFeature {
+  /**
+   * @param {object} transport
+   * @param {boolean} capture install uncaught/unhandled handlers
+   */
+  constructor (transport) {
+    this._transport = transport
+    this._onUncaught = null
+    this._onRejection = null
+  }
+
+  setTracing (on) {
+    this._tracing = on === true
+  }
+
+  notifyError (err, context) {
+    const payload = notifyPayload(err, context)
+    if (this._tracing) addTraceIds(payload)
+    markReported(err)
+    this._transport.send('process:exception', payload)
+  }
+
+  /**
+   * Worker threads (NIO-293): reported through `uncaughtExceptionMonitor`, which does not change
+   * Node's default termination of the worker (no 'uncaughtException' listener is added).
+   */
+  enableThreadCapture () {
+    this._onMonitor = (err) => {
+      let payload
+      try {
+        payload = uncaughtPayload(err)
+      } catch (_) {
+        payload = { message: String(err && err.message) }
+      }
+      if (this._tracing) addTraceIds(payload)
+      try {
+        this._transport.send('process:exception', payload)
+      } catch (_) {}
+    }
+    process.on('uncaughtExceptionMonitor', this._onMonitor)
+  }
+
+  enableCapture () {
+    this._onUncaught = (err) => {
+      try {
+        console.error(err)
+      } catch (_) {}
+      const onlyListener = process.listeners('uncaughtException').length <= 1
+      let exited = false
+      const exit = () => {
+        if (exited) return
+        exited = true
+        if (onlyListener) process.exit(1)
+      }
+      let payload
+      try {
+        payload = uncaughtPayload(err)
+      } catch (_) {
+        payload = { message: String(err && err.message) }
+      }
+      if (this._tracing) addTraceIds(payload)
+      try {
+        const g = globalThis[Symbol.for('@pmx/io:standalone')]
+        if (g && typeof g.onUncaught === 'function') g.onUncaught(err)
+      } catch (_) {}
+      try {
+        this._transport.send('process:exception', payload, exit)
+      } catch (_) {}
+      if (onlyListener) {
+        // Exit after the send callback or 100 ms, whichever comes first (NIO-070).
+        setTimeout(exit, 100)
+      }
+    }
+    this._onRejection = (reason) => {
+      // NIO-070 uses the cluster wrapper's behaviour (40 §4.1) in both modes: a falsy reason
+      // (e.g. `Promise.reject()`) still prints the warning, followed by the value itself, and is
+      // reported as "No error but unhandledRejection was caught!" (70 T-INT-022/024, Q-NIO-030).
+      try {
+        console.error(REJECTION_PREFIX)
+        console.error(reason)
+      } catch (_) {}
+      let payload
+      if (!reason) {
+        payload = { message: 'No error but unhandledRejection was caught!' }
+      } else {
+        try {
+          payload = uncaughtPayload(reason)
+        } catch (_) {
+          payload = { message: String(reason && reason.message) }
+        }
+      }
+      if (this._tracing && payload) addTraceIds(payload)
+      try {
+        this._transport.send('process:exception', payload)
+      } catch (_) {}
+    }
+    process.on('uncaughtException', this._onUncaught)
+    process.on('unhandledRejection', this._onRejection)
+  }
+
+  expressErrorHandler () {
+    this._transport.send('axm:option:configuration', { error: true })
+    return (err, req, res, next) => {
+      try {
+        const e = toError(err)
+        const payload = {
+          message: e.message,
+          stack: e.stack,
+          name: e.name,
+          metadata: {
+            http: {
+              url: req.url,
+              params: req.params,
+              method: req.method,
+              query: req.query,
+              body: req.body,
+              path: req.path,
+              route: req.route && req.route.path !== undefined ? req.route.path : undefined
+            },
+            custom: { user: req.user && typeof req.user === 'object' ? req.user.id : undefined }
+          }
+        }
+        markReported(err)
+        this._transport.send('process:exception', payload)
+      } catch (_) {}
+      return next(err)
+    }
+  }
+
+  koaErrorHandler () {
+    this._transport.send('axm:option:configuration', { error: true })
+    return async (ctx, next) => {
+      try {
+        await next()
+      } catch (err) {
+        try {
+          const e = toError(err)
+          const request = ctx.request || {}
+          markReported(err)
+          this._transport.send('process:exception', {
+            message: e.message,
+            stack: e.stack,
+            name: e.name,
+            metadata: {
+              http: {
+                url: request.url,
+                params: ctx.params,
+                method: request.method,
+                query: request.query,
+                body: request.body,
+                path: request.path,
+                route: ctx._matchedRoute
+              },
+              custom: { user: ctx.user && typeof ctx.user === 'object' ? ctx.user.id : undefined }
+            }
+          })
+        } catch (_) {}
+        throw err
+      }
+    }
+  }
+
+  destroy () {
+    if (this._onUncaught) process.removeListener('uncaughtException', this._onUncaught)
+    if (this._onRejection) process.removeListener('unhandledRejection', this._onRejection)
+    if (this._onMonitor) process.removeListener('uncaughtExceptionMonitor', this._onMonitor)
+    this._onMonitor = null
+    this._onUncaught = null
+    this._onRejection = null
+  }
+}
+
+module.exports = { NotifyFeature, toError, sourceExcerpt, notifyPayload, uncaughtPayload, REJECTION_PREFIX, REPORTED, markReported }

package/lib/features/profiling.js

@@ -0,0 +1,208 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Remote-triggered profiling through the built-in inspector (80 A.7, NIO-077, 02 D-06).
+
+const { shortUuid } = require('../util')
+const debug = require('../debug')('axm:features:profiling')
+
+const DISABLED_FLAGS = {
+  heapdump: false,
+  'feature.profiler.heap_snapshot': false,
+  'feature.profiler.heap_sampling': false,
+  'feature.profiler.cpu_js': false
+}
+const ENABLED_FLAGS = {
+  heapdump: true,
+  'feature.profiler.heapsnapshot': false,
+  'feature.profiler.heapsampling': true,
+  'feature.profiler.cpu_js': true
+}
+
+function canUseInspector () {
+  if (process.versions.bun) return false
+  // process.features.inspector tells without loading the module (keeps startup cheap).
+  if (process.features && typeof process.features.inspector === 'boolean') return process.features.inspector
+  try {
+    const inspector = require('inspector')
+    return typeof inspector.Session === 'function'
+  } catch (_) {
+    return false
+  }
+}
+
+function initiatedOf (opts) {
+  return opts && typeof opts.initiated === 'string' ? opts.initiated : 'manual'
+}
+
+function timeoutOf (opts) {
+  if (!opts) return null
+  const t = typeof opts.timeout === 'string' ? Number(opts.timeout) : opts.timeout
+  return typeof t === 'number' && Number.isFinite(t) && t > 0 ? t : null
+}
+
+class ProfilingFeature {
+  constructor (transport, actions) {
+    this._transport = transport
+    this._actions = actions
+    this._session = null
+    this._available = false
+    this._running = null // { kind: 'cpu'|'heap', uuid, at, initiated, timer, started }
+    this._enabling = null
+  }
+
+  /**
+   * IO-005 step 2: decide whether the inspector is usable. The in-process session itself is
+   * connected on first use, so that an instrumented app that is never profiled pays nothing.
+   */
+  connect () {
+    this._available = canUseInspector()
+    return this._available
+  }
+
+  _ensureSession () {
+    if (this._session) return true
+    if (!this._available) return false
+    try {
+      const inspector = require('inspector')
+      const session = new inspector.Session()
+      session.connect()
+      this._session = session
+      return true
+    } catch (err) {
+      debug('inspector unusable: %s', err && err.message)
+      this._available = false
+      return false
+    }
+  }
+
+  /** Enable the Profiler and HeapProfiler domains on first use (keeps init cheap). */
+  _enable () {
+    if (!this._enabling) {
+      this._enabling = Promise.all([this._post('Profiler.enable'), this._post('HeapProfiler.enable')])
+    }
+    return this._enabling
+  }
+
+  _post (method, params) {
+    return new Promise((resolve, reject) => {
+      if (!this._session) return reject(new Error('Profiler not available'))
+      this._session.post(method, params || {}, (err, res) => (err ? reject(err) : resolve(res)))
+    })
+  }
+
+  /** Register the five actions (after sending the profiler flags). */
+  init () {
+    if (!this._available) {
+      if (!process.versions.bun) console.error('Failed to require the profiler via inspector, disabling profiling ...')
+      this._transport.send('axm:option:configuration', DISABLED_FLAGS)
+      return false
+    }
+    this._transport.send('axm:option:configuration', ENABLED_FLAGS)
+    const a = this._actions
+    a.register('km:heapdump', undefined, (opts, reply) => this._heapdump(opts, reply))
+    a.register('km:cpu:profiling:start', undefined, (opts, reply) => this._start('cpu', opts, reply))
+    a.register('km:cpu:profiling:stop', undefined, (reply) => this._stop('cpu', reply))
+    a.register('km:heap:sampling:start', undefined, (opts, reply) => this._start('heap', opts, reply))
+    a.register('km:heap:sampling:stop', undefined, (reply) => this._stop('heap', reply))
+    return true
+  }
+
+  _start (kind, opts, reply) {
+    if (!this._ensureSession()) return reply({ err: 'Profiler not available', success: false })
+    if (this._running) return reply({ err: 'A profiling is already running', success: false })
+    const uuid = shortUuid()
+    const run = { kind, uuid, at: Date.now(), initiated: initiatedOf(opts), timer: null }
+    this._running = run
+    reply({ success: true, uuid })
+    const samplingInterval = Number(opts && opts.samplingInterval) > 0 ? Number(opts.samplingInterval) : 16384
+    const started = this._enable().then(() => kind === 'cpu'
+      ? this._post('Profiler.start')
+      : this._post('HeapProfiler.startSampling', { samplingInterval }))
+    started.catch((err) => {
+      debug('profiler start failed: %s', err && err.message)
+      if (this._running === run) this._running = null
+    })
+    const timeout = timeoutOf(opts)
+    if (timeout) {
+      run.timer = setTimeout(() => {
+        if (this._running === run) this._finish(run).catch(() => {})
+      }, timeout)
+      if (run.timer.unref) run.timer.unref()
+    }
+  }
+
+  _stop (kind, reply) {
+    const run = this._running
+    if (!run || run.kind !== kind) return reply({ err: 'No profiling are already running', success: false })
+    reply({ success: true, uuid: run.uuid })
+    this._finish(run).catch((err) => debug('profiler stop failed: %s', err && err.message))
+  }
+
+  async _finish (run) {
+    if (run.timer) clearTimeout(run.timer)
+    this._running = null
+    let profile
+    if (run.kind === 'cpu') {
+      profile = (await this._post('Profiler.stop')).profile
+    } else {
+      profile = (await this._post('HeapProfiler.stopSampling')).profile
+    }
+    const type = run.kind === 'cpu' ? 'cpuprofile' : 'heapprofile'
+    const payload = {
+      uuid: run.uuid,
+      duration: Date.now() - run.at,
+      at: run.at,
+      data: JSON.stringify(profile),
+      success: true,
+      initiated: run.initiated,
+      type
+    }
+    payload[type] = true
+    this._transport.send('profilings', payload)
+  }
+
+  _heapdump (opts, reply) {
+    if (!this._ensureSession()) return reply({ err: 'Profiler not available', success: false })
+    reply({ success: true })
+    const at = Date.now()
+    const initiated = initiatedOf(opts)
+    const t = setTimeout(() => {
+      const chunks = []
+      const onChunk = (m) => chunks.push(m.params.chunk)
+      this._session.on('HeapProfiler.addHeapSnapshotChunk', onChunk)
+      this._enable().then(() => this._post('HeapProfiler.takeHeapSnapshot', { reportProgress: false }))
+        .then(() => {
+          this._session.removeListener('HeapProfiler.addHeapSnapshotChunk', onChunk)
+          this._transport.send('profilings', {
+            data: chunks.join(''),
+            at,
+            initiated,
+            duration: Date.now() - at,
+            type: 'heapdump'
+          })
+        }, (err) => {
+          this._session.removeListener('HeapProfiler.addHeapSnapshotChunk', onChunk)
+          reply({ success: err && err.message, err })
+        })
+    }, 200)
+    if (t.unref) t.unref()
+  }
+
+  destroy () {
+    if (this._running) {
+      if (this._running.timer) clearTimeout(this._running.timer)
+      const kind = this._running.kind
+      this._running = null
+      this._post(kind === 'cpu' ? 'Profiler.stop' : 'HeapProfiler.stopSampling').catch(() => {})
+    }
+    if (this._session) {
+      try {
+        this._session.disconnect()
+      } catch (_) {}
+    }
+    this._session = null
+  }
+}
+
+module.exports = { ProfilingFeature, canUseInspector, DISABLED_FLAGS, ENABLED_FLAGS }