threadforge 0.1.1 → 0.2.1

package/dist/registry/ServiceRegistry.js

@@ -0,0 +1,735 @@
+/**
+ * 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";
+import { RegistryMode } from "../core/config-enums.js";
+// ─── Base Registry ──────────────────────────────────────────
+export class ServiceRegistry extends EventEmitter {
+    mode;
+    nodeId;
+    host;
+    heartbeatIntervalMs;
+    healthTimeoutMs;
+    httpBasePort;
+    staleReapMultiplier;
+    registrations;
+    localRegistrations;
+    localInstances;
+    _clusterSecret;
+    _previousClusterSecret;
+    _heartbeatTimer;
+    _reapTimer;
+    _backend;
+    _drainTimers;
+    _knownPeers;
+    _expectedClusterSize;
+    // REG-M4: Flapping detection — consecutive healthy heartbeats before re-promoting
+    _healthyStreak;
+    _minHealthyThreshold;
+    _degraded;
+    _multicastSocket;
+    _multicastAddr;
+    _multicastPort;
+    _multicastRateTimer;
+    constructor(options = {}) {
+        super();
+        this.mode = options.mode ?? RegistryMode.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._previousClusterSecret = null;
+        this.staleReapMultiplier = options.staleReapMultiplier ?? 3;
+        this.registrations = new Map();
+        this.localRegistrations = new Map();
+        this.localInstances = new Map();
+        this._heartbeatTimer = null;
+        this._reapTimer = null;
+        this._backend = null;
+        this._drainTimers = new Map();
+        this._knownPeers = new Map();
+        this._expectedClusterSize = parseInt(process.env.FORGE_EXPECTED_CLUSTER_SIZE || "0", 10);
+        // REG-M4: Require 3 consecutive healthy heartbeats before re-promoting
+        this._healthyStreak = new Map();
+        this._minHealthyThreshold = 3;
+        this._degraded = false;
+    }
+    /**
+     * 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 === RegistryMode.MULTICAST) {
+            await this._startMulticast();
+        }
+        else if (this.mode === RegistryMode.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,
+            name: registration.name,
+            nodeId: this.nodeId,
+            host: this.host,
+            ports: registration.ports ?? {},
+            udsPath: registration.udsPath ?? null,
+            workers: registration.workers ?? 0,
+            contract: {
+                methods: [],
+                events: [],
+                ...registration.contract,
+            },
+            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());
+        // REG-M4: Flapping detection — require consecutive healthy heartbeats
+        // before re-promoting a previously unhealthy service
+        if (existing && existing.health.status === "unhealthy" && reg.health.status === "healthy") {
+            const streak = (this._healthyStreak.get(key) ?? 0) + 1;
+            this._healthyStreak.set(key, streak);
+            if (streak < this._minHealthyThreshold) {
+                // Keep as unhealthy until threshold is met; update lastSeen so it doesn't get reaped
+                existing.lastSeen = reg.lastSeen;
+                existing.health.lastHeartbeat = reg.health.lastHeartbeat;
+                return;
+            }
+            // Threshold met — promote to healthy and clear streak counter
+            this._healthyStreak.delete(key);
+        }
+        else if (reg.health.status !== "healthy") {
+            // Reset streak counter if not healthy
+            this._healthyStreak.delete(key);
+        }
+        else {
+            // Healthy and not previously unhealthy — clear any streak tracking
+            this._healthyStreak.delete(key);
+        }
+        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)
+     */
+    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,
+                });
+            }
+        }
+        // REG-M5: When degraded (quorum lost), exclude remote endpoints unless they are the only option
+        if (this._degraded) {
+            const localEndpoints = endpoints.filter(e => e.transport === "local" || e.transport === "uds");
+            if (localEndpoints.length > 0) {
+                localEndpoints.sort((a, b) => a.priority - b.priority);
+                return localEndpoints;
+            }
+            // Fall through to all endpoints if no local ones available
+        }
+        // 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.
+     */
+    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,
+                memory: reg.health.memory,
+                rpcLatencyP99: reg.health.rpcLatencyP99,
+                pendingRequests: reg.health.pendingRequests,
+                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 {
+                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 === RegistryMode.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 === RegistryMode.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;
+    }
+    /**
+     * REG-M3: Rotate the cluster secret at runtime.
+     * The current secret becomes the previous secret (accepted during rotation),
+     * and the new secret becomes the current one used for signing.
+     */
+    rotateSecret(newSecret) {
+        if (!newSecret || typeof newSecret !== 'string') {
+            throw new Error('New cluster secret must be a non-empty string');
+        }
+        this._previousClusterSecret = this._clusterSecret;
+        this._clusterSecret = newSecret;
+    }
+    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);
+}
+//# sourceMappingURL=ServiceRegistry.js.map