@j0hanz/superfetch 2.4.2 → 2.4.4

package/dist/cache.js

@@ -6,29 +6,12 @@ import { getErrorMessage } from './errors.js';
 import { stableStringify as stableJsonStringify } from './json.js';
 import { logDebug, logWarn } from './observability.js';
 import { isObject } from './type-guards.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;
-}
+/* -------------------------------------------------------------------------------------------------
+ * Cached payload codec
+ * ------------------------------------------------------------------------------------------------- */
 function hasOptionalStringProperty(value, key) {
     const prop = value[key];
-    if (prop === undefined)
-        return true;
-    return typeof prop === 'string';
+    return prop === undefined ? true : typeof prop === 'string';
 }
 function isCachedPayload(value) {
     if (!isObject(value))
@@ -41,6 +24,34 @@ function isCachedPayload(value) {
         return false;
     return true;
 }
+class CachedPayloadCodec {
+    parse(raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            return isCachedPayload(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    resolveContent(payload) {
+        if (typeof payload.markdown === 'string')
+            return payload.markdown;
+        if (typeof payload.content === 'string')
+            return payload.content;
+        return null;
+    }
+}
+const payloadCodec = new CachedPayloadCodec();
+export function parseCachedPayload(raw) {
+    return payloadCodec.parse(raw);
+}
+export function resolveCachedPayloadContent(payload) {
+    return payloadCodec.resolveContent(payload);
+}
+/* -------------------------------------------------------------------------------------------------
+ * Cache key codec (hashing + parsing + resource URI)
+ * ------------------------------------------------------------------------------------------------- */
 const CACHE_HASH = {
     URL_HASH_LENGTH: 32,
     VARY_HASH_LENGTH: 16,
@@ -64,50 +75,59 @@ function buildCacheKey(namespace, urlHash, varyHash) {
 function getVaryHash(vary) {
     if (!vary)
         return undefined;
-    let varyString;
-    if (typeof vary === 'string') {
-        varyString = vary;
-    }
-    else {
-        varyString = stableStringify(vary);
-    }
+    const varyString = typeof vary === 'string' ? vary : stableStringify(vary);
     if (varyString === null)
         return null;
     if (!varyString)
         return undefined;
     return createHashFragment(varyString, CACHE_HASH.VARY_HASH_LENGTH);
 }
+function buildCacheResourceUri(namespace, urlHash) {
+    return `superfetch://cache/${namespace}/${urlHash}`;
+}
+class CacheKeyCodec {
+    create(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);
+    }
+    parse(cacheKey) {
+        if (!cacheKey)
+            return null;
+        const [namespace, ...rest] = cacheKey.split(':');
+        const urlHash = rest.join(':');
+        if (!namespace || !urlHash)
+            return null;
+        return { namespace, urlHash };
+    }
+    toResourceUri(cacheKey) {
+        const parts = this.parse(cacheKey);
+        if (!parts)
+            return null;
+        return buildCacheResourceUri(parts.namespace, parts.urlHash);
+    }
+}
+const cacheKeyCodec = new CacheKeyCodec();
 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);
+    return cacheKeyCodec.create(namespace, url, vary);
 }
 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 };
-}
-function buildCacheResourceUri(namespace, urlHash) {
-    return `superfetch://cache/${namespace}/${urlHash}`;
+    return cacheKeyCodec.parse(cacheKey);
 }
 export function toResourceUri(cacheKey) {
-    const parts = parseCacheKey(cacheKey);
-    if (!parts)
-        return null;
-    return buildCacheResourceUri(parts.namespace, parts.urlHash);
-}
-// Cache behavior contract (native implementation):
-// - Max entries: config.cache.maxKeys
-// - TTL in ms: config.cache.ttl * 1000
-// - Access does NOT extend TTL
+    return cacheKeyCodec.toResourceUri(cacheKey);
+}
+/* -------------------------------------------------------------------------------------------------
+ * In-memory LRU cache (native)
+ * Contract:
+ * - Max entries: config.cache.maxKeys
+ * - TTL in ms: config.cache.ttl * 1000
+ * - Access does NOT extend TTL
+ * ------------------------------------------------------------------------------------------------- */
 class NativeLruCache {
     max;
     ttlMs;
@@ -135,10 +155,7 @@ class NativeLruCache {
             return;
         const now = Date.now();
         this.entries.delete(key);
-        this.entries.set(key, {
-            value,
-            expiresAtMs: now + this.ttlMs,
-        });
+        this.entries.set(key, { value, expiresAtMs: now + this.ttlMs });
         this.maybePurge(now);
         while (this.entries.size > this.max) {
             const oldestKey = this.entries.keys().next().value;
@@ -159,131 +176,141 @@ class NativeLruCache {
     }
     purgeExpired(now) {
         for (const [key, entry] of this.entries) {
-            if (this.isExpired(entry, now)) {
+            if (this.isExpired(entry, now))
                 this.entries.delete(key);
-            }
         }
     }
     isExpired(entry, now) {
         return entry.expiresAtMs <= now;
     }
 }
-const contentCache = new NativeLruCache({
-    max: config.cache.maxKeys,
-    ttlMs: config.cache.ttl * 1000,
-});
-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);
+class InMemoryCacheStore {
+    cache = new NativeLruCache({
+        max: config.cache.maxKeys,
+        ttlMs: config.cache.ttl * 1000,
+    });
+    listeners = new Set();
+    isEnabled() {
+        return config.cache.enabled;
     }
-}
-export function get(cacheKey) {
-    if (!isCacheReadable(cacheKey))
-        return undefined;
-    return runCacheOperation(cacheKey, 'Cache get error', () => contentCache.get(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();
+    keys() {
+        return [...this.cache.keys()];
     }
-    catch (error) {
-        logCacheError(message, cacheKey, error);
-        return undefined;
+    onUpdate(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
     }
-}
-export function set(cacheKey, content, metadata) {
-    if (!isCacheWritable(cacheKey, content))
-        return;
-    runCacheOperation(cacheKey, 'Cache set error', () => {
-        const now = Date.now();
-        const expiresAtMs = now + config.cache.ttl * 1000;
-        const entry = buildCacheEntry({
+    get(cacheKey) {
+        if (!this.isReadable(cacheKey))
+            return undefined;
+        return this.run(cacheKey, 'Cache get error', () => this.cache.get(cacheKey));
+    }
+    set(cacheKey, content, metadata) {
+        if (!this.isWritable(cacheKey, content))
+            return;
+        this.run(cacheKey, 'Cache set error', () => {
+            const now = Date.now();
+            const expiresAtMs = now + config.cache.ttl * 1000; // preserve existing behavior
+            const entry = this.buildEntry(content, metadata, now, expiresAtMs);
+            this.cache.set(cacheKey, entry);
+            this.notify(cacheKey);
+        });
+    }
+    isReadable(cacheKey) {
+        return config.cache.enabled && Boolean(cacheKey);
+    }
+    isWritable(cacheKey, content) {
+        return config.cache.enabled && Boolean(cacheKey) && Boolean(content);
+    }
+    run(cacheKey, message, operation) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            this.logError(message, cacheKey, error);
+            return undefined;
+        }
+    }
+    buildEntry(content, metadata, fetchedAtMs, expiresAtMs) {
+        return {
+            url: metadata.url,
             content,
-            metadata,
-            fetchedAtMs: now,
-            expiresAtMs,
+            fetchedAt: new Date(fetchedAtMs).toISOString(),
+            expiresAt: new Date(expiresAtMs).toISOString(),
+            ...(metadata.title === undefined ? {} : { title: metadata.title }),
+        };
+    }
+    notify(cacheKey) {
+        if (this.listeners.size === 0)
+            return;
+        const parts = cacheKeyCodec.parse(cacheKey);
+        if (!parts)
+            return;
+        const event = { cacheKey, ...parts };
+        for (const listener of this.listeners)
+            listener(event);
+    }
+    logError(message, cacheKey, error) {
+        logWarn(message, {
+            key: cacheKey.length > 100 ? cacheKey.slice(0, 100) : cacheKey,
+            error: getErrorMessage(error),
         });
-        persistCacheEntry(cacheKey, entry);
-    });
+    }
 }
-export function keys() {
-    return [...contentCache.keys()];
+const store = new InMemoryCacheStore();
+export function onCacheUpdate(listener) {
+    return store.onUpdate(listener);
 }
-export function isEnabled() {
-    return config.cache.enabled;
+export function get(cacheKey) {
+    return store.get(cacheKey);
 }
-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 }),
-    };
+export function set(cacheKey, content, metadata) {
+    store.set(cacheKey, content, metadata);
 }
-function persistCacheEntry(cacheKey, entry) {
-    contentCache.set(cacheKey, entry);
-    notifyCacheUpdate(cacheKey);
+export function keys() {
+    return store.keys();
 }
-function logCacheError(message, cacheKey, error) {
-    logWarn(message, {
-        key: cacheKey.length > 100 ? cacheKey.slice(0, 100) : cacheKey,
-        error: getErrorMessage(error),
-    });
+export function isEnabled() {
+    return store.isEnabled();
 }
+/* -------------------------------------------------------------------------------------------------
+ * MCP cached content resource (superfetch://cache/markdown/{urlHash})
+ * ------------------------------------------------------------------------------------------------- */
 const CACHE_NAMESPACE = 'markdown';
 const HASH_PATTERN = /^[a-f0-9.]+$/i;
 const INVALID_CACHE_PARAMS_MESSAGE = 'Invalid cache resource parameters';
 function throwInvalidCacheParams() {
     throw new McpError(ErrorCode.InvalidParams, INVALID_CACHE_PARAMS_MESSAGE);
 }
-function resolveCacheParams(params) {
-    const parsed = requireRecordParams(params);
-    const namespace = requireParamString(parsed, 'namespace');
-    const urlHash = requireParamString(parsed, 'urlHash');
-    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
-        throwInvalidCacheParams();
-    }
-    return { namespace, urlHash };
+function resolveStringParam(value) {
+    return typeof value === 'string' ? value : null;
+}
+function isValidNamespace(namespace) {
+    return namespace === CACHE_NAMESPACE;
+}
+function isValidHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
 }
 function requireRecordParams(value) {
-    if (!isObject(value)) {
+    if (!isObject(value))
         throwInvalidCacheParams();
-    }
     return value;
 }
 function requireParamString(params, key) {
-    const raw = params[key];
-    const resolved = resolveStringParam(raw);
+    const resolved = resolveStringParam(params[key]);
     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 resolveCacheParams(params) {
+    const parsed = requireRecordParams(params);
+    const namespace = requireParamString(parsed, 'namespace');
+    const urlHash = requireParamString(parsed, 'urlHash');
+    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
+        throwInvalidCacheParams();
+    }
+    return { namespace, urlHash };
 }
 function isValidCacheResourceUri(uri) {
     if (!uri)
@@ -307,9 +334,6 @@ function isValidCacheResourceUri(uri) {
         return false;
     return isValidNamespace(namespace) && isValidHash(urlHash);
 }
-function resolveStringParam(value) {
-    return typeof value === 'string' ? value : null;
-}
 function buildResourceEntry(namespace, urlHash) {
     return {
         name: `${namespace}:${urlHash}`,
@@ -321,7 +345,7 @@ function buildResourceEntry(namespace, urlHash) {
 function listCachedResources() {
     const resources = keys()
         .map((key) => {
-        const parts = parseCacheKey(key);
+        const parts = cacheKeyCodec.parse(key);
         if (parts?.namespace !== CACHE_NAMESPACE)
             return null;
         return buildResourceEntry(parts.namespace, parts.urlHash);
@@ -347,18 +371,13 @@ function attachInitializedGate(server) {
 }
 function getClientResourceCapabilities(server) {
     const caps = server.server.getClientCapabilities();
-    if (!caps || !isObject(caps)) {
+    if (!caps || !isObject(caps))
         return { listChanged: false, subscribe: false };
-    }
     const { resources } = caps;
-    if (!isObject(resources)) {
+    if (!isObject(resources))
         return { listChanged: false, subscribe: false };
-    }
     const { listChanged, subscribe } = resources;
-    return {
-        listChanged: listChanged === true,
-        subscribe: subscribe === true,
-    };
+    return { listChanged: listChanged === true, subscribe: subscribe === true };
 }
 function registerResourceSubscriptionHandlers(server) {
     const subscriptions = new Set();
@@ -395,34 +414,37 @@ function notifyResourceUpdate(server, uri, subscriptions) {
         });
     });
 }
-export function registerCachedContentResource(server, serverIcon) {
-    const isInitialized = attachInitializedGate(server);
-    const subscriptions = registerResourceSubscriptionHandlers(server);
-    registerCacheContentResource(server, serverIcon);
-    registerCacheUpdateSubscription(server, subscriptions, isInitialized);
+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 = payloadCodec.parse(content);
+    const resolvedContent = payload ? payloadCodec.resolveContent(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 buildCachedContentResponse(uri, cacheKey) {
     const cached = requireCacheEntry(cacheKey);
     return buildMarkdownContentResponse(uri, cached.content);
 }
-function registerCacheContentResource(server, serverIcon) {
+function registerCacheContentResource(server, serverIcons) {
     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/markdown',
-        ...(serverIcon
-            ? {
-                icons: [
-                    {
-                        src: serverIcon,
-                        mimeType: 'image/svg+xml',
-                        sizes: ['any'],
-                    },
-                ],
-            }
-            : {}),
+        ...(serverIcons ? { icons: serverIcons } : {}),
     }, (uri, params) => {
         const { namespace, urlHash } = resolveCacheParams(params);
         const cacheKey = `${namespace}:${urlHash}`;
@@ -435,10 +457,9 @@ function registerCacheUpdateSubscription(server, subscriptions, isInitialized) {
             return;
         const { listChanged, subscribe } = getClientResourceCapabilities(server);
         if (subscribe) {
-            const resourceUri = toResourceUri(cacheKey);
-            if (resourceUri) {
+            const resourceUri = cacheKeyCodec.toResourceUri(cacheKey);
+            if (resourceUri)
                 notifyResourceUpdate(server, resourceUri, subscriptions);
-            }
         }
         if (listChanged) {
             server.sendResourceListChanged();
@@ -446,76 +467,26 @@ function registerCacheUpdateSubscription(server, subscriptions, isInitialized) {
     });
     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 parseDownloadParams(namespace, hash) {
-    const resolvedNamespace = resolveStringParam(namespace);
-    const resolvedHash = resolveStringParam(hash);
-    if (!resolvedNamespace || !resolvedHash)
-        return null;
-    if (!isValidNamespace(resolvedNamespace))
-        return null;
-    if (!isValidHash(resolvedHash))
-        return null;
-    return { namespace: resolvedNamespace, hash: resolvedHash };
-}
-function buildCacheKeyFromParams(params) {
-    return `${params.namespace}:${params.hash}`;
-}
-function sendJsonError(res, status, error, code) {
-    res.writeHead(status, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error, code }));
-}
-function respondBadRequest(res, message) {
-    sendJsonError(res, 400, message, 'BAD_REQUEST');
-}
-function respondNotFound(res) {
-    sendJsonError(res, 404, 'Content not found or expired', 'NOT_FOUND');
-}
-function respondServiceUnavailable(res) {
-    sendJsonError(res, 503, 'Download service is disabled', '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}`;
+export function registerCachedContentResource(server, serverIcons) {
+    const isInitialized = attachInitializedGate(server);
+    const subscriptions = registerResourceSubscriptionHandlers(server);
+    registerCacheContentResource(server, serverIcons);
+    registerCacheUpdateSubscription(server, subscriptions, isInitialized);
 }
-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;
+/* -------------------------------------------------------------------------------------------------
+ * Filename generation
+ * ------------------------------------------------------------------------------------------------- */
+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 stripCommonPageExtension(segment) {
     return segment.replace(/\.(html?|php|aspx?|jsp)$/i, '');
@@ -528,6 +499,12 @@ function normalizeUrlFilenameSegment(segment) {
         return null;
     return cleaned;
 }
+function getLastPathSegment(url) {
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    return segments[segments.length - 1] ?? null;
+}
 function extractFilenameFromUrl(url) {
     try {
         const urlObj = new URL(url);
@@ -540,20 +517,6 @@ function extractFilenameFromUrl(url) {
         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()
@@ -569,27 +532,52 @@ function sanitizeFilename(name, extension) {
         .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)
+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 parseDownloadParams(namespace, hash) {
+    const resolvedNamespace = resolveStringParam(namespace);
+    const resolvedHash = resolveStringParam(hash);
+    if (!resolvedNamespace || !resolvedHash)
         return null;
-    const content = resolveCachedPayloadContent(payload);
-    if (!content)
+    if (!isValidNamespace(resolvedNamespace))
         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,
-    };
+    if (!isValidHash(resolvedHash))
+        return null;
+    return { namespace: resolvedNamespace, hash: resolvedHash };
+}
+function buildCacheKeyFromParams(params) {
+    return `${params.namespace}:${params.hash}`;
+}
+function sendJsonError(res, status, error, code) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error, code }));
+}
+function respondBadRequest(res, message) {
+    sendJsonError(res, 400, message, 'BAD_REQUEST');
+}
+function respondNotFound(res) {
+    sendJsonError(res, 404, 'Content not found or expired', 'NOT_FOUND');
+}
+function respondServiceUnavailable(res) {
+    sendJsonError(res, 503, 'Download service is disabled', 'SERVICE_UNAVAILABLE');
 }
 function buildContentDisposition(fileName) {
     const encodedName = encodeURIComponent(fileName).replace(/'/g, '%27');
@@ -603,6 +591,21 @@ function sendDownloadPayload(res, payload) {
     res.setHeader('X-Content-Type-Options', 'nosniff');
     res.end(payload.content);
 }
+function resolveDownloadPayload(params, cacheEntry) {
+    const payload = payloadCodec.parse(cacheEntry.content);
+    if (!payload)
+        return null;
+    const content = payloadCodec.resolveContent(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,
+    };
+}
 export function handleDownload(res, namespace, hash) {
     if (!config.cache.enabled) {
         respondServiceUnavailable(res);