threadforge 0.1.1 → 0.2.1

package/src/registry/ServiceRegistry.js

@@ -1,797 +0,0 @@
-/**
- * Service Registry
- *
- * The registry is the brain of horizontal scaling. It answers one
- * question for every proxy call: WHERE is this service?
- *
- * ═══════════════════════════════════════════════════════════════
- * GROWTH STORY
- * ═══════════════════════════════════════════════════════════════
- *
- * PHASE 1: Single machine ($20/mo VPS)
- *   Registry mode: 'embedded'
- *   - Runs in-process inside the supervisor
- *   - All services are local (UDS or colocated)
- *   - Registry is just a Map in memory
- *   - Zero operational overhead
- *
- * PHASE 2: 2-3 machines ($100/mo)
- *   Registry mode: 'multicast'
- *   - Each supervisor announces its services via UDP multicast
- *     on the local network (or via a simple HTTP gossip protocol)
- *   - Nodes discover each other automatically
- *   - No external dependencies (no etcd, no consul)
- *   - Services that move to another machine are auto-discovered
- *
- * PHASE 3: 10+ machines (serious scale)
- *   Registry mode: 'external'
- *   - Pluggable backend: Redis, etcd, Consul, or managed service
- *   - Full service mesh capabilities
- *   - Health checks, circuit breakers, canary deployments
- *
- * The proxy layer doesn't know or care which phase you're in.
- * this.users.getUser('123') works identically in all three.
- *
- * ═══════════════════════════════════════════════════════════════
- * REGISTRATION PROTOCOL
- * ═══════════════════════════════════════════════════════════════
- *
- * When a service starts, it registers:
- *
- *   {
- *     name: 'users',
- *     nodeId: 'node-abc123',
- *     host: '10.0.1.5',
- *     ports: {
- *       http: 4001,        // HTTP port (for remote calls via /__forge/invoke)
- *     },
- *     udsPath: '/tmp/forge-1234/users-1.sock',  // local only
- *     workers: 4,
- *     contract: {          // what methods are available
- *       methods: ['getUser', 'createUser', 'listUsers'],
- *       events: ['user.created'],
- *     },
- *     health: {
- *       status: 'healthy',
- *       cpu: 23,           // percent
- *       memory: 156,       // MB
- *       rpcLatencyP50: 2,  // ms
- *       rpcLatencyP99: 18, // ms
- *       pendingRequests: 12,
- *       lastHeartbeat: 1707500000000,
- *     },
- *     metadata: {
- *       version: '1.2.3',
- *       region: 'us-east-1',
- *       startedAt: 1707500000000,
- *     },
- *   }
- *
- * ═══════════════════════════════════════════════════════════════
- * TOPOLOGY RESOLUTION
- * ═══════════════════════════════════════════════════════════════
- *
- * When a proxy call is made, the registry resolves the transport:
- *
- *   registry.resolve('users')
- *   → [
- *       { transport: 'local', instance: ... },     // colocated
- *       { transport: 'uds', path: '/tmp/...' },    // same machine
- *       { transport: 'http', host: '10.0.1.5:4001' },  // remote
- *     ]
- *
- * The proxy picks the BEST option:
- *   1. Colocated (same process) → always preferred
- *   2. UDS (same machine) → preferred over network
- *   3. HTTP (closest region) → fallback
- */
-
-import crypto from "node:crypto";
-import { EventEmitter } from "node:events";
-import os from "node:os";
-
-/**
- * @typedef {Object} ServiceRegistration
- * @property {string} name
- * @property {string} nodeId
- * @property {string} host
- * @property {{http?: number}} ports
- * @property {string|null} udsPath
- * @property {number} workers
- * @property {{methods: string[], events: string[]}} contract
- * @property {ServiceHealth} health
- * @property {Object} metadata
- */
-
-/**
- * @typedef {Object} ServiceHealth
- * @property {'healthy'|'degraded'|'unhealthy'|'draining'} status
- * @property {number} cpu
- * @property {number} memory
- * @property {number} rpcLatencyP50
- * @property {number} rpcLatencyP99
- * @property {number} pendingRequests
- * @property {number} lastHeartbeat
- */
-
-/**
- * @typedef {Object} ResolvedEndpoint
- * @property {'local'|'uds'|'http'} transport
- * @property {string} nodeId
- * @property {object} [instance]  - for 'local'
- * @property {string} [path]      - for 'uds'
- * @property {string} [address]   - for 'http'
- * @property {ServiceHealth} health
- * @property {number} priority    - lower = preferred
- */
-
-// ─── Base Registry ──────────────────────────────────────────
-
-export class ServiceRegistry extends EventEmitter {
-  /**
-   * @param {Object} options
-   * @param {string} [options.mode='embedded'] - 'embedded' | 'multicast' | 'external'
-   * @param {string} [options.nodeId] - Unique node identifier
-   * @param {string} [options.host] - This node's reachable address
-   * @param {number} [options.heartbeatIntervalMs=5000]
-   * @param {number} [options.healthTimeoutMs=15000] - Mark unhealthy after this
-   * @param {number} [options.httpBasePort=4000] - Base port for auto HTTP binding
-   */
-  constructor(options = {}) {
-    super();
-
-    this.mode = options.mode ?? "embedded";
-    this.nodeId = options.nodeId ?? `node-${crypto.randomBytes(4).toString("hex")}`;
-    this.host = options.host ?? getLocalIP();
-    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 5000;
-    this.healthTimeoutMs = options.healthTimeoutMs ?? 15000;
-    this.httpBasePort = options.httpBasePort ?? 4000;
-    this._clusterSecret = options.clusterSecret ?? process.env.FORGE_CLUSTER_SECRET ?? null;
-    this.staleReapMultiplier = options.staleReapMultiplier ?? 3;
-
-    /**
-     * All known service registrations across all nodes.
-     * Key: `${serviceName}@${nodeId}`
-     * @type {Map<string, ServiceRegistration>}
-     */
-    this.registrations = new Map();
-
-    /**
-     * Services running on THIS node.
-     * @type {Map<string, ServiceRegistration>}
-     */
-    this.localRegistrations = new Map();
-
-    /**
-     * Colocated service instances (same process).
-     * @type {Map<string, {service: object, ctx: object}>}
-     */
-    this.localInstances = new Map();
-
-    /** @type {NodeJS.Timeout|null} */
-    this._heartbeatTimer = null;
-
-    /** @type {NodeJS.Timeout|null} */
-    this._reapTimer = null;
-
-    /** @type {Object|null} - multicast/external backend */
-    this._backend = null;
-
-    /** @type {Map<string, NodeJS.Timeout>} pending drain timers from deregister() */
-    this._drainTimers = new Map();
-
-    /**
-     * Split-brain protection: track known peer nodes for quorum checks.
-     * @type {Map<string, number>} nodeId → last seen timestamp
-     */
-    this._knownPeers = new Map();
-
-    /** Expected cluster size for quorum calculation (0 = disabled) */
-    this._expectedClusterSize = parseInt(process.env.FORGE_EXPECTED_CLUSTER_SIZE || '0', 10);
-  }
-
-  /**
-   * Start the registry. In embedded mode this is a no-op.
-   * In multicast/external mode, connects to peers.
-   */
-  async start() {
-    // Start heartbeat with jitter to prevent thundering herd across nodes
-    const jitter = Math.floor(Math.random() * this.heartbeatIntervalMs * 0.2);
-    this._heartbeatTimer = setInterval(() => {
-      this._sendHeartbeats();
-    }, this.heartbeatIntervalMs + jitter);
-    this._heartbeatTimer.unref();
-
-    // Start reaper (remove stale registrations)
-    this._reapTimer = setInterval(() => {
-      this._reapStale();
-    }, this.healthTimeoutMs);
-    this._reapTimer.unref();
-
-    if (this.mode === "multicast") {
-      await this._startMulticast();
-    } else if (this.mode === "external") {
-      await this._startExternal();
-    }
-
-    return this;
-  }
-
-  /**
-   * Register a local service.
-   * Called by the Supervisor when a service worker starts.
-   */
-  register(registration) {
-    const key = `${registration.name}@${this.nodeId}`;
-
-    const reg = {
-      ...registration,
-      nodeId: this.nodeId,
-      host: this.host,
-      health: {
-        status: "healthy",
-        cpu: 0,
-        memory: 0,
-        rpcLatencyP50: 0,
-        rpcLatencyP99: 0,
-        pendingRequests: 0,
-        lastHeartbeat: Date.now(),
-        ...registration.health,
-      },
-      metadata: {
-        version: process.env.npm_package_version ?? "0.0.0",
-        region: process.env.FORGE_REGION ?? "local",
-        startedAt: Date.now(),
-        ...registration.metadata,
-      },
-    };
-
-    this.registrations.set(key, reg);
-    this.localRegistrations.set(registration.name, reg);
-
-    this.emit("registered", reg);
-    this._announceToNetwork(reg);
-
-    return reg;
-  }
-
-  /**
-   * Register a colocated service instance (same process).
-   */
-  registerLocal(name, instance) {
-    this.localInstances.set(name, instance);
-  }
-
-  /**
-   * Deregister a service (shutting down).
-   */
-  deregister(serviceName) {
-    const key = `${serviceName}@${this.nodeId}`;
-    const reg = this.registrations.get(key);
-
-    if (reg) {
-      reg.health.status = "draining";
-      this.emit("deregistering", reg);
-
-      // Announce to network so other nodes stop routing to us
-      this._announceToNetwork(reg);
-
-      // Remove after drain period
-      const drainTimer = setTimeout(() => {
-        this._drainTimers.delete(key);
-        this.registrations.delete(key);
-        this.localRegistrations.delete(serviceName);
-        this.localInstances.delete(serviceName);
-        this.emit("deregistered", { name: serviceName, nodeId: this.nodeId });
-      }, 5000);
-      drainTimer.unref();
-      this._drainTimers.set(key, drainTimer);
-    }
-  }
-
-  /**
-   * Receive a registration from another node.
-   */
-  receiveRemoteRegistration(reg) {
-    if (!reg || typeof reg.name !== 'string' || typeof reg.nodeId !== 'string') return;
-    if (!reg.host || typeof reg.host !== 'string') return;
-    if (!reg.health || typeof reg.health.status !== 'string') return;
-
-    if (reg.nodeId === this.nodeId) return; // ignore self
-
-    const key = `${reg.name}@${reg.nodeId}`;
-    const existing = this.registrations.get(key);
-
-    // Set lastSeen to local clock to avoid clock skew issues with remote timestamps
-    reg.lastSeen = Date.now();
-
-    // Track peer nodes for split-brain detection
-    this._knownPeers.set(reg.nodeId, Date.now());
-
-    this.registrations.set(key, reg);
-
-    if (!existing) {
-      this.emit("discovered", reg);
-    }
-  }
-
-  /**
-   * Check if we can see a quorum of the expected cluster.
-   * Returns true if quorum is met or split-brain detection is disabled.
-   * A node should avoid serving traffic if it's partitioned from the majority.
-   */
-  hasQuorum() {
-    if (this._expectedClusterSize <= 0) return true;
-
-    // Count recently-seen peers (within 2x health timeout)
-    const cutoff = Date.now() - this.healthTimeoutMs * 2;
-    let activePeers = 0;
-    for (const [, lastSeen] of this._knownPeers) {
-      if (lastSeen > cutoff) activePeers++;
-    }
-
-    // +1 for self
-    const visibleNodes = activePeers + 1;
-    const quorum = Math.floor(this._expectedClusterSize / 2) + 1;
-    return visibleNodes >= quorum;
-  }
-
-  /**
-   * Update health for a local service.
-   */
-  updateHealth(serviceName, health) {
-    const reg = this.localRegistrations.get(serviceName);
-    if (reg) {
-      Object.assign(reg.health, health, { lastHeartbeat: Date.now() });
-    }
-  }
-
-  // ─── Resolution ─────────────────────────────────────────
-
-  /**
-   * Resolve endpoints for a service, ordered by preference.
-   *
-   * Returns all known instances with their transport type and
-   * health status, sorted by priority:
-   *   1. Local (colocated, same process)
-   *   2. UDS (same machine, different process)
-   *   3. HTTP (remote, same region)
-   *   4. HTTP (remote, different region)
-   *
-   * @param {string} serviceName
-   * @returns {ResolvedEndpoint[]}
-   */
-  resolve(serviceName) {
-    const endpoints = [];
-
-    const isColocated = this.localInstances.has(serviceName);
-    let localAdded = false;
-
-    for (const [_key, reg] of this.registrations) {
-      if (reg.name !== serviceName) continue;
-      if (reg.health.status === "unhealthy") continue;
-
-      const isLocal = reg.nodeId === this.nodeId;
-      const isDraining = reg.health.status === "draining";
-
-      if (isDraining) continue;
-
-      if (isColocated && isLocal) {
-        if (!localAdded) {
-          endpoints.push({
-            transport: "local",
-            nodeId: reg.nodeId,
-            instance: this.localInstances.get(serviceName),
-            health: reg.health,
-            priority: 0, // highest priority
-          });
-          localAdded = true;
-        }
-      } else if (isLocal && reg.udsPath) {
-        endpoints.push({
-          transport: "uds",
-          nodeId: reg.nodeId,
-          path: reg.udsPath,
-          health: reg.health,
-          priority: 1,
-        });
-      } else if (reg.ports?.http) {
-        const sameRegion = reg.metadata?.region === (process.env.FORGE_REGION ?? "local");
-        endpoints.push({
-          transport: "http",
-          nodeId: reg.nodeId,
-          address: `${reg.host}:${reg.ports.http}`,
-          health: reg.health,
-          priority: sameRegion ? 2 : 3,
-        });
-      }
-    }
-
-    // Sort by priority, then by health
-    endpoints.sort((a, b) => {
-      if (a.priority !== b.priority) return a.priority - b.priority;
-      // Prefer lower latency
-      return (a.health.rpcLatencyP50 ?? 0) - (b.health.rpcLatencyP50 ?? 0);
-    });
-
-    return endpoints;
-  }
-
-  /**
-   * Resolve the BEST single endpoint for a service.
-   * Used by the proxy when making a call.
-   *
-   * @param {string} serviceName
-   * @returns {ResolvedEndpoint|null}
-   */
-  resolveBest(serviceName) {
-    const endpoints = this.resolve(serviceName);
-    return endpoints[0] ?? null;
-  }
-
-  /**
-   * Get all known services and their locations.
-   */
-  topology() {
-    const services = new Map();
-
-    for (const [, reg] of this.registrations) {
-      if (!services.has(reg.name)) {
-        services.set(reg.name, []);
-      }
-      services.get(reg.name).push({
-        nodeId: reg.nodeId,
-        host: reg.host,
-        transport: this.localInstances?.has(reg.name) ? "colocated"
-                 : reg.nodeId === this.nodeId ? "local"
-                 : "http",
-        status: reg.health.status,
-        cpu: reg.health.cpu,
-        workers: reg.workers,
-      });
-    }
-
-    return Object.fromEntries(services);
-  }
-
-  // ─── Multicast Discovery ────────────────────────────────
-
-  /**
-   * Multicast mode: UDP broadcast on the local network.
-   * Each node announces its services every heartbeat interval.
-   * New nodes are discovered automatically.
-   */
-  async _startMulticast() {
-    if (!this._clusterSecret) {
-      if (process.env.NODE_ENV === 'production') {
-        throw new Error('[Registry] FORGE_CLUSTER_SECRET is required for multicast discovery in production');
-      }
-      console.warn(
-        "[Registry] FORGE_CLUSTER_SECRET not set — multicast messages are unauthenticated. Set a shared secret for production use.",
-      );
-    }
-
-    const dgram = await import("node:dgram");
-    const MULTICAST_ADDR = process.env.FORGE_MULTICAST_ADDRESS || "239.255.42.42";
-    const MULTICAST_PORT = parseInt(process.env.FORGE_MULTICAST_PORT || "42042", 10);
-
-    // Create UDP socket for sending/receiving announcements
-    const socket = dgram.createSocket({ type: "udp4", reuseAddr: true });
-
-    // Rate limiting: track message counts per source IP
-    const _multicastRateCounts = new Map();
-    const _multicastRateTimer = setInterval(() => { _multicastRateCounts.clear(); }, 1000);
-    _multicastRateTimer.unref();
-    this._multicastRateTimer = _multicastRateTimer;
-
-    socket.on("message", (buf, rinfo) => {
-      // 1. Size check FIRST
-      if (buf.length > 8192) return;
-
-      // 2. Rate limit per source IP: reject if > 10/sec
-      const srcAddr = rinfo.address;
-      const rateCount = (_multicastRateCounts.get(srcAddr) ?? 0) + 1;
-      _multicastRateCounts.set(srcAddr, rateCount);
-      if (rateCount > 10) return;
-
-      // 3. JSON.parse
-      let msg;
-      try {
-        msg = JSON.parse(buf.toString());
-      } catch (err) {
-        console.warn("[ServiceRegistry] Received malformed multicast message");
-        return;
-      }
-
-      // 4. Signature verification BEFORE checking message structure
-      if (this._clusterSecret) {
-        const sig = msg.sig ?? "";
-        const { sig: _, ...rest } = msg;
-        const canonical = JSON.stringify(sortKeys(rest));
-        const expected = crypto.createHmac("sha256", this._clusterSecret)
-          .update(canonical)
-          .digest("hex");
-        try {
-          const sigBuf = Buffer.from(sig, "hex");
-          const expBuf = Buffer.from(expected, "hex");
-          if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
-            return;
-          }
-        } catch {
-          return;
-        }
-      }
-
-      // 5. THEN check message type, nodeId, etc.
-      if (!msg || typeof msg !== 'object' || !msg.type || msg.type !== 'forge:announce') {
-        return;
-      }
-      if (msg.nodeId === this.nodeId) return; // Ignore own announcements
-
-      // Replay protection: reject stale messages
-      if (typeof msg.timestamp === 'number') {
-        const MAX_MESSAGE_AGE = (this.heartbeatIntervalMs ?? 30000) * 2;
-        if (Math.abs(Date.now() - msg.timestamp) > MAX_MESSAGE_AGE) {
-          return;
-        }
-      }
-
-      for (const reg of msg.services) {
-        this.receiveRemoteRegistration(reg);
-      }
-    });
-
-    await new Promise((resolve) => {
-      socket.bind(MULTICAST_PORT, () => {
-        socket.addMembership(MULTICAST_ADDR);
-        resolve();
-      });
-    });
-
-    this._multicastSocket = socket;
-    this._multicastAddr = MULTICAST_ADDR;
-    this._multicastPort = MULTICAST_PORT;
-  }
-
-  /**
-   * Announce services to the network.
-   */
-  _announceToNetwork(reg) {
-    if (this.mode === "multicast" && this._multicastSocket) {
-      const allServices = [...this.localRegistrations.values()];
-      const testPayload = JSON.stringify({
-        type: "forge:announce",
-        nodeId: this.nodeId,
-        services: allServices,
-      });
-
-      if (Buffer.byteLength(testPayload) > 1400) {
-        // Split services into chunks that fit in a UDP packet
-        const chunks = [];
-        let current = [];
-        let currentSize = 0;
-        for (const svc of allServices) {
-          const svcSize = Buffer.byteLength(JSON.stringify(svc));
-          if (currentSize + svcSize > 1200 && current.length > 0) {
-            chunks.push(current);
-            current = [];
-            currentSize = 0;
-          }
-          current.push(svc);
-          currentSize += svcSize;
-        }
-        if (current.length > 0) chunks.push(current);
-
-        for (const chunk of chunks) {
-          this._sendMulticastPayload(chunk);
-        }
-      } else {
-        this._sendMulticastPayload(allServices);
-      }
-    }
-
-    if (this.mode === "external" && this._backend) {
-      this._backend.set(`forge/services/${reg.name}/${this.nodeId}`, JSON.stringify(reg), {
-        ttl: Math.ceil(this.healthTimeoutMs / 1000),
-      });
-    }
-  }
-
-  _sendMulticastPayload(services) {
-    const payload = {
-      type: "forge:announce",
-      nodeId: this.nodeId,
-      services,
-      timestamp: Date.now(),
-    };
-
-    // Sign with HMAC if cluster secret is configured
-    // Use canonical JSON (recursive sorted keys) to ensure consistent signatures across environments
-    if (this._clusterSecret) {
-      const canonical = JSON.stringify(sortKeys(payload));
-      const sig = crypto.createHmac("sha256", this._clusterSecret).update(canonical).digest("hex");
-      payload.sig = sig;
-    }
-
-    const buf = Buffer.from(JSON.stringify(payload));
-    this._multicastSocket.send(buf, this._multicastPort, this._multicastAddr);
-  }
-
-  // ─── External Backend ───────────────────────────────────
-
-  async _startExternal() {
-    throw new Error(
-      'External registry backend not yet implemented. Planned backends: Redis, etcd, Consul. ' +
-      'Use "embedded" or "multicast" mode for now.'
-    );
-  }
-
-  /**
-   * Set an external backend (Redis, etcd, etc.)
-   *
-   * The backend must implement:
-   *   get(key) → string
-   *   set(key, value, options) → void
-   *   watch(prefix, callback) → void
-   *   delete(key) → void
-   */
-  setBackend(backend) {
-    this._backend = backend;
-  }
-
-  // ─── Health Management ──────────────────────────────────
-
-  _sendHeartbeats() {
-    for (const [, reg] of this.localRegistrations) {
-      reg.health.lastHeartbeat = Date.now();
-      reg.health.cpu = getCpuUsage();
-      reg.health.memory = Math.round(process.memoryUsage().rss / 1024 / 1024);
-      this._announceToNetwork(reg);
-    }
-  }
-
-  _reapStale() {
-    const now = Date.now();
-
-    for (const [key, reg] of this.registrations) {
-      if (reg.nodeId === this.nodeId) continue; // don't reap self
-
-      // Use lastSeen (local receive time) instead of remote lastHeartbeat to avoid clock skew
-      const age = now - (reg.lastSeen ?? reg.health?.lastHeartbeat ?? 0);
-      if (age > this.healthTimeoutMs) {
-        if (reg.health.status !== "unhealthy") {
-          reg.health.status = "unhealthy";
-          this.emit("unhealthy", reg);
-        }
-
-        // Remove after multiplier * timeout
-        if (age > this.healthTimeoutMs * this.staleReapMultiplier) {
-          this.registrations.delete(key);
-          this.emit("removed", reg);
-        }
-      }
-    }
-
-    // Reap stale peers from split-brain tracking
-    const peerCutoff = now - this.healthTimeoutMs * this.staleReapMultiplier;
-    for (const [nodeId, lastSeen] of this._knownPeers) {
-      if (lastSeen < peerCutoff) {
-        this._knownPeers.delete(nodeId);
-      }
-    }
-
-    // Emit warning if quorum is lost
-    if (!this.hasQuorum()) {
-      this.emit("quorum-lost", {
-        expectedSize: this._expectedClusterSize,
-        activePeers: this._knownPeers.size,
-        nodeId: this.nodeId,
-      });
-    }
-  }
-
-  /**
-   * Expose the topology via HTTP for gossip / dashboards.
-   * The supervisor can mount this on its metrics server.
-   */
-  httpHandler(req, res) {
-    if (req.url === "/_forge/topology") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(
-        JSON.stringify(
-          {
-            nodeId: this.nodeId,
-            host: this.host,
-            mode: this.mode,
-            registrations: [...this.registrations.values()],
-            topology: this.topology(),
-          },
-          null,
-          2,
-        ),
-      );
-      return true;
-    }
-
-    const parsedUrl = new URL(req.url, "http://localhost");
-    if (parsedUrl.pathname === "/_forge/resolve" && req.method === "GET") {
-      const service = parsedUrl.searchParams.get("service");
-      if (service) {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify(this.resolve(service), null, 2));
-      } else {
-        res.writeHead(400);
-        res.end("Missing ?service= parameter");
-      }
-      return true;
-    }
-
-    return false;
-  }
-
-  async stop() {
-    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
-    if (this._reapTimer) clearInterval(this._reapTimer);
-
-    // Clear all pending drain timers from deregister()
-    for (const timer of this._drainTimers.values()) {
-      clearTimeout(timer);
-    }
-    this._drainTimers.clear();
-
-    // Immediately remove all local services (skip drain period during stop)
-    for (const name of [...this.localRegistrations.keys()]) {
-      const key = `${name}@${this.nodeId}`;
-      this.registrations.delete(key);
-      this.localRegistrations.delete(name);
-      this.localInstances.delete(name);
-      this.emit("deregistered", { name, nodeId: this.nodeId });
-    }
-
-    if (this._multicastRateTimer) {
-      clearInterval(this._multicastRateTimer);
-    }
-    if (this._multicastSocket) {
-      this._multicastSocket.close();
-    }
-  }
-}
-
-// ─── Utilities ──────────────────────────────────────────────
-
-function sortKeys(obj) {
-  if (Array.isArray(obj)) return obj.map(sortKeys);
-  if (obj && typeof obj === 'object') {
-    return Object.keys(obj).sort().reduce((acc, k) => { acc[k] = sortKeys(obj[k]); return acc; }, {});
-  }
-  return obj;
-}
-
-function getLocalIP() {
-  const interfaces = os.networkInterfaces();
-  for (const name of Object.keys(interfaces)) {
-    for (const iface of interfaces[name]) {
-      if (iface.family === "IPv4" && !iface.internal) {
-        return iface.address;
-      }
-    }
-  }
-  return "127.0.0.1";
-}
-
-let lastCpuUsage = process.cpuUsage();
-let lastCpuTime = Date.now();
-
-function getCpuUsage() {
-  const now = Date.now();
-  const elapsed = now - lastCpuTime;
-  if (elapsed === 0) return 0;
-
-  const usage = process.cpuUsage(lastCpuUsage);
-  lastCpuUsage = process.cpuUsage();
-  lastCpuTime = now;
-
-  // user + system time in microseconds / elapsed wall time in microseconds
-  const cpuPercent = ((usage.user + usage.system) / 1000 / elapsed) * 100;
-  return Math.round(cpuPercent);
-}