@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/standalone/transport.js

@@ -0,0 +1,1023 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The standalone root's prodman transport (80 NIO-262..NIO-269; prodman spec 11 APM-001…053;
+// 95 §1–§4): configuration, handshake, WebSocket session, status, channels, commands, logs and
+// shutdown. The instance keeps sending IPC-shaped messages (`send(type, data)`); `axm:monitor`,
+// `axm:action` and `axm:option:configuration` feed the next `status`, other types become packets.
+
+const os = require('os')
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+const { VERSION } = require('../constants')
+const container = require('./container')
+const debug = require('../debug')('axm:standalone')
+
+const IO_VERSION = '@pm2/io ' + VERSION
+const STATUS_INTERVAL = 1000
+const PING_INTERVAL = 5000
+const PONG_TIMEOUT = 20000
+const OFFLINE_QUEUE = 200
+const SEND_QUEUE = 1000
+// bytes the socket may hold unsent before packets wait in the (bounded) queue instead
+const MAX_BUFFERED = 1024 * 1024
+const RING = 200
+const LOG_BATCH_MS = 250
+const LOG_BATCH_BYTES = 64 * 1024
+const LOG_BATCH_MAX = 4 * 1024 * 1024
+const LOG_LINES_PER_SECOND = 2000
+const LOG_DROP_REPORT_MS = 60000
+const NOT_QUEUED = ['status', 'logs', 'trace-span', 'trace-spans']
+const REFUSAL = '%s is not available: %s runs without PM2 (@pm2/io standalone)'
+
+// -- configuration (NIO-262) ----------------------------------------------------------------------
+
+const IPV4 = /^\d+\.\d+\.\d+\.\d+(:\d+)?(\/|$)/
+
+function resolveUrl (configured, env) {
+  env = env || process.env
+  let raw = null
+  for (const v of [configured, env.PRODMAN_URL, env.KEYMETRICS_NODE]) {
+    if (typeof v === 'string' && v.trim()) {
+      raw = v.trim()
+      break
+    }
+  }
+  if (raw === null) raw = 'https://pmx.aidra.io'
+  if (!raw.includes('://')) {
+    const host = raw.split('/')[0]
+    const plain = host === 'localhost' || host.startsWith('localhost:') || IPV4.test(raw) || host.startsWith('[')
+    raw = (plain ? 'http://' : 'https://') + raw
+  }
+  return raw.replace(/\/+$/, '')
+}
+
+function serverName (cfg, info, host) {
+  const app = cfg.appName || null
+  const h = host || container.hostname()
+  info = info || new container.ContainerInfo({ inContainer: false, runtime: 'unknown', orchestrator: 'none' })
+  if (cfg.explicitServerName) return container.expand(String(cfg.explicitServerName), info.nameContext(app, h))
+  const dflt = info.defaultMachineName(app, h)
+  if (dflt) return dflt
+  if (!app) return null
+  return container.truncateName(`${app}@${h}`)
+}
+
+/** Environment (APM-010) overlaid by `apmOptions` (options win); `base` = a resolved config. */
+function resolveConfig (apmOptions, env, info, base) {
+  env = env || process.env
+  const o = apmOptions && typeof apmOptions === 'object' ? apmOptions : {}
+  const b = base || null
+  const opt = (k) => (o[k] !== undefined && o[k] !== null && o[k] !== '' ? o[k] : undefined)
+  const pick = (k, envName) => {
+    const v = opt(k)
+    if (v !== undefined) return v
+    if (b && b[k]) return b[k]
+    return env[envName] || null
+  }
+  const cfg = {}
+  cfg.url = resolveUrl(opt('url') || (b ? b.url : undefined), env)
+  cfg.publicKey = pick('publicKey', 'PM2_PUBLIC_KEY')
+  cfg.secretKey = pick('secretKey', 'PM2_SECRET_KEY')
+  cfg.appName = pick('appName', 'PM2_APP_NAME')
+  let explicit = opt('serverName')
+  if (explicit === undefined && b) explicit = b.explicitServerName
+  if (explicit === undefined || explicit === null) explicit = env.PM2_MACHINE_NAME || null
+  cfg.explicitServerName = explicit
+  cfg.sendLogs = opt('sendLogs') !== undefined ? Boolean(o.sendLogs) : Boolean(b && b.sendLogs)
+  cfg.disableLogs = opt('disableLogs') !== undefined ? Boolean(o.disableLogs) : Boolean(b && b.disableLogs)
+  let cap = opt('captureLogs')
+  if (cap === undefined) cap = b ? b.captureLogs : (env.PMX_IO_CAPTURE_LOGS || 'stdio')
+  cap = String(cap).toLowerCase()
+  if (cap === 'false' || cap === 'none' || cap === '0') cap = 'off'
+  if (cap === 'sys') cap = 'stdio'
+  if (cap !== 'stdio' && cap !== 'off') {
+    debug('unknown captureLogs %s, using stdio', cap)
+    cap = 'stdio'
+  }
+  if (cfg.disableLogs) cap = 'off'
+  cfg.captureLogs = cap
+  const lf = opt('logFilter')
+  cfg.logFilter = lf !== undefined ? lf : (b ? b.logFilter : undefined)
+  let proxy = opt('proxy')
+  if (proxy === undefined) proxy = b ? b.proxy : (env.PMX_IO_PROXY || null)
+  cfg.proxy = proxy || null
+  cfg.missing = [['PM2_PUBLIC_KEY', 'publicKey'], ['PM2_SECRET_KEY', 'secretKey'], ['PM2_APP_NAME', 'appName']].filter(([, k]) => !cfg[k]).map(([n]) => n)
+  for (const k of ['publicKey', 'secretKey', 'appName']) if (cfg[k] !== null) cfg[k] = String(cfg[k])
+  cfg.serverName = serverName(cfg, info)
+  return cfg
+}
+
+function matchesFilter (flt, text) {
+  if (flt === undefined || flt === null || flt === '') return false
+  if (typeof flt === 'string') return text.includes(flt)
+  if (flt instanceof RegExp) {
+    flt.lastIndex = 0
+    return flt.test(text)
+  }
+  return false
+}
+
+function redact (url) {
+  try {
+    const u = new URL(url)
+    if (u.username || u.password) {
+      u.username = '***'
+      u.password = ''
+    }
+    return u.href
+  } catch (_) {
+    return '<url>'
+  }
+}
+
+// -- footprint (NIO-263) --------------------------------------------------------------------------
+
+function procCpuTicks (pid) {
+  let data
+  try {
+    data = fs.readFileSync(`/proc/${pid}/stat`, 'latin1')
+  } catch (_) {
+    return null
+  }
+  const rp = data.lastIndexOf(')')
+  if (rp < 0) return null
+  const f = data.slice(rp + 2).split(' ')
+  if (f[0] === 'Z') return null
+  const u = Number(f[11])
+  const s = Number(f[12])
+  return Number.isFinite(u) && Number.isFinite(s) ? u + s : null
+}
+
+function procMemory (pid) {
+  try {
+    const t = fs.readFileSync(`/proc/${pid}/smaps_rollup`, 'latin1')
+    const m = /^Pss:\s+(\d+)/m.exec(t)
+    if (m) return Number(m[1]) * 1024
+  } catch (_) {}
+  try {
+    const t = fs.readFileSync(`/proc/${pid}/statm`, 'latin1').split(' ')
+    return Number(t[1]) * 4096
+  } catch (_) {
+    return null
+  }
+}
+
+class Footprint {
+  constructor (relayPids) {
+    this.relayPids = relayPids
+    this.linux = fs.existsSync(`/proc/${process.pid}/stat`)
+    this.tck = 100
+    this._prev = new Map()
+    this._prevT = null
+    this._prevSelf = null
+  }
+
+  sample () {
+    const now = Date.now() / 1000
+    const dt = this._prevT !== null ? now - this._prevT : 0
+    this._prevT = now
+    if (!this.linux) {
+      const u = process.cpuUsage()
+      const t = (u.user + u.system) / 1e6
+      const prev = this._prevSelf
+      this._prevSelf = t
+      const cpu = prev !== null && dt > 0 ? Math.max(0, (t - prev) / dt * 100) : 0
+      return { cpu: Math.round(cpu * 10) / 10, memory: process.memoryUsage().rss }
+    }
+    const pids = [process.pid]
+    try {
+      for (const p of this.relayPids()) if (!pids.includes(p)) pids.push(p)
+    } catch (_) {}
+    let ticks = 0
+    let mem = 0
+    const seen = new Map()
+    for (const pid of pids) {
+      const t = procCpuTicks(pid)
+      if (t === null) continue
+      const m = procMemory(pid)
+      if (m !== null) mem += m
+      const prev = this._prev.get(pid)
+      if (prev !== undefined) ticks += Math.max(0, t - prev)
+      seen.set(pid, t)
+    }
+    this._prev = seen
+    const cpu = dt > 0 ? (ticks / this.tck) / dt * 100 : 0
+    return { cpu: Math.round(cpu * 10) / 10, memory: mem }
+  }
+}
+
+// -- host facts -----------------------------------------------------------------------------------
+
+function username () {
+  for (const k of ['SUDO_USER', 'C9_USER', 'LOGNAME', 'USER', 'LNAME', 'USERNAME']) if (process.env[k]) return process.env[k]
+  try {
+    return os.userInfo().username
+  } catch (_) {
+    return null
+  }
+}
+
+function cpuModel () {
+  const c = os.cpus()
+  return c && c[0] ? c[0].model : null
+}
+
+function appVersion () {
+  if (process.env.PMX_APP_VERSION) return process.env.PMX_APP_VERSION
+  try {
+    const { readPackageJsonSync } = require('../util')
+    const pkg = readPackageJsonSync()
+    if (pkg && typeof pkg.version === 'string') return pkg.version
+  } catch (_) {}
+  return null
+}
+
+function backoff (baseMs, attempt) {
+  const ms = Math.min(60000, baseMs * Math.pow(2, attempt))
+  return Math.round(ms * (0.8 + Math.random() * 0.4))
+}
+
+function countLines (text) {
+  const n = text.split('\n').length - (text.endsWith('\n') ? 1 : 0)
+  return n || 1
+}
+
+// -- transport ------------------------------------------------------------------------------------
+
+class ProdmanTransport {
+  /**
+   * @param {object} cfg resolveConfig() result
+   * @param {object} info ContainerInfo
+   * @param {{relayPids?: Function}} [opts]
+   */
+  constructor (cfg, info, opts) {
+    opts = opts || {}
+    this.kind = 'standalone'
+    this.cfg = cfg
+    this.info = info
+    this._listeners = []
+    this._pending = [] // [channel, text, cb]
+    this.tracingLayer = null // 80 NIO-298 (prodman `tracing` key for this app)
+    this._ws = null
+    this._connecting = false
+    this._stopping = false
+    this._closed = false
+    this._timers = { status: null, ping: null, retry: null, logs: null }
+    this._hsAttempt = 0
+    this._wsAttempt = 0
+    this._lastRefusal = null
+    this.collectLogs = false
+    this._batchSupported = false
+    this.ring = { out: [], err: [] }
+    this._batch = { out: [], err: [] }
+    this._batchBytes = 0
+    this._batchSince = null
+    this._windowStart = 0
+    this._windowLines = 0
+    this._droppedLines = 0
+    this._dropReportedAt = null
+    this.monitor = {}
+    this.actions = new Map()
+    this.options = {}
+    this.startedAt = Date.now()
+    this.uniqueId = crypto.randomBytes(12).toString('hex')
+    this.serverUniqueId = crypto.randomBytes(16).toString('hex')
+    this.footprint = new Footprint(opts.relayPids || (() => []))
+    this.hostMetrics = new container.HostMetrics(info)
+    this._shutdownPayload = null
+    this._shutdownSentOn = null
+    this._ip = null
+    this.statusCount = 0
+  }
+
+  get server () {
+    return this.cfg.serverName
+  }
+
+  get appName () {
+    return this.cfg.appName
+  }
+
+  /** pmx 97 PAP-050: the application (init option > PMX_APPLICATION > default). */
+  get application () {
+    return require('../application').current()
+  }
+
+  /** PAP-050: init decided the application; the tracing layer is resolved again for it. */
+  setApplication () {
+    if (this._tracingBlock !== undefined) this._applyTracing(this._tracingBlock)
+  }
+
+  ref () {
+    return { pm_id: 0, name: this.cfg.appName, application: this.application, rev: null, server: this.cfg.serverName }
+  }
+
+  batchSupported () {
+    return this._batchSupported
+  }
+
+  init () {
+    return this
+  }
+
+  start () {
+    this._schedule(() => this._run(), 0)
+  }
+
+  reconfigure (cfg) {
+    const reconnect = cfg.url !== this.cfg.url || cfg.publicKey !== this.cfg.publicKey || cfg.secretKey !== this.cfg.secretKey ||
+      cfg.serverName !== this.cfg.serverName || cfg.proxy !== this.cfg.proxy
+    this.cfg = cfg
+    if (reconnect && this._ws) this._ws.terminate()
+  }
+
+  // -- connection -----------------------------------------------------------------------------
+
+  _schedule (fn, ms) {
+    if (this._stopping) return
+    clearTimeout(this._timers.retry)
+    this._timers.retry = setTimeout(fn, ms)
+    if (this._timers.retry.unref) this._timers.retry.unref()
+  }
+
+  async _run () {
+    if (this._stopping || this._ws || this._connecting) return
+    this._connecting = true
+    try {
+      if (this.info.ecsPending()) {
+        try {
+          await this.info.fetchEcs()
+          const name = serverName(this.cfg, this.info)
+          if (name) this.cfg = Object.assign({}, this.cfg, { serverName: name })
+        } catch (err) {
+          debug('ECS metadata failed: %s', err && err.message)
+        }
+      }
+      debug('prodman %s as %s (app %s)', redact(this.cfg.url), this.server, this.appName)
+      let hs
+      try {
+        hs = await this._handshake()
+      } catch (err) {
+        this._connecting = false
+        if (err && err.refused) {
+          if (err.message !== this._lastRefusal) {
+            this._lastRefusal = err.message
+            try {
+              process.stderr.write(`[@pm2/io] prodman refused the connection: ${err.message}\n`)
+            } catch (_) {}
+          }
+        }
+        const delay = backoff(1000, this._hsAttempt++)
+        debug('handshake failed (%s), retrying in %d ms', err && err.message, delay)
+        this._schedule(() => this._run(), delay)
+        return
+      }
+      this._hsAttempt = 0
+      this._lastRefusal = null
+      if (hs.collectLogs) this.collectLogs = true
+      this._batchSupported = hs.traceSpansBatch
+      this._applyTracing(hs.tracing)
+      this._connect(hs.endpoint)
+    } catch (err) {
+      this._connecting = false
+      debug('connection failed: %s', err && err.message)
+      this._schedule(() => this._run(), backoff(5000, this._wsAttempt++))
+    }
+  }
+
+  handshakeBody () {
+    const limits = this.hostMetrics.limits()
+    const n = this.info.inContainer() ? limits.cpusRoundedUp() : (os.cpus() || []).length || 1
+    const model = cpuModel() || 'unknown'
+    const cpus = []
+    for (let i = 0; i < n; i++) cpus.push({ model, speed: 0 })
+    return {
+      public_id: this.cfg.publicKey,
+      private_id: this.cfg.secretKey,
+      data: {
+        MACHINE_NAME: this.server,
+        PUBLIC_KEY: this.cfg.publicKey,
+        RECYCLE: false,
+        PM2_VERSION: null,
+        IO_VERSION,
+        MEMORY: Math.floor(limits.memoryBytes / 1048576),
+        HOSTNAME: container.hostname(),
+        CPUS: cpus
+      }
+    }
+  }
+
+  async _handshake () {
+    const { httpRequest } = require('../transport/ws')
+    const body = JSON.stringify(this.handshakeBody())
+    const res = await httpRequest('POST', this.cfg.url + '/api/node/verifyPM2', body, {
+      'Content-Type': 'application/json',
+      'User-Agent': '@pmx/io/' + VERSION,
+      Accept: 'application/json'
+    }, { timeout: 15000, proxy: this.cfg.proxy || undefined })
+    let doc
+    try {
+      doc = JSON.parse(res.body.toString('utf8'))
+    } catch (_) {
+      throw new Error(`handshake: HTTP ${res.status}, not JSON`)
+    }
+    const ws = doc && doc.endpoints && typeof doc.endpoints.ws === 'string' ? doc.endpoints.ws : null
+    if (!doc || doc.active !== true || !ws) {
+      const e = new Error((doc && typeof doc.msg === 'string' && doc.msg) || 'bucket not active')
+      e.refused = true
+      throw e
+    }
+    const p = doc.prodman && typeof doc.prodman === 'object' ? doc.prodman : {}
+    return { endpoint: ws, collectLogs: p.collect_logs === true, traceSpansBatch: p.trace_spans_batch === true, tracing: p.tracing }
+  }
+
+  _pongTimeout () {
+    const v = Number(process.env.PRODMAN_WS_TIMEOUT)
+    return Number.isFinite(v) && v > 0 ? v : PONG_TIMEOUT
+  }
+
+  _connect (endpoint) {
+    if (this._stopping) {
+      this._connecting = false
+      return
+    }
+    const { WebSocketClient } = require('../transport/ws')
+    const ws = new WebSocketClient(endpoint, {
+      'X-KM-PUBLIC': this.cfg.publicKey,
+      'X-KM-SECRET': this.cfg.secretKey,
+      'X-KM-SERVER': this.server,
+      'X-PM2-VERSION': IO_VERSION,
+      'X-PROTOCOL-VERSION': '1',
+      'User-Agent': '@pmx/io/' + VERSION
+    }, { proxy: this.cfg.proxy || undefined })
+    let lastSeen = Date.now()
+    let opened = false
+    ws.on('open', () => {
+      opened = true
+      this._ws = ws
+      this._connecting = false
+      this._wsAttempt = 0
+      debug('connected to %s', redact(endpoint))
+      try {
+        const addr = ws._socket && ws._socket.localAddress
+        if (typeof addr === 'string' && addr.includes('.') && !addr.startsWith('127.')) this._ip = addr
+      } catch (_) {}
+      this._sendStatus(true)
+      if (this._shutdownPayload && this._shutdownSentOn !== ws) {
+        // CTR-022: re-sent on a new connection while the shutdown is in progress
+        this._pending.unshift(['agent:shutdown', JSON.stringify({ channel: 'agent:shutdown', payload: this._shutdownPayload }), null])
+      }
+      this._drain()
+      this._timers.status = setInterval(() => this._sendStatus(false), STATUS_INTERVAL)
+      if (this._timers.status.unref) this._timers.status.unref()
+      this._timers.ping = setInterval(() => {
+        if (Date.now() - lastSeen > this._pongTimeout()) return ws.terminate()
+        ws.ping()
+      }, PING_INTERVAL)
+      if (this._timers.ping.unref) this._timers.ping.unref()
+      this._timers.logs = setInterval(() => this._flushLogs(false), LOG_BATCH_MS)
+      if (this._timers.logs.unref) this._timers.logs.unref()
+    })
+    ws.on('drain', () => this._drain())
+    ws.on('pong', () => { lastSeen = Date.now() })
+    ws.on('ping', () => { lastSeen = Date.now() })
+    ws.on('message', (text) => {
+      lastSeen = Date.now()
+      this._onText(text)
+    })
+    ws.on('error', (err) => debug('socket error: %s', err && err.message))
+    ws.on('close', () => {
+      if (!opened) this._connecting = false
+      if (this._ws === ws) this._disconnected()
+      if (this._stopping) return
+      const delay = backoff(5000, this._wsAttempt++)
+      debug('connection closed, reconnecting in %d ms', delay)
+      this._schedule(() => this._run(), delay)
+    })
+  }
+
+  _disconnected () {
+    this._ws = null
+    clearInterval(this._timers.status)
+    clearInterval(this._timers.ping)
+    clearInterval(this._timers.logs)
+    this._trimOffline()
+    this._batch = { out: [], err: [] }
+    this._batchBytes = 0
+    this._batchSince = null
+  }
+
+  _connected () {
+    return Boolean(this._ws && this._ws.readyState === 1)
+  }
+
+  // -- queue ----------------------------------------------------------------------------------
+
+  _lost (entry) {
+    if (entry && entry[2]) {
+      try {
+        entry[2](new Error('not delivered'))
+      } catch (_) {}
+    }
+  }
+
+  _trimOffline () {
+    const kept = []
+    for (const e of this._pending) {
+      if (NOT_QUEUED.includes(e[0])) this._lost(e)
+      else kept.push(e)
+    }
+    while (kept.length > OFFLINE_QUEUE) kept.shift()
+    this._pending = kept
+  }
+
+  _evict () {
+    const q = this._pending
+    for (const wanted of ['status', 'logs', 'trace-span', 'trace-spans']) {
+      const i = q.findIndex((e) => e[0] === wanted)
+      if (i !== -1) return this._lost(q.splice(i, 1)[0])
+    }
+    const i = q.findIndex((e) => e[0] !== 'process:exception' && e[0] !== 'agent:shutdown')
+    if (i !== -1) this._lost(q.splice(i, 1)[0])
+  }
+
+  _drain () {
+    // a slow prodman leaves data in the socket: stop at MAX_BUFFERED (resumed on 'drain') so the
+    // queue's bounds and eviction apply instead of an unbounded socket buffer
+    while (this._pending.length && this._connected() && this._ws.bufferedAmount() < MAX_BUFFERED) {
+      const [ch, text, cb] = this._pending.shift()
+      if (ch === 'agent:shutdown') this._shutdownSentOn = this._ws
+      if (!this._ws.send(text, cb ? (err) => cb(err) : undefined)) {
+        this._pending.unshift([ch, text, cb])
+        return
+      }
+    }
+  }
+
+  /** Queue or write one packet. While disconnected only APM-026 channels are kept (≤ 200). */
+  packet (channel, payload, cb, front) {
+    let text
+    try {
+      text = JSON.stringify({ channel, payload })
+    } catch (err) {
+      debug('cannot encode %s: %s', channel, err && err.message)
+      if (cb) process.nextTick(cb, err)
+      return false
+    }
+    if (this._closed) {
+      if (cb) process.nextTick(cb, new Error('closed'))
+      return false
+    }
+    if (!this._connected()) {
+      if (NOT_QUEUED.includes(channel)) {
+        if (cb) process.nextTick(cb, new Error('not connected'))
+        return false
+      }
+      this._pending.push([channel, text, cb])
+      this._trimOffline()
+      return true
+    }
+    if (this._pending.length >= SEND_QUEUE) this._evict()
+    // only exceptions and agent:shutdown are left: drop the oldest exception (hard bound)
+    if (this._pending.length >= SEND_QUEUE * 2) this._lost(this._pending.splice(this._pending.findIndex((e) => e[0] !== 'agent:shutdown'), 1)[0])
+    if (front) this._pending.unshift([channel, text, cb])
+    else this._pending.push([channel, text, cb])
+    this._drain()
+    return true
+  }
+
+  // -- the instance's messages ----------------------------------------------------------------
+
+  send (type, data, cb) {
+    try {
+      return this._route(type, data, cb)
+    } catch (err) {
+      debug('send failed: %s', err && err.message)
+      if (cb) process.nextTick(cb, err)
+      return false
+    }
+  }
+
+  _route (type, data, cb) {
+    const done = () => {
+      if (cb) process.nextTick(cb)
+      return true
+    }
+    switch (type) {
+      case 'axm:monitor':
+        if (data && typeof data === 'object') this.monitor = data
+        return done()
+      case 'axm:action':
+        if (data && typeof data.action_name === 'string') this.actions.set(data.action_name, data)
+        return done()
+      case 'axm:option:configuration':
+        if (data && typeof data === 'object') Object.assign(this.options, data)
+        return done()
+      case 'human:event': {
+        const d = Object.assign({}, data)
+        const name = d.__name
+        delete d.__name
+        return this.packet('human:event', { at: Date.now(), name: typeof name === 'string' ? name : 'event', data: d, process: this.ref() }, cb)
+      }
+      case 'process:exception': {
+        const payload = Object.assign({}, data)
+        if (payload.last_logs === undefined && this.cfg.captureLogs !== 'off') {
+          payload.last_logs = this.ring.err.slice(-20).concat(this.ring.out.slice(-20))
+        }
+        return this.packet('process:exception', { at: Date.now(), data: payload, process: this.ref() }, cb)
+      }
+      case 'trace-span':
+      case 'trace-spans':
+      case 'axm:reply':
+      case 'profilings':
+      case 'application:dependencies':
+        return this.packet(type, { at: Date.now(), data, process: this.ref() }, cb)
+      case 'ready':
+        return this.packet('ready', { at: Date.now(), data: {}, process: this.ref() }, cb)
+      default:
+        if (typeof type === 'string' && type.startsWith('axm:scoped_action:')) return this.packet(type, { at: Date.now(), data, process: this.ref() }, cb)
+        debug('not forwarded to prodman: %s', type)
+        return done()
+    }
+  }
+
+  sendRaw (msg, cb) {
+    if (msg === 'ready') return this.send('ready', {}, cb)
+    if (msg && typeof msg === 'object' && typeof msg.type === 'string') return this.send(msg.type, msg.data, cb)
+    if (cb) process.nextTick(cb)
+    return false
+  }
+
+  onMessage (fn) {
+    this._listeners.push(fn)
+  }
+
+  offMessage (fn) {
+    this._listeners = this._listeners.filter((f) => f !== fn)
+  }
+
+  isConnected () {
+    return true
+  }
+
+  /** IPC transports are destroyed on re-init; the prodman connection is not (see destroyAll). */
+  destroy () {
+    this._listeners = []
+  }
+
+  // -- status (NIO-265) -----------------------------------------------------------------------
+
+  statusPayload () {
+    const fp = this.footprint.sample()
+    let options = this.options
+    try {
+      if (JSON.stringify(options).length > 8192) options = {}
+    } catch (_) {
+      options = {}
+    }
+    const limits = this.hostMetrics.limits()
+    const host = container.hostname()
+    const user = username()
+    const bun = typeof process.versions.bun === 'string'
+    const script = process.argv[1] || null
+    const runtime = {
+      kind: bun ? 'bun' : 'node',
+      version: bun ? process.versions.bun : process.versions.node,
+      versionSource: 'process',
+      interpreter: bun ? 'bun' : 'node',
+      interpreterPath: process.execPath,
+      interpreterArgs: [],
+      nodeArgs: process.execArgv,
+      virtualenv: null,
+      script,
+      args: process.argv.slice(2),
+      cwd: safeCwd(),
+      execMode: 'standalone',
+      instances: 1,
+      user,
+      nodeEnv: process.env.NODE_ENV || null,
+      watch: false,
+      autorestart: false,
+      maxMemoryRestart: null,
+      killTimeout: null,
+      cronRestart: null,
+      mergeLogs: false
+    }
+    if (this._version === undefined) this._version = appVersion()
+    const proc = {
+      pid: process.pid,
+      name: this.appName,
+      pm_id: 0,
+      status: 'online',
+      exec_mode: 'fork_mode',
+      restart_time: 0,
+      instances: 1,
+      pm_uptime: this.startedAt,
+      created_at: this.startedAt,
+      unique_id: this.uniqueId,
+      cpu: fp.cpu,
+      memory: fp.memory,
+      axm_monitor: this.monitor,
+      axm_actions: Array.from(this.actions.values()),
+      axm_options: options,
+      axm_dynamic: {},
+      version: this._version,
+      node_version: process.versions.node,
+      node_env: process.env.NODE_ENV || null,
+      pm_cwd: safeCwd(),
+      path: script,
+      args: process.argv.slice(2),
+      versioning: null,
+      runtime,
+      // prodman 02 PROTO-170 (pmx 97 PAP-050)
+      application: this.application
+    }
+    const inContainer = this.info.inContainer()
+    const cpus = os.cpus() || []
+    const server = {
+      username: user,
+      hostname: host,
+      uptime: os.uptime(),
+      platform: os.platform(),
+      pm2_version: null,
+      pm2_agent_version: IO_VERSION,
+      node_version: process.version,
+      unique_id: this.serverUniqueId,
+      loadavg: os.loadavg(),
+      total_mem: limits.memoryBytes,
+      type: os.type(),
+      arch: os.arch(),
+      cpus: inContainer ? limits.cpusRoundedUp() : cpus.length || 1,
+      cpu_model: cpuModel(),
+      system: this.hostMetrics.collect(),
+      agent_kind: '@pm2/io',
+      ephemeral: this.info.ephemeral(),
+      // prodman 02 PROTO-164: the `tracing` settings key is applied (80 NIO-298)
+      tracing_control: 1,
+      // prodman 02 PROTO-171: applications support, protocol 1
+      applications: 1
+    }
+    if (inContainer) server.container = this.info.block(this.appName || null, host, limits)
+    if (this._ip === null) this._ip = internalIp()
+    this.statusCount++
+    return { at: Date.now(), server_name: this.server, internal_ip: this._ip, data: { process: [proc], server } }
+  }
+
+  _sendStatus (front) {
+    try {
+      this.packet('status', this.statusPayload(), null, front)
+    } catch (err) {
+      debug('status failed: %s', err && err.message)
+    }
+  }
+
+  // -- incoming (NIO-266) ---------------------------------------------------------------------
+
+  _onText (text) {
+    let msg
+    try {
+      msg = JSON.parse(typeof text === 'string' ? text : text.toString('utf8'))
+    } catch (_) {
+      debug('ignoring a malformed message')
+      return
+    }
+    if (!msg || typeof msg !== 'object' || typeof msg.channel !== 'string') return
+    const ch = msg.channel
+    const p = msg.payload
+    if (!p) return
+    try {
+      if (ch === 'trigger:action' || ch === 'trigger:scoped_action') this._triggerAction(p)
+      else if (ch === 'trigger:pm2:action') this._pm2Action(p)
+      else if (ch === 'status:resend') this._sendStatus(true)
+      else if (ch === 'prodman:settings') {
+        if (typeof p.collect_logs === 'boolean') this.collectLogs = p.collect_logs
+        this._applyTracing(p.tracing)
+      } else debug('ignoring channel %s', ch)
+    } catch (err) {
+      debug('handling %s failed: %s', ch, err && err.message)
+    }
+  }
+
+  /**
+   * 80 NIO-298, prodman 02 PROTO-160/161: the `tracing` key of the handshake / prodman:settings,
+   * resolved for this app; a change goes to the instance as a `pmx:tracing` message.
+   */
+  _applyTracing (block) {
+    const { layerFromBlock } = require('../tracing/control')
+    this._tracingBlock = block
+    const layer = layerFromBlock(block, this.appName, this.application)
+    const prev = this.tracingLayer ? JSON.stringify(this.tracingLayer) : '{}'
+    this.tracingLayer = layer
+    if (JSON.stringify(layer) === prev) return
+    const m = { type: 'pmx:tracing', data: layer }
+    for (const fn of this._listeners.slice()) {
+      try {
+        fn(m)
+      } catch (_) {}
+    }
+  }
+
+  _triggerAction (p) {
+    const name = p.action_name
+    const id = p.process_id !== undefined ? p.process_id : 0
+    if (typeof name !== 'string') return
+    if (!this.actions.has(name)) {
+      this.packet('trigger:action:failure', { success: false, err: 'unknown action ' + name, id, action_name: name })
+      return
+    }
+    this.packet('trigger:action:success', { success: true, id, action_name: name })
+    const m = { msg: name, action_name: name, opts: p.opts !== undefined ? p.opts : p.options, uuid: p.uuid }
+    for (const fn of this._listeners.slice()) {
+      try {
+        fn(m)
+      } catch (_) {}
+    }
+  }
+
+  _pm2Action (p) {
+    const method = p.method_name
+    if (typeof method !== 'string') return
+    const params = p.parameters && typeof p.parameters === 'object' ? p.parameters : {}
+    let err = null
+    let data = null
+    if (method === 'ping') data = { msg: 'pong' }
+    else if (method === 'getLogs') data = this.getLogs(params.lines, params.type)
+    else if (method === 'startLogging') {
+      this.collectLogs = true
+      data = { success: true }
+    } else if (method === 'stopLogging') {
+      if (!this.cfg.sendLogs) this.collectLogs = false
+      data = { success: true }
+    } else {
+      err = { message: REFUSAL.replace('%s', method).replace('%s', this.appName) }
+    }
+    this.packet('trigger:pm2:result', {
+      ret: { err, data },
+      meta: {
+        method_name: method,
+        app_name: this.appName,
+        machine_name: this.server,
+        public_key: this.cfg.publicKey,
+        request_id: params.request_id
+      }
+    })
+  }
+
+  // -- logs (NIO-267) -------------------------------------------------------------------------
+
+  getLogs (lines, kind) {
+    let n = Number(lines)
+    if (!Number.isFinite(n) || lines === undefined || lines === null) n = RING
+    n = Math.max(0, Math.min(RING, Math.floor(n)))
+    kind = kind === 'out' || kind === 'err' || kind === 'both' ? kind : 'both'
+    const out = n && kind !== 'err' ? this.ring.out.slice(-n).join('') : ''
+    const err = n && kind !== 'out' ? this.ring.err.slice(-n).join('') : ''
+    return [{ pm_id: 0, name: this.appName, out, err }]
+  }
+
+  forwardingLogs () {
+    return Boolean(this.cfg.sendLogs) || this.collectLogs
+  }
+
+  /** The capture sink (the root's own chunks and relayed ones). Never throws. */
+  onLogChunk (stream, text) {
+    try {
+      if (!text || this.cfg.captureLogs === 'off' || matchesFilter(this.cfg.logFilter, text)) return
+      stream = stream === 'err' ? 'err' : 'out'
+      const ring = this.ring[stream]
+      ring.push(text)
+      if (ring.length > RING) ring.shift()
+      if (this._connected() && this.forwardingLogs()) {
+        if (this._batchBytes + text.length > LOG_BATCH_MAX) {
+          this._droppedLines += countLines(text)
+        } else {
+          this._batch[stream].push(text)
+          this._batchBytes += text.length
+          if (this._batchSince === null) this._batchSince = Date.now()
+          if (this._batchBytes >= LOG_BATCH_BYTES) setImmediate(() => this._flushLogs(false))
+        }
+      }
+    } catch (_) {}
+  }
+
+  _flushLogs (force) {
+    const now = Date.now()
+    const due = this._batchSince !== null && (force || this._batchBytes >= LOG_BATCH_BYTES || now - this._batchSince >= LOG_BATCH_MS)
+    const batches = []
+    if (due) {
+      for (const stream of ['out', 'err']) if (this._batch[stream].length) batches.push([stream, this._batch[stream].join('')])
+      this._batch = { out: [], err: [] }
+      this._batchBytes = 0
+      this._batchSince = null
+    }
+    if (now - this._windowStart >= 1000) {
+      this._windowStart = now
+      this._windowLines = 0
+    }
+    const out = []
+    for (const [stream, text] of batches) {
+      let lines = text.split(/(?<=\n)/)
+      const allowed = Math.max(0, LOG_LINES_PER_SECOND - this._windowLines)
+      if (lines.length > allowed) {
+        this._droppedLines += lines.length - allowed
+        lines = lines.slice(0, allowed)
+      }
+      this._windowLines += lines.length
+      if (lines.length) out.push([stream, lines.join('')])
+    }
+    let report = 0
+    if (this._droppedLines && (this._dropReportedAt === null || now - this._dropReportedAt >= LOG_DROP_REPORT_MS)) {
+      report = this._droppedLines
+      this._droppedLines = 0
+      this._dropReportedAt = now
+    }
+    for (const [stream, text] of out) this.packet('logs', { at: now, data: text, log_type: stream, process: this.ref() })
+    if (report) {
+      this.packet('logs', { at: now, data: `[@pm2/io] ${report} log lines not sent (rate limit)\n`, log_type: 'err', process: this.ref() })
+    }
+  }
+
+  // -- shutdown (NIO-268, 95 CTR-022) ---------------------------------------------------------
+
+  /**
+   * Sends agent:shutdown (once), flushes for at most `flushMs` and closes with 1000. Resolves
+   * when done. Synchronous callers (process 'exit') get a best-effort immediate write.
+   */
+  shutdown (reason, signal, planned, flushMs) {
+    if (this._shutdownPayload || this._closed) return Promise.resolve(false)
+    this._shutdownPayload = { at: Date.now(), reason, signal: signal || null, planned: planned === true }
+    try {
+      this._flushLogs(true)
+    } catch (_) {}
+    this.packet('agent:shutdown', this._shutdownPayload, null, false)
+    return this.flush(flushMs === undefined ? 1000 : flushMs).then(() => {
+      this.close(1000, 'Shutting down')
+      return true
+    })
+  }
+
+  /** Waits until the queue and the socket's buffer are empty (connected or connecting only). */
+  flush (ms) {
+    const deadline = Date.now() + ms
+    return new Promise((resolve) => {
+      const check = () => {
+        const empty = this._pending.length === 0 && (!this._ws || this._ws.bufferedAmount() === 0)
+        if (empty || Date.now() >= deadline || (!this._ws && !this._connecting)) return resolve()
+        const t = setTimeout(check, 20)
+        if (t.unref) t.unref()
+      }
+      check()
+    })
+  }
+
+  close (code, reason) {
+    this._stopping = true
+    this._closed = true
+    clearTimeout(this._timers.retry)
+    this._disconnectTimers()
+    if (this._ws) {
+      const ws = this._ws
+      try {
+        ws.close(code || 1000, reason)
+      } catch (_) {}
+    }
+  }
+
+  _disconnectTimers () {
+    clearInterval(this._timers.status)
+    clearInterval(this._timers.ping)
+    clearInterval(this._timers.logs)
+  }
+
+  destroyAll () {
+    this.close(1000, 'Shutting down')
+    if (this._ws) {
+      const ws = this._ws
+      const t = setTimeout(() => ws.terminate(), 100)
+      if (t.unref) t.unref()
+    }
+    this._listeners = []
+  }
+}
+
+function internalIp () {
+  const ifaces = os.networkInterfaces()
+  for (const name of Object.keys(ifaces)) {
+    for (const a of ifaces[name] || []) {
+      if ((a.family === 'IPv4' || a.family === 4) && !a.internal) return a.address
+    }
+  }
+  return null
+}
+
+function safeCwd () {
+  try {
+    return process.cwd()
+  } catch (_) {
+    return null
+  }
+}
+
+module.exports = { ProdmanTransport, resolveConfig, resolveUrl, serverName, matchesFilter, Footprint, IO_VERSION, REFUSAL, NOT_QUEUED }