@j0hanz/superfetch 2.5.2 → 2.6.0

package/dist/resources.js

@@ -4,17 +4,27 @@ import { stableStringify } from './json.js';
 /* -------------------------------------------------------------------------------------------------
  * Configuration Resource
  * ------------------------------------------------------------------------------------------------- */
+const REDACTED = '<REDACTED>';
+const CONFIG_RESOURCE_NAME = 'config';
+const CONFIG_RESOURCE_URI = 'internal://config';
+const JSON_MIME = 'application/json';
+function redactIfPresent(value) {
+    return value ? REDACTED : undefined;
+}
+function redactArray(values) {
+    return values.map(() => REDACTED);
+}
 function scrubAuth(auth) {
     return {
         ...auth,
-        clientSecret: auth.clientSecret ? '<REDACTED>' : undefined,
-        staticTokens: auth.staticTokens.map(() => '<REDACTED>'),
+        clientSecret: redactIfPresent(auth.clientSecret),
+        staticTokens: redactArray(auth.staticTokens),
     };
 }
 function scrubSecurity(security) {
     return {
         ...security,
-        apiKey: security.apiKey ? '<REDACTED>' : undefined,
+        apiKey: redactIfPresent(security.apiKey),
     };
 }
 function scrubConfig(source) {
@@ -25,17 +35,17 @@ function scrubConfig(source) {
     };
 }
 export function registerConfigResource(server) {
-    server.registerResource('config', new ResourceTemplate('internal://config', { list: undefined }), {
+    server.registerResource(CONFIG_RESOURCE_NAME, new ResourceTemplate(CONFIG_RESOURCE_URI, { list: undefined }), {
         title: 'Server Configuration',
         description: 'Current runtime configuration (secrets redacted)',
-        mimeType: 'application/json',
+        mimeType: JSON_MIME,
     }, (uri) => {
         const scrubbed = scrubConfig(config);
         return {
             contents: [
                 {
                     uri: uri.href,
-                    mimeType: 'application/json',
+                    mimeType: JSON_MIME,
                     text: stableStringify(scrubbed),
                 },
             ],

package/dist/server-tuning.d.ts

@@ -2,6 +2,8 @@ export interface HttpServerTuningTarget {
     headersTimeout?: number;
     requestTimeout?: number;
     keepAliveTimeout?: number;
+    maxConnections?: number;
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
     closeIdleConnections?: () => void;
     closeAllConnections?: () => void;
 }

package/dist/server-tuning.js

@@ -1,30 +1,32 @@
 import { config } from './config.js';
-import { logDebug } from './observability.js';
+import { logDebug, logWarn } from './observability.js';
+const DROP_LOG_INTERVAL_MS = 10_000;
 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;
+    const { maxConnections } = config.server.http;
+    if (typeof maxConnections === 'number' && maxConnections > 0) {
+        server.maxConnections = maxConnections;
+        if (typeof server.on === 'function') {
+            let lastLoggedAt = 0;
+            let droppedSinceLastLog = 0;
+            server.on('drop', (data) => {
+                droppedSinceLastLog += 1;
+                const now = Date.now();
+                if (now - lastLoggedAt < DROP_LOG_INTERVAL_MS)
+                    return;
+                logWarn('Incoming connection dropped (maxConnections reached)', {
+                    maxConnections,
+                    dropped: droppedSinceLastLog,
+                    data,
+                });
+                lastLoggedAt = now;
+                droppedSinceLastLog = 0;
+            });
+        }
     }
 }
 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');
-        }
-        return;
-    }
-    if (shutdownCloseIdleConnections) {
-        if (typeof server.closeIdleConnections === 'function') {
-            server.closeIdleConnections();
-            logDebug('Closed idle HTTP connections during shutdown');
-        }
+    if (typeof server.closeIdleConnections === 'function') {
+        server.closeIdleConnections();
+        logDebug('Closed idle HTTP connections during shutdown');
     }
 }

package/dist/session.d.ts

@@ -4,6 +4,7 @@ export interface SessionEntry {
     createdAt: number;
     lastSeen: number;
     protocolInitialized: boolean;
+    authFingerprint: string;
 }
 export interface SessionStore {
     get: (sessionId: string) => SessionEntry | undefined;

package/dist/session.js

@@ -14,11 +14,13 @@ export function composeCloseHandlers(first, second) {
         }
     };
 }
-/* -------------------------------------------------------------------------------------------------
- * Cleanup loop
- * ------------------------------------------------------------------------------------------------- */
+const MIN_CLEANUP_INTERVAL_MS = 10_000;
+const MAX_CLEANUP_INTERVAL_MS = 60_000;
 function getCleanupIntervalMs(sessionTtlMs) {
-    return Math.min(Math.max(Math.floor(sessionTtlMs / 2), 10_000), 60_000);
+    return Math.min(Math.max(Math.floor(sessionTtlMs / 2), MIN_CLEANUP_INTERVAL_MS), MAX_CLEANUP_INTERVAL_MS);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
 }
 function isAbortError(error) {
     return error instanceof Error && error.name === 'AbortError';
@@ -26,11 +28,11 @@ function isAbortError(error) {
 function handleSessionCleanupError(error) {
     if (isAbortError(error))
         return;
-    logWarn('Session cleanup loop failed', {
-        error: error instanceof Error ? error.message : 'Unknown error',
-    });
+    logWarn('Session cleanup loop failed', { error: formatError(error) });
 }
 function isSessionExpired(session, now, sessionTtlMs) {
+    if (sessionTtlMs <= 0)
+        return false;
     return now - session.lastSeen > sessionTtlMs;
 }
 class SessionCleanupLoop {
@@ -47,16 +49,17 @@ class SessionCleanupLoop {
     }
     async run(signal) {
         const intervalMs = getCleanupIntervalMs(this.sessionTtlMs);
-        for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
+        const ticks = setIntervalPromise(intervalMs, Date.now, {
             signal,
             ref: false,
-        })) {
+        });
+        for await (const getNow of ticks) {
             const now = getNow();
             const evicted = this.store.evictExpired();
             for (const session of evicted) {
                 void session.transport.close().catch((err) => {
                     logWarn('Failed to close expired session', {
-                        error: err instanceof Error ? err : new Error(String(err)),
+                        error: formatError(err),
                     });
                 });
             }
@@ -72,9 +75,6 @@ class SessionCleanupLoop {
 export function startSessionCleanupLoop(store, sessionTtlMs) {
     return new SessionCleanupLoop(store, sessionTtlMs).start();
 }
-/* -------------------------------------------------------------------------------------------------
- * Session store (in-memory, Map order used for LRU)
- * ------------------------------------------------------------------------------------------------- */
 function moveSessionToEnd(sessions, sessionId, session) {
     sessions.delete(sessionId);
     sessions.set(sessionId, session);
@@ -87,9 +87,13 @@ class InMemorySessionStore {
         this.sessionTtlMs = sessionTtlMs;
     }
     get(sessionId) {
+        if (!sessionId)
+            return undefined;
         return this.sessions.get(sessionId);
     }
     touch(sessionId) {
+        if (!sessionId)
+            return;
         const session = this.sessions.get(sessionId);
         if (!session)
             return;
@@ -97,9 +101,13 @@ class InMemorySessionStore {
         moveSessionToEnd(this.sessions, sessionId, session);
     }
     set(sessionId, entry) {
-        this.sessions.set(sessionId, entry);
+        if (!sessionId)
+            return;
+        moveSessionToEnd(this.sessions, sessionId, entry);
     }
     remove(sessionId) {
+        if (!sessionId)
+            return undefined;
         const session = this.sessions.get(sessionId);
         this.sessions.delete(sessionId);
         return session;
@@ -114,8 +122,7 @@ class InMemorySessionStore {
         this.inflight += 1;
     }
     decrementInFlight() {
-        if (this.inflight > 0)
-            this.inflight -= 1;
+        this.inflight = Math.max(0, this.inflight - 1);
     }
     clear() {
         const entries = [...this.sessions.values()];
@@ -126,10 +133,10 @@ class InMemorySessionStore {
         const now = Date.now();
         const evicted = [];
         for (const [id, session] of this.sessions.entries()) {
-            if (isSessionExpired(session, now, this.sessionTtlMs)) {
-                this.sessions.delete(id);
-                evicted.push(session);
-            }
+            if (!isSessionExpired(session, now, this.sessionTtlMs))
+                continue;
+            this.sessions.delete(id);
+            evicted.push(session);
         }
         return evicted;
     }
@@ -146,9 +153,6 @@ class InMemorySessionStore {
 export function createSessionStore(sessionTtlMs) {
     return new InMemorySessionStore(sessionTtlMs);
 }
-/* -------------------------------------------------------------------------------------------------
- * Slot tracker
- * ------------------------------------------------------------------------------------------------- */
 class SessionSlotTracker {
     store;
     slotReleased = false;
@@ -172,27 +176,31 @@ class SessionSlotTracker {
 export function createSlotTracker(store) {
     return new SessionSlotTracker(store);
 }
+function currentLoad(store) {
+    return store.size() + store.inFlight();
+}
 export function reserveSessionSlot(store, maxSessions) {
-    if (store.size() + store.inFlight() >= maxSessions) {
+    if (maxSessions <= 0)
+        return false;
+    if (currentLoad(store) >= maxSessions)
         return false;
-    }
     store.incrementInFlight();
     return true;
 }
-/* -------------------------------------------------------------------------------------------------
- * Capacity policy
- * ------------------------------------------------------------------------------------------------- */
 function isAtCapacity(store, maxSessions) {
-    return store.size() + store.inFlight() >= maxSessions;
+    return currentLoad(store) >= maxSessions;
 }
 export function ensureSessionCapacity({ store, maxSessions, evictOldest, }) {
+    if (maxSessions <= 0)
+        return false;
     const currentSize = store.size();
     const inflight = store.inFlight();
     if (currentSize + inflight < maxSessions)
         return true;
     const canFreeSlot = currentSize >= maxSessions && currentSize - 1 + inflight < maxSessions;
-    if (canFreeSlot && evictOldest(store)) {
-        return !isAtCapacity(store, maxSessions);
-    }
-    return false;
+    if (!canFreeSlot)
+        return false;
+    if (!evictOldest(store))
+        return false;
+    return !isAtCapacity(store, maxSessions);
 }

package/dist/tasks.d.ts

@@ -34,6 +34,8 @@ export interface CreateTaskResult {
 declare class TaskManager {
     private tasks;
     private waiters;
+    constructor();
+    private startCleanupLoop;
     createTask(options?: CreateTaskOptions, statusMessage?: string, ownerKey?: string): TaskState;
     getTask(taskId: string, ownerKey?: string): TaskState | undefined;
     updateTask(taskId: string, updates: Partial<Omit<TaskState, 'taskId' | 'createdAt'>>): void;

package/dist/tasks.js

@@ -1,5 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
+import { setInterval } from 'node:timers';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { createUnrefTimeout } from './timer-utils.js';
 const DEFAULT_TTL_MS = 60000;
 const DEFAULT_POLL_INTERVAL_MS = 1000;
 const DEFAULT_OWNER_KEY = 'default';
@@ -15,6 +19,19 @@ function isTerminalStatus(status) {
 class TaskManager {
     tasks = new Map();
     waiters = new Map();
+    constructor() {
+        this.startCleanupLoop();
+    }
+    startCleanupLoop() {
+        const interval = setInterval(() => {
+            for (const [id, task] of this.tasks) {
+                if (this.isExpired(task)) {
+                    this.tasks.delete(id);
+                }
+            }
+        }, 60000);
+        interval.unref();
+    }
     createTask(options, statusMessage = 'Task started', ownerKey = DEFAULT_OWNER_KEY) {
         const taskId = randomUUID();
         const now = new Date().toISOString();
@@ -99,13 +116,52 @@ class TaskManager {
             return undefined;
         if (isTerminalStatus(task.status))
             return task;
+        const createdAtMs = Date.parse(task.createdAt);
+        const deadlineMs = Number.isFinite(createdAtMs)
+            ? createdAtMs + task.ttl
+            : Number.NaN;
+        if (Number.isFinite(deadlineMs) && deadlineMs <= Date.now()) {
+            this.tasks.delete(taskId);
+            return undefined;
+        }
         return new Promise((resolve, reject) => {
+            const runInContext = AsyncLocalStorage.snapshot();
+            const resolveInContext = (value) => {
+                runInContext(() => {
+                    resolve(value);
+                });
+            };
+            const rejectInContext = (error) => {
+                runInContext(() => {
+                    if (error instanceof Error) {
+                        reject(error);
+                    }
+                    else {
+                        reject(new Error(String(error)));
+                    }
+                });
+            };
+            let settled = false;
+            let waiter = null;
+            let deadlineTimeout;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
             const onAbort = () => {
-                cleanup();
-                removeWaiter();
-                reject(new McpError(ErrorCode.ConnectionClosed, 'Request was cancelled'));
+                settle(() => {
+                    cleanup();
+                    removeWaiter();
+                    rejectInContext(new McpError(ErrorCode.ConnectionClosed, 'Request was cancelled'));
+                });
             };
             const cleanup = () => {
+                if (deadlineTimeout) {
+                    deadlineTimeout.cancel();
+                    deadlineTimeout = undefined;
+                }
                 if (signal) {
                     signal.removeEventListener('abort', onAbort);
                 }
@@ -114,13 +170,16 @@ class TaskManager {
                 const waiters = this.waiters.get(taskId);
                 if (!waiters)
                     return;
-                waiters.delete(waiter);
+                if (waiter)
+                    waiters.delete(waiter);
                 if (waiters.size === 0)
                     this.waiters.delete(taskId);
             };
-            const waiter = (updated) => {
-                cleanup();
-                resolve(updated);
+            waiter = (updated) => {
+                settle(() => {
+                    cleanup();
+                    resolveInContext(updated);
+                });
             };
             if (signal?.aborted) {
                 onAbort();
@@ -132,6 +191,29 @@ class TaskManager {
             if (signal) {
                 signal.addEventListener('abort', onAbort, { once: true });
             }
+            if (Number.isFinite(deadlineMs)) {
+                const timeoutMs = Math.max(0, deadlineMs - Date.now());
+                if (timeoutMs === 0) {
+                    settle(() => {
+                        cleanup();
+                        removeWaiter();
+                        this.tasks.delete(taskId);
+                        resolveInContext(undefined);
+                    });
+                    return;
+                }
+                deadlineTimeout = createUnrefTimeout(timeoutMs, { timeout: true });
+                void deadlineTimeout.promise
+                    .then(() => {
+                    settle(() => {
+                        cleanup();
+                        removeWaiter();
+                        this.tasks.delete(taskId);
+                        resolveInContext(undefined);
+                    });
+                })
+                    .catch(rejectInContext);
+            }
         });
     }
     notifyWaiters(task) {
@@ -151,11 +233,11 @@ class TaskManager {
         return Date.now() - createdAt > task.ttl;
     }
     encodeCursor(index) {
-        return Buffer.from(String(index)).toString('base64');
+        return Buffer.from(String(index)).toString('base64url');
     }
     decodeCursor(cursor) {
         try {
-            const decoded = Buffer.from(cursor, 'base64').toString('utf8');
+            const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
             const value = Number.parseInt(decoded, 10);
             if (!Number.isFinite(value) || value < 0)
                 return null;

package/dist/timer-utils.d.ts

@@ -0,0 +1,5 @@
+export interface CancellableTimeout<T> {
+    promise: Promise<T>;
+    cancel: () => void;
+}
+export declare function createUnrefTimeout<T>(timeoutMs: number, value: T): CancellableTimeout<T>;

package/dist/timer-utils.js

@@ -0,0 +1,20 @@
+import { setTimeout as setTimeoutPromise } from 'node:timers/promises';
+import { isError } from './type-guards.js';
+export function createUnrefTimeout(timeoutMs, value) {
+    const controller = new AbortController();
+    const promise = setTimeoutPromise(timeoutMs, value, {
+        ref: false,
+        signal: controller.signal,
+    }).catch((err) => {
+        if (isError(err) && err.name === 'AbortError') {
+            return new Promise(() => { });
+        }
+        throw err;
+    });
+    return {
+        promise,
+        cancel: () => {
+            controller.abort();
+        },
+    };
+}

package/dist/tools.d.ts

@@ -1,8 +1,11 @@
+import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult, ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 import type { MarkdownTransformResult } from './transform-types.js';
 export interface FetchUrlInput {
     url: string;
+    skipNoiseRemoval?: boolean | undefined;
+    forceRefresh?: boolean | undefined;
 }
 export interface ToolContentBlock {
     type: 'text';
@@ -29,6 +32,8 @@ export type ToolErrorResponse = CallToolResult & {
     structuredContent: {
         error: string;
         url: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
     };
     isError: true;
 };
@@ -38,7 +43,11 @@ export interface FetchPipelineOptions<T> {
     cacheNamespace: string;
     signal?: AbortSignal;
     cacheVary?: Record<string, unknown> | string;
-    transform: (html: string, url: string) => T | Promise<T>;
+    forceRefresh?: boolean;
+    transform: (input: {
+        buffer: Uint8Array;
+        encoding: string;
+    }, url: string) => T | Promise<T>;
     serialize?: (result: T) => string;
     deserialize?: (cached: string) => T | undefined;
 }
@@ -46,6 +55,7 @@ export interface PipelineResult<T> {
     data: T;
     fromCache: boolean;
     url: string;
+    originalUrl?: string;
     fetchedAt: string;
     cacheKey?: string | null;
 }
@@ -68,9 +78,16 @@ export interface ProgressNotification {
 export interface ToolHandlerExtra {
     signal?: AbortSignal;
     requestId?: string | number;
+    sessionId?: unknown;
+    requestInfo?: unknown;
     _meta?: RequestMeta;
     sendNotification?: (notification: ProgressNotification) => Promise<void>;
 }
+export declare const fetchUrlInputSchema: z.ZodObject<{
+    url: z.ZodURL;
+    skipNoiseRemoval: z.ZodOptional<z.ZodBoolean>;
+    forceRefresh: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 export declare const FETCH_URL_TOOL_NAME = "fetch-url";
 interface ProgressReporter {
     report: (progress: number, message: string) => Promise<void>;
@@ -87,8 +104,6 @@ interface InlineContentResult {
 export type InlineResult = ReturnType<InlineContentLimiter['apply']>;
 declare class InlineContentLimiter {
     apply(content: string, cacheKey: string | null): InlineContentResult;
-    private resolveResourceUri;
-    private buildTruncatedFallback;
 }
 export declare function executeFetchPipeline<T>(options: FetchPipelineOptions<T>): Promise<PipelineResult<T>>;
 interface SharedFetchOptions<T extends {
@@ -96,7 +111,12 @@ interface SharedFetchOptions<T extends {
 }> {
     readonly url: string;
     readonly signal?: AbortSignal;
-    readonly transform: (html: string, normalizedUrl: string) => T | Promise<T>;
+    readonly cacheVary?: Record<string, unknown> | string;
+    readonly forceRefresh?: boolean;
+    readonly transform: (input: {
+        buffer: Uint8Array;
+        encoding: string;
+    }, normalizedUrl: string) => T | Promise<T>;
     readonly serialize?: (result: T) => string;
     readonly deserialize?: (cached: string) => T | undefined;
 }
@@ -109,7 +129,10 @@ export declare function performSharedFetch<T extends {
     pipeline: PipelineResult<T>;
     inlineResult: InlineResult;
 }>;
-export declare function createToolErrorResponse(message: string, url: string): ToolErrorResponse;
+export declare function createToolErrorResponse(message: string, url: string, extra?: {
+    statusCode?: number;
+    details?: Record<string, unknown>;
+}): ToolErrorResponse;
 export declare function handleToolError(error: unknown, url: string, fallbackMessage?: string): ToolErrorResponse;
 type MarkdownPipelineResult = MarkdownTransformResult & {
     readonly content: string;