@j0hanz/superfetch 2.0.0 → 2.1.0

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, id = null) {
+    res.status(status).json({
+        jsonrpc: '2.0',
+        error: {
+            code,
+            message,
+        },
+        id,
+    });
+}
+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, null);
+}
+function respondBadRequest(res, id) {
+    sendJsonRpcError(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400, id);
+}
+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, null);
+        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, body.id ?? null);
+        return null;
+    }
+    if (!isInitializeRequest(body)) {
+        respondBadRequest(res, body.id ?? null);
+        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/rate-limit.js

@@ -36,8 +36,8 @@ function createRateLimitHandler(store, options) {
     };
 }
 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-middleware.d.ts

@@ -1,2 +1,7 @@
 import type { Express, RequestHandler } from 'express';
-export declare function attachBaseMiddleware(app: Express, jsonParser: RequestHandler, rateLimitMiddleware: RequestHandler, corsMiddleware: RequestHandler): void;
+export declare function attachBaseMiddleware(options: {
+    app: Express;
+    jsonParser: RequestHandler;
+    rateLimitMiddleware: RequestHandler;
+    corsMiddleware: RequestHandler;
+}): void;

package/dist/http/server-middleware.js

@@ -1,123 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { config } from '../config/index.js';
 import { runWithRequestContext } from '../services/context.js';
+import { createHostValidationMiddleware, createOriginValidationMiddleware, } from './host-allowlist.js';
 import { getSessionId } from './sessions.js';
-const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
-function getNonEmptyStringHeader(value) {
-    if (typeof value !== 'string')
-        return null;
-    const trimmed = value.trim();
-    return trimmed === '' ? null : trimmed;
-}
-function respondHostNotAllowed(res) {
-    res.status(403).json({
-        error: 'Host not allowed',
-        code: 'HOST_NOT_ALLOWED',
-    });
-}
-function respondOriginNotAllowed(res) {
-    res.status(403).json({
-        error: 'Origin not allowed',
-        code: 'ORIGIN_NOT_ALLOWED',
-    });
-}
-function tryParseOriginHostname(originHeader) {
-    try {
-        return new URL(originHeader).hostname.toLowerCase();
-    }
-    catch {
-        return null;
-    }
-}
-function takeFirstHostValue(value) {
-    const first = value.split(',')[0];
-    if (!first)
-        return null;
-    const trimmed = first.trim();
-    return trimmed ? trimmed : null;
-}
-function stripIpv6Brackets(value) {
-    if (!value.startsWith('['))
-        return null;
-    const end = value.indexOf(']');
-    if (end === -1)
-        return null;
-    return value.slice(1, end);
-}
-function stripPortIfPresent(value) {
-    const colonIndex = value.indexOf(':');
-    if (colonIndex === -1)
-        return value;
-    return value.slice(0, colonIndex);
-}
-function normalizeHost(value) {
-    const trimmed = value.trim().toLowerCase();
-    if (!trimmed)
-        return null;
-    const first = takeFirstHostValue(trimmed);
-    if (!first)
-        return null;
-    const ipv6 = stripIpv6Brackets(first);
-    if (ipv6)
-        return ipv6;
-    return stripPortIfPresent(first);
-}
-function isWildcardHost(host) {
-    return host === '0.0.0.0' || host === '::';
-}
-function addLoopbackHosts(allowedHosts) {
-    for (const host of LOOPBACK_HOSTS) {
-        allowedHosts.add(host);
-    }
-}
-function addConfiguredHost(allowedHosts) {
-    const configuredHost = normalizeHost(config.server.host);
-    if (!configuredHost)
-        return;
-    if (isWildcardHost(configuredHost))
-        return;
-    allowedHosts.add(configuredHost);
-}
-function addExplicitAllowedHosts(allowedHosts) {
-    for (const host of config.security.allowedHosts) {
-        allowedHosts.add(host);
-    }
-}
-function buildAllowedHosts() {
-    const allowedHosts = new Set();
-    addLoopbackHosts(allowedHosts);
-    addConfiguredHost(allowedHosts);
-    addExplicitAllowedHosts(allowedHosts);
-    return allowedHosts;
-}
-function createHostValidationMiddleware() {
-    const allowedHosts = buildAllowedHosts();
-    return (req, res, next) => {
-        const hostHeader = typeof req.headers.host === 'string' ? req.headers.host : '';
-        const normalized = normalizeHost(hostHeader);
-        if (!normalized || !allowedHosts.has(normalized)) {
-            respondHostNotAllowed(res);
-            return;
-        }
-        next();
-    };
-}
-function createOriginValidationMiddleware() {
-    const allowedHosts = buildAllowedHosts();
-    return (req, res, next) => {
-        const originHeader = getNonEmptyStringHeader(req.headers.origin);
-        if (!originHeader) {
-            next();
-            return;
-        }
-        const originHostname = tryParseOriginHostname(originHeader);
-        if (!originHostname || !allowedHosts.has(originHostname)) {
-            respondOriginNotAllowed(res);
-            return;
-        }
-        next();
-    };
-}
 function createJsonParseErrorHandler() {
     return (err, _req, res, next) => {
         if (err instanceof SyntaxError && 'body' in err) {
@@ -154,7 +39,8 @@ function registerHealthRoute(app) {
         });
     });
 }
