@j0hanz/superfetch 2.0.1 → 2.1.1

package/dist/http/server.js

@@ -1,17 +1,17 @@
-import { randomUUID } from 'node:crypto';
 import { setInterval as setIntervalPromise } from 'node:timers/promises';
 import { config, enableHttpMode } from '../config/index.js';
-import { FetchError } from '../errors/app-error.js';
-import * as cache from '../services/cache.js';
-import { runWithRequestContext } from '../services/context.js';
 import { destroyAgents } from '../services/fetcher.js';
-import { logDebug, logError, logInfo, logWarn } from '../services/logger.js';
-import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
+import { logError, logInfo, logWarn } from '../services/logger.js';
+import { shutdownTransformWorkerPool } from '../services/transform-worker-pool.js';
 import { getErrorMessage } from '../utils/error-details.js';
-import { generateSafeFilename } from '../utils/filename-generator.js';
 import { createAuthMetadataRouter, createAuthMiddleware } from './auth.js';
+import { attachBaseMiddleware } from './base-middleware.js';
+import { createCorsMiddleware } from './cors.js';
+import { registerDownloadRoutes } from './download-routes.js';
+import { errorHandler } from './error-handler.js';
 import { registerMcpRoutes } from './mcp-routes.js';
-import { createSessionStore, getSessionId, startSessionCleanupLoop, } from './mcp-sessions.js';
+import { createSessionStore, startSessionCleanupLoop, } from './mcp-sessions.js';
+import { applyHttpServerTuning, drainConnectionsOnShutdown, } from './server-tuning.js';
 function getRateLimitKey(req) {
     return req.ip ?? req.socket.remoteAddress ?? 'unknown';
 }
@@ -104,327 +104,6 @@ function handleRateLimitExceeded(res, entry, now, options) {
     });
     return true;
 }
