@j0hanz/superfetch 1.2.4 → 2.0.0

package/dist/http/server.js

@@ -1,31 +1,16 @@
-import { styleText } from 'node:util';
 import { config, enableHttpMode } from '../config/index.js';
-import { destroyAgents } from '../services/fetcher.js';
-import { logError, logInfo, logWarn } from '../services/logger.js';
-import { destroyTransformWorkers } from '../services/transform-worker-pool.js';
+import { logError, logInfo } from '../services/logger.js';
 import { errorHandler } from '../middleware/error-handler.js';
-import { getErrorMessage } from '../utils/error-utils.js';
-import { createAuthMiddleware } from './auth.js';
+import { createAuthMetadataRouter, createAuthMiddleware } from './auth.js';
 import { createCorsMiddleware } from './cors.js';
 import { registerDownloadRoutes } from './download-routes.js';
 import { registerMcpRoutes } from './mcp-routes.js';
 import { createRateLimitMiddleware } from './rate-limit.js';
-import { attachBaseMiddleware, buildCorsOptions } from './server-middleware.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';
-function isLoopbackHost(host) {
-    return host === '127.0.0.1' || host === '::1' || host === 'localhost';
-}
-function assertHttpConfiguration() {
-    if (!config.security.allowRemote && !isLoopbackHost(config.server.host)) {
-        logError('Refusing to bind to non-loopback host without ALLOW_REMOTE=true', { host: config.server.host });
-        process.exit(1);
-    }
-    if (!config.security.apiKey) {
-        logError('API_KEY is required for HTTP mode; refusing to start');
-        process.exit(1);
-    }
-}
 function startListening(app) {
     return app
         .listen(config.server.port, config.server.host, () => {
@@ -33,63 +18,69 @@ function startListening(app) {
             host: config.server.host,
             port: config.server.port,
         });
-        process.stdout.write(`${styleText('green', '✓')} superFetch MCP server running at ${styleText('cyan', `http://${config.server.host}:${config.server.port}`)}\n`);
-        process.stdout.write(`  Health check: ${styleText('dim', `http://${config.server.host}:${config.server.port}/health`)}\n`);
-        process.stdout.write(`  MCP endpoint: ${styleText('dim', `http://${config.server.host}:${config.server.port}/mcp`)}\n`);
-        process.stdout.write(`\n${styleText('dim', 'Run with --stdio flag for direct stdio integration')}\n`);
+        const baseUrl = `http://${config.server.host}:${config.server.port}`;
+        logInfo(`superFetch MCP server running at ${baseUrl} (health: ${baseUrl}/health, mcp: ${baseUrl}/mcp)`);
+        logInfo('Run with --stdio flag for direct stdio integration');
     })
         .on('error', (err) => {
         logError('Failed to start server', err);
         process.exit(1);
     });
 }
-function createShutdownHandler(server, sessionStore, sessionCleanupController, stopRateLimitCleanup) {
-    return async (signal) => {
-        process.stdout.write(`\n${styleText('yellow', signal)} received, shutting down gracefully...\n`);
-        stopRateLimitCleanup();
-        sessionCleanupController.abort();
-        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),
-            });
-        })));
-        destroyAgents();
-        destroyTransformWorkers();
-        server.close(() => {
-            logInfo('HTTP server closed');
-            process.exit(0);
-        });
-        setTimeout(() => {
-            logError('Forced shutdown after timeout');
-            process.exit(1);
-        }, 10000).unref();
+function buildMiddleware() {
+    const { middleware: rateLimitMiddleware, stop: stopRateLimitCleanup } = createRateLimitMiddleware(config.rateLimit);
+    const authMiddleware = createAuthMiddleware();
+    // No CORS - MCP clients don't run in browsers
+    const corsMiddleware = createCorsMiddleware();
+    return {
+        rateLimitMiddleware,
+        stopRateLimitCleanup,
+        authMiddleware,
+        corsMiddleware,
     };
 }
