@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/relay/hub.js

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The root's local hub (80 NIO-263, NIO-291; Part G.5 relay protocol version 1).
+//
+// Node descendants (cluster workers of an app that is its own primary, child_process.fork/spawn
+// of node or bun) connect and speak the relay protocol: UTF-8 JSON objects, one per line. On
+// Linux the hub is an abstract Unix socket, written `@pmx-io-<pid>-<16 hex>` in PMX_IO_HUB (the
+// `@` stands for the NUL byte); elsewhere a socket in a new 0700 temporary directory. The first
+// line of a connection must be the hello `{"__pmx_relay__":"hello","pid":…,"token":…,"rt":"node",
+// "v":1}` within 2 s, with the token compared in constant time; a hello of another runtime closes
+// the connection (NIO-296). At most 32 connections may await their hello. Node has no API for
+// the peer's credentials, so the uid check of PYI-153 is not made (the token guards the socket).
+// The listener and every connection are unref'd: the hub never keeps the app alive.
+
+const net = require('net')
+const fs = require('fs')
+const path = require('path')
+const debug = require('../debug')('axm:relay')
+
+const RELAY_KEY = '__pmx_relay__'
+const HELLO_TIMEOUT = 2000
+const MAX_HELLO = 4096
+const MAX_PENDING = 32
+const MAX_LINE = 16 * 1024 * 1024
+
+/** n random bytes as hex; /dev/urandom first (loading crypto costs ~5 ms at start-up). */
+function randomHex (n) {
+  try {
+    const buf = Buffer.alloc(n)
+    const fd = fs.openSync('/dev/urandom', 'r')
+    try {
+      if (fs.readSync(fd, buf, 0, n, null) === n) return buf.toString('hex')
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch (_) {}
+  return require('crypto').randomBytes(n).toString('hex')
+}
+
+function newToken () {
+  return randomHex(16)
+}
+
+/** `@name` → the abstract socket path; anything else unchanged. */
+function socketPath (addr) {
+  return typeof addr === 'string' && addr.startsWith('@') ? '\0' + addr.slice(1) : addr
+}
+
+function helloLine (pid, token) {
+  const o = { [RELAY_KEY]: 'hello', pid }
+  if (token !== undefined) o.token = token
+  o.rt = 'node'
+  o.v = 1
+  return JSON.stringify(o) + '\n'
+}
+
+function tokenOk (got, want) {
+  if (typeof got !== 'string' || typeof want !== 'string') return false
+  const a = Buffer.from(got, 'utf8')
+  const b = Buffer.from(want, 'utf8')
+  const crypto = require('crypto')
+  if (a.length !== b.length) {
+    crypto.timingSafeEqual(b, b)
+    return false
+  }
+  return crypto.timingSafeEqual(a, b)
+}
+
+/** The pid of a valid hello line for this hub, else null (and the reason). */
+function checkHello (line, token) {
+  let msg
+  try {
+    msg = JSON.parse(line)
+  } catch (_) {
+    return { pid: null, why: 'not JSON' }
+  }
+  if (!msg || typeof msg !== 'object' || msg[RELAY_KEY] !== 'hello') return { pid: null, why: 'not a hello' }
+  if (!tokenOk(msg.token, token)) return { pid: null, why: 'bad token' }
+  const rt = msg.rt === undefined ? 'python' : msg.rt
+  if (rt !== 'node') return { pid: null, why: 'runtime ' + rt }
+  if (!Number.isInteger(msg.pid) || msg.pid <= 0) return { pid: null, why: 'bad pid' }
+  return { pid: msg.pid, why: null }
+}
+
+/** Split a stream into lines; calls onLine(text) for each complete line. */
+function lineReader (onLine, onTooLong) {
+  let buf = ''
+  return (chunk) => {
+    buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+    let nl
+    while ((nl = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, nl)
+      buf = buf.slice(nl + 1)
+      if (line) onLine(line)
+    }
+    if (buf.length > MAX_LINE) {
+      buf = ''
+      if (onTooLong) onTooLong()
+    }
+  }
+}
+
+class Hub {
+  /**
+   * @param {(msg: object, pid: number) => void} onMessage relay message (not hellos)
+   * @param {{token?: string}} [opts]
+   */
+  constructor (onMessage, opts) {
+    this.onMessage = onMessage
+    this.token = (opts && opts.token) || newToken()
+    this.address = ''
+    this._server = null
+    this._tmpdir = null
+    this._pending = 0
+    this._relays = new Map() // socket → Set of pids announced on it
+    this._sockets = new Set()
+  }
+
+  /** Start listening (synchronously bound); returns the PMX_IO_HUB value. */
+  start () {
+    let listenPath
+    // Abstract sockets: Linux, on Node >= 20 and Bun (Node 18's listen fails with EADDRINUSE on
+    // them); elsewhere a socket in a new 0700 temporary directory
+    const major = Number(String(process.versions.node || '0').split('.')[0])
+    if (process.platform === 'linux' && (major >= 20 || typeof process.versions.bun === 'string')) {
+      const name = `pmx-io-${process.pid}-${randomHex(8)}`
+      this.address = '@' + name
+      listenPath = '\0' + name
+    } else {
+      this._tmpdir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'pmx-io-'))
+      fs.chmodSync(this._tmpdir, 0o700)
+      listenPath = path.join(this._tmpdir, 'hub.sock')
+      this.address = listenPath
+      // the directory and its socket file outlive the process unless removed at exit
+      this._onExit = () => this._removeTmpdir()
+      process.on('exit', this._onExit)
+    }
+    const server = net.createServer({ pauseOnConnect: false }, (sock) => this._accept(sock))
+    server.on('error', (err) => debug('hub error: %s', err && err.message))
+    this._server = server
+    // The address is chosen (and exported) now; binding waits until the app's first line has
+    // run (NIO-024): a descendant needs tens of milliseconds to start and load its preload.
+    const listen = () => {
+      if (this._server !== server) return
+      // exclusive: a cluster worker (pmx cluster mode) binds itself instead of asking its primary
+      server.listen({ path: listenPath, exclusive: true })
+      server.unref()
+    }
+    if (this._deferListen === false) listen()
+    else {
+      const t = setImmediate(listen)
+      if (t.unref) t.unref()
+    }
+    return this.address
+  }
+
+  _accept (sock) {
+    if (sock.unref) sock.unref()
+    if (this._pending >= MAX_PENDING) {
+      debug('hub: %d connections await a hello, closing a new one', this._pending)
+      sock.destroy()
+      return
+    }
+    this._pending++
+    let helloDone = false
+    let buf = ''
+    const timer = setTimeout(() => {
+      debug('hub: no hello within %d ms, closing', HELLO_TIMEOUT)
+      sock.destroy()
+    }, HELLO_TIMEOUT)
+    if (timer.unref) timer.unref()
+    const settle = () => {
+      if (!helloDone) {
+        helloDone = true
+        this._pending--
+        clearTimeout(timer)
+      }
+    }
+    // decode as a stream: a multi-byte UTF-8 character split across two chunks stays intact
+    sock.setEncoding('utf8')
+    sock.on('error', () => {})
+    sock.on('close', () => {
+      settle()
+      this._relays.delete(sock)
+      this._sockets.delete(sock)
+    })
+    const onData = (chunk) => {
+      buf += chunk
+      const nl = buf.indexOf('\n')
+      if (nl === -1) {
+        if (buf.length > MAX_HELLO) sock.destroy()
+        return
+      }
+      const res = checkHello(buf.slice(0, nl), this.token)
+      settle()
+      if (res.pid === null) {
+        debug('hub: invalid hello (%s), closing', res.why)
+        sock.destroy()
+        return
+      }
+      sock.removeListener('data', onData)
+      const pids = new Set([res.pid])
+      this._relays.set(sock, pids)
+      this._sockets.add(sock)
+      const reader = lineReader((line) => this._line(line, sock, pids), () => sock.destroy())
+      sock.on('data', reader)
+      const rest = buf.slice(nl + 1)
+      buf = ''
+      if (rest) reader(rest)
+    }
+    sock.on('data', onData)
+  }
+
+  _line (line, sock, pids) {
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch (_) {
+      debug('hub: malformed line ignored')
+      return
+    }
+    if (!msg || typeof msg !== 'object') return
+    const kind = msg[RELAY_KEY]
+    if (kind === 'hello') {
+      // a relay forwards the hellos of the relays below it (no token)
+      if (Number.isInteger(msg.pid) && msg.pid > 0) pids.add(msg.pid)
+      return
+    }
+    if (kind === 'msg' || kind === 'metrics' || kind === 'log') {
+      try {
+        this.onMessage(msg, pids.values().next().value)
+      } catch (err) {
+        debug('hub: relay message failed: %s', err && err.message)
+      }
+      return
+    }
+    debug('hub: unknown relay message %s ignored', kind)
+  }
+
+  /** Pids of the live relays (footprint, NIO-263). */
+  relayPids () {
+    const out = []
+    for (const set of this._relays.values()) for (const p of set) if (!out.includes(p)) out.push(p)
+    return out
+  }
+
+  stop () {
+    if (this._server) {
+      try {
+        this._server.close()
+      } catch (_) {}
+      this._server = null
+    }
+    for (const s of this._sockets) {
+      try {
+        s.destroy()
+      } catch (_) {}
+    }
+    this._sockets.clear()
+    this._relays.clear()
+    this._removeTmpdir()
+  }
+
+  _removeTmpdir () {
+    if (this._onExit) {
+      process.removeListener('exit', this._onExit)
+      this._onExit = null
+    }
+    if (this._tmpdir) {
+      try {
+        fs.rmSync(this._tmpdir, { recursive: true, force: true })
+      } catch (_) {}
+      this._tmpdir = null
+    }
+  }
+}
+
+module.exports = { Hub, RELAY_KEY, socketPath, helloLine, checkHello, tokenOk, newToken, lineReader, HELLO_TIMEOUT, MAX_PENDING }

