@mcpmesh/sdk 2.3.0 → 2.5.0

package/dist/__tests__/stop-dispatchers.spec.js

@@ -0,0 +1,227 @@
+/**
+ * Tests for #1173 — concurrent claim-dispatcher shutdown under one
+ * shared drain budget, and #1163 MED-2 — `MeshAgent.shutdown()` reaching
+ * the registry unregister (`handle.shutdown()`) regardless of drain
+ * outcome.
+ *
+ * Mirrors the Python fix in PR #1172
+ * (`_mcp_mesh/engine/claim_dispatcher.py::stop_dispatchers`):
+ *   - N dispatchers drain CONCURRENTLY against the SAME window (one
+ *     drain window of wall time, not N stacked 30s windows);
+ *   - the whole phase is hard-capped at drain + grace, after which the
+ *     remaining drains are abandoned with a warning;
+ *   - never rejects — a wedged dispatcher must not prevent the registry
+ *     cleanup callers sequence afterwards.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { stopDispatchers } from "../claim-dispatcher.js";
+import { MeshAgent } from "../agent.js";
+import { ApiRuntime } from "../api-runtime.js";
+import { MeshExpress } from "../express.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Build a stub dispatcher whose stop() runs the given impl. */
+function fakeDispatcher(capability, stopImpl) {
+    return {
+        capability,
+        stop: vi.fn(stopImpl),
+    };
+}
+describe("stopDispatchers (#1173)", () => {
+    let warnSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        vi.spyOn(console, "log").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("stops dispatchers concurrently — wall time is one drain window, not N", async () => {
+        const d1 = fakeDispatcher("cap-a", () => sleep(200));
+        const d2 = fakeDispatcher("cap-b", () => sleep(200));
+        const d3 = fakeDispatcher("cap-c", () => sleep(200));
+        const t0 = Date.now();
+        await stopDispatchers([d1, d2, d3], 2000, 2000);
+        const elapsed = Date.now() - t0;
+        // Sequential would be >= 600ms; concurrent is ~200ms. The 500ms
+        // bound leaves ~300ms of CI scheduling-jitter headroom while still
+        // failing a sequential drain.
+        expect(elapsed).toBeLessThan(500);
+        expect(d1.stop).toHaveBeenCalledWith(2000);
+        expect(d2.stop).toHaveBeenCalledWith(2000);
+        expect(d3.stop).toHaveBeenCalledWith(2000);
+    });
+    it("passes the SHARED drain window to every dispatcher", async () => {
+        const ds = [
+            fakeDispatcher("cap-a", async () => { }),
+            fakeDispatcher("cap-b", async () => { }),
+            fakeDispatcher("cap-c", async () => { }),
+        ];
+        await stopDispatchers(ds, 250, 100);
+        for (const d of ds) {
+            expect(d.stop).toHaveBeenCalledWith(250);
+        }
+    });
+    it("abandons a hanging drain at the hard cap (drain + grace) with a warning", async () => {
+        const hanging = fakeDispatcher("cap-stuck", () => new Promise(() => { }));
+        const t0 = Date.now();
+        await stopDispatchers([hanging], 50, 50);
+        const elapsed = Date.now() - t0;
+        // Returned at ~100ms (50 drain + 50 grace), not hung forever.
+        expect(elapsed).toBeGreaterThanOrEqual(90);
+        expect(elapsed).toBeLessThan(1000);
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("exceeded the shared budget"));
+    });
+    it("a rejecting stop() does not skip its peers and does not reject", async () => {
+        const bad = fakeDispatcher("cap-bad", async () => {
+            throw new Error("stop blew up");
+        });
+        const good = fakeDispatcher("cap-good", () => sleep(20));
+        await expect(stopDispatchers([bad, good], 500, 100)).resolves.toBeUndefined();
+        expect(good.stop).toHaveBeenCalledTimes(1);
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("error stopping dispatcher capability=cap-bad"), expect.any(Error));
+    });
+    it("is a no-op for an empty dispatcher list", async () => {
+        await expect(stopDispatchers([], 50, 50)).resolves.toBeUndefined();
+    });
+});
+describe("MeshAgent.shutdown() — unregister runs regardless of drain outcome (#1163 MED-2 / #1173)", () => {
+    beforeEach(() => {
+        vi.spyOn(console, "warn").mockImplementation(() => { });
+        vi.spyOn(console, "log").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    /**
+     * Drive the REAL `shutdown()` against a stub `this` (same pattern as
+     * the event-loop specs) so we don't have to bind a full agent to the
+     * napi runtime. Only the fields shutdown() reads are provided.
+     */
+    function stubAgentThis(dispatchers) {
+        return {
+            _claimDispatchers: dispatchers,
+            _a2aClients: new Map(),
+            httpsProxy: undefined,
+            handle: { shutdown: vi.fn(async () => { }) },
+        };
+    }
+    it("calls handle.shutdown() even when a dispatcher drain hangs", async () => {
+        const hanging = fakeDispatcher("cap-stuck", () => new Promise(() => { }));
+        const stubThis = stubAgentThis([hanging]);
+        const handle = stubThis.handle; // shutdown() nulls this.handle
+        const shutdown = MeshAgent.prototype.shutdown;
+        await shutdown.call(stubThis, {
+            drainTimeoutMs: 30,
+            drainGraceMs: 30,
+        });
+        expect(handle.shutdown).toHaveBeenCalledTimes(1);
+        // Handle nulled + dispatcher list cleared after a successful unregister.
+        expect(stubThis.handle).toBeNull();
+        expect(stubThis._claimDispatchers).toEqual([]);
+    });
+    it("calls handle.shutdown() even when a dispatcher stop() throws", async () => {
+        const bad = fakeDispatcher("cap-bad", async () => {
+            throw new Error("drain blew up");
+        });
+        const stubThis = stubAgentThis([bad]);
+        const handle = stubThis.handle;
+        const shutdown = MeshAgent.prototype.shutdown;
+        await shutdown.call(stubThis, {
+            drainTimeoutMs: 30,
+            drainGraceMs: 30,
+        });
+        expect(handle.shutdown).toHaveBeenCalledTimes(1);
+    });
+    it("drains slow dispatchers concurrently within one budget", async () => {
+        const d1 = fakeDispatcher("cap-a", () => sleep(200));
+        const d2 = fakeDispatcher("cap-b", () => sleep(200));
+        const d3 = fakeDispatcher("cap-c", () => sleep(200));
+        const stubThis = stubAgentThis([d1, d2, d3]);
+        const handle = stubThis.handle;
+        const shutdown = MeshAgent.prototype.shutdown;
+        const t0 = Date.now();
+        await shutdown.call(stubThis, {
+            drainTimeoutMs: 2000,
+            drainGraceMs: 2000,
+        });
+        const elapsed = Date.now() - t0;
+        // Sequential would be >= 600ms; concurrent is ~200ms. 500ms bound
+        // leaves ~300ms of CI scheduling-jitter headroom.
+        expect(elapsed).toBeLessThan(500);
+        expect(handle.shutdown).toHaveBeenCalledTimes(1);
+    });
+    it("shutdown() is idempotent — repeat calls return the SAME promise and never re-run the teardown", async () => {
+        const d = fakeDispatcher("cap-a", () => sleep(50));
+        const stubThis = stubAgentThis([d]);
+        const handle = stubThis.handle;
+        const shutdown = MeshAgent.prototype.shutdown;
+        const p1 = shutdown.call(stubThis, {
+            drainTimeoutMs: 1000,
+            drainGraceMs: 1000,
+        });
+        // Re-entrant call while the first teardown is mid-drain — the
+        // user-code-shutdown() + signal-during-drain race. Must NOT start
+        // a second concurrent teardown (double dispatcher stop, double
+        // napi handle.shutdown()).
+        const p2 = shutdown.call(stubThis, {
+            drainTimeoutMs: 1000,
+            drainGraceMs: 1000,
+        });
+        expect(p2).toBe(p1);
+        await p1;
+        // A call AFTER completion also returns the memoized promise.
+        const p3 = shutdown.call(stubThis);
+        expect(p3).toBe(p1);
+        await p3;
+        expect(d.stop).toHaveBeenCalledTimes(1);
+        expect(handle.shutdown).toHaveBeenCalledTimes(1);
+        // shutdown() itself flags the shutdown so the event loop's failure
+        // branch can exit promptly.
+        expect(stubThis.shutdownRequested).toBe(true);
+    });
+});
+describe("shutdown() idempotency — ApiRuntime / MeshExpress (same memoized-promise pattern)", () => {
+    beforeEach(() => {
+        vi.spyOn(console, "warn").mockImplementation(() => { });
+        vi.spyOn(console, "log").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("ApiRuntime.shutdown() memoizes — one napi handle.shutdown() across repeat calls", async () => {
+        const stubThis = {
+            handle: { shutdown: vi.fn(async () => { }) },
+            shutdownPromise: null,
+            shutdownRequested: false,
+        };
+        const handle = stubThis.handle; // shutdown() nulls this.handle
+        const shutdown = ApiRuntime.prototype.shutdown;
+        const p1 = shutdown.call(stubThis);
+        const p2 = shutdown.call(stubThis);
+        expect(p2).toBe(p1);
+        await p1;
+        expect(shutdown.call(stubThis)).toBe(p1);
+        expect(handle.shutdown).toHaveBeenCalledTimes(1);
+        expect(stubThis.shutdownRequested).toBe(true);
+    });
+    it("MeshExpress.shutdown() memoizes — one napi handle.shutdown() across repeat calls", async () => {
+        const stubThis = {
+            handle: { shutdown: vi.fn(async () => { }) },
+            server: null,
+            shutdownPromise: null,
+            shutdownRequested: false,
+        };
+        const handle = stubThis.handle;
+        const shutdown = MeshExpress.prototype.shutdown;
+        const p1 = shutdown.call(stubThis);
+        const p2 = shutdown.call(stubThis);
+        expect(p2).toBe(p1);
+        await p1;
+        expect(shutdown.call(stubThis)).toBe(p1);
+        expect(handle.shutdown).toHaveBeenCalledTimes(1);
+        expect(stubThis.shutdownRequested).toBe(true);
+    });
+});
+//# sourceMappingURL=stop-dispatchers.spec.js.map

package/dist/__tests__/stop-dispatchers.spec.js.map

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

package/dist/agent.d.ts

@@ -48,6 +48,13 @@ export declare function __getWorkerToolMap(): Map<string, (...args: unknown[]) =
  * - Dependency injection for tool functions
  */
 export declare class MeshAgent {
+    /**
+     * Hard cap on the signal-path shutdown sequence. Must exceed the
+     * dispatcher drain hard-cap (30s drain + 10s grace, see
+     * `stopDispatchers`) so a clean drain isn't cut short; the extra 5s
+     * covers pool/A2A teardown and the registry unregister.
+     */
+    private static readonly SIGNAL_SHUTDOWN_TIMEOUT_MS;
     private server;
     private config;
     private agentId;
@@ -63,6 +70,23 @@ export declare class MeshAgent {
     private started;
     private tracingEnabled;
     private shutdownRequested;
+    /**
+     * Memoized in-flight (or completed) teardown. `shutdown()` is
+     * idempotent: the first caller creates this promise and every later
+     * caller — user code, the signal handler, a second signal — awaits
+     * the SAME teardown instead of racing a concurrent one (double
+     * dispatcher drain, double napi `handle.shutdown()`).
+     */
+    private shutdownPromise;
+    /**
+     * This agent's own SIGINT/SIGTERM handler references, kept so
+     * shutdown() can `process.off` them. Without removal, sequential
+     * MeshAgent instances in one process (legal across async chunk
+     * boundaries) accumulate stale handlers whose memoized — already
+     * resolved — shutdown() would `process.exit(0)` immediately on the
+     * next signal, cutting short the LIVE agent's drain.
+     */
+    private signalHandlers;
     /**
      * Resolved dependencies: composite key -> proxy
      * Key format: "${toolName}:dep_${depIndex}" (e.g., "myTool:dep_0")
@@ -190,10 +214,15 @@ export declare class MeshAgent {
      * Install signal handlers for graceful shutdown.
      * Ensures agent unregisters from registry on SIGINT/SIGTERM.
      *
-     * Calls handle.shutdown() directly to trigger Rust core unregistration.
-     * This causes nextEvent() to return with a "shutdown" event, breaking
-     * the event loop cleanly. The shutdown is async but we don't await it
-     * in the signal handler - the event loop handles the exit.
+     * Runs the FULL `shutdown()` sequence (issue #1163 MED-2): claim
+     * dispatchers drain their in-flight jobs (concurrently, under one
+     * shared budget — see `stopDispatchers`), A2A clients / HTTP pool /
+     * tool-worker pool close, and `handle.shutdown()` unregisters from
+     * the registry (which also resolves the event loop's `nextEvent()`
+     * with a "shutdown" event, ending it cleanly).
+     *
+     * The whole sequence is bounded by a force-exit timer so a hang in
+     * any cleanup step cannot wedge the process past its SIGTERM grace.
      */
     private installSignalHandlers;
     /**
@@ -202,6 +231,15 @@ export declare class MeshAgent {
     private startHeartbeat;
     /**
      * Run the event loop to handle mesh events.
+     *
+     * Resilience (issue #1163 MED-1): the loop must outlive individual
+     * failures. A throw from an event handler (e.g. a malformed event
+     * hitting a non-null assertion) is logged and the loop continues; a
+     * `nextEvent()` rejection (e.g. a transient napi failure) backs off
+     * exponentially (capped) and retries. Only the "shutdown" event — or
+     * the handle being torn down — exits the loop. Previously a single
+     * throw broke the loop permanently, freezing dependency-topology
+     * updates for the process lifetime while the agent kept serving.
      */
     private runEventLoop;
     /**
@@ -237,6 +275,16 @@ export declare class MeshAgent {
      * Get all resolved dependencies.
      */
     getAllDependencies(): Map<string, McpMeshTool>;
+    /**
+     * Inject a mock/fake proxy for a capability (the documented mock
+     * contract — see `meshctl man testing --typescript`).
+     *
+     * Fills the dependency slot of every registered tool that declares the
+     * capability and marks those slots resolved with the settle state, so
+     * the settling-window grace (#1193) never waits on a caller-supplied
+     * dependency.
+     */
+    setMockDependency(capability: string, mock: McpMeshTool): void;
     /**
      * Get the agent handle for advanced operations.
      */
@@ -251,8 +299,20 @@ export declare class MeshAgent {
     getAgentId(): string;
     /**
      * Shutdown the agent gracefully.
+     *
+     * Idempotent and re-entrant: the first call runs the teardown; every
+     * later call (user code, the signal handler, a double signal) returns
+     * the SAME promise — later calls' `opts` are ignored. The memo is
+     * never cleared: shutdown is terminal, and re-running a half-torn-down
+     * cleanup after a failure would be worse than surfacing the original
+     * rejection to every caller.
      */
-    shutdown(): Promise<void>;
+    shutdown(opts?: {
+        /** Shared in-flight-handler drain window for claim dispatchers. */
+        drainTimeoutMs?: number;
+        /** Headroom on top of the drain window before drains are abandoned. */
+        drainGraceMs?: number;
+    }): Promise<void>;
 }
 /**
  * Create a MeshAgent wrapping a FastMCP server.

package/dist/agent.d.ts.map

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