@j0hanz/superfetch 1.2.5 → 2.0.1

package/dist/http/mcp-session.js

@@ -1,145 +1,23 @@
-import { randomUUID } from 'node:crypto';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
-import { config } from '../config/index.js';
-import { logError, logInfo, logWarn } from '../services/logger.js';
-import { getErrorMessage } from '../utils/error-utils.js';
-import { createMcpServer } from '../server.js';
-import { createSlotTracker, ensureSessionCapacity, reserveSessionSlot, respondBadRequest, respondServerBusy, } from './mcp-session-helpers.js';
-import {} from './sessions.js';
-function startSessionInitTimeout(transport, tracker, clearInitTimeout, timeoutMs) {
-    if (timeoutMs <= 0)
-        return null;
-    const timeout = setTimeout(() => {
-        clearInitTimeout();
-        if (tracker.isInitialized())
-            return;
-        tracker.releaseSlot();
-        void transport.close().catch((error) => {
-            logWarn('Failed to close stalled session', {
-                error: getErrorMessage(error),
-            });
-        });
-        logWarn('Session initialization timed out', { timeoutMs });
-    }, timeoutMs);
-    timeout.unref();
-    return timeout;
-}
-function handleSessionInitialized(id, transport, options, tracker, clearInitTimeout) {
-    clearInitTimeout();
-    tracker.markInitialized();
-    tracker.releaseSlot();
-    const now = Date.now();
-    options.sessionStore.set(id, {
-        transport,
-        createdAt: now,
-        lastSeen: now,
-    });
-    logInfo('Session initialized', { sessionId: id });
-}
-function handleSessionClosed(id, options) {
-    options.sessionStore.remove(id);
-    logInfo('Session closed', { sessionId: id });
-}
-function handleTransportClose(transport, options, tracker, clearInitTimeout) {
-    clearInitTimeout();
-    if (!tracker.isInitialized()) {
-        tracker.releaseSlot();
-    }
-    if (transport.sessionId) {
-        options.sessionStore.remove(transport.sessionId);
-    }
-}
-function createTransportForNewSession(options) {
-    const tracker = createSlotTracker();
-    let initTimeout = null;
-    const clearInitTimeout = () => {
-        if (!initTimeout)
-            return;
-        clearTimeout(initTimeout);
-        initTimeout = null;
-    };
-    const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => randomUUID(),
-        onsessioninitialized: (id) => {
-            handleSessionInitialized(id, transport, options, tracker, clearInitTimeout);
-        },
-        onsessionclosed: (id) => {
-            handleSessionClosed(id, options);
-        },
-    });
-    transport.onclose = () => {
-        handleTransportClose(transport, options, tracker, clearInitTimeout);
-    };
-    initTimeout = startSessionInitTimeout(transport, tracker, clearInitTimeout, config.server.sessionInitTimeoutMs);
-    return { transport, releaseSlot: tracker.releaseSlot, clearInitTimeout };
-}
-function findExistingTransport(sessionId, options) {
-    if (!sessionId) {
-        return null;
-    }
-    const existingSession = options.sessionStore.get(sessionId);
-    if (!existingSession) {
+import { sendJsonRpcError } from './jsonrpc-http.js';
+import { evictExpiredSessions } from './mcp-session-eviction.js';
+import { createAndConnectTransport } from './mcp-session-init.js';
+import { respondBadRequest } from './mcp-session-slots.js';
+export async function resolveTransportForPost({ res, body, sessionId, options, }) {
+    if (sessionId) {
+        const existingSession = options.sessionStore.get(sessionId);
+        if (existingSession) {
+            options.sessionStore.touch(sessionId);
+            return existingSession.transport;
+        }
+        // Client supplied a session id but it doesn't exist; Streamable HTTP: invalid session IDs => 404.
+        sendJsonRpcError(res, -32600, 'Session not found', 404);
         return null;
     }
-    options.sessionStore.touch(sessionId);
-    return existingSession.transport;
-}
-function shouldInitializeSession(sessionId, body) {
-    return !sessionId && isInitializeRequest(body);
-}
-async function createAndConnectTransport(options, res) {
-    if (!ensureSessionCapacity(options.sessionStore, options.maxSessions, res, evictOldestSession)) {
-        return null;
-    }
-    if (!reserveSessionSlot(options.sessionStore, options.maxSessions)) {
-        respondServerBusy(res);
-        return null;
-    }
-    const { transport, releaseSlot, clearInitTimeout } = createTransportForNewSession(options);
-    const mcpServer = createMcpServer();
-    try {
-        await mcpServer.connect(transport);
-    }
-    catch (error) {
-        clearInitTimeout();
-        releaseSlot();
-        logError('Failed to initialize MCP session', error instanceof Error ? error : undefined);
-        throw error;
-    }
-    return transport;
-}
-export async function resolveTransportForPost(_req, res, body, sessionId, options) {
-    const existingTransport = findExistingTransport(sessionId, options);
-    if (existingTransport) {
-        return existingTransport;
-    }
-    if (!shouldInitializeSession(sessionId, body)) {
+    if (!isInitializeRequest(body)) {
         respondBadRequest(res);
         return null;
     }
     evictExpiredSessions(options.sessionStore);
-    return createAndConnectTransport(options, res);
-}
-export function evictExpiredSessions(store) {
-    const evicted = store.evictExpired();
-    for (const session of evicted) {
-        void session.transport.close().catch((error) => {
-            logWarn('Failed to close expired session', {
-                error: getErrorMessage(error),
-            });
-        });
-    }
-    return evicted.length;
-}
-function evictOldestSession(store) {
-    const session = store.evictOldest();
-    if (!session)
-        return false;
-    void session.transport.close().catch((error) => {
-        logWarn('Failed to close evicted session', {
-            error: getErrorMessage(error),
-        });
-    });
-    return true;
+    return createAndConnectTransport({ options, res });
 }

package/dist/http/mcp-sessions.d.ts

@@ -0,0 +1,43 @@
+import type { Request, Response } from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { SessionEntry } from '../config/types/runtime.js';
+export interface SessionStore {
+    get: (sessionId: string) => SessionEntry | undefined;
+    touch: (sessionId: string) => void;
+    set: (sessionId: string, entry: SessionEntry) => void;
+    remove: (sessionId: string) => SessionEntry | undefined;
+    size: () => number;
+    clear: () => SessionEntry[];
+    evictExpired: () => SessionEntry[];
+    evictOldest: () => SessionEntry | undefined;
+}
+export interface McpSessionOptions {
+    readonly sessionStore: SessionStore;
+    readonly maxSessions: number;
+}
+export declare function sendJsonRpcError(res: Response, code: number, message: string, status?: number): void;
+export declare function getSessionId(req: Request): string | undefined;
+export declare function createSessionStore(sessionTtlMs: number): SessionStore;
+export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
+interface SlotTracker {
+    readonly releaseSlot: () => void;
+    readonly markInitialized: () => void;
+    readonly isInitialized: () => boolean;
+}
+export declare function createSlotTracker(): SlotTracker;
+export declare function ensureSessionCapacity({ store, maxSessions, res, evictOldest, }: {
+    store: SessionStore;
+    maxSessions: number;
+    res: Response;
+    evictOldest: (store: SessionStore) => boolean;
+}): boolean;
+export declare function resolveTransportForPost({ res, body, sessionId, options, }: {
+    res: Response;
+    body: {
+        method: string;
+    };
+    sessionId: string | undefined;
+    options: McpSessionOptions;
+}): Promise<StreamableHTTPServerTransport | null>;
+export declare function startSessionCleanupLoop(store: SessionStore, sessionTtlMs: number): AbortController;
+export {};

package/dist/http/mcp-sessions.js

@@ -0,0 +1,392 @@
+import { randomUUID } from 'node:crypto';
+import { setInterval as setIntervalPromise } from 'node:timers/promises';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { config } from '../config/index.js';
+import { logError, logInfo, logWarn } from '../services/logger.js';
+import { getErrorMessage } from '../utils/error-details.js';
+import { createMcpServer } from '../server.js';
+export function sendJsonRpcError(res, code, message, status = 400) {
+    res.status(status).json({
+        jsonrpc: '2.0',
+        error: {
+            code,
+            message,
+        },
+        id: null,
+    });
+}
+export function getSessionId(req) {
+    const header = req.headers['mcp-session-id'];
+    return Array.isArray(header) ? header[0] : header;
+}
+export function createSessionStore(sessionTtlMs) {
+    const sessions = new Map();
+    return {
+        get: (sessionId) => sessions.get(sessionId),
+        touch: (sessionId) => {
+            touchSession(sessions, sessionId);
+        },
+        set: (sessionId, entry) => {
+            sessions.set(sessionId, entry);
+        },
+        remove: (sessionId) => removeSession(sessions, sessionId),
+        size: () => sessions.size,
+        clear: () => clearSessions(sessions),
+        evictExpired: () => evictExpiredSessions(sessions, sessionTtlMs),
+        evictOldest: () => evictOldestSession(sessions),
+    };
+}
+function touchSession(sessions, sessionId) {
+    const session = sessions.get(sessionId);
+    if (session) {
+        session.lastSeen = Date.now();
+    }
+}
+function removeSession(sessions, sessionId) {
+    const session = sessions.get(sessionId);
+    sessions.delete(sessionId);
+    return session;
+}
+function clearSessions(sessions) {
+    const entries = Array.from(sessions.values());
+    sessions.clear();
+    return entries;
+}
+function evictExpiredSessions(sessions, sessionTtlMs) {
+    const now = Date.now();
+    const evicted = [];
+    for (const [id, session] of sessions.entries()) {
+        if (now - session.lastSeen > sessionTtlMs) {
+            sessions.delete(id);
+            evicted.push(session);
+        }
+    }
+    return evicted;
+}
+function evictOldestSession(sessions) {
+    let oldestId;
+    let oldestSeen = Number.POSITIVE_INFINITY;
+    for (const [id, session] of sessions.entries()) {
+        if (session.lastSeen < oldestSeen) {
+            oldestSeen = session.lastSeen;
+            oldestId = id;
+        }
+    }
+    if (!oldestId)
+        return undefined;
+    const session = sessions.get(oldestId);
+    sessions.delete(oldestId);
+    return session;
+}
+let inFlightSessions = 0;
+export function reserveSessionSlot(store, maxSessions) {
+    if (store.size() + inFlightSessions >= maxSessions) {
+        return false;
+    }
+    inFlightSessions += 1;
+    return true;
+}
+function releaseSessionSlot() {
+    if (inFlightSessions > 0) {
+        inFlightSessions -= 1;
+    }
+}
+export function createSlotTracker() {
+    let slotReleased = false;
+    let initialized = false;
+    return {
+        releaseSlot: () => {
+            if (slotReleased)
+                return;
+            slotReleased = true;
+            releaseSessionSlot();
+        },
+        markInitialized: () => {
+            initialized = true;
+        },
+        isInitialized: () => initialized,
+    };
+}
+function isServerAtCapacity(store, maxSessions) {
+    return store.size() + inFlightSessions >= maxSessions;
+}
+function tryEvictSlot(store, maxSessions, evictOldest) {
+    const currentSize = store.size();
+    const canFreeSlot = currentSize >= maxSessions &&
+        currentSize - 1 + inFlightSessions < maxSessions;
+    return canFreeSlot && evictOldest(store);
+}
+export function ensureSessionCapacity({ store, maxSessions, res, evictOldest, }) {
+    if (!isServerAtCapacity(store, maxSessions)) {
+        return true;
+    }
+    if (tryEvictSlot(store, maxSessions, evictOldest)) {
+        return !isServerAtCapacity(store, maxSessions);
+    }
+    respondServerBusy(res);
+    return false;
+}
+function respondServerBusy(res) {
+    sendJsonRpcError(res, -32000, 'Server busy: maximum sessions reached', 503);
+}
+function respondBadRequest(res) {
+    sendJsonRpcError(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400);
+}
+function createTimeoutController() {
+    let initTimeout = null;
+    return {
+        clear: () => {
+            if (!initTimeout)
+                return;
+            clearTimeout(initTimeout);
+            initTimeout = null;
+        },
+        set: (timeout) => {
+            initTimeout = timeout;
+        },
+    };
+}
+function createTransportAdapter(transport) {
+    const adapter = buildTransportAdapter(transport);
+    attachTransportAccessors(adapter, transport);
+    return adapter;
+}
+function buildTransportAdapter(transport) {
+    return {
+        start: () => transport.start(),
+        send: (message, options) => transport.send(message, options),
+        close: () => transport.close(),
+    };
+}
+function createAccessorDescriptor(getter, setter) {
+    return {
+        get: getter,
+        ...(setter ? { set: setter } : {}),
+        enumerable: true,
+        configurable: true,
+    };
+}
+function createOnCloseDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onclose, (handler) => {
+        transport.onclose = handler;
+    });
+}
+function createOnErrorDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onerror, (handler) => {
+        transport.onerror = handler;
+    });
+}
+function createOnMessageDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onmessage, (handler) => {
+        transport.onmessage = handler;
+    });
+}
+function attachTransportAccessors(adapter, transport) {
+    Object.defineProperties(adapter, {
+        onclose: createOnCloseDescriptor(transport),
+        onerror: createOnErrorDescriptor(transport),
+        onmessage: createOnMessageDescriptor(transport),
+        sessionId: createAccessorDescriptor(() => transport.sessionId),
+    });
+}
+function startSessionInitTimeout({ transport, tracker, clearInitTimeout, timeoutMs, }) {
+    if (timeoutMs <= 0)
+        return null;
+    const timeout = setTimeout(() => {
+        clearInitTimeout();
+        if (tracker.isInitialized())
+            return;
+        tracker.releaseSlot();
+        void transport.close().catch((error) => {
+            logWarn('Failed to close stalled session', {
+                error: getErrorMessage(error),
+            });
+        });
+        logWarn('Session initialization timed out', { timeoutMs });
+    }, timeoutMs);
+    timeout.unref();
+    return timeout;
+}
+function createSessionTransport({ tracker, timeoutController, }) {
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    transport.onclose = () => {
+        timeoutController.clear();
+        if (!tracker.isInitialized()) {
+            tracker.releaseSlot();
+        }
+    };
+    timeoutController.set(startSessionInitTimeout({
+        transport,
+        tracker,
+        clearInitTimeout: timeoutController.clear,
+        timeoutMs: config.server.sessionInitTimeoutMs,
+    }));
+    return transport;
+}
+async function connectTransportOrThrow({ transport, clearInitTimeout, releaseSlot, }) {
+    const mcpServer = createMcpServer();
+    const transportAdapter = createTransportAdapter(transport);
+    try {
+        await mcpServer.connect(transportAdapter);
+    }
+    catch (error) {
+        clearInitTimeout();
+        releaseSlot();
+        void transport.close().catch((closeError) => {
+            logWarn('Failed to close transport after connect error', {
+                error: getErrorMessage(closeError),
+            });
+        });
+        logError('Failed to initialize MCP session', error instanceof Error ? error : undefined);
+        throw error;
+    }
+}
+function evictExpiredSessionsWithClose(store) {
+    const evicted = store.evictExpired();
+    for (const session of evicted) {
+        void session.transport.close().catch((error) => {
+            logWarn('Failed to close expired session', {
+                error: getErrorMessage(error),
+            });
+        });
+    }
+    return evicted.length;
+}
+function evictOldestSessionWithClose(store) {
+    const session = store.evictOldest();
+    if (!session)
+        return false;
+    void session.transport.close().catch((error) => {
+        logWarn('Failed to close evicted session', {
+            error: getErrorMessage(error),
+        });
+    });
+    return true;
+}
+function reserveSessionIfPossible({ options, res, }) {
+    if (!ensureSessionCapacity({
+        store: options.sessionStore,
+        maxSessions: options.maxSessions,
+        res,
+        evictOldest: evictOldestSessionWithClose,
+    })) {
+        return false;
+    }
+    if (!reserveSessionSlot(options.sessionStore, options.maxSessions)) {
+        respondServerBusy(res);
+        return false;
+    }
+    return true;
+}
+function resolveSessionId({ transport, res, tracker, clearInitTimeout, }) {
+    const { sessionId } = transport;
+    if (typeof sessionId !== 'string') {
+        clearInitTimeout();
+        tracker.releaseSlot();
+        respondBadRequest(res);
+        return null;
+    }
+    return sessionId;
+}
+function finalizeSession({ store, transport, sessionId, tracker, clearInitTimeout, }) {
+    clearInitTimeout();
+    tracker.markInitialized();
+    tracker.releaseSlot();
+    const now = Date.now();
+    store.set(sessionId, {
+        transport,
+        createdAt: now,
+        lastSeen: now,
+    });
+    transport.onclose = () => {
+        store.remove(sessionId);
+        logInfo('Session closed');
+    };
+    logInfo('Session initialized');
+}
+async function createAndConnectTransport({ options, res, }) {
+    if (!reserveSessionIfPossible({ options, res }))
+        return null;
+    const tracker = createSlotTracker();
+    const timeoutController = createTimeoutController();
+    const transport = createSessionTransport({ tracker, timeoutController });
+    await connectTransportOrThrow({
+        transport,
+        clearInitTimeout: timeoutController.clear,
+        releaseSlot: tracker.releaseSlot,
+    });
+    const sessionId = resolveSessionId({
+        transport,
+        res,
+        tracker,
+        clearInitTimeout: timeoutController.clear,
+    });
+    if (!sessionId)
+        return null;
+    finalizeSession({
+        store: options.sessionStore,
+        transport,
+        sessionId,
+        tracker,
+        clearInitTimeout: timeoutController.clear,
+    });
+    return transport;
+}
+export async function resolveTransportForPost({ res, body, sessionId, options, }) {
+    if (sessionId) {
+        const existingSession = options.sessionStore.get(sessionId);
+        if (existingSession) {
+            options.sessionStore.touch(sessionId);
+            return existingSession.transport;
+        }
+        // Client supplied a session id but it doesn't exist; Streamable HTTP: invalid session IDs => 404.
+        sendJsonRpcError(res, -32600, 'Session not found', 404);
+        return null;
+    }
+    if (!isInitializeRequest(body)) {
+        respondBadRequest(res);
+        return null;
+    }
+    evictExpiredSessionsWithClose(options.sessionStore);
+    return createAndConnectTransport({ options, res });
+}
+export function startSessionCleanupLoop(store, sessionTtlMs) {
+    const controller = new AbortController();
+    void runSessionCleanupLoop(store, sessionTtlMs, controller.signal).catch(handleSessionCleanupError);
+    return controller;
+}
+async function runSessionCleanupLoop(store, sessionTtlMs, signal) {
+    const intervalMs = getCleanupIntervalMs(sessionTtlMs);
+    for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
+        signal,
+        ref: false,
+    })) {
+        handleSessionEvictions(store, getNow());
+    }
+}
+function getCleanupIntervalMs(sessionTtlMs) {
+    return Math.min(Math.max(Math.floor(sessionTtlMs / 2), 10000), 60000);
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function handleSessionEvictions(store, now) {
+    const evicted = evictExpiredSessionsWithClose(store);
+    if (evicted > 0) {
+        logInfo('Expired sessions evicted', {
+            evicted,
+            timestamp: new Date(now).toISOString(),
+        });
+    }
+}
+function handleSessionCleanupError(error) {
+    if (isAbortError(error)) {
+        return;
+    }
+    logWarn('Session cleanup loop failed', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+    });
+}

