imapflow 2.2.5 → 2.2.7

package/dist/esm/commands/idle.js

@@ -1,4 +1,4 @@
-import { guardedPromise, hasCapability, logConnectionError, restampConnectionError, unrefTimer, clearTimer, getSelectedMailbox } from '../tools.js';
+import { guardedPromise, hasCapability, isServerRefusal, logConnectionError, restampConnectionError, unrefTimer, clearTimer, getSelectedMailbox } from '../tools.js';
 const NOOP_INTERVAL = 2 * 60 * 1000;
 /**
  * Marks the connection as idling on behalf of one session and returns a release function.
@@ -57,8 +57,11 @@ async function runIdle(connection) {
                     path: connection.mailbox && connection.mailbox.path,
                     cid: connection.id
                 });
-                connection.write('DONE');
+                // Marked before the write: write() closes the connection when the transport is
+                // already gone, and close() breaks IDLE through this very function, which
+                // would otherwise write DONE again from inside itself
                 doneSent = true;
+                connection.write('DONE');
                 releaseIdling();
                 if (connection.preCheck === ownPreCheck) {
                     connection.preCheck = false; // unset itself
@@ -124,7 +127,10 @@ async function runIdle(connection) {
         // A tagged NO or BAD only means the server refused IDLE; the connection is still usable,
         // so the waiters are released by the finally block below and their own commands run.
         // Anything else (close, lost socket, parser failure) fails the waiters too.
-        let refusedByServer = ['NO', 'BAD'].includes(err.responseStatus);
+        let refusedByServer = isServerRefusal(err);
+        if (refusedByServer) {
+            connection.skipIdle = true;
+        }
         if (preCheckWaitQueue.length && !refusedByServer) {
             // One error for the whole queue: every waiter failed at the same site, for the same
             // reason. Built inside the guard so a teardown with nothing queued - the common case -
@@ -310,7 +316,7 @@ export default async function idle(connection, maxIdleTime) {
     // If server supports IDLE (RFC 2177, folded into base IMAP4rev2), use it for
     // real-time push notifications. Otherwise, fall back to periodic polling with
     // NOOP/STATUS/SELECT.
-    if (hasCapability(connection, 'IDLE')) {
+    if (hasCapability(connection, 'IDLE') && !connection.skipIdle) {
         let idleTimer;
         let stillIdling = false;
         // IDLE loop: runs IDLE, and if maxIdleTime is reached, breaks and restarts to keep the
@@ -334,13 +340,17 @@ export default async function idle(connection, maxIdleTime) {
             }
             let resp = await runIdle(connection);
             clearTimeout(idleTimer);
-            if (!stillIdling) {
+            // A restart only makes sense with nothing queued behind the break (a CLOSE, say; run()
+            // re-arms auto-IDLE once that command is done) and the mailbox still selected on a
+            // usable connection
+            const canRestart = stillIdling && !connection.requestQueue.length && !!getSelectedMailbox(connection) && connection.usable;
+            if (!canRestart) {
                 return resp;
             }
             stillIdling = false;
         }
     }
-    // Fallback for servers without IDLE support: poll at regular intervals using
+    // Fallback for servers without IDLE support, or that refused it: poll at regular intervals using
     // NOOP (default), STATUS, or SELECT depending on missingIdleCommand config.
     return runPollingFallback(connection, maxIdleTime);
 }

package/dist/esm/commands/list.js

@@ -375,6 +375,15 @@ export default async function list(connection, reference, mailbox, options) {
         // Subscribed-only mailboxes that weren't in LIST are intentionally ignored
         // (they may be phantom entries from old subscriptions to deleted mailboxes).
         let runLsub = async () => {
+            // LIST has completed, so its entries are indexed once instead of searched per LSUB
+            // response, which was quadratic in the folder count. The first entry for a path wins,
+            // as with the linear search it replaces
+            let entriesByPath = new Map();
+            for (let entry of entries) {
+                if (!entriesByPath.has(entry.path)) {
+                    entriesByPath.set(entry.path, entry);
+                }
+            }
             let response = await connection.exec('LSUB', [encodePath(connection, normalizedReference), encodePath(connection, normalizedMailbox)], {
                 untagged: {
                     LSUB: async (untagged) => {
@@ -400,7 +409,7 @@ export default async function list(connection, reference, mailbox, options) {
                         entry.parent = entry.delimiter ? entry.path.split(entry.delimiter) : [entry.path];
                         entry.name = entry.parent.pop();
                         // Merge LSUB data into existing LIST entry if found
-                        let existing = entries.find(existing => existing.path === entry.path);
+                        let existing = entriesByPath.get(entry.path);
                         if (existing) {
                             existing.subscribed = true;
                             // Merge any additional flags from LSUB into the LIST entry

package/dist/esm/commands/login.js

@@ -1,4 +1,4 @@
-import { getStatusCode, getErrorText } from '../tools.js';
+import { getStatusCode, getErrorText, isServerRefusal } from '../tools.js';
 /**
  * Authenticates user using the IMAP LOGIN command.
  *
@@ -30,7 +30,11 @@ export default async function login(connection, username, password) {
         if (errorCode) {
             err.serverResponseCode = errorCode;
         }
-        err.authenticationFailed = true;
+        // Only a tagged NO/BAD is the server refusing the credentials; a lost connection or a
+        // timeout during LOGIN says nothing about them, and a caller may retry it
+        if (isServerRefusal(err)) {
+            err.authenticationFailed = true;
+        }
         err.response = await getErrorText(err.response);
         throw err;
     }

package/dist/esm/commands/logout.js

@@ -1,3 +1,7 @@
+import { clearTimer } from '../tools.js';
+// How long to wait for the server to answer LOGOUT before closing the socket anyway. Without a
+// bound of its own, an unanswered LOGOUT kept logout() pending until the socket timeout.
+const LOGOUT_TIMEOUT = 10 * 1000;
 /**
  * Logs out the user and closes the connection.
  *
@@ -16,6 +20,8 @@ export default async function logout(connection) {
         return false;
     }
     let response;
+    // close() rejects the pending LOGOUT with NoConnection, which counts as a completed logout
+    let timer = setTimeout(() => connection.close(), LOGOUT_TIMEOUT);
     try {
         response = await connection.exec('LOGOUT');
         return true;
@@ -33,6 +39,7 @@ export default async function logout(connection) {
         // Set state to LOGOUT before closing to prevent any further commands from
         // being queued. The socket is closed unconditionally in this finally block
         // regardless of whether the LOGOUT command succeeded or failed.
+        clearTimer(timer);
         connection.state = connection.states.LOGOUT;
         if (response && typeof response.next === 'function') {
             response.next();

package/dist/esm/commands/namespace.js

@@ -31,7 +31,8 @@ export default async function namespace(connection) {
     }
     let response;
     try {
-        let map = {};
+        // NIL personal namespaces and a missing NAMESPACE response leave the defaults in place
+        let map = { personal: [], other: false, shared: false };
         response = await connection.exec('NAMESPACE', false, {
             untagged: {
                 // The NAMESPACE response (RFC 2342) contains exactly three sections:
@@ -43,19 +44,22 @@ export default async function namespace(connection) {
                     if (!untagged.attributes || !untagged.attributes.length) {
                         return;
                     }
-                    map.personal = getNamsepaceInfo(untagged.attributes[0]);
+                    // NIL personal namespaces are legal (RFC 2342 section 5, e.g. after an anonymous login)
+                    map.personal = getNamsepaceInfo(untagged.attributes[0]) || [];
                     map.other = getNamsepaceInfo(untagged.attributes[1]);
                     map.shared = getNamsepaceInfo(untagged.attributes[2]);
                 }
             }
         });
+        // Release the response before touching the parsed data, so nothing below can leave the
+        // reader parked behind this command
+        response.next();
         connection.namespaces = map;
         // make sure that we have the first personal namespace always set
         if (!connection.namespaces.personal[0]) {
             connection.namespaces.personal[0] = { prefix: '', delimiter: '.' };
         }
         connection.namespaces.personal[0].prefix = connection.namespaces.personal[0].prefix || '';
-        response.next();
         connection.namespace = connection.namespaces.personal[0];
         return connection.namespace;
     }

package/dist/esm/commands/quota.js

@@ -11,7 +11,9 @@ export default async function quota(connection, path) {
         // nothing to do here
         return;
     }
-    if (!connection.capabilities.has('QUOTA')) {
+    // An RFC 9208 server advertises its QUOTA=RES-* resource types and does not have to list
+    // the bare RFC 2087 QUOTA token as well
+    if (!connection.capabilities.has('QUOTA') && ![...connection.capabilities.keys()].some(capability => capability.startsWith('QUOTA=RES-'))) {
         return false;
     }
     path = normalizePath(connection, path);

package/dist/esm/commands/rename.js

@@ -21,7 +21,8 @@ export default async function rename(connection, path, newPath) {
     // as IMAP servers will not rename an active mailbox.
     let selected = getSelectedMailbox(connection);
     if (selected && selected.path === path) {
-        await connection.run('CLOSE');
+        // UNSELECT where possible, CLOSE would expunge messages flagged \Deleted
+        await connection.run('CLOSE', { unselect: true });
     }
     let response;
     try {

package/dist/esm/commands/select.js

@@ -226,6 +226,11 @@ export default async function select(connection, pathInput, options) {
         if (!currentMailbox || currentMailbox.path !== path) {
             emitSafe(connection, 'mailboxOpen', connection.mailbox);
         }
+        else if (typeof map.exists === 'number' && map.exists !== currentMailbox.exists) {
+            // A re-SELECT of the open mailbox (the SELECT polling fallback) gets its EXISTS here
+            // instead of in the global handler, so it is reported the same way
+            emitSafe(connection, 'exists', { path, count: map.exists, prevCount: currentMailbox.exists });
+        }
         response.next();
         return map;
     }

package/dist/esm/commands/status.js

@@ -1,4 +1,4 @@
-import { encodePath, normalizePath, buildStatusQueryAttributes, isRev2Active, isAuthenticatedState, emitSafe, getSelectedMailbox } from '../tools.js';
+import { encodePath, normalizePath, buildStatusQueryAttributes, isRev2Active, isAuthenticatedState, emitSafe, getSelectedMailbox, logConnectionError } from '../tools.js';
 import { parseStatusList } from './status-fields.js';
 // STATUS fields that also refresh the live mailbox state when the queried mailbox is the
 // currently selected one. Keyed by the output property name parseStatusList() reports.
@@ -89,7 +89,12 @@ export default async function status(connection, path, query) {
         // Not a deadlock, and only reachable when the server rejects the STATUS, but a polled
         // STATUS of a missing folder ends the poll early.
         if (err.responseStatus === 'NO') {
-            let folders = await connection.run('LIST', '', path, { listOnly: true });
+            // A failing probe (lost connection, throttling) answers nothing about the mailbox,
+            // so STATUS then fails the same way as any other failed STATUS
+            let folders = await connection.run('LIST', '', path, { listOnly: true }).catch((listErr) => {
+                logConnectionError(connection, 'Failed to check if the mailbox exists', listErr);
+                return false;
+            });
             if (folders && !folders.length) {
                 let error = new Error(`Mailbox doesn't exist: ${path}`);
                 error.code = 'NotFound';

package/dist/esm/commands/store.d.ts

@@ -16,4 +16,4 @@ export interface StoreCommandOptions extends StoreOptions {
  * @param options - Store options
  * @returns True on success, false on failure or if nothing to do
  */
