imapflow 2.2.6 → 2.2.7

package/dist/cjs/download.js

@@ -15,6 +15,9 @@ const libbase64_1 = __importDefault(require("libbase64"));
 const mailsplit_1 = require("@zone-eu/mailsplit");
 const flowed_decoder_js_1 = __importDefault(require("@zone-eu/mailsplit/lib/flowed-decoder.js"));
 const limited_passthrough_js_1 = require("./limited-passthrough.js");
+// What a wait on the head stream listens for: it can take more input, it failed, or it went
+// away (a consumer destroying it closes it without a 'drain')
+const DRAIN_WAIT_EVENTS = ['drain', 'error', 'close'];
 const tools_js_1 = require("./tools.js");
 /**
  * Implements ImapFlow.download(), see its documentation
@@ -54,7 +57,8 @@ async function downloadMessage(client, range, part, options) {
             range = uid;
             downloadOptions.uid = true;
         }
-        if (!response.bodyStructure.childNodes) {
+        // bodyStructure is unset when the server sent BODYSTRUCTURE NIL
+        if (!response.bodyStructure?.childNodes) {
             // single text message
             part = 'TEXT';
         }
@@ -297,11 +301,54 @@ async function downloadMessage(client, range, part, options) {
     // at the bound still gets its terminating chunk. Infinity when the server reported no
     // size, which leaves the loop bounded by maxBytes alone.
     let maxTotalBytes = (0, limited_passthrough_js_1.normalizeByteLimit)(meta.expectedSize ? meta.expectedSize * 2 + chunkSize : 0);
-    // Fetch remaining chunks in a loop, writing each to the decoder stream.
-    // Stops when the server returns a short chunk (< chunkSize), answers with more than the
-    // requested window, the byte limiter is satisfied, or the consumer destroys the output
-    // stream. Throws when the ceiling above is crossed.
-    let fetchAllParts = async () => {
+    // Resolves once the head stream can take more input, rejects when it fails, and resolves
+    // when it goes away. finish() is the listener itself: 'drain' and 'close' emit no arguments,
+    // 'error' emits the error, and removal needs no separate handler references. It removes
+    // only the listeners this wait installed - removeAllListeners('error') also took off the
+    // forwarder pipeStage() attached to the head stream when the pipeline was built, and the
+    // head must keep that forwarder for the life of the download or a chunk failure has nowhere
+    // to go.
+    let waitForDrain = () => new Promise((resolve, reject) => {
+        const finish = (err) => {
+            for (let event of DRAIN_WAIT_EVENTS) {
+                stream.removeListener(event, finish);
+            }
+            /* c8 ignore next 2 */ // stream error during a backpressure drain wait is timing-dependent
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve();
+            }
+        };
+        for (let event of DRAIN_WAIT_EVENTS) {
+            stream.once(event, finish);
+        }
+    });
+    // Writes a chunk and waits out the backpressure. A base64 decoder defers its write callback,
+    // so a chunk the size of its buffer is never taken synchronously and the head chunk waits
+    // here as much as any other. A stream failure during the wait is thrown unless the download
+    // was already aborted (the consumer destroyed the stream).
+    let writeAndDrain = async (chunk) => {
+        if (writeChunk(chunk) !== false) {
+            return;
+        }
+        try {
+            await waitForDrain();
+            /* c8 ignore next 5 */ // re-throw path only triggers on a stream error mid-drain, which is timing-dependent
+        }
+        catch (err) {
+            if (!fetchAborted) {
+                throw err;
+            }
+        }
+    };
+    // Writes the head chunk, then fetches the remaining chunks in a loop, writing each to the
+    // decoder stream. Stops when the server returns a short chunk (< chunkSize), answers with
+    // more than the requested window, the byte limiter is satisfied, or the consumer destroys
+    // the output stream. Throws when the ceiling above is crossed.
+    let fetchAllParts = async (head) => {
+        await writeAndDrain(head);
         while (hasMore && !isLimited() && !fetchAborted) {
             if (processed >= maxTotalBytes) {
                 // Loud on purpose. Everything written downstream by this point holds
@@ -314,7 +361,9 @@ async function downloadMessage(client, range, part, options) {
                 throw err;
             }
             let { response, chunk } = await getNextPart();
-            if (fetchAborted) {
+            // A consumer that gave up while the chunk was in flight: its 'close' may still be a
+            // tick away from setting fetchAborted, so the stream's own flag is checked as well
+            if (fetchAborted || output.destroyed) {
                 break;
             }
             if (response === false) {
@@ -329,48 +378,7 @@ async function downloadMessage(client, range, part, options) {
             if (!chunk) {
                 break;
             }
-            // Handle backpressure
-            if (writeChunk(chunk) === false) {
-                // Wait for drain event before continuing
-                try {
-                    await new Promise((resolve, reject) => {
-                        // finish() is the listener itself, as settle() is for the TLS upgrade:
-                        // 'drain' and 'close' emit no arguments, 'error' emits the error, and
-                        // removal needs no separate handler references. It removes only the
-                        // three listeners this wait installed - removeAllListeners('error')
-                        // also took off the forwarder pipeStage() attached to the head stream
-                        // when the pipeline was built, and the head must keep that forwarder
-                        // for the life of the download or a chunk failure has nowhere to go.
-                        const finish = (err) => {
-                            for (let event of ['drain', 'error', 'close']) {
-                                stream.removeListener(event, finish);
-                            }
-                            /* c8 ignore next 2 */ // stream error during a backpressure drain wait is timing-dependent
-                            if (err) {
-                                reject(err);
-                            }
-                            else {
-                                resolve();
-                            }
-                        };
-                        stream.once('drain', finish);
-                        stream.once('error', finish);
-                        stream.once('close', finish);
-                    });
-                    /* c8 ignore start */ // re-throw path only triggers on a stream error mid-drain, which is timing-dependent
-                }
-                catch (err) {
-                    // Re-throw only if not aborted
-                    if (!fetchAborted) {
-                        throw err;
-                    }
-                }
-                /* c8 ignore stop */
-                // Check if we should abort after waiting
-                if (fetchAborted) {
-                    break;
-                }
-            }
+            await writeAndDrain(chunk);
         }
     };
     // A download is a sequence of chunk FETCHes with a backpressure wait in between. Those
@@ -389,13 +397,10 @@ async function downloadMessage(client, range, part, options) {
             client.autoidle();
         }
     };
-    // Kick off the download pipeline asynchronously. The first chunk was
-    // already fetched above (to get metadata); write it to the decoder
-    // stream and then fetch remaining chunks via fetchAllParts().
-    // setImmediate ensures the caller gets the {meta, content} return
-    // value before streaming begins.
-    let runFetchAllParts = () => {
-        fetchAllParts()
+    // Runs the download pipeline with the head chunk fetched above (for its metadata): it is
+    // written to the decoder stream and the remaining chunks follow
+    let runFetchAllParts = (head) => {
+        fetchAllParts(head)
             .catch(err => {
             if (!fetchAborted && stream && !stream.destroyed) {
                 stream.emit('error', err);
@@ -427,36 +432,8 @@ async function downloadMessage(client, range, part, options) {
             // for a routine-looking connection code.
             .catch(err => client.log.error({ msg: 'Failed to fail the download stream', err, cid: client.id }));
     };
-    setImmediate(() => {
-        let writeResult;
-        try {
-            writeResult = writeChunk(chunk);
-        }
-        catch (err) {
-            stream.emit('error', err);
-            finishDownload();
-            /* c8 ignore next 3 */ // emitting the error above triggers cleanup (fetchAborted=true), so this end() guard is already false here
-            if (!fetchAborted && stream && !stream.destroyed) {
-                stream.end();
-            }
-            return;
-        }
-        /* c8 ignore next 9 */ // `stream` is piped to the limiter before this runs, so the head write drains synchronously and always returns true (verified for chunkSize up to 8MB); the drain-wait branch is unreachable
-        if (!writeResult) {
-            // Initial chunk filled the buffer, wait for drain
-            stream.once('drain', () => {
-                if (!fetchAborted) {
-                    runFetchAllParts();
-                }
-                else {
-                    finishDownload();
-                }
-            });
-        }
-        else {
-            runFetchAllParts();
-        }
-    });
+    // Deferred so the caller gets the {meta, content} return value before streaming begins
+    setImmediate(() => runFetchAllParts(chunk));
     return {
         meta,
         content: output
@@ -476,14 +453,16 @@ async function downloadMessageParts(client, range, parts, options) {
         // no mailbox selected, nothing to do
         return {};
     }
-    let downloadOptions = Object.assign({
-        chunkSize: 64 * 1024,
-        maxBytes: Infinity
-    }, options || {});
+    let downloadOptions = options || {};
+    // Asked as a partial fetch so at most maxBytes of each part crosses the wire, and enforced
+    // again on the answer for servers that ignore the partial specifier
+    let maxBytes = (0, limited_passthrough_js_1.normalizeByteLimit)(downloadOptions.maxBytes);
     let query = { bodyParts: [] };
     for (let part of parts) {
         query.bodyParts.push(part + '.mime');
-        query.bodyParts.push(part);
+        // The partial specifier carries a 32-bit length (RFC 9051 "number"), so a cap beyond
+        // that is applied on the answer alone
+        query.bodyParts.push(maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes });
     }
     let response = await client.fetchOne(range, query, downloadOptions);
     if (!response || !response.bodyParts) {
@@ -501,6 +480,18 @@ async function downloadMessageParts(client, range, parts, options) {
         if (keyParts.length === 1) {
             // content
             let key = keyParts[0];
+            if (content.length > maxBytes) {
+                // The server ignored the partial specifier and sent the whole part, the quirk
+                // download() tolerates the same way: keep what was asked for
+                client.log.warn({
+                    msg: 'Server returned more than the requested window, truncating the part',
+                    part: key,
+                    maxBytes,
+                    received: content.length,
+                    cid: client.id
+                });
+                content = content.subarray(0, maxBytes);
+            }
             if (!data[key]) {
                 data[key] = { content };
             }

package/dist/cjs/handler/imap-compiler.js

@@ -24,6 +24,10 @@ const safeNumber = (value) => {
     let num = Math.round(Number(value));
     return Number.isSafeInteger(num) && num >= 0 ? num : 0;
 };
+// Log output stands in a placeholder for any value longer than this, so a log entry never
+// carries a copy of a large token (a message body, a long unquoted server token)
+const LOG_VALUE_LIMIT = 100;
+const logPlaceholder = (length, kind) => `"(* ${length}B ${kind} *)"`;
 // Characters that cannot appear in an IMAP quoted string: CR and LF terminate a
 // command line, and NUL is outside the CHAR production entirely. A value carrying
 // any of them has to be sent as a literal, so quoting it is never correct.
@@ -132,8 +136,8 @@ async function compiler(response, options) {
             return;
         }
         if (typeof node === 'string' || Buffer.isBuffer(node)) {
-            if (isLogging && node.length > 100) {
-                resp.push(emitEntry('"(* ' + node.length + 'B string *)"'));
+            if (isLogging && node.length > LOG_VALUE_LIMIT) {
+                resp.push(emitEntry(logPlaceholder(node.length, 'string')));
             }
             else {
                 resp.push(emitEntry(isLogging ? JSON.stringify(node.toString()) : quoteString(node.toString())));
@@ -152,7 +156,7 @@ async function compiler(response, options) {
         switch (node.type.toUpperCase()) {
             case 'LITERAL':
                 if (isLogging) {
-                    resp.push(emitEntry('"(* ' + node.value.length + 'B literal *)"'));
+                    resp.push(emitEntry(logPlaceholder(node.value.length, 'literal')));
                 }
                 else {
                     // The literal size marker counts octets - string values are written as
@@ -184,8 +188,8 @@ async function compiler(response, options) {
                 }
                 break;
             case 'STRING':
-                if (isLogging && node.value.length > 100) {
-                    resp.push(emitEntry('"(* ' + node.value.length + 'B string *)"'));
+                if (isLogging && node.value.length > LOG_VALUE_LIMIT) {
+                    resp.push(emitEntry(logPlaceholder(node.value.length, 'string')));
                 }
                 else {
                     val = (node.value || '').toString();
@@ -243,11 +247,16 @@ async function compiler(response, options) {
             case 'SECTION':
                 val = (node.value || '').toString();
                 if (!node.section || val) {
-                    // Verify the value contains only valid ATOM-CHAR characters.
-                    // Strip a leading backslash before checking (system flags like \Seen start with '\').
-                    // If any character fails verification, fall back to an IMAP quoted string
-                    // (JSON.stringify is used only for log output, where values are display-escaped).
-                    if (node.value === '' || imap_formal_syntax_js_1.default.verify(val.charAt(0) === '\\' ? val.slice(1) : val, imap_formal_syntax_js_1.default['ATOM-CHAR']()) >= 0) {
+                    if (isLogging && val.length > LOG_VALUE_LIMIT) {
+                        // A server can put a line's worth of bytes in one unquoted token
+                        val = logPlaceholder(val.length, 'atom');
+                    }
+                    else if (node.value === '' ||
+                        imap_formal_syntax_js_1.default.verify(val.charAt(0) === '\\' ? val.slice(1) : val, imap_formal_syntax_js_1.default['ATOM-CHAR']()) >= 0) {
+                        // An empty value, or one with a character outside ATOM-CHAR (checked
+                        // past a leading backslash, as system flags like \Seen carry one), goes
+                        // out as an IMAP quoted string. JSON.stringify is used only for log
+                        // output, where values are display-escaped.
                         val = isLogging ? JSON.stringify(val) : quoteString(val);
                     }
                     resp.push(emitEntry(val));

package/dist/cjs/handler/limits.d.ts

@@ -2,6 +2,17 @@ import type { ImapFlowError } from '../errors.js';
 export declare const MAX_LITERAL_SIZE: number;
 export declare const MAX_LINE_SIZE: number;
 export declare const MAX_RESPONSE_SIZE: number;
+export declare const ERROR_CONTEXT_LENGTH = 1024;
+/**
+ * The input a parse error carries: a bounded prefix with the full length.
+ *
+ * @param input - The input that failed to parse
+ * @returns The bounded prefix and the full length
+ */
+export declare const boundedInput: (input: string) => {
+    input: string;
+    inputLength: number;
+};
 /**
  * Normalizes a configured size limit. A non-negative integer is honored as-is (including 0, which
  * means "reject anything non-empty"), and `Infinity` disables the limit; anything else falls back

package/dist/cjs/handler/limits.js

@@ -3,7 +3,7 @@
 // (ImapStream) and the standalone token parser cannot drift apart, and so the documented
 // defaults in the ImapFlowOptions type describe both paths.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLiteralTooLargeError = exports.normalizeLimit = exports.MAX_RESPONSE_SIZE = exports.MAX_LINE_SIZE = exports.MAX_LITERAL_SIZE = void 0;
+exports.createLiteralTooLargeError = exports.normalizeLimit = exports.boundedInput = exports.ERROR_CONTEXT_LENGTH = exports.MAX_RESPONSE_SIZE = exports.MAX_LINE_SIZE = exports.MAX_LITERAL_SIZE = void 0;
 // Maximum allowed literal size: 1GB (1073741824 bytes)
 exports.MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
 // Default maximum length of a single line (a response without a literal). Matches the literal cap:
@@ -20,6 +20,21 @@ exports.MAX_LINE_SIZE = exports.MAX_LITERAL_SIZE;
 // of exactly the maximum permitted size impossible to receive. Configuring both limits calls for
 // the same headroom - set maxResponseSize above maxLiteralSize, not equal to it.
 exports.MAX_RESPONSE_SIZE = 2 * exports.MAX_LITERAL_SIZE;
+// How much of the offending input a parse error carries along. The error travels whole into log
+// entries (pino copies every property of a logged error) and into the rejection of the command
+// the line belonged to, and the line can be as long as the configured line cap.
+exports.ERROR_CONTEXT_LENGTH = 1024;
+/**
+ * The input a parse error carries: a bounded prefix with the full length.
+ *
+ * @param input - The input that failed to parse
+ * @returns The bounded prefix and the full length
+ */
+const boundedInput = (input) => ({
+    input: input.slice(0, exports.ERROR_CONTEXT_LENGTH),
+    inputLength: input.length
+});
+exports.boundedInput = boundedInput;
 /**
  * Normalizes a configured size limit. A non-negative integer is honored as-is (including 0, which
  * means "reject anything non-empty"), and `Infinity` disables the limit; anything else falls back

package/dist/cjs/handler/parser-instance.d.ts

@@ -21,6 +21,16 @@ export declare class ParserInstance {
      * @param options.literals - Pre-parsed literal values from the stream.
      */
     constructor(input?: Buffer | string | null | undefined, options?: ParserOptions | undefined);
+    /**
+     * The context a parse error carries: a bounded prefix of the input (and of the element that
+     * failed, when there is one) with their full lengths, and the position.
+     *
+     * @param element - The element that failed to parse
+     * @returns The context to attach to the error
+     */
+    errorContext(element?: string | undefined): {
+        [key: string]: unknown;
+    };
     /**
      * Extracts and returns the IMAP tag from the beginning of the response.
      * The tag is typically "*" for untagged responses, "+" for continuation requests,

package/dist/cjs/handler/parser-instance.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ParserInstance = void 0;
 const imap_formal_syntax_js_1 = __importDefault(require("./imap-formal-syntax.js"));
 const token_parser_js_1 = require("./token-parser.js");
+const limits_js_1 = require("./limits.js");
 /**
  * Parses a single IMAP response line into its structural components: tag, command,
  * and attributes. Handles status responses (OK, NO, BAD, PREAUTH, BYE) with their
@@ -27,6 +28,22 @@ class ParserInstance {
         this.remainder = this.input;
         this.pos = 0;
     }
+    /**
+     * The context a parse error carries: a bounded prefix of the input (and of the element that
+     * failed, when there is one) with their full lengths, and the position.
+     *
+     * @param element - The element that failed to parse
+     * @returns The context to attach to the error
+     */
+    errorContext(element) {
+        let context = { ...(0, limits_js_1.boundedInput)(this.input), pos: this.pos };
+        if (element !== undefined) {
+            let bounded = (0, limits_js_1.boundedInput)(element);
+            context.element = bounded.input;
+            context.elementLength = bounded.inputLength;
+        }
+        return context;
+    }
     /**
      * Extracts and returns the IMAP tag from the beginning of the response.
      * The tag is typically "*" for untagged responses, "+" for continuation requests,
@@ -128,7 +145,7 @@ class ParserInstance {
         if (/^\s/.test(this.remainder)) {
             let error = new Error(`Unexpected whitespace at position ${this.pos} [E1]`);
             error.code = 'ParserError1';
-            error.parserContext = { input: this.input, pos: this.pos };
+            error.parserContext = this.errorContext();
             throw error;
         }
         if ((match = this.remainder.match(/^\s*[^\s]+(?=\s|$)/))) {
@@ -142,9 +159,7 @@ class ParserInstance {
                     let error = new Error(`Server returned an error: ${this.input}`);
                     error.code = 'ParserErrorExchange';
                     error.parserContext = {
-                        input: this.input,
-                        element,
-                        pos: this.pos,
+                        ...this.errorContext(element),
                         value: {
                             tag: '*',
                             command: 'BAD',
@@ -155,14 +170,14 @@ class ParserInstance {
                 }
                 let error = new Error(`Unexpected char at position ${this.pos + errPos} [E2: ${JSON.stringify(element.charAt(errPos))}]`);
                 error.code = 'ParserError2';
-                error.parserContext = { input: this.input, element, pos: this.pos };
+                error.parserContext = this.errorContext(element);
                 throw error;
             }
         }
         else {
             let error = new Error(`Unexpected end of input at position ${this.pos} [E3]`);
             error.code = 'ParserError3';
-            error.parserContext = { input: this.input, pos: this.pos };
+            error.parserContext = this.errorContext();
             throw error;
         }
         this.pos += match[0].length;
@@ -183,13 +198,13 @@ class ParserInstance {
             }
             let error = new Error(`Unexpected end of input at position ${this.pos} [E4]`);
             error.code = 'ParserError4';
-            error.parserContext = { input: this.input, pos: this.pos };
+            error.parserContext = this.errorContext();
             throw error;
         }
         if (imap_formal_syntax_js_1.default.verify(this.remainder.charAt(0), imap_formal_syntax_js_1.default.SP()) >= 0) {
             let error = new Error(`Unexpected char at position ${this.pos} [E5: ${JSON.stringify(this.remainder.charAt(0))}]`);
             error.code = 'ParserError5';
-            error.parserContext = { input: this.input, element: this.remainder, pos: this.pos };
+            error.parserContext = this.errorContext(this.remainder);
             throw error;
         }
         this.pos++;
@@ -207,13 +222,13 @@ class ParserInstance {
         if (!this.remainder.length) {
             let error = new Error(`Unexpected end of input at position ${this.pos} [E6]`);
             error.code = 'ParserError6';
-            error.parserContext = { input: this.input, pos: this.pos };
+            error.parserContext = this.errorContext();
             throw error;
         }
         if (/^\s/.test(this.remainder)) {
             let error = new Error(`Unexpected whitespace at position ${this.pos} [E7]`);
             error.code = 'ParserError7';
-            error.parserContext = { input: this.input, element: this.remainder, pos: this.pos };
+            error.parserContext = this.errorContext(this.remainder);
             throw error;
         }
         const tokenParser = new token_parser_js_1.TokenParser(this, this.pos, this.remainder, this.options);