@j0hanz/superfetch 2.0.1 → 2.1.1

package/dist/cache.js

@@ -0,0 +1,674 @@
+import { setInterval as setIntervalPromise } from 'node:timers/promises';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { config } from './config.js';
+import { sha256Hex } from './crypto.js';
+import { getErrorMessage } from './errors.js';
+import { logDebug, logWarn } from './observability.js';
+import { isRecord } from './utils.js';
+export function parseCachedPayload(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return isCachedPayload(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveCachedPayloadContent(payload) {
+    if (typeof payload.markdown === 'string') {
+        return payload.markdown;
+    }
+    if (typeof payload.content === 'string') {
+        return payload.content;
+    }
+    return null;
+}
+function hasOptionalStringProperty(value, key) {
+    const prop = value[key];
+    if (prop === undefined)
+        return true;
+    return typeof prop === 'string';
+}
+function isCachedPayload(value) {
+    if (!isRecord(value))
+        return false;
+    if (!hasOptionalStringProperty(value, 'content'))
+        return false;
+    if (!hasOptionalStringProperty(value, 'markdown'))
+        return false;
+    if (!hasOptionalStringProperty(value, 'title'))
+        return false;
+    return true;
+}
+const CACHE_HASH = {
+    URL_HASH_LENGTH: 16,
+    VARY_HASH_LENGTH: 12,
+};
+const CACHE_VARY_LIMITS = {
+    MAX_STRING_LENGTH: 4096,
+    MAX_KEYS: 64,
+    MAX_ARRAY_LENGTH: 64,
+    MAX_DEPTH: 6,
+    MAX_NODES: 512,
+};
+function bumpStableStringifyNodeCount(state) {
+    state.nodes += 1;
+    return state.nodes <= CACHE_VARY_LIMITS.MAX_NODES;
+}
+function stableStringifyPrimitive(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    const json = JSON.stringify(value);
+    return typeof json === 'string' ? json : '';
+}
+function stableStringifyArray(value, state) {
+    if (value.length > CACHE_VARY_LIMITS.MAX_ARRAY_LENGTH) {
+        return null;
+    }
+    const parts = ['['];
+    let length = 1;
+    for (let index = 0; index < value.length; index += 1) {
+        if (index > 0) {
+            parts.push(',');
+            length += 1;
+            if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+                return null;
+        }
+        const entry = stableStringifyInner(value[index], state);
+        if (entry === null)
+            return null;
+        parts.push(entry);
+        length += entry.length;
+        if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+            return null;
+    }
+    parts.push(']');
+    length += 1;
+    return length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH ? null : parts.join('');
+}
+function stableStringifyRecord(value, state) {
+    const keys = Object.keys(value);
+    if (keys.length > CACHE_VARY_LIMITS.MAX_KEYS) {
+        return null;
+    }
+    keys.sort((a, b) => a.localeCompare(b));
+    const parts = ['{'];
+    let length = 1;
+    let isFirst = true;
+    for (const key of keys) {
+        const entryValue = value[key];
+        if (entryValue === undefined)
+            continue;
+        const encodedValue = stableStringifyInner(entryValue, state);
+        if (encodedValue === null)
+            return null;
+        const entry = `${JSON.stringify(key)}:${encodedValue}`;
+        if (!isFirst) {
+            parts.push(',');
+            length += 1;
+            if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+                return null;
+        }
+        parts.push(entry);
+        length += entry.length;
+        if (length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH)
+            return null;
+        isFirst = false;
+    }
+    parts.push('}');
+    length += 1;
+    return length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH ? null : parts.join('');
+}
+function stableStringifyObject(value, state) {
+    if (state.stack.has(value)) {
+        return null;
+    }
+    if (state.depth >= CACHE_VARY_LIMITS.MAX_DEPTH) {
+        return null;
+    }
+    state.stack.add(value);
+    state.depth += 1;
+    try {
+        if (Array.isArray(value)) {
+            return stableStringifyArray(value, state);
+        }
+        return isRecord(value) ? stableStringifyRecord(value, state) : null;
+    }
+    finally {
+        state.depth -= 1;
+        state.stack.delete(value);
+    }
+}
+function stableStringifyInner(value, state) {
+    if (!bumpStableStringifyNodeCount(state)) {
+        return null;
+    }
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value !== 'object') {
+        return stableStringifyPrimitive(value);
+    }
+    return stableStringifyObject(value, state);
+}
+function stableStringify(value) {
+    const state = {
+        depth: 0,
+        nodes: 0,
+        stack: new WeakSet(),
+    };
+    return stableStringifyInner(value, state);
+}
+function createHashFragment(input, length) {
+    return sha256Hex(input).substring(0, length);
+}
+function buildCacheKey(namespace, urlHash, varyHash) {
+    return varyHash
+        ? `${namespace}:${urlHash}.${varyHash}`
+        : `${namespace}:${urlHash}`;
+}
+function getVaryHash(vary) {
+    if (!vary)
+        return undefined;
+    let varyString;
+    if (typeof vary === 'string') {
+        varyString =
+            vary.length > CACHE_VARY_LIMITS.MAX_STRING_LENGTH ? null : vary;
+    }
+    else {
+        varyString = stableStringify(vary);
+    }
+    if (varyString === null)
+        return null;
+    if (!varyString)
+        return undefined;
+    return createHashFragment(varyString, CACHE_HASH.VARY_HASH_LENGTH);
+}
+export function createCacheKey(namespace, url, vary) {
+    if (!namespace || !url)
+        return null;
+    const urlHash = createHashFragment(url, CACHE_HASH.URL_HASH_LENGTH);
+    const varyHash = getVaryHash(vary);
+    if (varyHash === null)
+        return null;
+    return buildCacheKey(namespace, urlHash, varyHash);
+}
+export function parseCacheKey(cacheKey) {
+    if (!cacheKey)
+        return null;
+    const [namespace, ...rest] = cacheKey.split(':');
+    const urlHash = rest.join(':');
+    if (!namespace || !urlHash)
+        return null;
+    return { namespace, urlHash };
+}
+export function toResourceUri(cacheKey) {
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return null;
+    return `superfetch://cache/${parts.namespace}/${parts.urlHash}`;
+}
+const contentCache = new Map();
+let cleanupController = null;
+const updateListeners = new Set();
+export function onCacheUpdate(listener) {
+    updateListeners.add(listener);
+    return () => {
+        updateListeners.delete(listener);
+    };
+}
+function notifyCacheUpdate(cacheKey) {
+    if (updateListeners.size === 0)
+        return;
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return;
+    const event = { cacheKey, ...parts };
+    for (const listener of updateListeners) {
+        listener(event);
+    }
+}
+function startCleanupLoop() {
+    if (cleanupController)
+        return;
+    cleanupController = new AbortController();
+    void runCleanupLoop(cleanupController.signal).catch((error) => {
+        if (error instanceof Error && error.name !== 'AbortError') {
+            logWarn('Cache cleanup loop failed', { error: getErrorMessage(error) });
+        }
+    });
+}
+async function runCleanupLoop(signal) {
+    const intervalMs = Math.floor(config.cache.ttl * 1000);
+    for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
+        signal,
+        ref: false,
+    })) {
+        enforceCacheLimits(getNow());
+    }
+}
+function enforceCacheLimits(now) {
+    for (const [key, item] of contentCache.entries()) {
+        if (now > item.expiresAt) {
+            contentCache.delete(key);
+        }
+    }
+    trimCacheToMaxKeys();
+}
+export function get(cacheKey) {
+    if (!isCacheReadable(cacheKey))
+        return undefined;
+    return runCacheOperation(cacheKey, 'Cache get error', () => readCacheEntry(cacheKey));
+}
+function isCacheReadable(cacheKey) {
+    return config.cache.enabled && Boolean(cacheKey);
+}
+function isCacheWritable(cacheKey, content) {
+    return config.cache.enabled && Boolean(cacheKey) && Boolean(content);
+}
+function runCacheOperation(cacheKey, message, operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        logCacheError(message, cacheKey, error);
+        return undefined;
+    }
+}
+function readCacheEntry(cacheKey) {
+    const now = Date.now();
+    return readCacheItem(cacheKey, now)?.entry;
+}
+function isExpired(item, now) {
+    return now > item.expiresAt;
+}
+function readCacheItem(cacheKey, now) {
+    const item = contentCache.get(cacheKey);
+    if (!item)
+        return undefined;
+    if (isExpired(item, now)) {
+        contentCache.delete(cacheKey);
+        return undefined;
+    }
+    return item;
+}
+export function set(cacheKey, content, metadata) {
+    if (!isCacheWritable(cacheKey, content))
+        return;
+    runCacheOperation(cacheKey, 'Cache set error', () => {
+        startCleanupLoop();
+        const now = Date.now();
+        const expiresAtMs = now + config.cache.ttl * 1000;
+        const entry = buildCacheEntry({
+            content,
+            metadata,
+            fetchedAtMs: now,
+            expiresAtMs,
+        });
+        persistCacheEntry(cacheKey, entry, expiresAtMs);
+    });
+}
+export function keys() {
+    return Array.from(contentCache.keys());
+}
+export function isEnabled() {
+    return config.cache.enabled;
+}
+function buildCacheEntry({ content, metadata, fetchedAtMs, expiresAtMs, }) {
+    return {
+        url: metadata.url,
+        content,
+        fetchedAt: new Date(fetchedAtMs).toISOString(),
+        expiresAt: new Date(expiresAtMs).toISOString(),
+        ...(metadata.title === undefined ? {} : { title: metadata.title }),
+    };
+}
+function persistCacheEntry(cacheKey, entry, expiresAtMs) {
+    contentCache.set(cacheKey, { entry, expiresAt: expiresAtMs });
+    trimCacheToMaxKeys();
+    notifyCacheUpdate(cacheKey);
+}
+function trimCacheToMaxKeys() {
+    if (contentCache.size <= config.cache.maxKeys)
+        return;
+    removeOldestEntries(contentCache.size - config.cache.maxKeys);
+}
+function removeOldestEntries(count) {
+    const iterator = contentCache.keys();
+    for (let removed = 0; removed < count; removed += 1) {
+        const next = iterator.next();
+        if (next.done)
+            break;
+        contentCache.delete(next.value);
+    }
+}
+function logCacheError(message, cacheKey, error) {
+    logWarn(message, {
+        key: cacheKey.length > 100 ? cacheKey.slice(0, 100) : cacheKey,
+        error: getErrorMessage(error),
+    });
+}
+const CACHE_NAMESPACE = 'markdown';
+const HASH_PATTERN = /^[a-f0-9.]+$/i;
+function resolveCacheParams(params) {
+    const parsed = requireRecordParams(params);
+    const namespace = requireParamString(parsed, 'namespace');
+    const urlHash = requireParamString(parsed, 'urlHash');
+    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return { namespace, urlHash };
+}
+function requireRecordParams(value) {
+    if (!isRecord(value)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return value;
+}
+function requireParamString(params, key) {
+    const raw = params[key];
+    const resolved = resolveStringParam(raw);
+    if (!resolved) {
+        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
+    }
+    return resolved;
+}
+function isValidNamespace(namespace) {
+    return namespace === CACHE_NAMESPACE;
+}
+function isValidHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
+}
+function resolveStringParam(value) {
+    return typeof value === 'string' ? value : null;
+}
+function buildResourceEntry(namespace, urlHash) {
+    return {
+        name: `${namespace}:${urlHash}`,
+        uri: `superfetch://cache/${namespace}/${urlHash}`,
+        description: `Cached content entry for ${namespace}`,
+        mimeType: 'text/markdown',
+    };
+}
+function listCachedResources() {
+    const resources = keys()
+        .map((key) => {
+        const parts = parseCacheKey(key);
+        if (parts?.namespace !== CACHE_NAMESPACE)
+            return null;
+        return buildResourceEntry(parts.namespace, parts.urlHash);
+    })
+        .filter((entry) => entry !== null);
+    return { resources };
+}
+function appendServerOnClose(server, handler) {
+    const previousOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        previousOnClose?.();
+        handler();
+    };
+}
+function registerResourceSubscriptionHandlers(server) {
+    const subscriptions = new Set();
+    server.server.setRequestHandler(SubscribeRequestSchema, (request) => {
+        subscriptions.add(request.params.uri);
+        return {};
+    });
+    server.server.setRequestHandler(UnsubscribeRequestSchema, (request) => {
+        subscriptions.delete(request.params.uri);
+        return {};
+    });
+    appendServerOnClose(server, () => {
+        subscriptions.clear();
+    });
+    return subscriptions;
+}
+function notifyResourceUpdate(server, uri, subscriptions) {
+    if (!server.isConnected())
+        return;
+    if (!subscriptions.has(uri))
+        return;
+    void server.server.sendResourceUpdated({ uri }).catch((error) => {
+        logWarn('Failed to send resource update notification', {
+            uri,
+            error: getErrorMessage(error),
+        });
+    });
+}
+export function registerCachedContentResource(server) {
+    const subscriptions = registerResourceSubscriptionHandlers(server);
+    registerCacheContentResource(server);
+    registerCacheUpdateSubscription(server, subscriptions);
+}
+function buildCachedContentResponse(uri, cacheKey) {
+    const cached = requireCacheEntry(cacheKey);
+    return buildMarkdownContentResponse(uri, cached.content);
+}
+function registerCacheContentResource(server) {
+    server.registerResource('cached-content', new ResourceTemplate('superfetch://cache/{namespace}/{urlHash}', {
+        list: listCachedResources,
+    }), {
+        title: 'Cached Content',
+        description: 'Access previously fetched web content from cache. Namespace: markdown. UrlHash: SHA-256 hash of the URL.',
+        mimeType: 'text/plain',
+    }, (uri, params) => {
+        const { namespace, urlHash } = resolveCacheParams(params);
+        const cacheKey = `${namespace}:${urlHash}`;
+        return buildCachedContentResponse(uri, cacheKey);
+    });
+}
+function registerCacheUpdateSubscription(server, subscriptions) {
+    const unsubscribe = onCacheUpdate(({ cacheKey }) => {
+        const resourceUri = toResourceUri(cacheKey);
+        if (!resourceUri)
+            return;
+        notifyResourceUpdate(server, resourceUri, subscriptions);
+        if (server.isConnected()) {
+            server.sendResourceListChanged();
+        }
+    });
+    appendServerOnClose(server, unsubscribe);
+}
+function requireCacheEntry(cacheKey) {
+    const cached = get(cacheKey);
+    if (!cached) {
+        throw new McpError(-32002, `Content not found in cache for key: ${cacheKey}`);
+    }
+    return cached;
+}
+function buildMarkdownContentResponse(uri, content) {
+    const payload = parseCachedPayload(content);
+    const resolvedContent = payload ? resolveCachedPayloadContent(payload) : null;
+    if (!resolvedContent) {
+        throw new McpError(ErrorCode.InternalError, 'Cached markdown content is missing');
+    }
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: resolvedContent,
+            },
+        ],
+    };
+}
+function validateNamespace(namespace) {
+    return namespace === 'markdown';
+}
+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))
+        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',
+    });
+}
+export function generateSafeFilename(url, title, hashFallback, extension = '.md') {
+    const fromUrl = extractFilenameFromUrl(url);
+    if (fromUrl)
+        return sanitizeFilename(fromUrl, extension);
+    if (title) {
+        const fromTitle = slugifyTitle(title);
+        if (fromTitle)
+            return sanitizeFilename(fromTitle, extension);
+    }
+    if (hashFallback) {
+        return `${hashFallback.substring(0, 16)}${extension}`;
+    }
+    return `download-${Date.now()}${extension}`;
+}
+function getLastPathSegment(url) {
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    const lastSegment = segments[segments.length - 1];
+    return lastSegment ?? null;
+}
+function stripCommonPageExtension(segment) {
+    return segment.replace(/\.(html?|php|aspx?|jsp)$/i, '');
+}
+function normalizeUrlFilenameSegment(segment) {
+    const cleaned = stripCommonPageExtension(segment);
+    if (!cleaned)
+        return null;
+    if (cleaned === 'index')
+        return null;
+    return cleaned;
+}
+function extractFilenameFromUrl(url) {
+    try {
+        const urlObj = new URL(url);
+        const lastSegment = getLastPathSegment(urlObj);
+        if (!lastSegment)
+            return null;
+        return normalizeUrlFilenameSegment(lastSegment);
+    }
+    catch {
+        return null;
+    }
+}
+const MAX_FILENAME_LENGTH = 200;
+const UNSAFE_CHARS_REGEX = /[<>:"/\\|?*]|\p{C}/gu;
+const WHITESPACE_REGEX = /\s+/g;
+function trimHyphens(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === '-') {
+        start += 1;
+    }
+    while (end > start && value[end - 1] === '-') {
+        end -= 1;
+    }
+    return value.slice(start, end);
+}
+function slugifyTitle(title) {
+    const slug = title
+        .toLowerCase()
+        .trim()
+        .replace(UNSAFE_CHARS_REGEX, '')
+        .replace(WHITESPACE_REGEX, '-')
+        .replace(/-+/g, '-');
+    const trimmed = trimHyphens(slug);
+    return trimmed || null;
+}
+function sanitizeFilename(name, extension) {
+    let sanitized = name
+        .replace(UNSAFE_CHARS_REGEX, '')
+        .replace(WHITESPACE_REGEX, '-')
+        .trim();
+    // Truncate if too long
+    const maxBase = MAX_FILENAME_LENGTH - extension.length;
+    if (sanitized.length > maxBase) {
+        sanitized = sanitized.substring(0, maxBase);
+    }
+    return `${sanitized}${extension}`;
+}
+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 = 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);
+}

