bare-operating-system/packages/bare-os-booter/lib/bare-os-swarm-subsystem-proc.js

/**
 * Per-file JSON for /proc/bare_os/swarm_*_status.json (and internal bare_os_swarm_*_status).
 * Surfaces always; “absent file” is not a mode — use `status` + `note` when a layer is not wired.
 */

/**
 * @param {string} fileKey e.g. `bare_os_swarm_replication_status`
 * @param {{
 *   disk: { peers?: { size: number } | null, [k: string]: unknown } | null,
 *   shellEnv: Record<string, string | undefined>,
 *   swarmConnectionManager: { snapshot?: () => unknown } | null,
 *   buildBareOsReplicationLiveSketch: (d: unknown, n: number) => unknown
 * }} d
 * @returns {string} JSON + newline
 */
export function bareOsFormatSwarmSubsystemProcJson(fileKey, d) {
  const disk = d.disk
  const shellEnv = d.shellEnv || {}
  const peers = disk && disk.peers && typeof disk.peers.size === 'number'
    ? disk.peers.size
    : 0
  const now = Date.now()
  /** @returns {unknown} */
  const snap = () => {
    try {
      const scm = d.swarmConnectionManager
      if (!scm || typeof scm.snapshot !== 'function') return null
      return scm.snapshot()
    } catch {
      return null
    }
  }
  const repLive =
    typeof d.buildBareOsReplicationLiveSketch === 'function' && disk
      ? d.buildBareOsReplicationLiveSketch(disk, peers)
      : null

  switch (fileKey) {
    case 'bare_os_swarm_replication_status':
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'replication',
          peerCount: peers,
          replicationLiveSketch: repLive ?? null,
          seedReplicationStatus:
            disk &&
            disk.seedReplicationStatus &&
            typeof disk.seedReplicationStatus === 'object'
              ? disk.seedReplicationStatus
              : null,
          note:
            'Focused replication slice. Full blob: /proc/bare_os/replication and metrics_live.replicationLive.'
        }) + '\n'
      )
    case 'bare_os_swarm_relay_status': {
      const raw = String(shellEnv.BARE_OS_BLIND_RELAY_TOPOLOGY_JSON || '').trim()
      let topology = null
      if (raw) {
        try {
          topology = JSON.parse(raw)
        } catch {
          topology = { parseError: true }
        }
      }
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'relay',
          status: topology ? 'env_present' : 'env_unset',
          blindRelayTopology: topology,
          envGate: 'BARE_OS_BLIND_RELAY_TOPOLOGY_JSON',
          note:
            topology
              ? 'Relay topology sketch from env (same idea as swarm.blindRelayTopology).'
              : 'Set BARE_OS_BLIND_RELAY_TOPOLOGY_JSON on the host for relay sketches.'
        }) + '\n'
      )
    }
    case 'bare_os_swarm_datagrams_status':
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'datagrams',
          status: 'logical',
          guestDatagramSockets: 'POSIX DGRAM bridges / USOCK when ctx wires them',
          metricsHint: 'See metrics_live.ipcTelemetry and env BARE_OS_POSIX_DGRAM_*',
          note:
            'No separate on-disk swarm datagram counters in stock booter; ipc + metrics_live carry hints.'
        }) + '\n'
      )
    case 'bare_os_swarm_connection_manager_status': {
      const s = snap()
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'connection_manager',
          snapshotPresent: !!s,
          snapshot: s,
          note:
            'BareOsSwarmConnectionManager snapshot (peer policy + protomux pool counters). No peer keys.'
        }) + '\n'
      )
    }
    case 'bare_os_swarm_key_broker_status':
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'key_broker',
          status: 'not_exposed',
          note:
            'Stock Bare OS does not expose a standalone Hyperswarm “key broker” daemon. Identity flows through Hypercore/Hyperdrive + Pear configuration.'
        }) + '\n'
      )
    case 'bare_os_swarm_holepunch_status':
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'holepunch',
          natTraversalMode: String(
            shellEnv.BARE_OS_NAT_TRAVERSAL_MODE || 'auto'
          ).trim(),
          dhtAllowlistClasses: String(
            shellEnv.BARE_OS_DHT_ADDRESS_CLASS_ALLOWLIST || ''
          ).trim(),
          deeperDetailPath: '/proc/bare_os/net_summary.json',
          note:
            'NAT/holepunch outcomes are summarized under net_summary.transport when the host wires stats.'
        }) + '\n'
      )
    case 'bare_os_swarm_datagram_replication_status':
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          subsystem: 'datagram_replication',
          replicationQueue:
            disk &&
            disk.seedReplicationQueue &&
            typeof disk.seedReplicationQueue === 'object'
              ? disk.seedReplicationQueue
              : null,
          peerCount: peers,
          note:
            'Correlation of UDP/logical datagram paths with replication is deployment-specific; seed replication queue shown when present.'
        }) + '\n'
      )
    default:
      return (
        JSON.stringify({
          schema: 1,
          atMs: now,
          fileKey,
          status: 'unknown_key',
          note:
            'Unrecognized swarm subsystem proc key; regenerate booter / report upstream.'
        }) + '\n'
      )
  }
}