-export default function store(connection: ImapFlow, range: string, flags: string | string[], options: StoreCommandOptions): Promise<boolean>;
+export default function store(connection: ImapFlow, range: string, flags: string | string[], options?: StoreCommandOptions | undefined): Promise<boolean>;

package/dist/esm/commands/store.js

@@ -9,13 +9,12 @@ import { formatFlag, canUseFlag, reportCommandError, getSelectedMailbox } from '
  * @returns True on success, false on failure or if nothing to do
  */
 export default async function store(connection, range, flags, options) {
+    options = options || {};
     let mailbox = getSelectedMailbox(connection);
     if (!mailbox || !range || (options.useLabels && !connection.capabilities.has('X-GM-EXT-1'))) {
         // nothing to do here
         return false;
     }
-    /* c8 ignore next */ // options.useLabels is dereferenced in the guard above, so options is always defined here
-    options = options || {};
     // Build the IMAP STORE operation name. The format is:
     //   [+|-]FLAGS[.SILENT] or [+|-]X-GM-LABELS
     // Where: no prefix = replace all, + = add, - = remove

package/dist/esm/download.js

@@ -8,6 +8,9 @@ import libbase64 from 'libbase64';
 import { Headers } from '@zone-eu/mailsplit';
 import FlowedDecoder from '@zone-eu/mailsplit/lib/flowed-decoder.js';
 import { LimitedPassthrough, normalizeByteLimit } from './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'];
 import { getDecoder, isUnsafeKey } from './tools.js';
 /**
  * Implements ImapFlow.download(), see its documentation
@@ -47,7 +50,8 @@ export 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';
         }
@@ -290,11 +294,54 @@ export 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 = 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
@@ -307,7 +354,9 @@ export 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) {
@@ -322,48 +371,7 @@ export 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
@@ -382,13 +390,10 @@ export 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);
@@ -420,36 +425,8 @@ export 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
@@ -469,14 +446,16 @@ export 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 = 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) {
@@ -494,6 +473,18 @@ export 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 };
             }