package/dist/config/env-parsers.d.ts

@@ -1,5 +1,6 @@
 import type { LogLevel } from './types/runtime.js';
 export declare function parseInteger(envValue: string | undefined, defaultValue: number, min?: number, max?: number): number;
+export declare function parseOptionalInteger(envValue: string | undefined, min?: number, max?: number): number | undefined;
 export declare function parseBoolean(envValue: string | undefined, defaultValue: boolean): boolean;
 export declare function parseList(envValue: string | undefined): string[];
 export declare function parseUrlEnv(value: string | undefined, name: string): URL | undefined;

package/dist/config/env-parsers.js

@@ -45,6 +45,18 @@ export function parseInteger(envValue, defaultValue, min, max) {
         return defaultValue;
     return parsed;
 }
+export function parseOptionalInteger(envValue, min, max) {
+    if (!envValue)
+        return undefined;
+    const parsed = parseInt(envValue, 10);
+    if (Number.isNaN(parsed))
+        return undefined;
+    if (isBelowMin(parsed, min))
+        return undefined;
+    if (isAboveMax(parsed, max))
+        return undefined;
+    return parsed;
+}
 export function parseBoolean(envValue, defaultValue) {
     if (!envValue)
         return defaultValue;

package/dist/config/index.d.ts

@@ -10,6 +10,13 @@ export declare const config: {
         sessionTtlMs: number;
         sessionInitTimeoutMs: number;
         maxSessions: number;
+        http: {
+            headersTimeoutMs: number | undefined;
+            requestTimeoutMs: number | undefined;
+            keepAliveTimeoutMs: number | undefined;
+            shutdownCloseIdleConnections: boolean;
+            shutdownCloseAllConnections: boolean;
+        };
     };
     fetcher: {
         timeout: number;