@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/tracing/w3c.js

@@ -0,0 +1,415 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// W3C Trace Context and Baggage (80 NIO-240..NIO-243, PYI-112/PYI-113, Part G.2): parsing,
+// serialisation, the SpanContext value object, NEW_TRACE and the carriers of inject/extract.
+// Pure functions: everything here works whether or not tracing is enabled.
+
+const debug = require('../debug')('axm:tracing')
+
+const BAGGAGE_MAX_ENTRIES = 64
+const BAGGAGE_MAX_BYTES = 8192
+const ZERO_TRACE = '0'.repeat(32)
+const ZERO_SPAN = '0'.repeat(16)
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})/
+const HEX32 = /^[0-9a-f]{32}$/
+const HEX16 = /^[0-9a-f]{16}$/
+// RFC 7230 token (baggage keys)
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+// tracestate is kept verbatim but never written when it holds a control character (G.2)
+const CTL = /[\x00-\x1f\x7f]/ // eslint-disable-line no-control-regex
+
+// ---------------------------------------------------------------------------------------------
+// values
+
+/** A header value as text: strings as is, Buffer/Uint8Array decoded as latin-1. */
+function text (v) {
+  if (typeof v === 'string') return v
+  if (v instanceof Uint8Array) return Buffer.from(v.buffer, v.byteOffset, v.byteLength).toString('latin1')
+  return null
+}
+
+function trimWs (s) {
+  return s.replace(/^[ \t]+|[ \t]+$/g, '')
+}
+
+/**
+ * PYI-112: → { traceId, spanId, sampled } or null. Surrounding whitespace trimmed; lowercase hex
+ * only; version ff invalid; version 00 exact; higher versions lenient; all-zero ids invalid.
+ */
+function parseTraceparent (value) {
+  let v = text(value)
+  if (v === null) return null
+  v = trimWs(v)
+  const m = TRACEPARENT_RE.exec(v)
+  if (!m) return null
+  const version = m[1]
+  if (version === 'ff') return null
+  const rest = v.slice(m[0].length)
+  if (version === '00') {
+    if (rest !== '') return null
+  } else if (rest !== '' && rest[0] !== '-') {
+    return null
+  }
+  if (m[2] === ZERO_TRACE || m[3] === ZERO_SPAN) return null
+  return { traceId: m[2], spanId: m[3], sampled: (parseInt(m[4], 16) & 1) === 1 }
+}
+
+// ---------------------------------------------------------------------------------------------
+// baggage (PYI-113). Internally an ordered array of [key, value] pairs ("bag"), so insertion
+// order survives keys that JavaScript objects would reorder (integer-like keys).
+
+const EMPTY_BAG = Object.freeze([])
+
+function utf8Len (s) {
+  return Buffer.byteLength(s, 'utf8')
+}
+
+/** Percent-decoding like Python's urllib.parse.unquote(errors='replace'). */
+function unquote (s) {
+  if (s.indexOf('%') === -1) return s
+  const chunks = []
+  let run = ''
+  for (let i = 0; i < s.length; i++) {
+    if (s.charCodeAt(i) === 0x25 && i + 2 < s.length + 1 && /^[0-9a-fA-F]{2}$/.test(s.slice(i + 1, i + 3))) {
+      if (run) chunks.push(Buffer.from(run, 'utf8'))
+      run = ''
+      chunks.push(Buffer.from([parseInt(s.slice(i + 1, i + 3), 16)]))
+      i += 2
+      continue
+    }
+    run += s[i]
+  }
+  if (run) chunks.push(Buffer.from(run, 'utf8'))
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+// baggage-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E ('%' is encoded too)
+function safeOctet (c) {
+  return c >= 0x21 && c <= 0x7e && c !== 0x22 && c !== 0x2c && c !== 0x3b && c !== 0x5c && c !== 0x25
+}
+
+function quote (s) {
+  let plain = true
+  for (let i = 0; i < s.length; i++) {
+    if (!safeOctet(s.charCodeAt(i))) {
+      plain = false
+      break
+    }
+  }
+  if (plain) return s
+  let out = ''
+  for (const ch of s) {
+    const c = ch.charCodeAt(0)
+    if (ch.length === 1 && safeOctet(c)) {
+      out += ch
+      continue
+    }
+    for (const b of Buffer.from(ch, 'utf8')) out += '%' + (b < 16 ? '0' : '') + b.toString(16).toUpperCase()
+  }
+  return out
+}
+
+/** Parse one or several `baggage` header values → bag (ordered [k, v] pairs, frozen). */
+function parseBaggage (values) {
+  if (values === undefined || values === null) return EMPTY_BAG
+  if (!Array.isArray(values)) values = [values]
+  const out = []
+  const index = new Map()
+  let size = 0
+  for (const raw of values) {
+    const t = text(raw)
+    if (!t) continue
+    for (const member of t.split(',')) {
+      const kv = member.split(';', 1)[0]
+      const eq = kv.indexOf('=')
+      if (eq === -1) continue
+      const k = trimWs(kv.slice(0, eq))
+      const v = trimWs(kv.slice(eq + 1))
+      if (!k || !TOKEN.test(k)) continue
+      const cost = k.length + 1 + utf8Len(v) + (out.length ? 1 : 0)
+      if (index.size >= BAGGAGE_MAX_ENTRIES || size + cost > BAGGAGE_MAX_BYTES) return Object.freeze(out)
+      size += cost
+      const val = unquote(v)
+      if (index.has(k)) {
+        out[index.get(k)] = [k, val]
+      } else {
+        index.set(k, out.length)
+        out.push([k, val])
+      }
+    }
+  }
+  return Object.freeze(out)
+}
+
+/** Serialise a bag in order, values percent-encoded (same limits as parsing). */
+function formatBaggage (bag) {
+  const parts = []
+  let size = 0
+  for (const [k, v] of bag) {
+    if (typeof k !== 'string' || !TOKEN.test(k)) continue
+    const member = k + '=' + quote(typeof v === 'string' ? v : String(v))
+    const cost = member.length + (parts.length ? 1 : 0)
+    if (parts.length >= BAGGAGE_MAX_ENTRIES || size + cost > BAGGAGE_MAX_BYTES) break
+    size += cost
+    parts.push(member)
+  }
+  return parts.join(',')
+}
+
+/** bag + entries (existing keys replaced in place, new ones appended). */
+function mergeBag (bag, entries) {
+  const out = bag.slice()
+  const pairs = entries instanceof Map ? Array.from(entries) : Array.isArray(entries) ? entries : Object.entries(entries || {})
+  for (const [k0, v0] of pairs) {
+    const k = String(k0)
+    const v = String(v0)
+    const i = out.findIndex((e) => e[0] === k)
+    if (i === -1) out.push([k, v])
+    else out[i] = [k, v]
+  }
+  return Object.freeze(out)
+}
+
+const objCache = new WeakMap()
+/** The frozen plain-object view of a bag (NIO-243). */
+function bagObject (bag) {
+  if (!bag || bag.length === 0) return EMPTY_OBJECT
+  let o = objCache.get(bag)
+  if (!o) {
+    o = {}
+    for (const [k, v] of bag) o[k] = v
+    Object.freeze(o)
+    objCache.set(bag, o)
+  }
+  return o
+}
+const EMPTY_OBJECT = Object.freeze({})
+
+function toBag (baggage) {
+  if (!baggage) return EMPTY_BAG
+  if (Array.isArray(baggage) && Object.isFrozen(baggage) && baggage.every((e) => Array.isArray(e))) return baggage
+  return mergeBag(EMPTY_BAG, baggage)
+}
+
+// ---------------------------------------------------------------------------------------------
+// SpanContext (NIO-240) and NEW_TRACE (NIO-247)
+
+const BAG = Symbol('pmx.bag')
+
+class SpanContext {
+  constructor (opts) {
+    const o = opts || {}
+    const { traceId, spanId } = o
+    if (typeof traceId !== 'string' || !HEX32.test(traceId) || traceId === ZERO_TRACE) {
+      throw new TypeError('traceId must be 32 lowercase hex digits, not all zero')
+    }
+    if (typeof spanId !== 'string' || !HEX16.test(spanId) || spanId === ZERO_SPAN) {
+      throw new TypeError('spanId must be 16 lowercase hex digits, not all zero')
+    }
+    const bag = o[BAG] || toBag(o.baggage)
+    Object.defineProperty(this, BAG, { value: bag, enumerable: false })
+    this.traceId = traceId
+    this.spanId = spanId
+    this.sampled = o.sampled === undefined ? true : Boolean(o.sampled)
+    this.traceState = typeof o.traceState === 'string' && o.traceState !== '' ? o.traceState : null
+    this.baggage = bagObject(bag)
+    this.isRemote = o.isRemote === undefined ? true : Boolean(o.isRemote)
+    Object.freeze(this)
+  }
+
+  traceparent () {
+    return `00-${this.traceId}-${this.spanId}-${this.sampled ? '01' : '00'}`
+  }
+
+  toJSON () {
+    return {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      sampled: this.sampled,
+      traceState: this.traceState,
+      baggage: this.baggage,
+      isRemote: this.isRemote
+    }
+  }
+}
+
+/** Internal constructor that skips validation (ids generated by the tracer). */
+function makeContext (traceId, spanId, sampled, traceState, bag, isRemote) {
+  return new SpanContext({ traceId, spanId, sampled, traceState, [BAG]: bag || EMPTY_BAG, isRemote })
+}
+
+function contextBag (ctx) {
+  return (ctx && ctx[BAG]) || EMPTY_BAG
+}
+
+function isSpanContext (v) {
+  return v instanceof SpanContext
+}
+
+const NEW_TRACE = Object.freeze({ toString: () => 'NEW_TRACE' })
+
+// ---------------------------------------------------------------------------------------------
+// carriers: extract (NIO-242)
+
+function isPlainObject (v) {
+  if (v === null || typeof v !== 'object') return false
+  const p = Object.getPrototypeOf(v)
+  return p === Object.prototype || p === null
+}
+
+/** All values of header `name` (lowercase) in a carrier. */
+function getAll (carrier, name) {
+  const out = []
+  const push = (v) => {
+    if (Array.isArray(v)) {
+      for (const x of v) out.push(x)
+    } else if (v !== undefined && v !== null) {
+      out.push(v)
+    }
+  }
+  if (carrier === null || carrier === undefined) return out
+  if (Array.isArray(carrier)) {
+    for (const item of carrier) {
+      if (!Array.isArray(item) || item.length < 2) continue
+      const k = text(item[0])
+      if (k !== null && k.toLowerCase() === name) push(item[1])
+    }
+    return out
+  }
+  if (carrier instanceof Map) {
+    for (const [k0, v] of carrier) {
+      const k = text(k0)
+      if (k !== null && k.toLowerCase() === name) push(v)
+    }
+    return out
+  }
+  if (isPlainObject(carrier)) {
+    for (const k of Object.keys(carrier)) {
+      if (k.toLowerCase() === name) push(carrier[k])
+    }
+    return out
+  }
+  if (typeof carrier.get === 'function') {
+    let v
+    try {
+      v = carrier.get(name)
+    } catch (_) {
+      v = undefined
+    }
+    push(v === null ? undefined : v)
+    return out
+  }
+  if (typeof carrier === 'object') {
+    for (const k of Object.keys(carrier)) {
+      if (k.toLowerCase() === name) push(carrier[k])
+    }
+  }
+  return out
+}
+
+function extract (carrier) {
+  try {
+    const tps = getAll(carrier, 'traceparent')
+    if (tps.length === 0) return null
+    const parsed = parseTraceparent(tps[0])
+    if (!parsed) return null
+    const states = getAll(carrier, 'tracestate').map(text).filter((s) => s)
+    const bag = parseBaggage(getAll(carrier, 'baggage'))
+    return makeContext(parsed.traceId, parsed.spanId, parsed.sampled, states.length ? states.join(',') : null, bag, true)
+  } catch (err) {
+    debug('extract failed: %s', err && err.message)
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// carriers: inject (NIO-241)
+
+/** The [name, value] pairs to write for a context and baggage (header hygiene, G.2). */
+function headersFor (ctx, bag) {
+  const out = [['traceparent', ctx.traceparent()]]
+  if (ctx.traceState && !CTL.test(ctx.traceState)) out.push(['tracestate', ctx.traceState])
+  if (bag && bag.length) {
+    const b = formatBaggage(bag)
+    if (b) out.push(['baggage', b])
+  }
+  return out
+}
+
+function writeHeaders (carrier, headers, overwrite, asBytes) {
+  const val = (v) => (asBytes ? Buffer.from(v, 'utf8') : v)
+  if (Array.isArray(carrier)) {
+    for (const [name, value] of headers) {
+      const idx = []
+      for (let i = 0; i < carrier.length; i++) {
+        const item = carrier[i]
+        if (!Array.isArray(item)) continue
+        const k = text(item[0])
+        if (k !== null && k.toLowerCase() === name) idx.push(i)
+      }
+      if (idx.length && !overwrite) continue
+      if (idx.length) {
+        carrier[idx[0]] = [carrier[idx[0]][0], val(value)]
+        for (let j = idx.length - 1; j >= 1; j--) carrier.splice(idx[j], 1)
+      } else {
+        carrier.push([name, val(value)])
+      }
+    }
+    return carrier
+  }
+  if (carrier instanceof Map) {
+    for (const [name, value] of headers) {
+      const existing = []
+      for (const k of carrier.keys()) {
+        const t = text(k)
+        if (t !== null && t.toLowerCase() === name) existing.push(k)
+      }
+      if (existing.length && !overwrite) continue
+      for (const k of existing) if (k !== name) carrier.delete(k)
+      carrier.set(name, val(value))
+    }
+    return carrier
+  }
+  if (carrier && typeof carrier.set === 'function' && typeof carrier.has === 'function') {
+    for (const [name, value] of headers) {
+      if (carrier.has(name) && !overwrite) continue
+      carrier.set(name, val(value))
+    }
+    return carrier
+  }
+  if (carrier !== null && typeof carrier === 'object') {
+    for (const [name, value] of headers) {
+      const existing = Object.keys(carrier).filter((k) => k.toLowerCase() === name)
+      if (existing.length && !overwrite) continue
+      for (const k of existing) if (k !== name) delete carrier[k]
+      carrier[name] = val(value)
+    }
+    return carrier
+  }
+  throw new TypeError('unsupported carrier')
+}
+
+module.exports = {
+  BAGGAGE_MAX_ENTRIES,
+  BAGGAGE_MAX_BYTES,
+  EMPTY_BAG,
+  EMPTY_OBJECT,
+  NEW_TRACE,
+  SpanContext,
+  makeContext,
+  contextBag,
+  isSpanContext,
+  parseTraceparent,
+  parseBaggage,
+  formatBaggage,
+  mergeBag,
+  bagObject,
+  toBag,
+  extract,
+  headersFor,
+  writeHeaders,
+  getAll,
+  text,
+  CTL
+}

package/lib/transport/ipc.js

@@ -0,0 +1,97 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Node IPC transport (80 A.9, 40 §6/§7): envelopes `{type, data}` over process.send.
+
+const debug = require('../debug')('axm:transport:ipc')
+
+const KEEPALIVE_RELEASE_MS = 3000
+const noop = () => {}
+
+function isClusterWorker () {
+  // Cheap check first: Node loads its internal cluster child module in every worker.
+  const list = process.moduleLoadList
+  if (Array.isArray(list) && list.length > 0) return list.includes('NativeModule internal/cluster/child')
+  try {
+    return require('cluster').isWorker === true
+  } catch (_) {
+    return false
+  }
+}
+
+class IPCTransport {
+  constructor () {
+    this._listeners = []
+    this._onMessage = null
+    this._releaseTimer = null
+    this.kind = 'ipc'
+  }
+
+  init () {
+    if (typeof process.send !== 'function') {
+      debug('no IPC channel, transport is inert')
+      return this
+    }
+    this._onMessage = (msg) => {
+      for (const fn of this._listeners.slice()) fn(msg)
+    }
+    process.on('message', this._onMessage)
+    // IO-093: our message listener must never keep an otherwise finished app alive.
+    // Node refs the channel when a 'message' listener is added; after a short window
+    // (so early daemon messages such as action triggers are still received) we unref it.
+    // If the app has other work, the process stays alive and messages keep flowing.
+    // Cluster workers are kept alive by Node's own cluster logic (40 §5.4): leave them.
+    if (!isClusterWorker()) {
+      this._releaseTimer = setTimeout(() => {
+        this._releaseTimer = null
+        try {
+          if (process.channel && typeof process.channel.unref === 'function') process.channel.unref()
+        } catch (_) {}
+      }, KEEPALIVE_RELEASE_MS)
+      if (this._releaseTimer.unref) this._releaseTimer.unref()
+    }
+    return this
+  }
+
+  isConnected () {
+    return typeof process.send === 'function' && process.connected !== false
+  }
+
+  /** Send a raw message (IO-090..IO-092). Returns -1 when there is no channel. */
+  sendRaw (msg, cb) {
+    if (typeof process.send !== 'function') {
+      if (cb) process.nextTick(cb)
+      return -1
+    }
+    if (process.connected === false) {
+      console.error('Process disconnected from parent! (not connected)')
+      process.exit(1)
+      return -1
+    }
+    try {
+      return process.send(msg, cb || noop)
+    } catch (err) {
+      console.error('Process disconnected from parent! (' + (err && err.message) + ')')
+      process.exit(1)
+      return -1
+    }
+  }
+
+  send (type, data, cb) {
+    return this.sendRaw({ type, data }, cb)
+  }
+
+  onMessage (fn) {
+    this._listeners.push(fn)
+  }
+
+  destroy () {
+    if (this._onMessage) process.removeListener('message', this._onMessage)
+    this._onMessage = null
+    this._listeners = []
+    if (this._releaseTimer) clearTimeout(this._releaseTimer)
+    this._releaseTimer = null
+  }
+}
+
+module.exports = { IPCTransport, isClusterWorker }