package/lib/relay/transport.js

@@ -0,0 +1,253 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Relay transports (80 NIO-263, NIO-291, NIO-293; Part G.5): what an instance uses when it is not
+// the root. It forwards exceptions (with metadata.pid, and metadata.thread_id from a worker
+// thread), events and spans, metric contributions and captured log chunks, and nothing else:
+// relays never run actions, never answer daemon messages and never open their own daemon or
+// prodman connection.
+//  * HubRelayTransport: a Node descendant process → the root's hub socket.
+//  * ThreadRelayTransport: a worker thread → the main thread, over BroadcastChannel
+//    `pmx-io:<pid>` (relay message objects, no hello or token: the channel is process-local).
+
+const net = require('net')
+const { RELAY_KEY, socketPath, helloLine } = require('./hub')
+const debug = require('../debug')('axm:relay')
+
+const FORWARDED = ['process:exception', 'human:event', 'trace-span']
+const MAX_QUEUE = 1000
+
+function wrapMessage (type, data, extraMeta) {
+  if (!FORWARDED.includes(type)) return null
+  if (type === 'process:exception' && data && typeof data === 'object') {
+    const d = Object.assign({}, data)
+    const meta = Object.assign({}, d.metadata && typeof d.metadata === 'object' ? d.metadata : {})
+    if (meta.pid === undefined) meta.pid = process.pid
+    if (extraMeta) for (const k of Object.keys(extraMeta)) if (meta[k] === undefined) meta[k] = extraMeta[k]
+    d.metadata = meta
+    data = d
+  }
+  return { [RELAY_KEY]: 'msg', m: { type, data } }
+}
+
+class HubRelayTransport {
+  /**
+   * @param {string} hub PMX_IO_HUB
+   * @param {string} token PMX_IO_HUB_TOKEN
+   * @param {{rootPid?: string, onUnreachable?: Function}} [opts]
+   */
+  constructor (hub, token, opts) {
+    this.kind = 'relay'
+    this.hub = hub
+    this.token = token
+    this.opts = opts || {}
+    this._sock = null
+    this._queue = []
+    this._connected = false
+    this._failed = false
+    this._listeners = []
+  }
+
+  init () {
+    let sock
+    try {
+      sock = net.connect(socketPath(this.hub))
+    } catch (err) {
+      this._fail(err)
+      return this
+    }
+    this._sock = sock
+    if (sock.unref) sock.unref()
+    sock.on('connect', () => {
+      this._connected = true
+      sock.write(helloLine(process.pid, this.token))
+      const q = this._queue
+      this._queue = []
+      for (const [line, cb] of q) sock.write(line, cb)
+    })
+    sock.on('error', (err) => this._fail(err))
+    sock.on('close', () => {
+      this._connected = false
+      if (!this._failed) {
+        this._failed = true
+        debug('hub connection closed')
+      }
+    })
+    // the hub never sends anything to relays
+    sock.on('data', () => {})
+    return this
+  }
+
+  _fail (err) {
+    if (this._failed) return
+    this._failed = true
+    debug('hub %s not reachable: %s', this.hub, err && err.message)
+    const q = this._queue
+    this._queue = []
+    for (const [, cb] of q) if (cb) process.nextTick(cb, err)
+    if (this.opts.onUnreachable) {
+      try {
+        this.opts.onUnreachable(err)
+      } catch (_) {}
+    }
+  }
+
+  _write (obj, cb) {
+    if (this._failed) {
+      if (cb) process.nextTick(cb, new Error('hub not reachable'))
+      return false
+    }
+    let line
+    try {
+      line = JSON.stringify(obj) + '\n'
+    } catch (err) {
+      if (cb) process.nextTick(cb, err)
+      return false
+    }
+    if (!this._connected) {
+      if (this._queue.length >= MAX_QUEUE) this._queue.shift()
+      this._queue.push([line, cb])
+      return true
+    }
+    return this._sock.write(line, cb)
+  }
+
+  send (type, data, cb) {
+    const w = wrapMessage(type, data)
+    if (!w) {
+      if (cb) process.nextTick(cb)
+      return true
+    }
+    return this._write(w, cb)
+  }
+
+  sendRaw (msg, cb) {
+    if (cb) process.nextTick(cb)
+    return true
+  }
+
+  sendRelay (obj) {
+    return this._write(obj)
+  }
+
+  sendLog (stream, text) {
+    return this._write({ [RELAY_KEY]: 'log', s: stream === 'err' ? 'err' : 'out', d: text })
+  }
+
+  sendContributions (list) {
+    return this._write({ [RELAY_KEY]: 'metrics', c: list })
+  }
+
+  onMessage (fn) {
+    this._listeners.push(fn)
+  }
+
+  isConnected () {
+    return this._connected
+  }
+
+  destroy () {
+    if (this._sock) {
+      try {
+        this._sock.end()
+      } catch (_) {}
+    }
+    this._listeners = []
+  }
+}
+
+function channelName (pid) {
+  return 'pmx-io:' + (pid || process.pid)
+}
+
+class ThreadRelayTransport {
+  constructor () {
+    this.kind = 'thread-relay'
+    this._ch = null
+    this._threadId = undefined
+    this._listeners = []
+  }
+
+  init () {
+    const wt = require('worker_threads')
+    this._threadId = wt.threadId
+    this._ch = new wt.BroadcastChannel(channelName())
+    if (this._ch.unref) this._ch.unref()
+    return this
+  }
+
+  _post (obj) {
+    try {
+      this._ch.postMessage(obj)
+      return true
+    } catch (err) {
+      debug('thread relay post failed: %s', err && err.message)
+      return false
+    }
+  }
+
+  send (type, data, cb) {
+    const w = wrapMessage(type, data, { thread_id: this._threadId })
+    const ok = w ? this._post(w) : true
+    if (cb) process.nextTick(cb)
+    return ok
+  }
+
+  sendRaw (msg, cb) {
+    if (cb) process.nextTick(cb)
+    return true
+  }
+
+  sendLog (stream, text) {
+    return this._post({ [RELAY_KEY]: 'log', s: stream === 'err' ? 'err' : 'out', d: text })
+  }
+
+  sendContributions (list) {
+    return this._post({ [RELAY_KEY]: 'metrics', c: list })
+  }
+
+  onMessage (fn) {
+    this._listeners.push(fn)
+  }
+
+  isConnected () {
+    return true
+  }
+
+  destroy () {
+    if (this._ch) {
+      try {
+        this._ch.close()
+      } catch (_) {}
+      this._ch = null
+    }
+  }
+}
+
+/** Main-thread side: receive thread relays' messages. Returns a close function. */
+function listenThreads (onMessage) {
+  let ch
+  try {
+    const wt = require('worker_threads')
+    ch = new wt.BroadcastChannel(channelName())
+  } catch (err) {
+    debug('thread relays unavailable: %s', err && err.message)
+    return () => {}
+  }
+  if (ch.unref) ch.unref()
+  ch.onmessage = (ev) => {
+    const msg = ev && ev.data
+    if (msg && typeof msg === 'object' && msg[RELAY_KEY]) {
+      try {
+        onMessage(msg, process.pid)
+      } catch (_) {}
+    }
+  }
+  return () => {
+    try {
+      ch.close()
+    } catch (_) {}
+  }
+}
+
+module.exports = { HubRelayTransport, ThreadRelayTransport, listenThreads, wrapMessage, channelName, FORWARDED }