@j0hanz/superfetch 2.0.0 → 2.1.0

package/dist/http/server.js

@@ -1,16 +1,207 @@
+import { setInterval as setIntervalPromise } from 'node:timers/promises';
 import { config, enableHttpMode } from '../config/index.js';
-import { logError, logInfo } from '../services/logger.js';
-import { errorHandler } from '../middleware/error-handler.js';
+import { destroyAgents } from '../services/fetcher.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 { 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 { createRateLimitMiddleware } from './rate-limit.js';
-import { assertHttpConfiguration } from './server-config.js';
-import { attachBaseMiddleware } from './server-middleware.js';
-import { createShutdownHandler, registerSignalHandlers, } from './server-shutdown.js';
-import { startSessionCleanupLoop } from './session-cleanup.js';
-import { createSessionStore } from './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';
+}
+function createCleanupInterval(store, options) {
+    const controller = new AbortController();
+    void startCleanupLoop(store, options, controller.signal).catch(handleCleanupError);
+    return controller;
+}
+function createRateLimitMiddleware(options) {
+    const store = new Map();
+    const cleanupController = createCleanupInterval(store, options);
+    const stop = () => {
+        cleanupController.abort();
+    };
+    const middleware = createRateLimitHandler(store, options);
+    return { middleware, stop, store };
+}
+function createRateLimitHandler(store, options) {
+    return (req, res, next) => {
+        if (shouldSkipRateLimit(req, options)) {
+            next();
+            return;
+        }
+        const now = Date.now();
+        const key = getRateLimitKey(req);
+        const resolution = resolveRateLimitEntry(store, key, now, options);
+        if (resolution.isNew) {
+            next();
+            return;
+        }
+        if (handleRateLimitExceeded(res, resolution.entry, now, options)) {
+            return;
+        }
+        next();
+    };
+}
+async function startCleanupLoop(store, options, signal) {
+    for await (const getNow of setIntervalPromise(options.cleanupIntervalMs, Date.now, { signal, ref: false })) {
+        evictStaleEntries(store, options, getNow());
+    }
+}
+function evictStaleEntries(store, options, now) {
+    for (const [key, entry] of store.entries()) {
+        if (now - entry.lastAccessed > options.windowMs * 2) {
+            store.delete(key);
+        }
+    }
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function handleCleanupError(error) {
+    if (isAbortError(error)) {
+        return;
+    }
+}
+function shouldSkipRateLimit(req, options) {
+    return !options.enabled || req.method === 'OPTIONS';
+}
+function resolveRateLimitEntry(store, key, now, options) {
+    const existing = store.get(key);
+    if (!existing || now > existing.resetTime) {
+        const entry = createNewEntry(now, options);
+        store.set(key, entry);
+        return { entry, isNew: true };
+    }
+    updateEntry(existing, now);
+    return { entry: existing, isNew: false };
+}
+function createNewEntry(now, options) {
+    return {
+        count: 1,
+        resetTime: now + options.windowMs,
+        lastAccessed: now,
+    };
+}
+function updateEntry(entry, now) {
+    entry.count += 1;
+    entry.lastAccessed = now;
+}
+function handleRateLimitExceeded(res, entry, now, options) {
+    if (entry.count <= options.maxRequests) {
+        return false;
+    }
+    const retryAfter = Math.max(1, Math.ceil((entry.resetTime - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.status(429).json({
+        error: 'Rate limit exceeded',
+        retryAfter,
+    });
+    return true;
+}
+function assertHttpConfiguration() {
+    ensureBindAllowed();
+    ensureStaticTokens();
+    if (config.auth.mode === 'oauth') {
+        ensureOauthConfiguration();
+    }
+}
+function ensureBindAllowed() {
+    const isLoopback = ['127.0.0.1', '::1', 'localhost'].includes(config.server.host);
+    if (!config.security.allowRemote && !isLoopback) {
+        logError('Refusing to bind to non-loopback host without ALLOW_REMOTE=true', { host: config.server.host });
+        process.exit(1);
+    }
+    if (!isLoopback &&
+        config.security.allowRemote &&
+        config.auth.mode !== 'oauth') {
+        logError('Remote HTTP mode requires OAuth configuration; refusing to start');
+        process.exit(1);
+    }
+}
+function ensureStaticTokens() {
+    if (config.auth.mode === 'static' && config.auth.staticTokens.length === 0) {
+        logError('At least one static access token is required for HTTP mode');
+        process.exit(1);
+    }
+}
+function ensureOauthConfiguration() {
+    if (!config.auth.issuerUrl || !config.auth.authorizationUrl) {
+        logError('OAUTH_ISSUER_URL and OAUTH_AUTHORIZATION_URL are required for OAuth mode');
+        process.exit(1);
+    }
+    if (!config.auth.tokenUrl) {
+        logError('OAUTH_TOKEN_URL is required for OAuth mode');
+        process.exit(1);
+    }
+    if (!config.auth.introspectionUrl) {
+        logError('OAUTH_INTROSPECTION_URL is required for OAuth mode');
+        process.exit(1);
+    }
+}
+function createShutdownHandler(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...`);
+    stopRateLimitCleanup();
+    sessionCleanupController.abort();
+    await closeSessions(sessionStore);
+    destroyAgents();
+    await shutdownTransformWorkerPool();
+    drainConnectionsOnShutdown(server);
+    closeServer(server);
+    scheduleForcedShutdown(10000);
+}
+async function closeSessions(sessionStore) {
+    const sessions = sessionStore.clear();
+    await Promise.allSettled(sessions.map((session) => session.transport.close().catch((error) => {
+        logWarn('Failed to close session during shutdown', {
+            error: getErrorMessage(error),
+        });
+    })));
+}
+function closeServer(server) {
+    server.close(() => {
+        logInfo('HTTP server closed');
+        process.exit(0);
+    });
+}
+function scheduleForcedShutdown(timeoutMs) {
+    setTimeout(() => {
+        logError('Forced shutdown after timeout');
+        process.exit(1);
+    }, timeoutMs).unref();
+}
+function registerSignalHandlers(shutdown) {
+    process.once('SIGINT', () => {
+        void shutdown('SIGINT');
+    });
+    process.once('SIGTERM', () => {
+        void shutdown('SIGTERM');
+    });
+}
 function startListening(app) {
     return app
         .listen(config.server.port, config.server.host, () => {
@@ -68,7 +259,12 @@ async function buildServerContext() {
 async function createAppWithMiddleware() {
     const { app, jsonParser } = await createExpressApp();
     const { rateLimitMiddleware, stopRateLimitCleanup, authMiddleware, corsMiddleware, } = buildMiddleware();
-    attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, corsMiddleware);
+    attachBaseMiddleware({
+        app,
+        jsonParser,
+        rateLimitMiddleware,
+        corsMiddleware,
+    });
     attachAuthMetadata(app);
     assertHttpConfiguration();
     return { app, authMiddleware, stopRateLimitCleanup };
@@ -82,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/session-cleanup.js

@@ -1,6 +1,6 @@
 import { setInterval as setIntervalPromise } from 'node:timers/promises';
 import { logInfo, logWarn } from '../services/logger.js';
-import { evictExpiredSessions } from './mcp-session.js';
+import { evictExpiredSessions } from './mcp-session-eviction.js';
 export function startSessionCleanupLoop(store, sessionTtlMs) {
     const controller = new AbortController();
     void runSessionCleanupLoop(store, sessionTtlMs, controller.signal).catch(handleSessionCleanupError);
@@ -8,11 +8,11 @@ export function startSessionCleanupLoop(store, sessionTtlMs) {
 }
 async function runSessionCleanupLoop(store, sessionTtlMs, signal) {
     const intervalMs = getCleanupIntervalMs(sessionTtlMs);
-    for await (const _ of setIntervalPromise(intervalMs, undefined, {
+    for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
         signal,
         ref: false,
     })) {
-        handleSessionEvictions(store);
+        handleSessionEvictions(store, getNow());
     }
 }
 function getCleanupIntervalMs(sessionTtlMs) {
@@ -21,10 +21,13 @@ function getCleanupIntervalMs(sessionTtlMs) {
 function isAbortError(error) {
     return error instanceof Error && error.name === 'AbortError';
 }
-function handleSessionEvictions(store) {
+function handleSessionEvictions(store, now) {
     const evicted = evictExpiredSessions(store);
     if (evicted > 0) {
-        logInfo('Expired sessions evicted', { evicted });
+        logInfo('Expired sessions evicted', {
+            evicted,
+            timestamp: new Date(now).toISOString(),
+        });
     }
 }
 function handleSessionCleanupError(error) {

package/dist/http.d.ts

@@ -0,0 +1,78 @@
+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(): Promise<{
+    shutdown: (signal: string) => Promise<void>;
+}>;
+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;
+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 {};