threadforge 0.1.1 → 0.2.1

package/dist/core/DirectMessageBus.js

@@ -0,0 +1,352 @@
+import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isExpectedIpcError } from "./ipc-errors.js";
+const EXIT_SOCKET_DIRS = new Set();
+let EXIT_CLEANUP_INSTALLED = false;
+function cleanupSocketDir(socketDir) {
+    try {
+        if (fs.existsSync(socketDir)) {
+            for (const f of fs.readdirSync(socketDir)) {
+                try {
+                    fs.unlinkSync(path.join(socketDir, f));
+                }
+                catch {
+                    /* ignore: cleanup — socket file may already be removed */
+                }
+            }
+            try {
+                fs.rmdirSync(socketDir);
+            }
+            catch {
+                /* ignore: cleanup — directory may already be removed or non-empty */
+            }
+        }
+    }
+    catch {
+        /* ignore: cleanup — best-effort removal of socket directory */
+    }
+}
+function installExitCleanupHook() {
+    if (EXIT_CLEANUP_INSTALLED)
+        return;
+    EXIT_CLEANUP_INSTALLED = true;
+    process.once("exit", () => {
+        for (const socketDir of EXIT_SOCKET_DIRS) {
+            cleanupSocketDir(socketDir);
+        }
+        EXIT_SOCKET_DIRS.clear();
+    });
+}
+function isWorkerSendable(worker) {
+    if (!worker)
+        return false;
+    if (typeof worker.isDead === "function" && worker.isDead())
+        return false;
+    if (typeof worker.isConnected === "function" && !worker.isConnected())
+        return false;
+    if (worker.process?.connected === false)
+        return false;
+    return true;
+}
+/**
+ * DirectMessageBus — Unix Domain Socket Mesh (Supervisor Side)
+ *
+ * The fundamental problem: cluster.Worker.send() can only transfer
+ * sockets/servers, not MessagePort objects. So we can't use MessageChannel
+ * for direct worker-to-worker communication in cluster mode.
+ *
+ * Solution: Each worker opens a Unix domain socket server. Workers connect
+ * directly to each other via these sockets. The supervisor only tells
+ * workers WHERE to connect (socket paths), then gets out of the way.
+ *
+ * Architecture:
+ *
+ *   SETUP (supervisor involved briefly):
+ *     1. Each worker starts a UDS server at /tmp/forge-{pid}/{service}-{worker}.sock
+ *     2. Worker reports its socket path to supervisor via IPC
+ *     3. Supervisor broadcasts the full socket registry to all workers
+ *     4. Workers establish direct connections to each other
+ *
+ *   RUNTIME (supervisor NOT involved in message routing):
+ *     Worker A ──UDS──► Worker B   (direct, length-prefixed JSON)
+ *     Worker B ──UDS──► Worker A
+ *
+ *   Supervisor only handles:
+ *     - Socket path registry distribution (one-time + on new workers)
+ *     - Health checks (periodic pull, not per-message)
+ *     - Worker lifecycle (restart, scale)
+ */
+export class DirectMessageBus extends EventEmitter {
+    workers;
+    socketRegistry;
+    _registeredWorkerIds;
+    _workerErrorHandlers;
+    _connections;
+    _socketDir;
+    _broadcastTimer;
+    constructor() {
+        super();
+        this.workers = new Map();
+        this.socketRegistry = new Map();
+        this._registeredWorkerIds = new Set();
+        this._workerErrorHandlers = new WeakMap();
+        this._connections = new Map();
+        // S-IPC-2: Random suffix prevents socket path prediction
+        this._socketDir = path.join(os.tmpdir(), `forge-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+        this._broadcastTimer = null;
+        try {
+            fs.mkdirSync(this._socketDir, { recursive: true });
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                console.error("[DirectMessageBus] mkdirSync failed:", e.message);
+        }
+        EXIT_SOCKET_DIRS.add(this._socketDir);
+        installExitCleanupHook();
+    }
+    get socketDir() {
+        return this._socketDir;
+    }
+    /**
+     * Register a worker. Tell it to start a UDS server, then
+     * broadcast the updated registry to all workers.
+     */
+    registerWorker(serviceName, worker, mode = "cluster") {
+        if (!this.workers.has(serviceName)) {
+            this.workers.set(serviceName, []);
+        }
+        const workerId = mode === "cluster" ? worker.id : worker.threadId;
+        const entry = {
+            id: workerId,
+            worker,
+            mode,
+            socketPath: null,
+        };
+        this.workers.get(serviceName).push(entry);
+        // Attach one shared error listener per worker so late IPC channel errors
+        // during churn don't surface as unhandled EventEmitter errors.
+        if (!this._workerErrorHandlers.has(worker)) {
+            const errorHandler = (err) => {
+                if (!isExpectedIpcError(err)) {
+                    console.error("[DirectMessageBus] Worker error:", err?.message ?? err);
+                }
+            };
+            this._workerErrorHandlers.set(worker, errorHandler);
+            worker.on("error", errorHandler);
+        }
+        entry._errorHandler = this._workerErrorHandlers.get(worker);
+        // Prevent duplicate message listener registration
+        // If workerId is already registered (e.g., crashed worker's ID reused), clean up stale listeners
+        if (this._registeredWorkerIds.has(workerId)) {
+            // Find and clean up stale entry with this workerId across all services
+            for (const [svcName, entries] of this.workers) {
+                const staleIdx = entries.findIndex((e) => e.id === workerId && e.worker !== worker);
+                if (staleIdx !== -1) {
+                    const stale = entries[staleIdx];
+                    if (stale._messageHandler)
+                        stale.worker.off("message", stale._messageHandler);
+                    if (stale.socketPath) {
+                        try {
+                            fs.unlinkSync(stale.socketPath);
+                        }
+                        catch {
+                            /* ignore: cleanup — stale socket may already be removed */
+                        }
+                        this.socketRegistry.delete(`${svcName}:${workerId}`);
+                    }
+                    entries.splice(staleIdx, 1);
+                    if (entries.length === 0)
+                        this.workers.delete(svcName);
+                }
+            }
+            this._registeredWorkerIds.delete(workerId);
+        }
+        this._registeredWorkerIds.add(workerId);
+        // Listen for supervisor-level IPC from this worker
+        const messageHandler = (msg) => {
+            const forgeMsg = msg;
+            if (!forgeMsg || !forgeMsg.type)
+                return;
+            switch (forgeMsg.type) {
+                case "forge:socket-ready":
+                    // In colocated groups a worker may host multiple services, each with its
+                    // own socket. Ignore ready messages for sibling services on this entry.
+                    if (forgeMsg.serviceName && forgeMsg.serviceName !== serviceName)
+                        break;
+                    entry.socketPath = forgeMsg.socketPath;
+                    this.socketRegistry.set(`${serviceName}:${forgeMsg.workerId}`, forgeMsg.socketPath);
+                    this._scheduleBroadcast();
+                    break;
+                case "forge:worker-ready":
+                    this._sendInitSocket(worker, serviceName, entry.id);
+                    this._sendRegistryTo(worker);
+                    break;
+                case "forge:channel-ready": {
+                    // CR-IPC-9: Track established connections
+                    const workerKey = `${serviceName}:${entry.id}`;
+                    if (!this._connections.has(workerKey)) {
+                        this._connections.set(workerKey, new Set());
+                    }
+                    if (forgeMsg.peerKey) {
+                        this._connections.get(workerKey).add(forgeMsg.peerKey);
+                    }
+                    break;
+                }
+                case "forge:metric":
+                case "forge:log":
+                case "forge:health-response": {
+                    const eventName = forgeMsg.type.replace("forge:", "");
+                    this.emit(eventName, { service: serviceName, ...forgeMsg });
+                    break;
+                }
+            }
+        };
+        entry._messageHandler = messageHandler;
+        worker.on("message", messageHandler);
+        // Tell the new worker to start its UDS server
+        this._sendInitSocket(worker, serviceName, entry.id);
+        this._sendRegistryTo(worker);
+    }
+    _scheduleBroadcast() {
+        // CR-IPC-5: Don't cancel existing timer — let the first registration broadcast on schedule
+        if (this._broadcastTimer)
+            return;
+        this._broadcastTimer = setTimeout(() => {
+            this._broadcastTimer = null;
+            this._broadcastRegistry();
+        }, 50 + Math.floor(Math.random() * 50));
+        // SUP-M3: Don't keep the process alive during shutdown
+        this._broadcastTimer.unref();
+    }
+    _sendInitSocket(worker, serviceName, workerId) {
+        if (!isWorkerSendable(worker))
+            return;
+        try {
+            worker.send({
+                type: "forge:init-socket",
+                socketDir: this._socketDir,
+                serviceName,
+                workerId,
+            });
+        }
+        catch (e) {
+            if (!isExpectedIpcError(e)) {
+                console.error("[DirectMessageBus] Failed to send init-socket:", e.message);
+            }
+        }
+    }
+    _sendRegistryTo(worker) {
+        if (!isWorkerSendable(worker))
+            return;
+        try {
+            const msg = {
+                type: "forge:socket-registry",
+                registry: Object.fromEntries(this.socketRegistry),
+            };
+            // S-IPC-1: Include cluster secret for handshake authentication
+            const secret = process.env.FORGE_CLUSTER_SECRET;
+            if (secret) {
+                msg.secret = secret;
+            }
+            worker.send(msg);
+        }
+        catch (e) {
+            if (!isExpectedIpcError(e)) {
+                console.error("[DirectMessageBus] Failed to send registry:", e.message);
+            }
+        }
+    }
+    _broadcastRegistry() {
+        for (const [, workers] of this.workers) {
+            for (const entry of workers) {
+                this._sendRegistryTo(entry.worker);
+            }
+        }
+    }
+    unregisterWorker(serviceName, workerId, options = {}) {
+        const workers = this.workers.get(serviceName);
+        if (!workers)
+            return;
+        const idx = workers.findIndex((w) => w.id === workerId);
+        if (idx === -1)
+            return;
+        const entry = workers[idx];
+        if (entry._messageHandler) {
+            entry.worker.off("message", entry._messageHandler);
+        }
+        if (entry.socketPath) {
+            try {
+                fs.unlinkSync(entry.socketPath);
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    console.error("[DirectMessageBus] unlink failed:", e.message);
+            }
+            this.socketRegistry.delete(`${serviceName}:${workerId}`);
+        }
+        workers.splice(idx, 1);
+        // Clean up the registered worker ID tracking
+        this._registeredWorkerIds.delete(workerId);
+        if (workers.length === 0) {
+            this.workers.delete(serviceName);
+        }
+        if (!options.suppressBroadcast && this.workers.size > 0) {
+            this._broadcastRegistry();
+        }
+    }
+    unregisterService(serviceName) {
+        const workers = [...(this.workers.get(serviceName) ?? [])];
+        for (const w of workers) {
+            this.unregisterWorker(serviceName, w.id);
+        }
+    }
+    requestHealthChecks() {
+        for (const [, workers] of this.workers) {
+            for (const entry of workers) {
+                if (!isWorkerSendable(entry.worker))
+                    continue;
+                try {
+                    entry.worker.send({ type: "forge:health-check", timestamp: Date.now() });
+                }
+                catch (err) {
+                    if (!isExpectedIpcError(err)) {
+                        console.error("[DirectMessageBus] Failed to send health-check:", err.message);
+                    }
+                }
+            }
+        }
+    }
+    stats() {
+        const result = {};
+        for (const [name, workers] of this.workers) {
+            result[name] = {
+                workerCount: workers.length,
+                ids: workers.map((w) => w.id),
+                directSockets: workers.filter((w) => w.socketPath).length,
+            };
+        }
+        return result;
+    }
+    /**
+     * CR-IPC-9: Get the connection matrix for debugging.
+     */
+    getConnectionMatrix() {
+        const result = {};
+        for (const [key, peers] of this._connections) {
+            result[key] = [...peers];
+        }
+        return result;
+    }
+    cleanup() {
+        if (this._broadcastTimer) {
+            clearTimeout(this._broadcastTimer);
+            this._broadcastTimer = null;
+        }
+        cleanupSocketDir(this._socketDir);
+        EXIT_SOCKET_DIRS.delete(this._socketDir);
+    }
+}
+//# sourceMappingURL=DirectMessageBus.js.map

package/dist/core/DirectMessageBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectMessageBus.js","sourceRoot":"","sources":["../../src/core/DirectMessageBus.ts"],"names":[],"mappings":"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"}

package/dist/core/EndpointResolver.d.ts

@@ -0,0 +1,111 @@
+interface Endpoint {
+    host: string;
+    port: number;
+    remote: boolean;
+}
+interface EndpointInput {
+    host: string;
+    port: number;
+    remote?: boolean;
+}
+interface WrappedEntry {
+    key: string;
+    host: string;
+    port: number;
+    remote: boolean;
+}
+interface RoutingStrategy {
+    pick(entries: WrappedEntry[], callContext?: unknown): WrappedEntry | WrappedEntry[] | null;
+    acquire?(endpointKey: string): void;
+    release?(endpointKey: string): void;
+}
+export declare class EndpointResolver {
+    private _endpoints;
+    private _counters;
+    private _strategies;
+    private _wrappedCache;
+    private _healthStatus;
+    private _failureCounts;
+    private _failureThreshold;
+    constructor();
+    /**
+     * Set a routing strategy for a specific service.
+     * When set, resolve() delegates to the strategy's pick() method
+     * instead of using built-in round-robin.
+     *
+     * The strategy must implement pick(entries, callContext) where entries
+     * are wrapped as { key: "host:port", host, port, remote }.
+     */
+    setStrategy(serviceName: string, strategy: RoutingStrategy): void;
+    /**
+     * Create an EndpointResolver from environment variables.
+     *
+     * Parses FORGE_SERVICE_ENDPOINTS first (full endpoint map with host/port/remote).
+     * Falls back to FORGE_SERVICE_PORTS (localhost-only port map) when endpoints
+     * aren't available.
+     */
+    static fromEnv(): EndpointResolver;
+    /**
+     * Resolve an endpoint for a service.
+     * Delegates to a configured RoutingStrategy when available,
+     * otherwise round-robins across instances.
+     */
+    resolve(serviceName: string, callContext?: unknown): Endpoint | Endpoint[] | null;
+    /**
+     * Get all endpoints for a service (used for broadcast/event delivery).
+     */
+    all(serviceName: string): Endpoint[];
+    /**
+     * Add or update an endpoint for a service.
+     * Used by dynamic registry discovery.
+     */
+    set(serviceName: string, endpoint: EndpointInput): void;
+    /**
+     * Remove a specific instance of a service.
+     * Used when a remote node goes down.
+     */
+    remove(serviceName: string, host: string, port: number): void;
+    /**
+     * COR-C1: Acquire a pending slot for a resolved endpoint.
+     * Delegates to the service's routing strategy if it supports acquire().
+     * Must be paired with releaseEndpoint() in a finally block.
+     */
+    acquireEndpoint(serviceName: string, endpointKey: string): void;
+    /**
+     * COR-C1: Release a pending slot for a resolved endpoint.
+     * Delegates to the service's routing strategy if it supports release().
+     */
+    releaseEndpoint(serviceName: string, endpointKey: string): void;
+    /**
+     * REG-H2: Update health status for a specific endpoint.
+     * Called when the Supervisor pushes health updates or on connection failure feedback.
+     */
+    setHealthStatus(host: string, port: number, status: 'healthy' | 'degraded' | 'unhealthy' | 'draining'): void;
+    /**
+     * REG-H2: Get the health status of a specific endpoint.
+     */
+    getHealthStatus(host: string, port: number): string;
+    /**
+     * REG-M2: Record a connection failure for an endpoint.
+     * After _failureThreshold consecutive failures, the endpoint is marked unhealthy.
+     * Returns the current consecutive failure count.
+     */
+    recordFailure(host: string, port: number): number;
+    /**
+     * REG-M2: Record a successful connection to an endpoint.
+     * Resets the consecutive failure counter and marks the endpoint healthy.
+     */
+    recordSuccess(host: string, port: number): void;
+    /**
+     * Check if a service has any known endpoints.
+     */
+    has(serviceName: string): boolean;
+    /**
+     * REG-H1: Apply a full endpoint map update (pushed from Supervisor).
+     * Merges new/updated endpoints and removes stale ones not present in the update.
+     * Only updates remote endpoints to avoid overwriting local colocated/UDS entries.
+     */
+    applyEndpointUpdate(endpointMap: Record<string, unknown>): void;
+}
+export {};
+//# sourceMappingURL=EndpointResolver.d.ts.map

package/dist/core/EndpointResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndpointResolver.d.ts","sourceRoot":"","sources":["../../src/core/EndpointResolver.ts"],"names":[],"mappings":"AAaA,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,eAAe;IACvB,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,YAAY,EAAE,GAAG,IAAI,CAAC;IAC3F,OAAO,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAWD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,WAAW,CAA+B;IAElD,OAAO,CAAC,aAAa,CAA8B;IAEnD,OAAO,CAAC,aAAa,CAAiE;IAEtF,OAAO,CAAC,cAAc,CAAsB;IAE5C,OAAO,CAAC,iBAAiB,CAAS;;IAYlC;;;;;;;OAOG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAOjE;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,IAAI,gBAAgB;IAkDlC;;;;OAIG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI;IAoDjF;;OAEG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIpC;;;OAGG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAuBvD;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAiB7D;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAO/D;;;OAGG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAO/D;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI;IAW5G;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAInD;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAWjD;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAW/C;;OAEG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAKjC;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CA+BhE"}