@emseepea/server 0.23.0 → 0.24.0

package/dist/index.js

@@ -8,9 +8,13 @@ import { readFileSync } from "node:fs";
 import { readdir, realpath } from "node:fs/promises";
 import { isIP } from "node:net";
 import { isAbsolute, join } from "node:path";
+import { performance } from "node:perf_hooks";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { z } from "zod";
+import { prepareAppShutdown, remainingAppShutdown, startAppShutdown, registerAppShutdownOwner } from "./app-shutdown.js";
 import { createMcpEventRuntime, McpEventInputError } from "./events.js";
+import { createExternalMcpEventRuntime } from "./events-external.js";
+export { ExternalMcpEventError } from "./events-external.js";
 import { createResourceInventory, ResourceInventoryCursorError } from "./resource-inventory.js";
 import { installObservability, observabilityState, } from "./telemetry.js";
 export { openTelemetry, structuredLogging, } from "./telemetry.js";
@@ -1093,6 +1097,8 @@ export function createEmseepea(options) {
     const readinessTimeoutMs = callbackTimeout("readiness", readiness, "readinessTimeoutMs", options.readinessTimeoutMs);
     const stopping = new AbortController();
     let eventRuntime;
+    let internalEventRuntime;
+    let externalEventRuntime;
     let pendingReadiness;
     async function ready() {
         if (stopping.signal.aborted)
@@ -1173,7 +1179,14 @@ export function createEmseepea(options) {
     if (options.events && !authentication) {
         throw new TypeError("MCP Events require authentication configuration");
     }
-    eventRuntime = options.events ? createMcpEventRuntime(options.events) : undefined;
+    if (options.events) {
+        if ("mode" in options.events) {
+            eventRuntime = externalEventRuntime = createExternalMcpEventRuntime(options.events);
+        }
+        else {
+            eventRuntime = internalEventRuntime = createMcpEventRuntime(options.events);
+        }
+    }
     const hasStreaming = tools.some((tool) => tool[TOOL_STREAMING]);
     const hasProgress = hasStreaming || resources.length > 0 || prompts.length > 0;
     if ([
@@ -1332,6 +1345,22 @@ export function createEmseepea(options) {
     });
     const nodeHandler = toNodeHandler(sdkHandler);
     const app = createMcpFastifyApp({ host: deployment.mode === "loopback" ? "127.0.0.1" : "0.0.0.0" });
+    const unstartedSockets = new Set();
+    app.server.on("connection", (socket) => {
+        if (stopping.signal.aborted) {
+            socket.destroy();
+            return;
+        }
+        unstartedSockets.add(socket);
+        socket.once("close", () => unstartedSockets.delete(socket));
+    });
+    app.server.on("request", (request, response) => {
+        unstartedSockets.delete(request.socket);
+        response.once("finish", () => {
+            if (stopping.signal.aborted)
+                queueMicrotask(() => app.server.closeIdleConnections());
+        });
+    });
     async function serveResourceSubscription(request, reply, uri) {
         if (!resourceSubscriptions || !resourceEvents)
             return;
@@ -1421,7 +1450,11 @@ export function createEmseepea(options) {
             .code(available ? 200 : 503).send(available ? "ready\n" : "not ready\n");
     });
     app.addHook("preClose", async () => {
+        prepareAppShutdown(app);
+        void startAppShutdown(app);
         stopping.abort();
+        for (const socket of unstartedSockets)
+            socket.destroy();
         await Promise.all([...activeSubscriptions].map((handler) => handler.close()));
     });
     if (authentication) {
@@ -1442,6 +1475,7 @@ export function createEmseepea(options) {
         handler: async (_request, reply) => { await reply.header("allow", "POST").code(405).send(); },
     });
     app.post("/mcp", { bodyLimit: maxRequestBytes }, async (request, reply) => {
+        const admittedAt = performance.now();
         if (deployment.mode === "production-behind-proxy" &&
             !validateProductionRequest(request, reply, deployment, limiter))
             return;
@@ -1538,95 +1572,111 @@ export function createEmseepea(options) {
         }
         if (eventRuntime && !legacy && isRecord(request.body) &&
             (request.body.method === "server/discover" || eventMethod)) {
-            if (!await eventRuntime.ready()) {
-                await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
-                return;
-            }
-            if (request.body.method === "server/discover") {
-                const activeTools = protectsCatalogue
-                    ? tools.filter((tool) => accessAllows(tool[TOOL_ACCESS], principal)) : tools;
-                const activeResources = protectsCatalogue
-                    ? resources.filter((resource) => accessAllows(resource[RESOURCE_ACCESS], principal)) : resources;
-                const activePrompts = protectsCatalogue
-                    ? prompts.filter((prompt) => accessAllows(prompt[PROMPT_ACCESS], principal)) : prompts;
-                const capabilities = {
-                    ...(activeTools.length ? { tools: { listChanged: false } } : {}),
-                    ...(activeResources.length ? { resources: {
-                            subscribe: Boolean(resourceSubscriptions), listChanged: false,
-                        } } : {}),
-                    ...(activePrompts.length ? { prompts: { listChanged: false } } : {}),
-                    ...(activeResources.some((resource) => resource[HAS_COMPLETION]) ||
-                        activePrompts.some((prompt) => prompt[HAS_COMPLETION]) ? { completions: {} } : {}),
-                    ...(clientLogging ? { logging: {} } : {}),
-                    events: {},
-                };
-                await reply.code(200).send({
-                    jsonrpc: "2.0",
-                    id: requestId(request.body.id),
-                    result: {
-                        supportedVersions: [PROTOCOL_VERSION],
-                        capabilities,
-                        resultType: "complete",
-                        ttlMs: protectsCatalogue ? 0 : cacheHints?.["server/discover"]?.ttlMs ?? 0,
-                        cacheScope: protectsCatalogue ? "private" : cacheHints?.["server/discover"]?.cacheScope ?? "private",
-                        ...(options.instructions ? { instructions: options.instructions } : {}),
-                        _meta: { "io.modelcontextprotocol/serverInfo": serverInfo },
-                    },
-                });
-                return;
-            }
-            if (!authInfo)
-                throw new Error("Events reached execution without verified authorization");
-            let ownerKey;
+            const disconnectedEvents = new AbortController();
+            const abortEvents = () => disconnectedEvents.abort();
+            request.raw.once("aborted", abortEvents);
+            reply.raw.once("close", abortEvents);
+            if (requestAlreadyClosed(request, reply))
+                abortEvents();
             try {
-                ownerKey = await eventRuntime.ownerKey(authInfo);
-            }
-            catch {
-                await sendRpcError(reply, 500, -32603, "Event owner identity unavailable", requestId(request.body.id));
-                return;
-            }
-            if (request.body.method === "events/list") {
-                try {
-                    const events = await eventRuntime.list(ownerKey);
+                const requestEvents = externalEventRuntime ? externalEventRuntime.forInvocation({
+                    signal: AbortSignal.any([stopping.signal, disconnectedEvents.signal]),
+                    deadlineMs: Date.now() + Math.max(0, operationTimeoutMs - (performance.now() - admittedAt)),
+                }) : eventRuntime;
+                if (!await requestEvents.ready()) {
+                    await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
+                    return;
+                }
+                if (request.body.method === "server/discover") {
+                    const activeTools = protectsCatalogue
+                        ? tools.filter((tool) => accessAllows(tool[TOOL_ACCESS], principal)) : tools;
+                    const activeResources = protectsCatalogue
+                        ? resources.filter((resource) => accessAllows(resource[RESOURCE_ACCESS], principal)) : resources;
+                    const activePrompts = protectsCatalogue
+                        ? prompts.filter((prompt) => accessAllows(prompt[PROMPT_ACCESS], principal)) : prompts;
+                    const capabilities = {
+                        ...(activeTools.length ? { tools: { listChanged: false } } : {}),
+                        ...(activeResources.length ? { resources: {
+                                subscribe: Boolean(resourceSubscriptions), listChanged: false,
+                            } } : {}),
+                        ...(activePrompts.length ? { prompts: { listChanged: false } } : {}),
+                        ...(activeResources.some((resource) => resource[HAS_COMPLETION]) ||
+                            activePrompts.some((prompt) => prompt[HAS_COMPLETION]) ? { completions: {} } : {}),
+                        ...(clientLogging ? { logging: {} } : {}),
+                        events: {},
+                    };
                     await reply.code(200).send({
                         jsonrpc: "2.0",
                         id: requestId(request.body.id),
-                        result: { events, _meta: { "io.modelcontextprotocol/serverInfo": serverInfo } },
+                        result: {
+                            supportedVersions: [PROTOCOL_VERSION],
+                            capabilities,
+                            resultType: "complete",
+                            ttlMs: protectsCatalogue ? 0 : cacheHints?.["server/discover"]?.ttlMs ?? 0,
+                            cacheScope: protectsCatalogue ? "private" : cacheHints?.["server/discover"]?.cacheScope ?? "private",
+                            ...(options.instructions ? { instructions: options.instructions } : {}),
+                            _meta: { "io.modelcontextprotocol/serverInfo": serverInfo },
+                        },
                     });
+                    return;
                 }
-                catch {
-                    await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
-                }
-                return;
-            }
-            if (request.body.method === "events/subscribe") {
+                if (!authInfo)
+                    throw new Error("Events reached execution without verified authorization");
+                let ownerKey;
                 try {
-                    const result = await eventRuntime.subscribe(ownerKey, request.body.params);
-                    await reply.code(200).send({ jsonrpc: "2.0", id: requestId(request.body.id), result });
+                    ownerKey = await requestEvents.ownerKey(authInfo);
                 }
-                catch (error) {
-                    if (error instanceof McpEventInputError) {
-                        await sendRpcError(reply, error.code === -32015 ? 200 : 400, error.code, error.message, requestId(request.body.id), { reason: error.reason });
-                        return;
-                    }
-                    await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
+                catch {
+                    await sendRpcError(reply, 500, -32603, "Event owner identity unavailable", requestId(request.body.id));
+                    return;
                 }
-                return;
-            }
-            if (request.body.method === "events/unsubscribe") {
-                try {
-                    await eventRuntime.unsubscribe(ownerKey, request.body.params);
-                    await reply.code(200).send({ jsonrpc: "2.0", id: requestId(request.body.id), result: {} });
+                if (request.body.method === "events/list") {
+                    try {
+                        const events = await requestEvents.list(ownerKey);
+                        await reply.code(200).send({
+                            jsonrpc: "2.0",
+                            id: requestId(request.body.id),
+                            result: { events, _meta: { "io.modelcontextprotocol/serverInfo": serverInfo } },
+                        });
+                    }
+                    catch {
+                        await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
+                    }
+                    return;
                 }
-                catch (error) {
-                    if (error instanceof McpEventInputError) {
-                        await sendRpcError(reply, 400, error.code, error.message, requestId(request.body.id), { reason: error.reason });
+                if (request.body.method === "events/subscribe") {
+                    try {
+                        const result = await requestEvents.subscribe(ownerKey, request.body.params);
+                        await reply.code(200).send({ jsonrpc: "2.0", id: requestId(request.body.id), result });
                     }
-                    else {
+                    catch (error) {
+                        if (error instanceof McpEventInputError) {
+                            await sendRpcError(reply, error.code === -32015 ? 200 : 400, error.code, error.message, requestId(request.body.id), { reason: error.reason });
+                            return;
+                        }
                         await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
                     }
+                    return;
                 }
-                return;
+                if (request.body.method === "events/unsubscribe") {
+                    try {
+                        await requestEvents.unsubscribe(ownerKey, request.body.params);
+                        await reply.code(200).send({ jsonrpc: "2.0", id: requestId(request.body.id), result: {} });
+                    }
+                    catch (error) {
+                        if (error instanceof McpEventInputError) {
+                            await sendRpcError(reply, 400, error.code, error.message, requestId(request.body.id), { reason: error.reason });
+                        }
+                        else {
+                            await sendRpcError(reply, 503, -32603, "Events are unavailable", requestId(request.body.id));
+                        }
+                    }
+                    return;
+                }
+            }
+            finally {
+                request.raw.off("aborted", abortEvents);
+                reply.raw.off("close", abortEvents);
             }
         }
         if (subscriptionTarget) {
@@ -1644,7 +1694,7 @@ export function createEmseepea(options) {
         try {
             await requestOperations.run({
                 deadlineMs: Date.now() + operationTimeoutMs,
-                signal: disconnected.signal,
+                signal: AbortSignal.any([disconnected.signal, stopping.signal]),
                 principal,
                 filterCatalogues: protectsCatalogue,
                 capability,
@@ -1670,17 +1720,32 @@ export function createEmseepea(options) {
         }
     });
     let drainingEvents = false;
-    const eventTimer = eventRuntime ? setInterval(() => {
+    const eventTimer = internalEventRuntime ? setInterval(() => {
         if (drainingEvents || stopping.signal.aborted)
             return;
         drainingEvents = true;
-        void eventRuntime.drain().catch(() => { }).finally(() => { drainingEvents = false; });
+        void internalEventRuntime.drain().catch(() => { }).finally(() => { drainingEvents = false; });
     }, 1000) : undefined;
     eventTimer?.unref();
+    let externalSettled = true;
+    if (externalEventRuntime)
+        registerAppShutdownOwner(app, async (invocation) => {
+            try {
+                return externalSettled = await externalEventRuntime.settle(invocation);
+            }
+            catch {
+                return externalSettled = false;
+            }
+        });
     app.addHook("onClose", async () => {
         if (eventTimer)
             clearInterval(eventTimer);
+        const ownersSettled = await startAppShutdown(app);
         await sdkHandler.close();
+        if (!externalSettled)
+            throw new Error("External Events shutdown has unfinished operations");
+        if (!ownersSettled)
+            throw new Error("APP_SHUTDOWN_INCOMPLETE");
     });
     runtimes.set(app, {
         deployment,
@@ -1912,8 +1977,12 @@ export async function serveEmseepea(app, options = {}) {
     return {
         url: new URL(`http://${urlHost}:${address.port}/mcp`),
         close: () => {
+            if (closing)
+                return closing;
+            prepareAppShutdown(app, shutdownTimeoutMs);
             runtime.stopping.abort();
-            return closing ??= closeApp(app, shutdownTimeoutMs, observabilityFlushTimeoutMs, runtime.finishObservability);
+            void startAppShutdown(app);
+            return closing = closeApp(app, remainingAppShutdown(app), observabilityFlushTimeoutMs, runtime.finishObservability);
         },
     };
 }
@@ -2524,14 +2593,27 @@ function promptArguments(schema) {
     })));
 }
 function sdkMetadataSchema(schema) {
+    // The declaration is captured once, but the SDK reads metadata again for
+    // subsequent registrations and requests. Keep output lazy: an input
+    // transform can be valid even when it has no representable output schema.
+    const documents = new Map();
+    const document = (io) => {
+        let captured = documents.get(io);
+        if (!captured) {
+            captured = deepFreeze(structuredClone(jsonMetadataSchema(schema, io)));
+            documents.set(io, captured);
+        }
+        return captured;
+    };
+    document("input");
     return {
         "~standard": {
             version: 1,
             vendor: "emseepea",
             validate: (value) => ({ value }),
             jsonSchema: {
-                input: () => jsonMetadataSchema(schema, "input"),
-                output: () => jsonMetadataSchema(schema, "output"),
+                input: () => document("input"),
+                output: () => document("output"),
             },
         },
     };
@@ -2702,7 +2784,12 @@ function requestId(value) {
 async function runWithDeadline(requestSignal, deadlineMs, work) {
     const remainingMs = deadlineMs - Date.now();
     const deadlineSignal = remainingMs > 0 ? AbortSignal.timeout(remainingMs) : AbortSignal.abort();
-    const signal = AbortSignal.any([requestSignal, deadlineSignal]);
+    const invocationSignal = requestOperations.getStore()?.signal;
+    const signal = AbortSignal.any([
+        requestSignal,
+        deadlineSignal,
+        ...(invocationSignal ? [invocationSignal] : []),
+    ]);
     return new Promise((resolve, reject) => {
         const onAbort = () => reject(new Error("Tool execution cancelled"));
         if (signal.aborted)
@@ -2968,13 +3055,19 @@ async function closeApp(app, timeoutMs, flushTimeoutMs, finishObservability) {
     let onClosed;
     const httpClosed = new Promise((resolve) => { onClosed = resolve; });
     app.server.once("close", onClosed);
-    const timeout = new Promise((resolve) => {
+    const timeout = new Promise((_resolve, reject) => {
         timer = setTimeout(() => {
-            app.server.close();
-            app.server.closeAllConnections();
-            resolve();
+            try {
+                app.server.close();
+                app.server.closeAllConnections();
+            }
+            catch {
+                // Cleanup failure must not hide the incomplete shutdown outcome.
+            }
+            finally {
+                reject(new Error("SERVER_SHUTDOWN_INCOMPLETE"));
+            }
         }, timeoutMs);
-        timer.unref();
     });
     try {
         await Promise.race([app.close(), timeout]);