-export function attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, corsMiddleware) {
+export function attachBaseMiddleware(options) {
+    const { app, jsonParser, rateLimitMiddleware, corsMiddleware } = options;
     app.use(createHostValidationMiddleware());
     app.use(createOriginValidationMiddleware());
     app.use(jsonParser);

package/dist/http/server-shutdown.js

@@ -1,6 +1,6 @@
 import { destroyAgents } from '../services/fetcher/agents.js';
 import { logError, logInfo, logWarn } from '../services/logger.js';
-import { getErrorMessage } from '../utils/error-utils.js';
+import { getErrorMessage } from '../utils/error-details.js';
 export function createShutdownHandler(server, sessionStore, sessionCleanupController, stopRateLimitCleanup) {
     return (signal) => shutdownServer(signal, server, sessionStore, sessionCleanupController, stopRateLimitCleanup);
 }

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

@@ -0,0 +1,9 @@
+export interface HttpServerTuningTarget {
+    headersTimeout?: number;
+    requestTimeout?: number;
+    keepAliveTimeout?: number;
+    closeIdleConnections?: () => void;
+    closeAllConnections?: () => void;
+}
+export declare function applyHttpServerTuning(server: HttpServerTuningTarget): void;
+export declare function drainConnectionsOnShutdown(server: HttpServerTuningTarget): void;

package/dist/http/server-tuning.js

@@ -0,0 +1,45 @@
+import { config } from '../config/index.js';
+import { logDebug } from '../services/logger.js';
+export function applyHttpServerTuning(server) {
+    const { headersTimeoutMs, requestTimeoutMs, keepAliveTimeoutMs } = config.server.http;
+    if (headersTimeoutMs !== undefined) {
+        server.headersTimeout = headersTimeoutMs;
+    }
+    if (requestTimeoutMs !== undefined) {
+        server.requestTimeout = requestTimeoutMs;
+    }
+    if (keepAliveTimeoutMs !== undefined) {
+        server.keepAliveTimeout = keepAliveTimeoutMs;
+    }
+    if (headersTimeoutMs !== undefined ||
+        requestTimeoutMs !== undefined ||
+        keepAliveTimeoutMs !== undefined) {
+        logDebug('Applied HTTP server tuning', {
+            headersTimeoutMs,
+            requestTimeoutMs,
+            keepAliveTimeoutMs,
+        });
+    }
+}
+export function drainConnectionsOnShutdown(server) {
+    const { shutdownCloseAllConnections, shutdownCloseIdleConnections } = config.server.http;
+    if (shutdownCloseAllConnections) {
+        if (typeof server.closeAllConnections === 'function') {
+            server.closeAllConnections();
+            logDebug('Closed all HTTP connections during shutdown');
+        }
+        else {
+            logDebug('HTTP server does not support closeAllConnections()');
+        }
+        return;
+    }
+    if (shutdownCloseIdleConnections) {
+        if (typeof server.closeIdleConnections === 'function') {
+            server.closeIdleConnections();
+            logDebug('Closed idle HTTP connections during shutdown');
+        }
+        else {
+            logDebug('HTTP server does not support closeIdleConnections()');
+        }
+    }
+}