-function registerSignalHandlers(shutdown) {
-    process.on('SIGINT', () => {
-        void shutdown('SIGINT');
-    });
-    process.on('SIGTERM', () => {
-        void shutdown('SIGTERM');
-    });
-}
-export async function startHttpServer() {
-    enableHttpMode();
-    const { app, jsonParser } = await createExpressApp();
-    const corsOptions = buildCorsOptions();
-    const { middleware: rateLimitMiddleware, stop: stopRateLimitCleanup } = createRateLimitMiddleware(config.rateLimit);
-    const authMiddleware = createAuthMiddleware(config.security.apiKey ?? '');
-    attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, authMiddleware, createCorsMiddleware(corsOptions));
-    assertHttpConfiguration();
+function createSessionInfrastructure() {
     const sessionStore = createSessionStore(config.server.sessionTtlMs);
     const sessionCleanupController = startSessionCleanupLoop(sessionStore, config.server.sessionTtlMs);
+    return { sessionStore, sessionCleanupController };
+}
+function registerHttpRoutes(app, sessionStore, authMiddleware) {
+    app.use('/mcp', authMiddleware);
+    app.use('/mcp/downloads', authMiddleware);
     registerMcpRoutes(app, {
         sessionStore,
         maxSessions: config.server.maxSessions,
     });
     registerDownloadRoutes(app);
     app.use(errorHandler);
+}
+function attachAuthMetadata(app) {
+    const authMetadataRouter = createAuthMetadataRouter();
+    if (authMetadataRouter) {
+        app.use(authMetadataRouter);
+    }
+}
+async function buildServerContext() {
+    const { app, authMiddleware, stopRateLimitCleanup } = await createAppWithMiddleware();
+    const { sessionStore, sessionCleanupController } = attachSessionRoutes(app, authMiddleware);
+    return { app, sessionStore, sessionCleanupController, stopRateLimitCleanup };
+}
+async function createAppWithMiddleware() {
+    const { app, jsonParser } = await createExpressApp();
+    const { rateLimitMiddleware, stopRateLimitCleanup, authMiddleware, corsMiddleware, } = buildMiddleware();
+    attachBaseMiddleware(app, jsonParser, rateLimitMiddleware, corsMiddleware);
+    attachAuthMetadata(app);
+    assertHttpConfiguration();
+    return { app, authMiddleware, stopRateLimitCleanup };
+}
+function attachSessionRoutes(app, authMiddleware) {
+    const { sessionStore, sessionCleanupController } = createSessionInfrastructure();
+    registerHttpRoutes(app, sessionStore, authMiddleware);
+    return { sessionStore, sessionCleanupController };
+}
+export async function startHttpServer() {
+    enableHttpMode();
+    const { app, sessionStore, sessionCleanupController, stopRateLimitCleanup } = await buildServerContext();
     const server = startListening(app);
     const shutdown = createShutdownHandler(server, sessionStore, sessionCleanupController, stopRateLimitCleanup);
     registerSignalHandlers(shutdown);
@@ -98,9 +89,6 @@ export async function startHttpServer() {
 async function createExpressApp() {
     const { default: express } = await import('express');
     const app = express();
-    if (config.server.trustProxy) {
-        app.set('trust proxy', true);
-    }
     const jsonParser = express.json({ limit: '1mb' });
     return { app, jsonParser };
 }

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-routes.js';
+import { evictExpiredSessions } from './mcp-session.js';
 export function startSessionCleanupLoop(store, sessionTtlMs) {
     const controller = new AbortController();
     void runSessionCleanupLoop(store, sessionTtlMs, controller.signal).catch(handleSessionCleanupError);

package/dist/middleware/error-handler.js

@@ -31,9 +31,7 @@ function buildErrorResponse(err) {
             ...(details && { details }),
         },
     };
-    if (process.env.NODE_ENV === 'development' && err.stack) {
-        response.error.stack = err.stack;
-    }
+    // Never expose stack traces in production
     return response;
 }
 function resolveRetryAfter(err) {

package/dist/resources/cached-content.js

@@ -1,45 +1,33 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import * as cache from '../services/cache.js';
+import { parseCacheKey, toResourceUri } from '../services/cache-keys.js';
 import { logWarn } from '../services/logger.js';
+import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
 import { getErrorMessage } from '../utils/error-utils.js';
-const VALID_NAMESPACES = new Set(['url', 'markdown', 'links']);
+import { isRecord } from '../utils/guards.js';
+const CACHE_NAMESPACE = 'markdown';
 const HASH_PATTERN = /^[a-f0-9.]+$/i;
 function buildResourceEntry(namespace, urlHash) {
     return {
         name: `${namespace}:${urlHash}`,
         uri: `superfetch://cache/${namespace}/${urlHash}`,
         description: `Cached content entry for ${namespace}`,
-        mimeType: resolveCacheMimeType(namespace),
+        mimeType: 'text/markdown',
     };
 }
 function listCachedResources() {
     const resources = cache
         .keys()
         .map((key) => {
-        const parts = cache.parseCacheKey(key);
-        return parts ? buildResourceEntry(parts.namespace, parts.urlHash) : null;
+        const parts = parseCacheKey(key);
+        if (parts?.namespace !== CACHE_NAMESPACE)
+            return null;
+        return buildResourceEntry(parts.namespace, parts.urlHash);
     })
         .filter((entry) => entry !== null);
     return { resources };
 }
-function buildCacheListPayload() {
-    const cacheKeys = cache.keys();
-    return {
-        totalEntries: cacheKeys.length,
-        entries: cacheKeys.map((key) => {
-            const parts = cache.parseCacheKey(key);
-            const namespace = parts?.namespace ?? 'unknown';
-            const urlHash = parts?.urlHash ?? 'unknown';
-            return {
-                namespace,
-                urlHash,
-                resourceUri: `superfetch://cache/${namespace}/${urlHash}`,
-            };
-        }),
-        timestamp: new Date().toISOString(),
-    };
-}
 function notifyResourceUpdate(server, uri) {
     if (!server.isConnected())
         return;
@@ -52,88 +40,54 @@ function notifyResourceUpdate(server, uri) {
 }
 export function registerCachedContentResource(server) {
     registerCacheContentResource(server);
-    registerCacheListResource(server);
     registerCacheUpdateSubscription(server);
 }
 function resolveCacheParams(params) {
-    const namespace = resolveStringParam(params.namespace);
-    const urlHash = resolveStringParam(params.urlHash);
-    if (!namespace || !urlHash) {
-        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
-    }
+    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 buildCachedContentResponse(uri, cacheKey, namespace) {
-    const cached = cache.get(cacheKey);
-    if (!cached) {
-        throw new McpError(ErrorCode.InvalidParams, `Content not found in cache for key: ${cacheKey}. Use superfetch://stats to see available cache entries.`);
-    }
-    if (namespace !== 'url' && namespace !== 'markdown') {
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: resolveCacheMimeType(namespace),
-                    text: cached.content,
-                },
-            ],
-        };
+function requireRecordParams(value) {
+    if (!isRecord(value)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
     }
-    const payload = parseCachedPayload(cached.content);
-    const resolvedContent = payload
-        ? resolvePayloadContent(payload, namespace)
-        : null;
-    if (!resolvedContent) {
-        throw new McpError(ErrorCode.InternalError, `Cached content is missing for namespace ${namespace}`);
+    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 {
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: resolveCacheMimeType(namespace),
-                text: resolvedContent,
-            },
-        ],
-    };
+    return resolved;
+}
+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: url, links, markdown. UrlHash: SHA-256 hash of the URL.',
+        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, namespace);
+        return buildCachedContentResponse(uri, cacheKey);
     });
 }
