@j0hanz/superfetch 1.2.1 → 1.2.3

package/README.md

@@ -291,13 +291,14 @@ Sessions are managed via the `mcp-session-id` header (see [HTTP Mode Details](#h
 
 Both tools return:
 
-- `structuredContent` for machine-readable fields (includes `contentSize`, `cached`, and optional `resourceUri`/`resourceMimeType`/`truncated`)
+- `structuredContent` for machine-readable fields (includes `contentSize`, `cached`, and optional `resourceUri`/`resourceMimeType`/`truncated`; Markdown responses may also include `file`)
 - `content` blocks that include:
   - a `text` block containing JSON of `structuredContent`
-  - in stdio mode, a `resource` block with a `file:///...` URI containing the full content
-  - in HTTP mode, a `resource` block when inline content is available; large payloads include a `resource_link` block when cache is enabled
+  - in stdio mode, a `resource` block with a `file:///...` URI embedding the full content
+  - in HTTP mode, a `resource` block when inline content is available
+  - when content exceeds `MAX_INLINE_CONTENT_CHARS` and cache is enabled, a `resource_link` block points to `superfetch://cache/...` and `structuredContent.resourceUri` is set
 
-If content exceeds `MAX_INLINE_CONTENT_CHARS` and cache is disabled, the server truncates output and appends `...[truncated]`.
+If content exceeds `MAX_INLINE_CONTENT_CHARS` and cache is disabled, the server truncates output, appends `...[truncated]`, and sets `truncated: true`.
 
 ---
 
@@ -305,16 +306,19 @@ If content exceeds `MAX_INLINE_CONTENT_CHARS` and cache is disabled, the server
 
 Fetches a webpage and converts it to AI-readable JSONL format with semantic content blocks. You can also request Markdown with `format: "markdown"`.
 
-| Parameter            | Type                  | Default   | Description                                   |
-| -------------------- | --------------------- | --------- | --------------------------------------------- |
-| `url`                | string                | required  | URL to fetch                                  |
-| `format`             | "jsonl" \| "markdown" | `"jsonl"` | Output format                                 |
-| `extractMainContent` | boolean               | `true`    | Use Readability to extract main content       |
-| `includeMetadata`    | boolean               | `true`    | Include page metadata                         |
-| `maxContentLength`   | number                | -         | Maximum content length in characters          |
-| `customHeaders`      | object                | -         | Custom HTTP headers (sanitized)               |
-| `timeout`            | number                | `30000`   | Request timeout in milliseconds (1000-120000) |
-| `retries`            | number                | `3`       | Number of retry attempts (1-10)               |
+| Parameter              | Type                  | Default                            | Description                                            |
+| ---------------------- | --------------------- | ---------------------------------- | ------------------------------------------------------ |
+| `url`                  | string                | required                           | URL to fetch                                           |
+| `format`               | "jsonl" \| "markdown" | `"jsonl"`                          | Output format                                          |
+| `includeContentBlocks` | boolean               | `true` (jsonl), `false` (markdown) | Include content block counts when `format: "markdown"` |
+| `extractMainContent`   | boolean               | `true`                             | Use Readability to extract main content                |
+| `includeMetadata`      | boolean               | `true`                             | Include page metadata                                  |
+| `maxContentLength`     | number                | -                                  | Maximum content length in characters (max 5,242,880)   |
+| `customHeaders`        | object                | -                                  | Custom HTTP headers (sanitized)                        |
+| `timeout`              | number                | `30000`                            | Request timeout in milliseconds (1000-120000)          |
+| `retries`              | number                | `3`                                | Number of retry attempts (1-10)                        |
+
+When `format: "markdown"` and `includeContentBlocks` is `false`, `contentBlocks` will be `0`.
 
 **Example `structuredContent`:**
 
@@ -337,15 +341,15 @@ Fetches a webpage and converts it to AI-readable JSONL format with semantic cont
 
 Fetches a webpage and converts it to clean Markdown with optional frontmatter.
 
-| Parameter            | Type    | Default  | Description                                   |
-| -------------------- | ------- | -------- | --------------------------------------------- |
-| `url`                | string  | required | URL to fetch                                  |
-| `extractMainContent` | boolean | `true`   | Extract main content only                     |
-| `includeMetadata`    | boolean | `true`   | Include YAML frontmatter                      |
-| `maxContentLength`   | number  | -        | Maximum content length in characters          |
-| `customHeaders`      | object  | -        | Custom HTTP headers (sanitized)               |
-| `timeout`            | number  | `30000`  | Request timeout in milliseconds (1000-120000) |
-| `retries`            | number  | `3`      | Number of retry attempts (1-10)               |
+| Parameter            | Type    | Default  | Description                                          |
+| -------------------- | ------- | -------- | ---------------------------------------------------- |
+| `url`                | string  | required | URL to fetch                                         |
+| `extractMainContent` | boolean | `true`   | Extract main content only                            |
+| `includeMetadata`    | boolean | `true`   | Include YAML frontmatter                             |
+| `maxContentLength`   | number  | -        | Maximum content length in characters (max 5,242,880) |
+| `customHeaders`      | object  | -        | Custom HTTP headers (sanitized)                      |
+| `timeout`            | number  | `30000`  | Request timeout in milliseconds (1000-120000)        |
+| `retries`            | number  | `3`      | Number of retry attempts (1-10)                      |
 
 **Example `structuredContent`:**
 
@@ -373,9 +377,9 @@ Fetches a webpage and converts it to clean Markdown with optional frontmatter.
 ### Large Content Handling
 
 - Inline limit is configurable via `MAX_INLINE_CONTENT_CHARS` (see `CONFIGURATION.md`).
-- If content exceeds the limit and cache is enabled, responses include `resourceUri` and a `resource_link` block.
-- If cache is disabled, content is truncated with `...[truncated]`.
-- Use `maxContentLength` per request to enforce a lower limit.
+- If content exceeds the limit and cache is enabled, responses include `resourceUri`/`resourceMimeType` and a `resource_link` block.
+- If cache is disabled, content is truncated with `...[truncated]` and `truncated: true`.
+- Use `maxContentLength` per request to enforce a lower limit (hard cap: 5,242,880 characters).
 - Upstream fetch size is capped at 10 MB of HTML; larger responses fail.
 
 ---
@@ -446,8 +450,12 @@ HTTP mode uses the MCP Streamable HTTP transport. The workflow is:
 2. The server returns `mcp-session-id` in the response headers.
 3. Use that header for subsequent `POST /mcp`, `GET /mcp`, and `DELETE /mcp` requests.
 
+`GET /mcp` and `DELETE /mcp` require `mcp-session-id`. `POST /mcp` without an `initialize` request will return 400.
+
 If `MAX_SESSIONS` is reached, the server evicts the oldest session when possible, otherwise returns a 503.
 
+Host header validation is always enforced in HTTP mode. When binding to `0.0.0.0` or `::`, set `ALLOWED_HOSTS` to the hostnames clients will send. If an `Origin` header is present, it must be allowed by `ALLOWED_ORIGINS` or `CORS_ALLOW_ALL`.
+
 ---
 
 ## Content Block Types
@@ -473,17 +481,22 @@ JSONL output includes semantic content blocks:
 
 Blocked destinations include:
 
-- Localhost and loopback addresses
-- Private IP ranges (`10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`)
-- Cloud metadata endpoints (AWS, GCP, Azure)
-- IPv6 link-local and unique local addresses
+- Loopback and unspecified addresses (`127.0.0.0/8`, `::1`, `0.0.0.0`, `::`)
+- Private/ULA ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`)
+- Link-local and shared address space (`169.254.0.0/16`, `100.64.0.0/10`, `fe80::/10`)
+- Multicast/reserved ranges (`224.0.0.0/4`, `240.0.0.0/4`, `ff00::/8`)
+- IPv6 transition ranges (`64:ff9b::/96`, `64:ff9b:1::/48`, `2001::/32`, `2002::/16`)
+- Cloud metadata endpoints (AWS/GCP/Azure/Alibaba) like `169.254.169.254`, `metadata.google.internal`, `metadata.azure.com`, `100.100.100.200`, `instance-data`
 - Internal suffixes such as `.local` and `.internal`
 
+DNS resolution is performed and blocked if any resolved IP matches a blocked range.
+
 ### URL Validation
 
 - Only `http` and `https` URLs
 - No embedded credentials in URLs
 - Max URL length: 2048 characters
+- Hostnames ending in `.local` or `.internal` are rejected
 
 ### Header Sanitization
 
@@ -491,7 +504,7 @@ Blocked headers: `host`, `authorization`, `cookie`, `x-forwarded-for`, `x-real-i
 
 ### Rate Limiting
 
-Rate limiting thresholds are configurable via `RATE_LIMIT_MAX` and `RATE_LIMIT_WINDOW_MS` (see `CONFIGURATION.md`).
+Rate limiting applies to `/mcp` and `/mcp/downloads` and is configurable via `RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`, and `RATE_LIMIT_CLEANUP_MS` (see `CONFIGURATION.md`).
 
 ---
 
@@ -499,20 +512,22 @@ Rate limiting thresholds are configurable via `RATE_LIMIT_MAX` and `RATE_LIMIT_W
 
 ### Scripts
 
-| Command                 | Description                        |
-| ----------------------- | ---------------------------------- |
-| `npm run dev`           | Development server with hot reload |
-| `npm run build`         | Compile TypeScript                 |
-| `npm start`             | Production server                  |
-| `npm run lint`          | Run ESLint                         |
-| `npm run type-check`    | TypeScript type checking           |
-| `npm run format`        | Format with Prettier               |
-| `npm test`              | Run Vitest tests                   |
-| `npm run test:coverage` | Run tests with coverage            |
-| `npm run bench`         | Run minimal performance benchmark  |
-| `npm run release`       | Create new release                 |
-| `npm run knip`          | Find unused exports/dependencies   |
-| `npm run knip:fix`      | Auto-fix unused code               |
+| Command                 | Description                          |
+| ----------------------- | ------------------------------------ |
+| `npm run dev`           | Development server with hot reload   |
+| `npm run build`         | Compile TypeScript                   |
+| `npm start`             | Production server                    |
+| `npm run lint`          | Run ESLint                           |
+| `npm run type-check`    | TypeScript type checking             |
+| `npm run format`        | Format with Prettier                 |
+| `npm test`              | Run Node test runner (builds dist)   |
+| `npm run test:coverage` | Run tests with experimental coverage |
+| `npm run bench`         | Run minimal performance benchmark    |
+| `npm run release`       | Create new release                   |
+| `npm run knip`          | Find unused exports/dependencies     |
+| `npm run knip:fix`      | Auto-fix unused code                 |
+
+> **Note:** Tests run via `node --test` with `--experimental-transform-types` to execute `.ts` test files. Node will emit an experimental warning.
 
 ### Tech Stack
 

package/dist/config/formatting.d.ts

@@ -4,4 +4,4 @@ export declare const CODE_BLOCK: {
     readonly format: (code: string, language?: string) => string;
 };
 export declare const FRONTMATTER_DELIMITER = "---";
-export declare const joinLines: (lines: string[]) => string;
+export declare const joinLines: (lines: readonly string[]) => string;

package/dist/config/types/content.d.ts

@@ -22,7 +22,7 @@ export interface ParagraphBlock extends ContentBlock {
 export interface ListBlock extends ContentBlock {
     type: 'list';
     ordered: boolean;
-    items: string[];
+    readonly items: readonly string[];
 }
 export interface CodeBlock extends ContentBlock {
     type: 'code';
@@ -31,8 +31,8 @@ export interface CodeBlock extends ContentBlock {
 }
 export interface TableBlock extends ContentBlock {
     type: 'table';
-    headers?: string[];
-    rows: string[][];
+    readonly headers?: readonly string[];
+    readonly rows: readonly (readonly string[])[];
 }
 export interface ImageBlock extends ContentBlock {
     type: 'image';

package/dist/config/types/runtime.d.ts

@@ -65,7 +65,7 @@ export interface FetchPipelineOptions<T> {
     /** Optional: cache variation input for headers/flags */
     cacheVary?: Record<string, unknown> | string;
     /** Transform function to process HTML into desired format */
-    transform: (html: string, url: string) => T;
+    transform: (html: string, url: string) => T | Promise<T>;
     /** Optional: serialize result for caching (defaults to JSON.stringify) */
     serialize?: (result: T) => string;
     /** Optional: deserialize cached content */

package/dist/config/types/tools.d.ts

@@ -1,24 +1,25 @@
 import type { ToolContentBlock } from './runtime.js';
 interface RequestOptions {
     /** Custom HTTP headers for the request */
-    customHeaders?: Record<string, string>;
+    customHeaders?: Record<string, string> | undefined;
     /** Request timeout in milliseconds (1000-120000) */
-    timeout?: number;
+    timeout?: number | undefined;
     /** Number of retry attempts (1-10) */
-    retries?: number;
+    retries?: number | undefined;
 }
 export interface FetchUrlInput extends RequestOptions {
     url: string;
-    extractMainContent?: boolean;
-    includeMetadata?: boolean;
-    maxContentLength?: number;
-    format?: 'jsonl' | 'markdown';
+    extractMainContent?: boolean | undefined;
+    includeMetadata?: boolean | undefined;
+    maxContentLength?: number | undefined;
+    format?: 'jsonl' | 'markdown' | undefined;
+    includeContentBlocks?: boolean | undefined;
 }
 export interface FetchMarkdownInput extends RequestOptions {
     url: string;
-    extractMainContent?: boolean;
-    includeMetadata?: boolean;
-    maxContentLength?: number;
+    extractMainContent?: boolean | undefined;
+    includeMetadata?: boolean | undefined;
+    maxContentLength?: number | undefined;
 }
 export interface FileDownloadInfo {
     downloadUrl: string;
@@ -38,11 +39,10 @@ export interface ToolErrorResponse {
     [x: string]: unknown;
     content: ToolContentBlock[];
     structuredContent: {
-        [x: string]: unknown;
         error: string;
         url: string;
         errorCode: string;
-    };
+    } & Record<string, unknown>;
     isError: true;
 }
 export interface ToolResponseBase {

package/dist/http/cors.js

@@ -13,13 +13,22 @@ function isValidOrigin(origin) {
 export function createCorsMiddleware(options) {
     return (req, res, next) => {
         const origin = resolveOrigin(req);
-        if (shouldSkipInvalidOrigin(origin)) {
-            next();
-            return;
-        }
-        if (!applyCorsHeaders(res, origin, options)) {
-            next();
-            return;
+        if (origin) {
+            if (!isValidOrigin(origin)) {
+                res.status(403).json({
+                    error: 'Origin not allowed',
+                    code: 'ORIGIN_NOT_ALLOWED',
+                });
+                return;
+            }
+            if (!isOriginAllowed(origin, options)) {
+                res.status(403).json({
+                    error: 'Origin not allowed',
+                    code: 'ORIGIN_NOT_ALLOWED',
+                });
+                return;
+            }
+            applyCorsHeaders(res, origin);
         }
         if (req.method === 'OPTIONS') {
             res.sendStatus(200);
@@ -31,20 +40,11 @@ export function createCorsMiddleware(options) {
 function resolveOrigin(req) {
     return req.headers.origin;
 }
-function shouldSkipInvalidOrigin(origin) {
-    return Boolean(origin && !isValidOrigin(origin));
-}
-function applyCorsHeaders(res, origin, options) {
-    if (isOriginAllowed(origin, options)) {
-        if (origin) {
-            res.vary('Origin');
-        }
-        res.header('Access-Control-Allow-Origin', origin ?? '*');
-        res.header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-        res.header('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id, Authorization, X-API-Key');
-        res.header('Access-Control-Expose-Headers', 'mcp-session-id');
-        res.header('Access-Control-Max-Age', '86400');
-        return true;
-    }
-    return options.allowedOrigins.length === 0;
+function applyCorsHeaders(res, origin) {
+    res.vary('Origin');
+    res.header('Access-Control-Allow-Origin', origin);
+    res.header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.header('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id, Authorization, X-API-Key');
+    res.header('Access-Control-Expose-Headers', 'mcp-session-id');
+    res.header('Access-Control-Max-Age', '86400');
 }

package/dist/http/download-routes.js

@@ -52,15 +52,20 @@ function resolveExtension(namespace) {
 function parseCachedPayload(raw) {
     try {
         const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === 'object') {
-            return parsed;
-        }
-        return null;
+        return isCachedPayload(parsed) ? parsed : null;
     }
     catch {
         return null;
     }
 }
+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') &&
+        (record.title === undefined || typeof record.title === 'string'));
+}
 function resolvePayloadContent(payload, namespace) {
     if (namespace === 'markdown') {
         if (typeof payload.markdown === 'string') {
@@ -80,7 +85,8 @@ export function resolveDownloadPayload(params, cacheEntry) {
     const content = resolvePayloadContent(payload, params.namespace);
     if (!content)
         return null;
-    const fileName = generateSafeFilename(cacheEntry.url, cacheEntry.title ?? payload.title, params.hash, resolveExtension(params.namespace));
+    const safeTitle = typeof payload.title === 'string' ? payload.title : undefined;
+    const fileName = generateSafeFilename(cacheEntry.url, cacheEntry.title ?? safeTitle, params.hash, resolveExtension(params.namespace));
     return {
         content,
         contentType: resolveContentType(params.namespace),

package/dist/http/mcp-routes.js

@@ -62,15 +62,6 @@ function resolveSessionTransport(sessionId, options, res) {
     options.sessionStore.touch(sessionId);
     return session.transport;
 }
-function resolveSessionTransportForDelete(sessionId, options) {
-    if (!sessionId)
-        return null;
-    const session = options.sessionStore.get(sessionId);
-    if (!session)
-        return null;
-    options.sessionStore.touch(sessionId);
-    return session.transport;
-}
 async function handlePost(req, res, options) {
     const sessionId = getSessionId(req);
     const { body } = req;
@@ -91,11 +82,9 @@ async function handleGet(req, res, options) {
     await handleTransportRequest(transport, req, res);
 }
 async function handleDelete(req, res, options) {
-    const transport = resolveSessionTransportForDelete(getSessionId(req), options);
-    if (!transport) {
-        res.status(204).end();
+    const transport = resolveSessionTransport(getSessionId(req), options, res);
+    if (!transport)
         return;
-    }
     await handleTransportRequest(transport, req, res);
 }
 export function registerMcpRoutes(app, options) {

package/dist/http/mcp-validation.js

@@ -2,7 +2,7 @@ function isRecord(value) {
     return value !== null && typeof value === 'object';
 }
 export function isMcpRequestBody(body) {
-    if (!isRecord(body))
+    if (!isRecord(body) || Array.isArray(body))
         return false;
     const { method, id, jsonrpc, params } = body;
     const methodValid = method === undefined || typeof method === 'string';

package/dist/http/server-middleware.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { config } from '../config/index.js';
-import { requestContext } from '../services/context.js';
+import { bindToRequestContext, runWithRequestContext, } from '../services/context.js';
 import { getSessionId } from './sessions.js';
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
 function normalizeHost(value) {
@@ -84,8 +84,10 @@ export function createContextMiddleware() {
     return (req, _res, next) => {
         const requestId = randomUUID();
         const sessionId = getSessionId(req);
-        requestContext.run({ requestId, sessionId }, () => {
-            next();
+        const context = sessionId === undefined ? { requestId } : { requestId, sessionId };
+        runWithRequestContext(context, () => {
+            const boundNext = bindToRequestContext(next);
+            boundNext();
         });
     };
 }

package/dist/http/server.js

@@ -2,6 +2,7 @@ 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 { errorHandler } from '../middleware/error-handler.js';
 import { getErrorMessage } from '../utils/error-utils.js';
 import { createAuthMiddleware } from './auth.js';
@@ -54,6 +55,7 @@ function createShutdownHandler(server, sessionStore, sessionCleanupController, s
             });
         })));
         destroyAgents();
+        destroyTransformWorkers();
         server.close(() => {
             logInfo('HTTP server closed');
             process.exit(0);

package/dist/index.js

@@ -34,6 +34,11 @@ process.on('unhandledRejection', (reason) => {
     const error = reason instanceof Error ? reason : new Error(String(reason));
     logError('Unhandled rejection', error);
     process.stderr.write(`Unhandled rejection: ${error.message}\n`);
+    if (shouldAttemptShutdown()) {
+        attemptShutdown('UNHANDLED_REJECTION');
+        return;
+    }
+    process.exit(1);
 });
 try {
     if (isStdioMode) {

package/dist/middleware/error-handler.js

@@ -31,7 +31,7 @@ function buildErrorResponse(err) {
             ...(details && { details }),
         },
     };
-    if (process.env.NODE_ENV === 'development') {
+    if (process.env.NODE_ENV === 'development' && err.stack) {
         response.error.stack = err.stack;
     }
     return response;

package/dist/resources/cached-content.js

@@ -163,15 +163,19 @@ function resolveStringParam(value) {
 function parseCachedPayload(raw) {
     try {
         const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === 'object') {
-            return parsed;
-        }
-        return null;
+        return isCachedPayload(parsed) ? parsed : null;
     }
     catch {
         return null;
     }
 }
+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') {

package/dist/server.js

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { config } from './config/index.js';
 import { destroyAgents } from './services/fetcher.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() {
@@ -30,6 +31,7 @@ export async function startStdioServer() {
     const handleShutdown = (signal) => {
         process.stderr.write(`\n${signal} received, shutting down superFetch MCP server...\n`);
         destroyAgents();
+        destroyTransformWorkers();
         server
             .close()
             .catch((err) => {

package/dist/services/cache.d.ts

@@ -17,5 +17,6 @@ export declare function toResourceUri(cacheKey: string): string | null;
 export declare function onCacheUpdate(listener: CacheUpdateListener): () => void;
 export declare function get(cacheKey: string | null): CacheEntry | undefined;
 export declare function set(cacheKey: string | null, content: string, metadata: CacheEntryMetadata): void;
-export declare function keys(): string[];
+export declare function keys(): readonly string[];
+export declare function isEnabled(): boolean;
 export {};

package/dist/services/cache.js

@@ -22,19 +22,16 @@ async function runCleanupLoop(signal) {
         signal,
         ref: false,
     })) {
-        evictExpiredEntries();
+        evictEntries();
     }
 }
-function evictExpiredEntries() {
+function evictEntries() {
     const now = Date.now();
     for (const [key, item] of contentCache.entries()) {
         if (now > item.expiresAt) {
             contentCache.delete(key);
         }
     }
-    enforceMaxKeys();
-}
-function enforceMaxKeys() {
     if (contentCache.size <= config.cache.maxKeys)
         return;
     const keysToRemove = contentCache.size - config.cache.maxKeys;
@@ -175,17 +172,36 @@ export function set(cacheKey, content, metadata) {
 export function keys() {
     return Array.from(contentCache.keys());
 }
+export function isEnabled() {
+    return config.cache.enabled;
+}
 function buildCacheEntry(cacheKey, content, metadata) {
-    return {
+    const entry = {
         url: metadata.url,
-        title: metadata.title,
         content,
         fetchedAt: new Date().toISOString(),
         expiresAt: new Date(Date.now() + config.cache.ttl * 1000).toISOString(),
     };
+    if (metadata.title !== undefined) {
+        entry.title = metadata.title;
+    }
+    return entry;
 }
 function persistCacheEntry(cacheKey, entry) {
     const expiresAt = Date.now() + config.cache.ttl * 1000;
     contentCache.set(cacheKey, { entry, expiresAt });
+    enforceMaxKeysLimit();
     emitCacheUpdate(cacheKey);
 }
+function enforceMaxKeysLimit() {
+    if (contentCache.size <= config.cache.maxKeys)
+        return;
+    const keysToRemove = contentCache.size - config.cache.maxKeys;
+    const iterator = contentCache.keys();
+    for (let i = 0; i < keysToRemove; i++) {
+        const { value, done } = iterator.next();
+        if (done)
+            break;
+        contentCache.delete(value);
+    }
+}

package/dist/services/context.d.ts

@@ -1,9 +1,9 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 interface RequestContext {
-    requestId: string;
-    sessionId?: string;
+    readonly requestId: string;
+    readonly sessionId?: string;
 }
-export declare const requestContext: AsyncLocalStorage<RequestContext>;
+export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+export declare function bindToRequestContext<T extends (...args: unknown[]) => unknown>(fn: T): T;
 export declare function getRequestId(): string | undefined;
 export declare function getSessionId(): string | undefined;
 export {};

package/dist/services/context.js

@@ -1,5 +1,15 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-export const requestContext = new AsyncLocalStorage();
+const requestContext = new AsyncLocalStorage();
+export function runWithRequestContext(context, fn) {
+    return requestContext.run(context, fn);
+}
+export function bindToRequestContext(fn) {
+    const store = requestContext.getStore();
+    if (!store) {
+        return fn;
+    }
+    return ((...args) => requestContext.run(store, () => fn(...args)));
+}
 export function getRequestId() {
     return requestContext.getStore()?.requestId;
 }