-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) {
-            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 } : { requestId, sessionId };
-        runWithRequestContext(context, () => {
-            next();
-        });
-    };
-}
-export function createCorsMiddleware() {
-    return (req, res, next) => {
-        // Handle OPTIONS preflight
-        if (req.method === 'OPTIONS') {
-            res.sendStatus(200);
-            return;
-        }
-        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);
-}
-const HASH_PATTERN = /^[a-f0-9.]+$/i;
-function validateNamespace(namespace) {
-    return namespace === 'markdown';
-}
-function validateHash(hash) {
-    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
-}
-function parseDownloadParams(req) {
-    const { namespace, hash } = req.params;
-    if (!namespace || !hash)
-        return null;
-    if (!validateNamespace(namespace))
-        return null;
-    if (!validateHash(hash))
-        return null;
-    return { namespace, hash };
-}
-function buildCacheKeyFromParams(params) {
-    return `${params.namespace}:${params.hash}`;
-}
-function respondBadRequest(res, message) {
-    res.status(400).json({
-        error: message,
-        code: 'BAD_REQUEST',
-    });
-}
-function respondNotFound(res) {
-    res.status(404).json({
-        error: 'Content not found or expired',
-        code: 'NOT_FOUND',
-    });
-}
-function respondServiceUnavailable(res) {
-    res.status(503).json({
-        error: 'Download service is disabled',
-        code: 'SERVICE_UNAVAILABLE',
-    });
-}
-function resolveDownloadPayload(params, cacheEntry) {
-    const payload = parseCachedPayload(cacheEntry.content);
-    if (!payload)
-        return null;
-    const content = resolveCachedPayloadContent(payload);
-    if (!content)
-        return null;
-    const safeTitle = typeof payload.title === 'string' ? payload.title : undefined;
-    const fileName = generateSafeFilename(cacheEntry.url, cacheEntry.title ?? safeTitle, params.hash, '.md');
-    return {
-        content,
-        contentType: 'text/markdown; charset=utf-8',
-        fileName,
-    };
-}
-function buildContentDisposition(fileName) {
-    const encodedName = encodeURIComponent(fileName).replace(/'/g, '%27');
-    return `attachment; filename="${fileName}"; filename*=UTF-8''${encodedName}`;
-}
-function sendDownloadPayload(res, payload) {
-    const disposition = buildContentDisposition(payload.fileName);
-    res.setHeader('Content-Type', payload.contentType);
-    res.setHeader('Content-Disposition', disposition);
-    res.setHeader('Cache-Control', `private, max-age=${config.cache.ttl}`);
-    res.setHeader('X-Content-Type-Options', 'nosniff');
-    res.send(payload.content);
-}
-function handleDownload(req, res) {
-    if (!config.cache.enabled) {
-        respondServiceUnavailable(res);
-        return;
-    }
-    const params = parseDownloadParams(req);
-    if (!params) {
-        respondBadRequest(res, 'Invalid namespace or hash format');
-        return;
-    }
-    const cacheKey = buildCacheKeyFromParams(params);
-    const cacheEntry = cache.get(cacheKey);
-    if (!cacheEntry) {
-        logDebug('Download request for missing cache key', { cacheKey });
-        respondNotFound(res);
-        return;
-    }
-    const payload = resolveDownloadPayload(params, cacheEntry);
-    if (!payload) {
-        logDebug('Download payload unavailable', { cacheKey });
-        respondNotFound(res);
-        return;
-    }
-    logDebug('Serving download', { cacheKey, fileName: payload.fileName });
-    sendDownloadPayload(res, payload);
-}
-export function registerDownloadRoutes(app) {
-    app.get('/mcp/downloads/:namespace/:hash', handleDownload);
-}
-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 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 }),
-        },
-    };
-    // Never expose stack traces in production
-    return response;
-}
-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';
-}
-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));
-}
 function assertHttpConfiguration() {
     ensureBindAllowed();
     ensureStaticTokens();
@@ -438,7 +117,9 @@ function ensureBindAllowed() {
         logError('Refusing to bind to non-loopback host without ALLOW_REMOTE=true', { host: config.server.host });
         process.exit(1);
     }
-    if (config.security.allowRemote && config.auth.mode !== 'oauth') {
+    if (!isLoopback &&
+        config.security.allowRemote &&
+        config.auth.mode !== 'oauth') {
         logError('Remote HTTP mode requires OAuth configuration; refusing to start');
         process.exit(1);
     }
@@ -464,7 +145,23 @@ function ensureOauthConfiguration() {
     }
 }
 function createShutdownHandler(server, sessionStore, sessionCleanupController, stopRateLimitCleanup) {
-    return (signal) => shutdownServer(signal, server, sessionStore, sessionCleanupController, stopRateLimitCleanup);
+    let inFlight = null;
+    let initialSignal = null;
+    return (signal) => {
+        if (inFlight) {
+            logWarn('Shutdown already in progress; ignoring signal', {
+                signal,
+                initialSignal,
+            });
+            return inFlight;
+        }
+        initialSignal = signal;
+        inFlight = shutdownServer(signal, server, sessionStore, sessionCleanupController, stopRateLimitCleanup).catch((error) => {
+            logError('Shutdown handler failed', error instanceof Error ? error : { error: getErrorMessage(error) });
+            throw error;
+        });
+        return inFlight;
+    };
 }
 async function shutdownServer(signal, server, sessionStore, sessionCleanupController, stopRateLimitCleanup) {
     logInfo(`${signal} received, shutting down gracefully...`);
@@ -472,6 +169,8 @@ async function shutdownServer(signal, server, sessionStore, sessionCleanupContro
     sessionCleanupController.abort();
     await closeSessions(sessionStore);
     destroyAgents();
+    await shutdownTransformWorkerPool();
+    drainConnectionsOnShutdown(server);
     closeServer(server);
     scheduleForcedShutdown(10000);
 }
@@ -496,10 +195,10 @@ function scheduleForcedShutdown(timeoutMs) {
     }, timeoutMs).unref();
 }
 function registerSignalHandlers(shutdown) {
-    process.on('SIGINT', () => {
+    process.once('SIGINT', () => {
         void shutdown('SIGINT');
     });
-    process.on('SIGTERM', () => {
+    process.once('SIGTERM', () => {
         void shutdown('SIGTERM');
     });
 }
@@ -579,6 +278,7 @@ export async function startHttpServer() {
     enableHttpMode();
     const { app, sessionStore, sessionCleanupController, stopRateLimitCleanup } = await buildServerContext();
     const server = startListening(app);
+    applyHttpServerTuning(server);
     const shutdown = createShutdownHandler(server, sessionStore, sessionCleanupController, stopRateLimitCleanup);
     registerSignalHandlers(shutdown);
     return { shutdown };

package/dist/http.d.ts

@@ -0,0 +1,86 @@
+import type { Express, NextFunction, Request, RequestHandler, Response } from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+interface SessionEntry {
+    readonly transport: StreamableHTTPServerTransport;
+    createdAt: number;
+    lastSeen: number;
+}
+interface McpRequestParams {
+    _meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface McpRequestBody {
+    jsonrpc: '2.0';
+    method: string;
+    id?: string | number;
+    params?: McpRequestParams;
+}
+export declare function startHttpServer(options?: {
+    registerSignalHandlers?: boolean;
+}): Promise<{
+    shutdown: (signal: string) => Promise<void>;
+    stop: () => Promise<void>;
+    url: string;
+    host: string;
+    port: number;
+}>;
+export declare function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void;
+export declare function normalizeHost(value: string): string | null;
+export declare function attachBaseMiddleware(options: {
+    app: Express;
+    jsonParser: RequestHandler;
+    rateLimitMiddleware: RequestHandler;
+    corsMiddleware: RequestHandler;
+}): void;
+export declare function createCorsMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+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;
+}
+interface McpSessionOptions {
+    readonly sessionStore: SessionStore;
+    readonly maxSessions: number;
+}
+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;
+type CloseHandler = (() => void) | undefined;
+export declare function composeCloseHandlers(first: CloseHandler, second: CloseHandler): CloseHandler;
+export declare function resolveTransportForPost({ res, body, sessionId, options, }: {
+    res: Response;
+    body: Pick<McpRequestBody, 'method' | 'id'>;
+    sessionId: string | undefined;
+    options: McpSessionOptions;
+}): Promise<StreamableHTTPServerTransport | null>;
+export declare function isJsonRpcBatchRequest(body: unknown): boolean;
+export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;
+export declare function ensureMcpProtocolVersionHeader(req: Request, res: Response): boolean;
+export declare function ensurePostAcceptHeader(req: Request): void;
+export declare function acceptsEventStream(req: Request): boolean;
+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;
+export {};