-function registerCacheListResource(server) {
-    server.registerResource('cached-urls', 'superfetch://cache/list', {
-        title: 'Cached URLs List',
-        description: 'List all URLs currently in cache with their namespaces',
-        mimeType: 'application/json',
-    }, (uri) => ({
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: 'application/json',
-                text: JSON.stringify(buildCacheListPayload(), null, 2),
-            },
-        ],
-    }));
-}
 function registerCacheUpdateSubscription(server) {
     const unsubscribe = cache.onCacheUpdate(({ cacheKey }) => {
-        const resourceUri = cache.toResourceUri(cacheKey);
+        const resourceUri = toResourceUri(cacheKey);
         if (!resourceUri)
             return;
         notifyResourceUpdate(server, resourceUri);
-        notifyResourceUpdate(server, 'superfetch://cache/list');
         if (server.isConnected()) {
             server.sendResourceListChanged();
         }
@@ -144,15 +98,8 @@ function registerCacheUpdateSubscription(server) {
         unsubscribe();
     };
 }
-function resolveCacheMimeType(namespace) {
-    if (namespace === 'markdown')
-        return 'text/markdown';
-    if (namespace === 'url')
-        return 'application/jsonl';
-    return 'application/json';
-}
 function isValidNamespace(namespace) {
-    return VALID_NAMESPACES.has(namespace);
+    return namespace === CACHE_NAMESPACE;
 }
 function isValidHash(hash) {
     return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
@@ -160,31 +107,26 @@ function isValidHash(hash) {
 function resolveStringParam(value) {
     return typeof value === 'string' ? value : null;
 }
-function parseCachedPayload(raw) {
-    try {
-        const parsed = JSON.parse(raw);
-        return isCachedPayload(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
+function requireCacheEntry(cacheKey) {
+    const cached = cache.get(cacheKey);
+    if (!cached) {
+        throw new McpError(-32002, `Content not found in cache for key: ${cacheKey}`);
     }
+    return cached;
 }
-function isCachedPayload(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const record = value;
-    return ((record.content === undefined || typeof record.content === 'string') &&
-        (record.markdown === undefined || typeof record.markdown === 'string'));
-}
-function resolvePayloadContent(payload, namespace) {
-    if (namespace === 'markdown') {
-        if (typeof payload.markdown === 'string') {
-            return payload.markdown;
-        }
-        if (typeof payload.content === 'string') {
-            return payload.content;
-        }
-        return null;
+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 typeof payload.content === 'string' ? payload.content : null;
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: resolvedContent,
+            },
+        ],
+    };
 }

package/dist/resources/index.js

@@ -1,86 +1,4 @@
-import { config } from '../config/index.js';
-import * as cache from '../services/cache.js';
 import { registerCachedContentResource } from './cached-content.js';
-function registerJsonResource(server, definition) {
-    server.registerResource(definition.name, definition.uri, {
-        title: definition.title,
-        description: definition.description,
-        mimeType: 'application/json',
-    }, (uri) => ({
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: 'application/json',
-                text: JSON.stringify(definition.buildPayload(), null, 2),
-            },
-        ],
-    }));
-}
-function buildHealthPayload() {
-    const memUsage = process.memoryUsage();
-    const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
-    const heapTotalMB = Math.round(memUsage.heapTotal / 1024 / 1024);
-    return {
-        status: 'healthy',
-        uptime: process.uptime(),
-        checks: {
-            cache: config.cache.enabled,
-            memory: {
-                heapUsed: heapUsedMB,
-                heapTotal: heapTotalMB,
-                percentage: Math.round((heapUsedMB / heapTotalMB) * 100),
-                healthy: heapUsedMB < 400,
-            },
-        },
-        timestamp: new Date().toISOString(),
-    };
-}
-function buildStatsPayload() {
-    return {
-        server: {
-            name: config.server.name,
-            version: config.server.version,
-            uptime: process.uptime(),
-            nodeVersion: process.version,
-            memoryUsage: process.memoryUsage(),
-        },
-        cache: {
-            enabled: config.cache.enabled,
-            ttl: config.cache.ttl,
-            maxKeys: config.cache.maxKeys,
-            totalKeys: cache.keys().length,
-        },
-        config: {
-            fetcher: {
-                timeout: config.fetcher.timeout,
-                maxRedirects: config.fetcher.maxRedirects,
-            },
-            extraction: {
-                extractMainContent: config.extraction.extractMainContent,
-                includeMetadata: config.extraction.includeMetadata,
-            },
-        },
-    };
-}
 export function registerResources(server) {
     registerCachedContentResource(server);
-    const resources = [
-        {
-            name: 'health',
-            uri: 'superfetch://health',
-            title: 'Server Health',
-            description: 'Real-time server health and dependency status',
-            buildPayload: buildHealthPayload,
-        },
-        {
-            name: 'stats',
-            uri: 'superfetch://stats',
-            title: 'Server Statistics',
-            description: 'Fetch statistics and cache performance metrics',
-            buildPayload: buildStatsPayload,
-        },
-    ];
-    for (const resource of resources) {
-        registerJsonResource(server, resource);
-    }
 }

package/dist/server.js

@@ -1,52 +1,66 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { config } from './config/index.js';
-import { destroyAgents } from './services/fetcher.js';
+import { destroyAgents } from './services/fetcher/agents.js';
 import { logError, logInfo } from './services/logger.js';
-import { destroyTransformWorkers } from './services/transform-worker-pool.js';
 import { registerTools } from './tools/index.js';
-import { registerResources } from './resources/index.js';
-export function createMcpServer() {
-    const server = new McpServer({
+import { registerCachedContentResource } from './resources/cached-content.js';
+function createServerInfo() {
+    return {
         name: config.server.name,
         version: config.server.version,
-    }, {
-        capabilities: {
-            tools: { listChanged: false },
-            resources: { listChanged: true, subscribe: true },
-            logging: {},
-        },
-        instructions: `superFetch MCP server v${config.server.version} - AI-optimized web content fetching with JSONL/Markdown output. Provides tools for fetching, parsing, and transforming web content into structured formats suitable for LLM consumption. Supports resource subscriptions for cache updates.`,
+    };
+}
+function createServerCapabilities() {
+    return {
+        tools: { listChanged: false },
+        resources: { listChanged: true, subscribe: true },
+        logging: {},
+    };
+}
+function createServerInstructions(serverVersion) {
+    return `superFetch MCP server |${serverVersion}| A high-performance web content fetching and processing server.`;
+}
+export function createMcpServer() {
+    const server = new McpServer(createServerInfo(), {
+        capabilities: createServerCapabilities(),
+        instructions: createServerInstructions(config.server.version),
     });
     registerTools(server);
-    registerResources(server);
+    registerCachedContentResource(server);
     return server;
 }
-export async function startStdioServer() {
-    const server = createMcpServer();
-    const transport = new StdioServerTransport();
+function attachServerErrorHandler(server) {
     server.server.onerror = (error) => {
         logError('[MCP Error]', error instanceof Error ? error : { error });
     };
-    const handleShutdown = (signal) => {
-        process.stderr.write(`\n${signal} received, shutting down superFetch MCP server...\n`);
-        destroyAgents();
-        destroyTransformWorkers();
-        server
-            .close()
-            .catch((err) => {
-            logError('Error during shutdown', err instanceof Error ? err : undefined);
-        })
-            .finally(() => {
-            process.exit(0);
-        });
+}
+function handleShutdownSignal(server, signal) {
+    process.stderr.write(`\n${signal} received, shutting down superFetch MCP server...\n`);
+    destroyAgents();
+    server
+        .close()
+        .catch((err) => {
+        logError('Error during shutdown', err instanceof Error ? err : undefined);
+    })
+        .finally(() => {
+        process.exit(0);
+    });
+}
+function createShutdownHandler(server) {
+    return (signal) => {
+        handleShutdownSignal(server, signal);
     };
+}
+function registerSignalHandlers(handler) {
     process.on('SIGINT', () => {
-        handleShutdown('SIGINT');
+        handler('SIGINT');
     });
     process.on('SIGTERM', () => {
-        handleShutdown('SIGTERM');
+        handler('SIGTERM');
     });
+}
+async function connectStdioServer(server, transport) {
     try {
         await server.connect(transport);
         logInfo('superFetch MCP server running on stdio');
@@ -56,3 +70,10 @@ export async function startStdioServer() {
         process.exit(1);
     }
 }
+export async function startStdioServer() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    attachServerErrorHandler(server);
+    registerSignalHandlers(createShutdownHandler(server));
+    await connectStdioServer(server, transport);
+}

package/dist/services/cache-keys.d.ts

@@ -0,0 +1,7 @@
+export interface CacheKeyParts {
+    namespace: string;
+    urlHash: string;
+}
+export declare function createCacheKey(namespace: string, url: string, vary?: Record<string, unknown> | string): string | null;
+export declare function parseCacheKey(cacheKey: string): CacheKeyParts | null;
+export declare function toResourceUri(cacheKey: string): string | null;

package/dist/services/cache-keys.js

@@ -0,0 +1,57 @@
+import { CACHE_HASH } from '../config/constants.js';
+import { sha256Hex } from '../utils/crypto.js';
+import { isRecord } from '../utils/guards.js';
+function stableStringify(value) {
+    if (!isRecord(value)) {
+        if (value === null || value === undefined) {
+            return '';
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    return `{${entries.join(',')}}`;
+}
+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;
+    const varyString = typeof vary === 'string' ? vary : stableStringify(vary);
+    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);
+    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}`;
+}