package/dist/http/mcp-validation.d.ts

@@ -1,2 +1,3 @@
 import type { McpRequestBody } from '../config/types/runtime.js';
+export declare function isJsonRpcBatchRequest(body: unknown): boolean;
 export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;

package/dist/http/mcp-validation.js

@@ -1,13 +1,14 @@
-function isRecord(value) {
-    return value !== null && typeof value === 'object';
+import { z } from 'zod';
+const paramsSchema = z.looseObject({});
+const mcpRequestSchema = z.looseObject({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: z.union([z.string(), z.number()]).optional(),
+    params: paramsSchema.optional(),
+});
+export function isJsonRpcBatchRequest(body) {
+    return Array.isArray(body);
 }
 export function isMcpRequestBody(body) {
-    if (!isRecord(body) || Array.isArray(body))
-        return false;
-    const { method, id, jsonrpc, params } = body;
-    const methodValid = method === undefined || typeof method === 'string';
-    const idValid = id === undefined || typeof id === 'string' || typeof id === 'number';
-    const jsonrpcValid = jsonrpc === undefined || jsonrpc === '2.0';
-    const paramsValid = params === undefined || typeof params === 'object';
-    return methodValid && idValid && jsonrpcValid && paramsValid;
+    return mcpRequestSchema.safeParse(body).success;
 }

package/dist/http/protocol-policy.d.ts

@@ -0,0 +1,2 @@
+import type { Request, Response } from 'express';
+export declare function ensureMcpProtocolVersionHeader(req: Request, res: Response): boolean;

package/dist/http/protocol-policy.js

@@ -0,0 +1,31 @@
+import { sendJsonRpcError } from './jsonrpc-http.js';
+const MCP_PROTOCOL_VERSION_HEADER = 'mcp-protocol-version';
+const MCP_PROTOCOL_VERSIONS = {
+    defaultVersion: '2025-03-26',
+    supported: new Set(['2025-03-26', '2025-11-25']),
+};
+function getHeaderValue(req, headerNameLower) {
+    const value = req.headers[headerNameLower];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return null;
+}
+function setHeaderValue(req, headerNameLower, value) {
+    // Express exposes req.headers as a plain object, but the type is readonly-ish.
+    req.headers[headerNameLower] = value;
+}
+export function ensureMcpProtocolVersionHeader(req, res) {
+    const raw = getHeaderValue(req, MCP_PROTOCOL_VERSION_HEADER);
+    const version = raw?.trim();
+    if (!version) {
+        setHeaderValue(req, MCP_PROTOCOL_VERSION_HEADER, MCP_PROTOCOL_VERSIONS.defaultVersion);
+        return true;
+    }
+    if (!MCP_PROTOCOL_VERSIONS.supported.has(version)) {
+        sendJsonRpcError(res, -32600, `Unsupported MCP-Protocol-Version: ${version}`, 400);
+        return false;
+    }
+    return true;
+}

package/dist/http/rate-limit.js

@@ -13,7 +13,11 @@ export function createRateLimitMiddleware(options) {
     const stop = () => {
         cleanupController.abort();
     };
-    const middleware = (req, res, next) => {
+    const middleware = createRateLimitHandler(store, options);
+    return { middleware, stop, store };
+}
+function createRateLimitHandler(store, options) {
+    return (req, res, next) => {
         if (shouldSkipRateLimit(req, options)) {
             next();
             return;
@@ -30,11 +34,10 @@ export function createRateLimitMiddleware(options) {
         }
         next();
     };
-    return { middleware, stop, store };
 }
 async function startCleanupLoop(store, options, signal) {
-    for await (const _ of setIntervalPromise(options.cleanupIntervalMs, undefined, { signal, ref: false })) {
-        evictStaleEntries(store, options, Date.now());
+    for await (const getNow of setIntervalPromise(options.cleanupIntervalMs, Date.now, { signal, ref: false })) {
+        evictStaleEntries(store, options, getNow());
     }
 }
 function evictStaleEntries(store, options, now) {

package/dist/http/server-config.d.ts

@@ -0,0 +1 @@
+export declare function assertHttpConfiguration(): void;