@ni-c/imap-mcp 0.3.0 → 0.4.0

package/dist/extract/index.d.ts

@@ -0,0 +1,41 @@
+import type { ExtractKind, ExtractRequest, ExtractResponse } from './types.js';
+export type { ExtractKind, ExtractReason, ExtractRequest, ExtractResponse, } from './types.js';
+/**
+ * How long a document may be parsed before the process doing it is killed.
+ *
+ * Generous next to the five seconds a regular expression gets in the sibling
+ * servers, because a hundred-page PDF is honest work — and finite, because a
+ * document that has not finished by now is not going to.
+ */
+export declare const EXTRACT_TIMEOUT_MS = 20000;
+/**
+ * Characters the child may return, before any of the paging below.
+ *
+ * Not a context budget — that is `max_chars` at the tool, and it is much
+ * smaller. This is the ceiling on what is held in memory and paged through,
+ * and the child enforces it for every format: nothing larger is ever built
+ * there, let alone sent back.
+ */
+export declare const MAX_EXTRACT_CHARS = 1000000;
+/** The same set as content types, for `get_server_info`. */
+export declare const EXTRACTABLE_TYPES: string[];
+/** Prose for the refusals, so every one of them names the same set. */
+export declare const EXTRACTABLE_TYPE_NAMES: string;
+export declare function extractKindOf(contentType: string): ExtractKind | undefined;
+export declare function isExtractable(contentType: string): boolean;
+/** The magic-byte verdict an honest container of this kind produces. */
+export declare function expectedSignature(kind: ExtractKind): string;
+export declare function extractDocumentText(request: ExtractRequest, limits?: ChildLimits): Promise<ExtractResponse>;
+/**
+ * Narrowed by the tests, never by the server.
+ *
+ * The timeout and the memory ceiling are the two guards whose whole purpose is
+ * what happens when they fire, and neither can be reached in a test at its real
+ * value without a document engineered to spend twenty seconds or a quarter of a
+ * gigabyte. Making them arguments is what lets the failure paths be exercised
+ * in milliseconds; nothing in `src/` passes them.
+ */
+export interface ChildLimits {
+    timeoutMs?: number;
+    memoryMb?: number;
+}

package/dist/extract/index.js

