@j0hanz/superfetch 2.0.1 → 2.1.1

package/dist/http/base-middleware.d.ts

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

package/dist/http/base-middleware.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { config } from '../config/index.js';
+import { runWithRequestContext } from '../services/context.js';
+import { logDebug } from '../services/logger.js';
+import { normalizeHost } from '../utils/host-normalizer.js';
+import { getSessionId } from './mcp-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 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) {
+        const normalized = normalizeHost(host);
+        if (!normalized) {
+            logDebug('Ignoring invalid allowed host entry', { host });
+            continue;
+        }
+        allowedHosts.add(normalized);
+    }
+}
+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) {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32700,
+                    message: 'Parse error: Invalid JSON',
+                },
+                id: null,
+            });
+            return;
+        }
+        next();
+    };
+}
+function createContextMiddleware() {
+    return (req, _res, next) => {
+        const requestId = randomUUID();
+        const sessionId = getSessionId(req);
+        const context = sessionId === undefined
+            ? { requestId, operationId: requestId }
+            : { requestId, operationId: requestId, sessionId };
+        runWithRequestContext(context, () => {
+            next();
+        });
+    };
+}
+function registerHealthRoute(app) {
+    app.get('/health', (_req, res) => {
+        res.json({
+            status: 'healthy',
+            name: config.server.name,
+            version: config.server.version,
+            uptime: process.uptime(),
+        });
+    });
+}
+export function attachBaseMiddleware(options) {
+    const { app, jsonParser, rateLimitMiddleware, corsMiddleware } = options;
+    app.use(createHostValidationMiddleware());
+    app.use(createOriginValidationMiddleware());
+    app.use(jsonParser);
+    app.use(createContextMiddleware());
+    app.use(createJsonParseErrorHandler());
+    app.use(corsMiddleware);
+    app.use('/mcp', rateLimitMiddleware);
+    registerHealthRoute(app);
+}

package/dist/http/cors.d.ts

@@ -1,7 +1,2 @@
 import type { NextFunction, Request, Response } from 'express';
-/**
- * Creates a minimal CORS middleware.
- * MCP clients are not browser-based, so CORS is not needed.
- * This just handles OPTIONS preflight requests.
- */
 export declare function createCorsMiddleware(): (req: Request, res: Response, next: NextFunction) => void;

package/dist/http/cors.js

