imapflow 1.7.5 → 1.7.6

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.7.5"
+    ".": "1.7.6"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.7.6](https://github.com/postalsys/imapflow/compare/v1.7.5...v1.7.6) (2026-08-24)
+
+
+### Bug Fixes
+
+* **errors:** stop a re-stamped rejection carrying the previous site's markers ([ffd266c](https://github.com/postalsys/imapflow/commit/ffd266c1459c6f29c5cc2286592a2b2ce88c2706))
+
 ## [1.7.5](https://github.com/postalsys/imapflow/compare/v1.7.4...v1.7.5) (2026-08-24)
 
 

package/lib/commands/idle.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { buildConnectionError, guardedPromise, hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
+const { guardedPromise, hasCapability, logConnectionError, restampConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -27,27 +27,6 @@ function claimIdling(connection) {
     };
 }
 
-/**
- * Builds the rejection a queued IDLE-break waiter receives when the IDLE command itself fails.
- *
- * The waiters are separate promises with separate consumers, so handing them the command's own
- * error would report a waiter that escapes as `rejectedFrom: 'pendingRequest'` - the site where
- * the IDLE command was rejected, not the site where the waiter was. That is precisely the
- * attribution the markers exist to give. Every own field of the original is carried over, because
- * a waiter rejection reaches callers through run() and they branch on `responseStatus`,
- * `serverResponseCode` and friends; only the site marker differs, and the original travels on as
- * `cause` so the command failure behind it stays visible.
- *
- * @param {Object} connection - IMAP connection instance
- * @param {Error} err - The error that failed the IDLE command
- * @returns {Error} Error stamped for the waiter site
- */
-function preCheckWaiterError(connection, err) {
-    let error = buildConnectionError(connection.id, err.code, err.message, Object.assign({}, err, { rejectedFrom: 'preCheckWaiter' }));
-    error.cause = err;
-    return error;
-}
-
 /**
  * Runs a single IDLE session on the connection.
  *
@@ -159,9 +138,15 @@ async function runIdle(connection) {
         return;
     } catch (err) {
         logConnectionError(connection, 'IDLE session failed', err);
-        while (preCheckWaitQueue.length) {
-            let { reject } = preCheckWaitQueue.shift();
-            reject(preCheckWaiterError(connection, err));
+        if (preCheckWaitQueue.length) {
+            // 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 -
+            // does not pay for an Error and its stack capture.
+            let waiterError = restampConnectionError(err, { rejectedFrom: 'preCheckWaiter' });
+            while (preCheckWaitQueue.length) {
+                let { reject } = preCheckWaitQueue.shift();
+                reject(waiterError);
+            }
         }
         return false;
     } finally {

package/lib/tools.js

@@ -72,6 +72,11 @@ class AuthenticationFailure extends Error {
 // Deliberate no-op, used as the observer a guarded promise attaches to its own rejection.
 const noop = () => {};
 
+// The fields buildConnectionError() stamps to say *where* a connection error was rejected, as
+// opposed to what went wrong. restampConnectionError() clears them, because they belong to the
+// site that built the error rather than to the failure it describes.
+const CONNECTION_ERROR_SITE_KEYS = ['rejectedFrom', 'command', 'path'];
+
 const tools = {
     noop,
 
@@ -104,6 +109,37 @@ const tools = {
         return error;
     },
 
+    /**
+     * Re-stamps an existing connection error for a different rejection site.
+     *
+     * The same failure can be handed to more than one promise - close() rejects the in-flight
+     * command, and runIdle() then rejects everything queued behind it - and each of those is a
+     * separate promise with a separate consumer. Sharing one error object reports whichever of
+     * them escapes under the first site's marker, which is the attribution these markers exist to
+     * give.
+     *
+     * Everything describing *what went wrong* is carried over, because a re-stamped error reaches
+     * user code through run() and callers branch on `responseStatus`, `serverResponseCode` and
+     * friends. Everything describing *where it was rejected* is dropped, because the new site owns
+     * those and a leftover `command` from the previous site is exactly as misleading as a leftover
+     * `rejectedFrom`. The original travels on as `cause`.
+     *
+     * @param {Error} err - The error being re-stamped
+     * @param {Object} meta - Fields for the new site, e.g. { rejectedFrom: 'preCheckWaiter' }
+     * @returns {Error} A separate error describing the same failure at the new site
+     */
+    restampConnectionError(err, meta) {
+        let error = tools.buildConnectionError(err.cid, err.code, err.message, err);
+        for (let key of CONNECTION_ERROR_SITE_KEYS) {
+            delete error[key];
+        }
+        if (meta) {
+            Object.assign(error, meta);
+        }
+        error.cause = err;
+        return error;
+    },
+
     /**
      * Creates a promise whose rejection is observed as soon as it exists.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.7.5",
+    "version": "1.7.6",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/unhandled-rejection-test.js

@@ -101,6 +101,59 @@ function installRejectionDetector(test) {
     };
 }
 
+// Drives a connection to the one state both IDLE-waiter tests need: IDLE issued but never
+// acknowledged with a "+", so preCheck() cannot send DONE and anything it queues stays queued
+// until close() tears the IDLE command down. Hands the connected client to `run`, and always
+// closes the server so the test ends.
+function withQueuedIdleWaiter(test, options, run, onError) {
+    const server = createMockServer({
+        extraCapabilities: 'IDLE',
+        onCommand(socket, tag, command) {
+            if (command === 'IDLE') {
+                return true;
+            }
+        }
+    });
+
+    server.listen(0, '127.0.0.1', async () => {
+        const client = new ImapFlow(
+            Object.assign(
+                {
+                    host: '127.0.0.1',
+                    port: server.address().port,
+                    secure: false,
+                    logger: false,
+                    disableAutoIdle: true,
+                    auth: { user: 'test', pass: 'test' }
+                },
+                options
+            )
+        );
+
+        try {
+            await client.connect();
+            await client.mailboxOpen('INBOX');
+
+            client.idle().catch(() => {
+                // Expected: IDLE rejects when the connection is closed
+            });
+
+            // Let the IDLE command reach the server and install preCheck()
+            await new Promise(r => setTimeout(r, 100));
+            test.equal(typeof client.preCheck, 'function', 'IDLE should have installed preCheck()');
+
+            await run(client);
+        } catch (err) {
+            if (onError) {
+                onError(err);
+            }
+            test.ok(false, 'Unexpected error: ' + err.message);
+        } finally {
+            server.close(() => test.done());
+        }
+    });
+}
+
 exports['Unhandled Rejection Prevention'] = {
     'exec() + close() race should not cause unhandled rejection'(test) {
         test.expect(2);
@@ -440,63 +493,23 @@ exports['Unhandled Rejection Prevention'] = {
     },
 
     'a preCheck() waiter rejection names its own site, not the IDLE command'(test) {
-        test.expect(6);
+        test.expect(8);
 
-        // IDLE is never acknowledged with a "+", so preCheck() cannot send DONE and its waiter
-        // stays queued until close() tears the IDLE command down.
-        const server = createMockServer({
-            extraCapabilities: 'IDLE',
-            onCommand(socket, tag, command) {
-                if (command === 'IDLE') {
-                    return true;
-                }
-            }
-        });
-
-        server.listen(0, '127.0.0.1', async () => {
-            const port = server.address().port;
-
-            const client = new ImapFlow({
-                host: '127.0.0.1',
-                port,
-                secure: false,
-                logger: false,
-                disableAutoIdle: true,
-                id: 'waiter-cid',
-                auth: {
-                    user: 'test',
-                    pass: 'test'
-                }
-            });
+        withQueuedIdleWaiter(test, { id: 'waiter-cid' }, async client => {
+            let waiter = client.preCheck();
+            client.close();
 
             try {
-                await client.connect();
-                await client.mailboxOpen('INBOX');
-
-                client.idle().catch(() => {
-                    // Expected: IDLE rejects when the connection is closed
-                });
-
-                await new Promise(r => setTimeout(r, 100));
-
-                let waiter = client.preCheck();
-                client.close();
-
-                try {
-                    await waiter;
-                    test.ok(false, 'the waiter should have rejected');
-                } catch (err) {
-                    test.equal(err.rejectedFrom, 'preCheckWaiter', 'the waiter names its own rejection site');
-                    test.equal(err.cid, 'waiter-cid', 'the waiter error carries the connection id');
-                    test.equal(err.code, 'NoConnection', 'the original code is preserved for callers that branch on it');
-                    test.ok(err.cause, 'the command failure travels on as the cause');
-                    test.equal(err.cause.rejectedFrom, 'pendingRequest', 'the cause still names the command site');
-                    test.equal(err.cause.command, 'IDLE', 'the cause still names the command');
-                }
+                await waiter;
+                test.ok(false, 'the waiter should have rejected');
             } catch (err) {
-                test.ok(false, 'Unexpected error: ' + err.message);
-            } finally {
-                server.close(() => test.done());
+                test.equal(err.rejectedFrom, 'preCheckWaiter', 'the waiter names its own rejection site');
+                test.equal(err.cid, 'waiter-cid', 'the waiter error carries the connection id');
+                test.equal(err.code, 'NoConnection', 'the original code is preserved for callers that branch on it');
+                test.strictEqual(err.command, undefined, 'the command belongs to the site the error came from, not to the waiter');
+                test.ok(err.cause, 'the command failure travels on as the cause');
+                test.equal(err.cause.rejectedFrom, 'pendingRequest', 'the cause still names the command site');
+                test.equal(err.cause.command, 'IDLE', 'the cause still names the command');
             }
         });
     },
@@ -504,62 +517,22 @@ exports['Unhandled Rejection Prevention'] = {
     'preCheck() waiter rejected by close() should not cause unhandled rejection'(test) {
         test.expect(2);
 
-        // Never acknowledge IDLE with a "+" continuation. preCheck() can only send DONE once
-        // the server has acknowledged, so its waiter stays queued until close() tears the
-        // IDLE command down and runIdle() rejects everything still waiting.
-        const server = createMockServer({
-            extraCapabilities: 'IDLE',
-            onCommand(socket, tag, command) {
-                if (command === 'IDLE') {
-                    return true;
-                }
-            }
-        });
-
-        server.listen(0, '127.0.0.1', async () => {
-            const port = server.address().port;
-
-            const client = new ImapFlow({
-                host: '127.0.0.1',
-                port,
-                secure: false,
-                logger: false,
-                disableAutoIdle: true,
-                auth: {
-                    user: 'test',
-                    pass: 'test'
-                }
-            });
-
-            const detector = installRejectionDetector(test);
-
-            try {
-                await client.connect();
-                await client.mailboxOpen('INBOX');
-
-                client.idle().catch(() => {
-                    // Expected: IDLE rejects when the connection is closed
-                });
-
-                // Let the IDLE command reach the server and install preCheck()
-                await new Promise(r => setTimeout(r, 100));
-                test.equal(typeof client.preCheck, 'function', 'IDLE should have installed preCheck()');
+        const detector = installRejectionDetector(test);
 
-                // Request an IDLE break and drop the returned promise on the floor, so the
-                // queued waiter has no handler of its own when close() rejects it
+        withQueuedIdleWaiter(
+            test,
+            {},
+            async client => {
+                // Request an IDLE break and drop the returned promise on the floor, so the queued
+                // waiter has no handler of its own when close() rejects it
                 client.preCheck();
-
                 client.close();
 
                 await new Promise(r => setTimeout(r, 100));
                 detector.check();
-            } catch (err) {
-                detector.check();
-                test.ok(false, 'Unexpected error: ' + err.message);
-            } finally {
-                server.close(() => test.done());
-            }
-        });
+            },
+            () => detector.check()
+        );
     },
 
     'BAD response to FETCH should not cause unhandled rejection (Death 2)'(test) {