@@ -0,0 +1,183 @@
+import { fork } from 'node:child_process';
+import { once } from 'node:events';
+/**
+ * How long a document may be parsed before the process doing it is killed.
+ *
+ * Generous next to the five seconds a regular expression gets in the sibling
+ * servers, because a hundred-page PDF is honest work — and finite, because a
+ * document that has not finished by now is not going to.
+ */
+export const EXTRACT_TIMEOUT_MS = 20_000;
+/**
+ * Characters the child may return, before any of the paging below.
+ *
+ * Not a context budget — that is `max_chars` at the tool, and it is much
+ * smaller. This is the ceiling on what is held in memory and paged through,
+ * and the child enforces it for every format: nothing larger is ever built
+ * there, let alone sent back.
+ */
+export const MAX_EXTRACT_CHARS = 1_000_000;
+/**
+ * V8 heap the parsing process may use.
+ *
+ * Best effort, and named as such. It bounds a pathological object graph, and
+ * when it fires the child aborts — on its own, which is the whole reason the
+ * parse is in a process. It does not bound typed arrays, which are external
+ * memory; the deflate pre-scan in `pdf.ts` and the entry caps in `ooxml.ts`
+ * are what cover those.
+ */
+const CHILD_MEMORY_MB = 256;
+/**
+ * Requests admitted at once, running and waiting together.
+ *
+ * Extractions run one at a time (see {@link queue}), so a request that arrives
+ * behind seven others would wait up to seven timeouts for its turn, holding
+ * its mailbox lock throughout. Past this many it is refused outright, which is
+ * an answer the caller can act on.
+ */
+const MAX_IN_FLIGHT = 8;
+/** Content types this server can read text out of, and what each one is. */
+const EXTRACTABLE = new Map([
+    ['application/pdf', 'pdf'],
+    [
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        'docx',
+    ],
+    ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'xlsx'],
+    [
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        'pptx',
+    ],
+    ['application/vnd.oasis.opendocument.text', 'odt'],
+    ['application/vnd.oasis.opendocument.spreadsheet', 'ods'],
+]);
+/** The same set as content types, for `get_server_info`. */
+export const EXTRACTABLE_TYPES = [...EXTRACTABLE.keys()];
+/** Prose for the refusals, so every one of them names the same set. */
+export const EXTRACTABLE_TYPE_NAMES = 'PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx) and OpenDocument text ' +
+    'and spreadsheets (.odt, .ods)';
+export function extractKindOf(contentType) {
+    return EXTRACTABLE.get(contentType.toLowerCase());
+}
+export function isExtractable(contentType) {
+    return EXTRACTABLE.has(contentType.toLowerCase());
+}
+/** The magic-byte verdict an honest container of this kind produces. */
+export function expectedSignature(kind) {
+    // Every OOXML and OpenDocument file is a zip, which is why `sniffContent`
+    // reports one for all five of them.
+    return kind === 'pdf' ? 'application/pdf' : 'application/zip';
+}
+/**
+ * Serialises extractions.
+ *
+ * One process per call and no limit would mean N concurrent tool calls holding
+ * N processes of {@link CHILD_MEMORY_MB} each, which is a memory limit that
+ * multiplies by a number the caller chooses. The queue is the whole mechanism:
+ * the next extraction starts when the previous process is gone.
+ */
+let queue = Promise.resolve();
+let inFlight = 0;
+export async function extractDocumentText(request, limits = {}) {
+    if (inFlight >= MAX_IN_FLIGHT)
+        return { ok: false, reason: 'busy' };
+    inFlight += 1;
+    try {
+        const run = queue.then(() => runInChild(request, limits), () => runInChild(request, limits));
+        queue = run.catch(() => undefined);
+        return await run;
+    }
+    finally {
+        inFlight -= 1;
+    }
+}
+/** A code for the log, never a message. */
+function codeOf(error) {
+    const value = error;
+    if (typeof value?.code === 'string')
+        return value.code;
+    if (typeof value?.name === 'string')
+        return value.name;
+    return 'unknown';
+}
+async function runInChild(request, limits = {}) {
+    const timeoutMs = limits.timeoutMs ?? EXTRACT_TIMEOUT_MS;
+    const memoryMb = limits.memoryMb ?? CHILD_MEMORY_MB;
+    const child = fork(new URL(import.meta.url.endsWith('.ts') ? './child.ts' : './child.js', import.meta.url), [], {
+        // Stated rather than inherited. The parent's own flags may be ones a
+        // child cannot take — `--input-type` is one — and an inherited flag that
+        // fails to parse would turn every extraction into a silent `internal`.
+        execArgv: [`--max-old-space-size=${memoryMb}`],
+        // Not tidiness — correctness. The parent's stdout is this server's
+        // JSON-RPC transport, and pdf.js logs. One line from inside the parser
+        // would corrupt the framing and hang the session. Discarded; stderr is
+        // shared, because that is where every other diagnostic in this server
+        // already goes.
+        stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+        // Structured clone rather than JSON: the request carries the document as
+        // a typed array, and JSON would turn it into an array of numbers ten
+        // times its size.
+        serialization: 'advanced',
+    });
+    let timer;
+    try {
+        return await new Promise((resolve) => {
+            // The first answer wins. Everything after it — the exit of a child that
+            // was killed because it had already answered, most of all — is silence,
+            // not a second verdict.
+            let settled = false;
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            timer = setTimeout(() => {
+                settle({ ok: false, reason: 'timeout' });
+            }, timeoutMs);
+            child.once('message', (value) => {
+                settle(value);
+            });
+            child.once('error', (error) => {
+                if (settled)
+                    return;
+                console.error(`imap-mcp: extraction process failed: ${codeOf(error)}`);
+                settle({ ok: false, reason: 'internal' });
+            });
+            child.once('exit', (code, signal) => {
+                // Only reached when the child left without answering. An abort is what
+                // V8 does when the heap limit is hit — and what the process does
+                // *instead of* taking the server with it, which is the property being
+                // bought here.
+                if (settled)
+                    return;
+                if (signal === 'SIGABRT' || code === 134) {
+                    settle({ ok: false, reason: 'out-of-memory' });
+                    return;
+                }
+                console.error(`imap-mcp: extraction process exited early: ${signal ?? `code ${code}`}`);
+                settle({ ok: false, reason: 'internal' });
+            });
+            try {
+                child.send(request);
+            }
+            catch (error) {
+                console.error(`imap-mcp: extraction request failed: ${codeOf(error)}`);
+                settle({ ok: false, reason: 'internal' });
+            }
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        // Unconditional: on the timeout path the process is still inside the parse
+        // and will never exit on its own. SIGKILL, because a parser stuck in native
+        // code does not check for anything gentler — and because a process, unlike
+        // a thread, can be killed from outside whatever it is doing.
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGKILL');
+            await once(child, 'exit');
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/extract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/extract/index.ts"],"names":[],"mappings":"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"}

package/dist/extract/ooxml.d.ts

@@ -0,0 +1,35 @@
+import type { ExtractKind, ExtractResponse } from './types.js';
+/**
+ * Turns markup into readable text. Injected rather than imported.
+ *
+ * `htmlToText` lives in `../analyze.ts`, and this module is reached from the
+ * extraction child, which Node loads directly — where a `../analyze.js`
+ * specifier does not resolve to the `.ts` beside it. Passing the function in
+ * keeps this file free of relative value imports, which is the property that
+ * lets it run in the child at all. It also makes the seam explicit: the tests
+ * hand it the same `htmlToText` the child does.
+ */
+export type MarkupToText = (markup: string, maxChars: number) => string;
+/**
+ * Reads the text of an OOXML or OpenDocument container.
+ *
+ * The whole defence lives in the `filter` callback below, and it is worth
+ * saying why that specific place. `unzipSync` inflates an entry into a buffer
+ * sized by the *declared* uncompressed size out of the central directory — a
+ * number the sender chose, checked against nothing. The filter is the last
+ * point before that allocation, and returning `false` there means the entry is
+ * never inflated and never sized.
+ *
+ * Measured on fflate 0.8.3: a declared size far past the real one does not blow
+ * up resident memory on Linux, because the allocation is virtual and untouched
+ * pages cost nothing; and a declared size *below* the real one truncates the
+ * output to what was declared, because fflate does not grow a caller-sized
+ * buffer. The guard stays regardless — it is free, it is the only thing
+ * standing between an *honest* high-ratio entry and its real expansion, and a
+ * host that does not overcommit would pay the full price.
+ *
+ * This never recurses. An entry that is itself an archive is not in the name
+ * allowlist, so a nested bomb is not descended into; that is a property to keep
+ * rather than an omission to fix.
+ */
+export declare function extractZipDocument(kind: Exclude<ExtractKind, 'pdf'>, bytes: Uint8Array, maxChars: number, toText: MarkupToText): Promise<ExtractResponse>;