@@ -1,11 +1,5 @@
-/**
- * Creates a minimal CORS middleware.
- * MCP clients are not browser-based, so CORS is not needed.
- * This just handles OPTIONS preflight requests.
- */
 export function createCorsMiddleware() {
     return (req, res, next) => {
-        // Handle OPTIONS preflight
         if (req.method === 'OPTIONS') {
             res.sendStatus(200);
             return;

package/dist/http/download-routes.js

@@ -3,7 +3,6 @@ import * as cache from '../services/cache.js';
 import { logDebug } from '../services/logger.js';
 import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
 import { generateSafeFilename } from '../utils/filename-generator.js';
-import { wrapAsync } from './async-handler.js';
 const HASH_PATTERN = /^[a-f0-9.]+$/i;
 function validateNamespace(namespace) {
     return namespace === 'markdown';
@@ -11,8 +10,13 @@ function validateNamespace(namespace) {
 function validateHash(hash) {
     return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
 }
+function isSingleParam(value) {
+    return typeof value === 'string';
+}
 function parseDownloadParams(req) {
     const { namespace, hash } = req.params;
+    if (!isSingleParam(namespace) || !isSingleParam(hash))
+        return null;
     if (!namespace || !hash)
         return null;
     if (!validateNamespace(namespace))
@@ -96,5 +100,5 @@ function handleDownload(req, res) {
     sendDownloadPayload(res, payload);
 }
 export function registerDownloadRoutes(app) {
-    app.get('/mcp/downloads/:namespace/:hash', wrapAsync(handleDownload));
+    app.get('/mcp/downloads/:namespace/:hash', handleDownload);
 }

package/dist/http/error-handler.d.ts

@@ -0,0 +1,2 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void;

package/dist/http/error-handler.js

@@ -0,0 +1,55 @@
+import { FetchError } from '../errors/app-error.js';
+import { logError } from '../services/logger.js';
+function getStatusCode(fetchError) {
+    return fetchError ? fetchError.statusCode : 500;
+}
+function getErrorCode(fetchError) {
+    return fetchError ? fetchError.code : 'INTERNAL_ERROR';
+}
+function getFetchErrorMessage(fetchError) {
+    return fetchError ? fetchError.message : 'Internal Server Error';
+}
+function getErrorDetails(fetchError) {
+    if (fetchError && Object.keys(fetchError.details).length > 0) {
+        return fetchError.details;
+    }
+    return undefined;
+}
+function resolveRetryAfter(fetchError) {
+    if (fetchError?.statusCode !== 429)
+        return undefined;
+    const { retryAfter } = fetchError.details;
+    return isRetryAfterValue(retryAfter) ? String(retryAfter) : undefined;
+}
+function isRetryAfterValue(value) {
+    return typeof value === 'number' || typeof value === 'string';
+}
+function setRetryAfterHeader(res, fetchError) {
+    const retryAfter = resolveRetryAfter(fetchError);
+    if (retryAfter === undefined)
+        return;
+    res.set('Retry-After', retryAfter);
+}
+function buildErrorResponse(fetchError) {
+    const details = getErrorDetails(fetchError);
+    const response = {
+        error: {
+            message: getFetchErrorMessage(fetchError),
+            code: getErrorCode(fetchError),
+            statusCode: getStatusCode(fetchError),
+            ...(details && { details }),
+        },
+    };
+    return response;
+}
+export function errorHandler(err, req, res, next) {
+    if (res.headersSent) {
+        next(err);
+        return;
+    }
+    const fetchError = err instanceof FetchError ? err : null;
+    const statusCode = getStatusCode(fetchError);
+    logError(`HTTP ${statusCode}: ${err.message} - ${req.method} ${req.path}`, err);
+    setRetryAfterHeader(res, fetchError);
+    res.status(statusCode).json(buildErrorResponse(fetchError));
+}

package/dist/http/mcp-routes.js

@@ -82,8 +82,8 @@ function resolveSessionTransport(sessionId, options, res) {
 }
 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']),
+    defaultVersion: '2025-11-25',
+    supported: new Set(['2025-11-25']),
 };
 function getHeaderValue(req, headerNameLower) {
     const value = req.headers[headerNameLower];

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

@@ -1,6 +1,6 @@
 import type { Request, Response } from 'express';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import type { SessionEntry } from '../config/types/runtime.js';
+import type { McpRequestBody, SessionEntry } from '../config/types/runtime.js';
 export interface SessionStore {
     get: (sessionId: string) => SessionEntry | undefined;
     touch: (sessionId: string) => void;
@@ -15,7 +15,7 @@ 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 sendJsonRpcError(res: Response, code: number, message: string, status?: number, id?: string | number | null): 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;
@@ -33,9 +33,7 @@ export declare function ensureSessionCapacity({ store, maxSessions, res, evictOl
 }): boolean;
 export declare function resolveTransportForPost({ res, body, sessionId, options, }: {
     res: Response;
-    body: {
-        method: string;
-    };
+    body: Pick<McpRequestBody, 'method' | 'id'>;
     sessionId: string | undefined;
     options: McpSessionOptions;
 }): Promise<StreamableHTTPServerTransport | null>;

package/dist/http/mcp-sessions.js

@@ -6,14 +6,14 @@ 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) {
+export function sendJsonRpcError(res, code, message, status = 400, id = null) {
     res.status(status).json({
         jsonrpc: '2.0',
         error: {
             code,
             message,
         },
-        id: null,
+        id,
     });
 }
 export function getSessionId(req) {
@@ -128,10 +128,10 @@ export function ensureSessionCapacity({ store, maxSessions, res, evictOldest, })
     return false;
 }
 function respondServerBusy(res) {
-    sendJsonRpcError(res, -32000, 'Server busy: maximum sessions reached', 503);
+    sendJsonRpcError(res, -32000, 'Server busy: maximum sessions reached', 503, null);
 }
-function respondBadRequest(res) {
-    sendJsonRpcError(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400);
+function respondBadRequest(res, id) {
+    sendJsonRpcError(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400, id);
 }
 function createTimeoutController() {
     let initTimeout = null;
@@ -286,7 +286,7 @@ function resolveSessionId({ transport, res, tracker, clearInitTimeout, }) {
     if (typeof sessionId !== 'string') {
         clearInitTimeout();
         tracker.releaseSlot();
-        respondBadRequest(res);
+        respondBadRequest(res, null);
         return null;
     }
     return sessionId;
@@ -343,11 +343,11 @@ export async function resolveTransportForPost({ res, body, sessionId, options, }
             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);
+        sendJsonRpcError(res, -32600, 'Session not found', 404, body.id ?? null);
         return null;
     }
     if (!isInitializeRequest(body)) {
-        respondBadRequest(res);
+        respondBadRequest(res, body.id ?? null);
         return null;
     }
     evictExpiredSessionsWithClose(options.sessionStore);

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()');
+        }
+    }
+}

package/dist/http/server.d.ts

@@ -1,13 +1,3 @@
-import type { Express, NextFunction, Request, RequestHandler, Response } from 'express';
-export declare function createCorsMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
-export declare function attachBaseMiddleware(options: {
-    app: Express;
-    jsonParser: RequestHandler;
-    rateLimitMiddleware: RequestHandler;
-    corsMiddleware: RequestHandler;
-}): void;
-export declare function registerDownloadRoutes(app: Express): void;
-export declare function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void;
 export declare function startHttpServer(): Promise<{
     shutdown: (signal: string) => Promise<void>;
 }>;