threadforge 0.1.0

package/src/registry/ServiceRegistry.js

@@ -0,0 +1,796 @@
+/**
+ * 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
+    this._heartbeatTimer = setInterval(() => {
+      this._sendHeartbeats();
+    }, this.heartbeatIntervalMs);
+    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);
+}