@j0hanz/superfetch 2.0.0 → 2.1.0

package/dist/services/transform-worker-pool.js

@@ -1,215 +1,244 @@
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
 import { Worker } from 'node:worker_threads';
-import { config } from '../config/index.js';
-import { getErrorMessage } from '../utils/error-utils.js';
-import { logWarn } from './logger.js';
-import { isWorkerResponse } from './transform-worker-types.js';
-class TransformWorkerPool {
-    workerUrl;
-    slots = [];
+import { FetchError } from '../errors/app-error.js';
+import { getErrorMessage } from '../utils/error-details.js';
+let pool = null;
+function resolveDefaultWorkerCount() {
+    const parallelism = typeof os.availableParallelism === 'function'
+        ? os.availableParallelism()
+        : os.cpus().length;
+    // Leave 1 core for the event loop; cap to avoid runaway memory.
+    return Math.min(16, Math.max(1, parallelism - 1));
+}
+const DEFAULT_TIMEOUT_MS = 30000;
+export function getOrCreateTransformWorkerPool() {
+    pool ??= new WorkerPool(resolveDefaultWorkerCount(), DEFAULT_TIMEOUT_MS);
+    return pool;
+}
+export async function shutdownTransformWorkerPool() {
+    if (!pool)
+        return;
+    await pool.close();
+    pool = null;
+}
+class WorkerPool {
+    workers = [];
     queue = [];
-    nextId = 1;
-    destroyed = false;
-    constructor(workerUrl, size) {
-        this.workerUrl = workerUrl;
-        for (let i = 0; i < size; i += 1) {
-            this.slots.push(this.spawnWorker());
-        }
-    }
-    run(request, signal) {
-        if (this.destroyed) {
-            return Promise.reject(new Error('Worker pool is shut down'));
-        }
-        return new Promise((resolve, reject) => {
-            if (signal?.aborted) {
-                reject(new Error('Aborted'));
-                return;
-            }
-            const task = this.createTask(request, resolve, reject, signal);
-            this.attachAbortHandler(task, signal);
-            this.enqueueTask(task);
-        });
-    }
-    async destroy() {
-        if (this.destroyed)
-            return;
-        this.destroyed = true;
-        const pending = this.queue.splice(0);
-        for (const task of pending) {
-            this.cleanupTask(task);
-            task.reject(new Error('Worker pool shutting down'));
-        }
-        for (const slot of this.slots) {
-            if (slot.current) {
-                const task = slot.current;
-                slot.current = undefined;
-                slot.busy = false;
-                this.cleanupTask(task);
-                task.reject(new Error('Worker pool shutting down'));
-            }
-        }
-        await Promise.allSettled(this.slots.map((slot) => slot.worker.terminate()));
-        this.slots = [];
-    }
-    dispatch() {
-        if (this.destroyed)
-            return;
-        const idle = this.slots.find((slot) => !slot.busy);
-        if (!idle)
-            return;
-        const task = this.queue.shift();
-        if (!task)
-            return;
-        task.status = 'running';
-        idle.busy = true;
-        idle.current = task;
-        try {
-            idle.worker.postMessage(task.request);
-        }
-        catch (error) {
-            this.failTask(idle, error);
+    inflight = new Map();
+    timeoutMs;
+    queueMax;
+    closed = false;
+    constructor(size, timeoutMs) {
+        const safeSize = Math.max(1, size);
+        this.timeoutMs = timeoutMs;
+        this.queueMax = safeSize * 2;
+        for (let index = 0; index < safeSize; index += 1) {
+            this.workers.push(this.spawnWorker(index));
         }
     }
-    createTask(request, resolve, reject, signal) {
-        const id = this.nextId;
-        this.nextId += 1;
-        return {
-            id,
-            request: { ...request, id },
-            resolve,
-            reject,
-            signal,
-            abortHandler: undefined,
-            status: 'queued',
-        };
-    }
-    attachAbortHandler(task, signal) {
-        if (!signal)
-            return;
-        const onAbort = () => {
-            if (task.status === 'queued') {
-                this.removeQueuedTask(task);
-                task.reject(new Error('Aborted'));
-                return;
-            }
-            this.abortRunningTask(task);
+    spawnWorker(workerIndex) {
+        const worker = new Worker(new URL('../workers/transform-worker.js', import.meta.url));
+        // Workers must not keep the process alive by themselves.
+        worker.unref();
+        const slot = {
+            worker,
+            busy: false,
+            currentTaskId: null,
         };
-        task.abortHandler = onAbort;
-        signal.addEventListener('abort', onAbort, { once: true });
-    }
-    enqueueTask(task) {
-        this.queue.push(task);
-        this.dispatch();
-    }
-    attachWorker(slot) {
-        slot.worker.on('message', (message) => {
-            this.handleMessage(slot, message);
+        worker.on('message', (raw) => {
+            this.onWorkerMessage(workerIndex, raw);
         });
-        slot.worker.on('error', (error) => {
-            this.handleWorkerFailure(slot, error);
+        worker.on('error', (error) => {
+            this.onWorkerBroken(workerIndex, `Transform worker error: ${getErrorMessage(error)}`);
         });
-        slot.worker.on('exit', (code) => {
-            if (code !== 0) {
-                this.handleWorkerFailure(slot, new Error(`Worker exited with code ${code}`));
-            }
+        worker.on('exit', (code) => {
+            this.onWorkerBroken(workerIndex, `Transform worker exited (code ${code})`);
         });
-    }
-    spawnWorker() {
-        const slot = {
-            worker: new Worker(this.workerUrl),
-            busy: false,
-            current: undefined,
-        };
-        this.attachWorker(slot);
         return slot;
     }
-    handleMessage(slot, message) {
-        const task = slot.current;
-        if (!task)
+    onWorkerBroken(workerIndex, message) {
+        if (this.closed)
             return;
-        if (!isWorkerResponse(message) || message.id !== task.id) {
-            this.handleWorkerFailure(slot, new Error('Unexpected worker response'));
+        const slot = this.workers[workerIndex];
+        if (!slot)
+            return;
+        if (slot.busy && slot.currentTaskId) {
+            this.failTask(slot.currentTaskId, new Error(message));
+        }
+        void slot.worker.terminate();
+        this.workers[workerIndex] = this.spawnWorker(workerIndex);
+        this.drainQueue();
+    }
+    onWorkerMessage(workerIndex, raw) {
+        if (!raw ||
+            typeof raw !== 'object' ||
+            !('type' in raw) ||
+            !('id' in raw) ||
+            typeof raw.id !== 'string' ||
+            typeof raw.type !== 'string') {
+            return;
+        }
+        const message = raw;
+        const inflight = this.inflight.get(message.id);
+        if (!inflight)
             return;
+        clearTimeout(inflight.timer);
+        if (inflight.signal && inflight.abortListener) {
+            inflight.signal.removeEventListener('abort', inflight.abortListener);
         }
-        slot.current = undefined;
-        slot.busy = false;
-        this.cleanupTask(task);
-        if (message.ok) {
-            task.resolve(message.result);
+        this.inflight.delete(message.id);
+        const slot = this.workers[workerIndex];
+        if (slot) {
+            slot.busy = false;
+            slot.currentTaskId = null;
+        }
+        if (message.type === 'result') {
+            inflight.resolve(message.result);
         }
         else {
-            task.reject(new Error(message.error));
+            const { error } = message;
+            if (error.name === 'FetchError') {
+                inflight.reject(new FetchError(error.message, error.url, error.statusCode, error.details ?? {}));
+            }
+            else {
+                inflight.reject(new Error(error.message));
+            }
         }
-        this.dispatch();
+        this.drainQueue();
     }
-    handleWorkerFailure(slot, error) {
-        const task = slot.current;
-        if (task) {
-            slot.current = undefined;
+    failTask(id, error) {
+        const inflight = this.inflight.get(id);
+        if (!inflight)
+            return;
+        clearTimeout(inflight.timer);
+        if (inflight.signal && inflight.abortListener) {
+            inflight.signal.removeEventListener('abort', inflight.abortListener);
+        }
+        this.inflight.delete(id);
+        inflight.reject(error);
+        const slot = this.workers[inflight.workerIndex];
+        if (slot) {
             slot.busy = false;
-            this.cleanupTask(task);
-            task.reject(error instanceof Error ? error : new Error(getErrorMessage(error)));
+            slot.currentTaskId = null;
         }
-        logWarn('Worker thread failure', {
-            error: getErrorMessage(error),
-        });
-        this.replaceWorker(slot);
-        this.dispatch();
     }
-    replaceWorker(slot) {
-        try {
-            void slot.worker.terminate();
+    async transform(html, url, options) {
+        if (this.closed) {
+            throw new Error('Transform worker pool closed');
         }
-        catch {
-            // Best-effort cleanup.
+        if (this.queue.length >= this.queueMax) {
+            throw new Error('Transform worker queue is full');
         }
-        slot.worker = new Worker(this.workerUrl);
-        slot.busy = false;
-        slot.current = undefined;
-        this.attachWorker(slot);
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                id: randomUUID(),
+                html,
+                url,
+                includeMetadata: options.includeMetadata,
+                signal: options.signal,
+                resolve,
+                reject,
+            });
+            this.drainQueue();
+        });
     }
-    failTask(slot, error) {
-        const task = slot.current;
-        if (!task)
+    drainQueue() {
+        if (this.queue.length === 0)
             return;
-        slot.current = undefined;
-        slot.busy = false;
-        this.cleanupTask(task);
-        task.reject(error instanceof Error ? error : new Error(String(error)));
-        this.dispatch();
+        for (let workerIndex = 0; workerIndex < this.workers.length; workerIndex += 1) {
+            const slot = this.workers[workerIndex];
+            if (!slot || slot.busy)
+                continue;
+            const task = this.queue.shift();
+            if (!task)
+                return;
+            this.dispatch(workerIndex, slot, task);
+            if (this.queue.length === 0)
+                return;
+        }
     }
-    abortRunningTask(task) {
-        const slot = this.slots.find((s) => s.current?.id === task.id);
-        if (!slot)
+    dispatch(workerIndex, slot, task) {
+        if (task.signal?.aborted) {
+            task.reject(new FetchError('Request was canceled', task.url, 499, {
+                reason: 'aborted',
+                stage: 'transform:dispatch',
+            }));
             return;
-        this.handleWorkerFailure(slot, new Error('Aborted'));
-    }
-    removeQueuedTask(task) {
-        const index = this.queue.findIndex((queued) => queued.id === task.id);
-        if (index >= 0) {
-            this.queue.splice(index, 1);
         }
-        this.cleanupTask(task);
+        slot.busy = true;
+        slot.currentTaskId = task.id;
+        const timer = setTimeout(() => {
+            try {
+                slot.worker.postMessage({ type: 'cancel', id: task.id });
+            }
+            catch {
+                // ignore
+            }
+            const inflight = this.inflight.get(task.id);
+            if (!inflight)
+                return;
+            clearTimeout(inflight.timer);
+            if (inflight.signal && inflight.abortListener) {
+                inflight.signal.removeEventListener('abort', inflight.abortListener);
+            }
+            this.inflight.delete(task.id);
+            inflight.reject(new FetchError('Request timeout', task.url, 504, {
+                reason: 'timeout',
+                stage: 'transform:worker-timeout',
+            }));
+            if (!this.closed) {
+                void slot.worker.terminate();
+                this.workers[workerIndex] = this.spawnWorker(workerIndex);
+                this.drainQueue();
+            }
+        }, this.timeoutMs).unref();
+        let abortListener;
+        if (task.signal) {
+            abortListener = () => {
+                try {
+                    slot.worker.postMessage({ type: 'cancel', id: task.id });
+                }
+                catch {
+                    // ignore
+                }
+            };
+            task.signal.addEventListener('abort', abortListener, { once: true });
+        }
+        this.inflight.set(task.id, {
+            resolve: task.resolve,
+            reject: task.reject,
+            timer,
+            signal: task.signal,
+            abortListener,
+            workerIndex,
+        });
+        slot.worker.postMessage({
+            type: 'transform',
+            id: task.id,
+            html: task.html,
+            url: task.url,
+            includeMetadata: task.includeMetadata,
+        });
     }
-    cleanupTask(task) {
-        if (task.signal && task.abortHandler) {
-            task.signal.removeEventListener('abort', task.abortHandler);
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const terminations = this.workers.map((slot) => slot.worker.terminate());
+        this.workers.length = 0;
+        for (const [id, inflight] of this.inflight.entries()) {
+            clearTimeout(inflight.timer);
+            if (inflight.signal && inflight.abortListener) {
+                inflight.signal.removeEventListener('abort', inflight.abortListener);
+            }
+            inflight.reject(new Error('Transform worker pool closed'));
+            this.inflight.delete(id);
         }
+        for (const task of this.queue) {
+            task.reject(new Error('Transform worker pool closed'));
+        }
+        this.queue.length = 0;
+        await Promise.allSettled(terminations);
     }
 }
-let pool = null;
-function getPool() {
-    if (pool)
-        return pool;
-    pool = new TransformWorkerPool(new URL('../workers/content-transform.worker.js', import.meta.url), config.workers.poolSize);
-    return pool;
-}
-export async function transformInWorker(request, signal) {
-    return getPool().run(request, signal);
-}
-export async function destroyTransformWorkers() {
-    if (!pool)
-        return;
-    const current = pool;
-    pool = null;
-    await current.destroy();
-}

package/dist/tools/handlers/fetch-single.shared.d.ts

@@ -1,6 +1,4 @@
-import type { PipelineResult, ToolContentBlock } from '../../config/types/runtime.js';
-import { executeFetchPipeline } from '../utils/fetch-pipeline.js';
-import { applyInlineContentLimit } from '../utils/inline-content.js';
+import type { FetchPipelineOptions, PipelineResult, ToolContentBlock } from '../../config/types/runtime.js';
 interface SharedFetchOptions<T extends {
     content: string;
 }> {
@@ -20,4 +18,14 @@ export declare function performSharedFetch<T extends {
 }>;
 export type InlineResult = ReturnType<typeof applyInlineContentLimit>;
 export declare function buildToolContentBlocks(structuredContent: Record<string, unknown>, fromCache: boolean, inlineResult: InlineResult, resourceName: string, cacheKey?: string | null, fullContent?: string, url?: string, title?: string): ToolContentBlock[];
+interface InlineContentResult {
+    content?: string;
+    contentSize: number;
+    resourceUri?: string;
+    resourceMimeType?: string;
+    error?: string;
+    truncated?: boolean;
+}
+declare function applyInlineContentLimit(content: string, cacheKey: string | null): InlineContentResult;
+export declare function executeFetchPipeline<T>(options: FetchPipelineOptions<T>): Promise<PipelineResult<T>>;
 export {};

package/dist/tools/handlers/fetch-single.shared.js

@@ -1,7 +1,13 @@
+import { TRUNCATION_MARKER } from '../../config/formatting.js';
 import { config } from '../../config/index.js';
+import * as cache from '../../services/cache.js';
+import { createCacheKey, toResourceUri } from '../../services/cache-keys.js';
+import { fetchNormalizedUrl } from '../../services/fetcher.js';
+import { logDebug } from '../../services/logger.js';
 import { generateSafeFilename } from '../../utils/filename-generator.js';
-import { executeFetchPipeline } from '../utils/fetch-pipeline.js';
-import { applyInlineContentLimit } from '../utils/inline-content.js';
+import { isRecord } from '../../utils/guards.js';
+import { transformToRawUrl } from '../../utils/url-transformer.js';
+import { normalizeUrl } from '../../utils/url-validator.js';
 function applyOptionalPipelineSerialization(pipelineOptions, options) {
     if (options.serialize !== undefined) {
         pipelineOptions.serialize = options.serialize;
@@ -92,3 +98,126 @@ export function buildToolContentBlocks(structuredContent, fromCache, inlineResul
     maybeAppendResourceLink(blocks, inlineResult, resourceName);
     return blocks;
 }
+function applyInlineContentLimit(content, cacheKey) {
+    const contentSize = content.length;
+    const inlineLimit = config.constants.maxInlineContentChars;
+    if (contentSize <= inlineLimit) {
+        return { content, contentSize };
+    }
+    const resourceUri = resolveResourceUri(cacheKey);
+    if (!resourceUri) {
+        return buildTruncatedFallback(content, contentSize, inlineLimit);
+    }
+    return {
+        contentSize,
+        resourceUri,
+        resourceMimeType: 'text/markdown',
+    };
+}
+function resolveResourceUri(cacheKey) {
+    if (!config.cache.enabled || !cacheKey)
+        return null;
+    return toResourceUri(cacheKey);
+}
+function buildTruncatedFallback(content, contentSize, inlineLimit) {
+    const maxContentLength = Math.max(0, inlineLimit - TRUNCATION_MARKER.length);
+    const truncatedContent = content.length > inlineLimit
+        ? `${content.substring(0, maxContentLength)}${TRUNCATION_MARKER}`
+        : content;
+    return {
+        content: truncatedContent,
+        contentSize,
+        truncated: true,
+    };
+}
+function attemptCacheRetrieval({ cacheKey, deserialize, cacheNamespace, normalizedUrl, }) {
+    if (!cacheKey)
+        return null;
+    const cached = cache.get(cacheKey);
+    if (!cached)
+        return null;
+    if (!deserialize) {
+        logCacheMiss('missing deserializer', cacheNamespace, normalizedUrl);
+        return null;
+    }
+    const data = deserialize(cached.content);
+    if (data === undefined) {
+        logCacheMiss('deserialize failure', cacheNamespace, normalizedUrl);
+        return null;
+    }
+    logDebug('Cache hit', { namespace: cacheNamespace, url: normalizedUrl });
+    return {
+        data,
+        fromCache: true,
+        url: normalizedUrl,
+        fetchedAt: cached.fetchedAt,
+        cacheKey,
+    };
+}
+function resolveNormalizedUrl(url) {
+    const { normalizedUrl: validatedUrl } = normalizeUrl(url);
+    const { url: normalizedUrl, transformed } = transformToRawUrl(validatedUrl);
+    return { normalizedUrl, originalUrl: validatedUrl, transformed };
+}
+export async function executeFetchPipeline(options) {
+    const resolvedUrl = resolveNormalizedUrl(options.url);
+    logRawUrlTransformation(resolvedUrl);
+    const cacheKey = createCacheKey(options.cacheNamespace, resolvedUrl.normalizedUrl, options.cacheVary);
+    const cachedResult = attemptCacheRetrieval({
+        cacheKey,
+        deserialize: options.deserialize,
+        cacheNamespace: options.cacheNamespace,
+        normalizedUrl: resolvedUrl.normalizedUrl,
+    });
+    if (cachedResult)
+        return cachedResult;
+    logDebug('Fetching URL', { url: resolvedUrl.normalizedUrl });
+    const fetchOptions = options.signal === undefined ? {} : { signal: options.signal };
+    const html = await fetchNormalizedUrl(resolvedUrl.normalizedUrl, fetchOptions);
+    const data = await options.transform(html, resolvedUrl.normalizedUrl);
+    if (cache.isEnabled()) {
+        persistCache({
+            cacheKey,
+            data,
+            serialize: options.serialize,
+            normalizedUrl: resolvedUrl.normalizedUrl,
+        });
+    }
+    return {
+        data,
+        fromCache: false,
+        url: resolvedUrl.normalizedUrl,
+        fetchedAt: new Date().toISOString(),
+        cacheKey,
+    };
+}
+function persistCache({ cacheKey, data, serialize, normalizedUrl, }) {
+    if (!cacheKey)
+        return;
+    const serializer = serialize ?? JSON.stringify;
+    const title = extractTitle(data);
+    const metadata = {
+        url: normalizedUrl,
+        ...(title === undefined ? {} : { title }),
+    };
+    cache.set(cacheKey, serializer(data), metadata);
+}
+function extractTitle(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { title } = value;
+    return typeof title === 'string' ? title : undefined;
+}
+function logCacheMiss(reason, cacheNamespace, normalizedUrl) {
+    logDebug(`Cache miss due to ${reason}`, {
+        namespace: cacheNamespace,
+        url: normalizedUrl,
+    });
+}
+function logRawUrlTransformation(resolvedUrl) {
+    if (!resolvedUrl.transformed)
+        return;
+    logDebug('Using transformed raw content URL', {
+        original: resolvedUrl.originalUrl,
+    });
+}

package/dist/tools/handlers/fetch-url.tool.d.ts

@@ -1,4 +1,10 @@
+import type { MarkdownTransformResult } from '../../config/types/content.js';
 import type { FetchUrlInput, ToolResponseBase } from '../../config/types/tools.js';
 export declare const FETCH_URL_TOOL_NAME = "fetch-url";
 export declare const FETCH_URL_TOOL_DESCRIPTION = "Fetches a webpage and converts it to clean Markdown format";
+type MarkdownPipelineResult = MarkdownTransformResult & {
+    readonly content: string;
+};
+export declare function parseCachedMarkdownResult(cached: string): MarkdownPipelineResult | undefined;
 export declare function fetchUrlToolHandler(input: FetchUrlInput): Promise<ToolResponseBase>;
+export {};