imapflow 1.7.2 → 1.7.3

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.7.2"
+    ".": "1.7.3"
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.7.3](https://github.com/postalsys/imapflow/compare/v1.7.2...v1.7.3) (2026-08-24)
+
+
+### Bug Fixes
+
+* **errors:** make the rejection guard structural and stamp every connection error ([67a4afc](https://github.com/postalsys/imapflow/commit/67a4afcc06a2699ea327e98459590901f2efb24c))
+* **errors:** name the rejection site on connection errors and guard the IDLE preCheck waiter ([55764f0](https://github.com/postalsys/imapflow/commit/55764f056f5aeb9771e493e9b659872f01ee7995))
+
 ## [1.7.2](https://github.com/postalsys/imapflow/compare/v1.7.1...v1.7.2) (2026-08-21)
 
 

package/lib/commands/fetch.js

@@ -254,7 +254,7 @@ module.exports = async (connection, range, query, options) => {
                 // the FETCH on a connection that is already gone.
                 let aborted = await connection.throttleWait(delay);
                 if (aborted) {
-                    throw connection.createNoConnectionError(connection.byeReason);
+                    throw connection.createNoConnectionError(connection.byeReason, { rejectedFrom: 'throttleAbort', command: 'FETCH' });
                 }
 
                 retryCount++;

package/lib/commands/idle.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
+const { guardedPromise, hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -85,7 +85,9 @@ async function runIdle(connection) {
         // Public interface for breaking IDLE. Returns a promise that resolves when
         // IDLE is actually broken and the connection is free for other commands.
         let connectionPreCheck = () => {
-            let handler = new Promise((resolve, reject) => {
+            // Guarded: the catch block below rejects every queued waiter synchronously while
+            // close() tears the connection down. See guardedPromise().
+            let handler = guardedPromise((resolve, reject) => {
                 preCheckWaitQueue.push({ resolve, reject });
             });
 

package/lib/imap-flow.js

@@ -43,13 +43,13 @@ const {
     parseUintValue,
     isUnsafeKey,
     getStringList,
+    guardedPromise,
+    guardedReject,
     MAX_UINT32_DIGITS
 } = require('./tools');
 
 const imapCommands = require('./imap-commands.js');
 
-const noop = () => {};
-
 const GREETING_TIMEOUT = 16 * 1000;
 const UPGRADE_TIMEOUT = 10 * 1000;
 
@@ -677,16 +677,12 @@ class ImapFlow extends EventEmitter {
     write(chunk) {
         if (!this.socket || this.socket.destroyed) {
             // do not write after connection end or logout
-            const error = new Error('Socket is already closed');
-            error.code = 'NoConnection';
-            throw error;
+            throw this.createConnectionError('NoConnection', 'Socket is already closed', { rejectedFrom: 'writeNoSocket' });
         }
 
         if (this.state === this.states.LOGOUT) {
             // should not happen
-            const error = new Error('Can not send data after logged out');
-            error.code = 'StateLogout';
-            throw error;
+            throw this.createConnectionError('StateLogout', 'Can not send data after logged out', { rejectedFrom: 'writeAfterLogout' });
         }
 
         if (this.writeSocket.destroyed) {
@@ -771,9 +767,7 @@ class ImapFlow extends EventEmitter {
                 let request = this.requestTagMap.get(data.tag);
                 if (request) {
                     this.requestTagMap.delete(request.tag);
-                    const error = new Error('Connection not available');
-                    error.code = 'NoConnection';
-                    request.reject(error);
+                    request.reject(this.createNoConnectionError(false, { rejectedFrom: 'sendAfterLogout', command: request.command }));
                 }
             }
             return;
@@ -864,26 +858,20 @@ class ImapFlow extends EventEmitter {
 
     exec(command, attributes, options) {
         if (this.state === this.states.LOGOUT || this.isClosed) {
-            const error = new Error('Connection not available');
-            error.code = 'NoConnection';
-            let p = Promise.reject(error);
-            p.catch(noop);
-            return p;
+            return guardedReject(this.createNoConnectionError(false, { rejectedFrom: 'execClosed', command }));
         }
 
         if (!this.socket || this.socket.destroyed) {
-            let error = new Error('Connection closed');
-            error.code = 'EConnectionClosed';
-            let p = Promise.reject(error);
-            p.catch(noop);
-            return p;
+            return guardedReject(this.createConnectionError('EConnectionClosed', 'Connection closed', { rejectedFrom: 'execNoSocket', command }));
         }
 
         let tag = (++this.tagCounter).toString(16).toUpperCase();
 
         options = options || {};
 
-        let promise = new Promise((resolve, reject) => {
+        // Guarded: close() rejects this request synchronously, possibly before the caller has
+        // attached its handler. See guardedPromise().
+        return guardedPromise((resolve, reject) => {
             this.requestTagMap.set(tag, { command, attributes, options, resolve, reject });
             this.requestQueue.push({ tag, command, attributes, options });
             // trySend() settles dispatch failures itself, by rejecting the affected
@@ -891,13 +879,6 @@ class ImapFlow extends EventEmitter {
             // dispatch machinery itself can never surface as a floating rejection.
             this.trySend().catch(err => logConnectionError(this, 'Failed to dispatch command', err));
         });
-
-        // Prevent unhandled promise rejection if close() rejects this request
-        // synchronously before the caller's handler is attached. The rejection
-        // still propagates normally to the caller's await/.catch().
-        promise.catch(noop);
-
-        return promise;
     }
 
     // Resolves an untagged server response to the keyword it is dispatched on. IMAP untagged
@@ -1366,7 +1347,7 @@ class ImapFlow extends EventEmitter {
                             // Connection closed during back-off: reject promptly with a
                             // connection error (carrying any server BYE reason) instead of
                             // waiting out the throttle delay.
-                            request.reject(this.createNoConnectionError(this.byeReason));
+                            request.reject(this.createNoConnectionError(this.byeReason, { rejectedFrom: 'throttleAbort', command: request.command }));
                             break;
                         }
                     }
@@ -1865,9 +1846,7 @@ class ImapFlow extends EventEmitter {
                 try {
                     /* c8 ignore start */ // race: connection closed during the TLS handshake window
                     if (this.isClosed) {
-                        let err = new Error('Connection closed during TLS upgrade');
-                        err.code = 'NoConnection';
-                        return settle(err);
+                        return settle(this.createNoConnectionError(false, { rejectedFrom: 'tlsUpgrade' }));
                     }
                     /* c8 ignore stop */
 
@@ -2433,7 +2412,8 @@ class ImapFlow extends EventEmitter {
             }
         }
 
-        let connectPromise = new Promise((resolve, reject) => {
+        // Guarded: close() rejects a pending connect() synchronously. See guardedPromise().
+        let connectPromise = guardedPromise((resolve, reject) => {
             // Whatever the proxy phase already used is gone from the budget
             this.connectTimeout = setTimeout(() => {
                 let err = deadline.error();
@@ -2533,10 +2513,6 @@ class ImapFlow extends EventEmitter {
             this.socket.on('error', this._connectErrorHandler);
         });
 
-        // Prevent unhandled promise rejection if close() rejects the connect
-        // promise synchronously. The rejection still propagates to the caller.
-        connectPromise.catch(noop);
-
         await connectPromise;
     }
 
@@ -2563,11 +2539,29 @@ class ImapFlow extends EventEmitter {
         setImmediate(() => this.close());
     }
 
-    // Builds the standard "connection not available" error, optionally annotated with the
-    // server's BYE reason. Single source of truth so every NoConnection rejection is consistent.
-    createNoConnectionError(byeReason) {
-        const error = new Error('Connection not available');
-        error.code = 'NoConnection';
+    // Builds an error describing a connection that is gone. Every such error is stamped here so
+    // the stamping cannot drift between sites: the connection id always travels on it, and each
+    // site names itself through `meta` (`rejectedFrom`, plus the command or mailbox path it
+    // belongs to).
+    //
+    // A stack trace only records where an error was built, and close() hands a rejection to every
+    // pending request and every queued lock in the same tick, so without these an error that
+    // reaches a global unhandledRejection handler arrives with nothing that identifies the
+    // connection it came from, let alone which of the rejected promises carried it.
+    createConnectionError(code, message, meta) {
+        const error = new Error(message);
+        error.code = code;
+        error.cid = this.id;
+        if (meta) {
+            Object.assign(error, meta);
+        }
+        return error;
+    }
+
+    // The standard "connection not available" error, optionally annotated with the server's BYE
+    // reason. Single source of truth so every NoConnection rejection is consistent.
+    createNoConnectionError(byeReason, meta) {
+        const error = this.createConnectionError('NoConnection', 'Connection not available', meta);
         if (byeReason) {
             error.reason = byeReason;
         }
@@ -2612,9 +2606,7 @@ class ImapFlow extends EventEmitter {
             if (typeof this._upgradeReject === 'function') {
                 let reject = this._upgradeReject;
                 this._upgradeReject = null;
-                let err = new Error('Connection closed during TLS upgrade');
-                err.code = 'NoConnection';
-                reject(err);
+                reject(this.createNoConnectionError(false, { rejectedFrom: 'upgrade' }));
             }
 
             if (typeof this.initialReject === 'function' && !this.options.verifyOnly) {
@@ -2630,9 +2622,9 @@ class ImapFlow extends EventEmitter {
                 if (this.byeReason) {
                     err.reason = this.byeReason;
                 }
-                // Synchronous rejection is safe: connectPromise.catch(noop) is already
-                // attached, so the rejection is observed immediately. close() is synchronous,
-                // so all cleanup completes before any microtask rejection handler runs.
+                // Synchronous rejection is safe: connectPromise was built by guardedPromise(),
+                // so the rejection is already observed. close() is synchronous, so all cleanup
+                // completes before any microtask rejection handler runs.
                 reject(err);
             }
 
@@ -2690,18 +2682,14 @@ class ImapFlow extends EventEmitter {
                 }
             }
 
-            // Helper to create connection error (delegates to the shared builder)
-            const createNoConnectionError = byeReason => this.createNoConnectionError(byeReason);
-
-            // Reject pending requests and locks synchronously. Each exec() and
-            // getMailboxLock() promise already has .catch(noop) attached, so the
-            // rejection is observed immediately and will not trigger
-            // unhandledRejection. close() is synchronous, so all remaining cleanup
-            // runs before any microtask rejection handler fires.
+            // Reject pending requests and locks synchronously. Every promise rejected here was
+            // built by guardedPromise(), so its rejection is already observed and cannot trigger
+            // unhandledRejection. close() is synchronous, so all remaining cleanup runs before
+            // any microtask rejection handler fires.
             let byeReason = this.byeReason;
 
             for (let request of pendingRequests) {
-                request.reject(createNoConnectionError(byeReason));
+                request.reject(this.createNoConnectionError(byeReason, { rejectedFrom: 'pendingRequest', command: request.command }));
             }
 
             // Clear current lock - holder will see errors when they try operations.
@@ -2720,7 +2708,7 @@ class ImapFlow extends EventEmitter {
                         lock.acquireTimer = null;
                     }
                     if (typeof lock.reject === 'function') {
-                        lock.reject(createNoConnectionError(byeReason));
+                        lock.reject(this.createNoConnectionError(byeReason, { rejectedFrom: 'mailboxLock', path: lock.path }));
                     }
                 }
             }
@@ -3720,9 +3708,7 @@ class ImapFlow extends EventEmitter {
                 lastRes = res;
 
                 if (this.isClosed || !this.socket || this.socket.destroyed) {
-                    let error = new Error('Connection closed');
-                    error.code = 'EConnectionClosed';
-                    throw error;
+                    throw this.createConnectionError('EConnectionClosed', 'Connection closed', { rejectedFrom: 'fetchStream', command: 'FETCH' });
                 }
 
                 yield res.response;
@@ -4427,7 +4413,7 @@ class ImapFlow extends EventEmitter {
         }
 
         if (!this.socket || this.socket.destroyed) {
-            throw this.createNoConnectionError();
+            throw this.createNoConnectionError(false, { rejectedFrom: 'noSocket', command });
         }
 
         clearTimeout(this.idleStartTimer);
@@ -4470,7 +4456,7 @@ class ImapFlow extends EventEmitter {
         }
 
         if (!this.socket || this.socket.destroyed) {
-            throw this.createNoConnectionError();
+            throw this.createNoConnectionError(false, { rejectedFrom: 'noSocket', command });
         }
 
         let handler = this.commands.get(command);
@@ -4587,9 +4573,7 @@ class ImapFlow extends EventEmitter {
 
                 if (!this.usable || !this.socket || this.socket.destroyed) {
                     this.log.trace({ msg: 'Failed to acquire mailbox lock', path, lockId, idling: this.idling });
-                    let error = new Error('Connection not available');
-                    error.code = 'NoConnection';
-                    reject(error);
+                    reject(this.createNoConnectionError(false, { rejectedFrom: 'mailboxLock', path }));
                     continue; // Process next lock in queue
                 }
 
@@ -4713,7 +4697,8 @@ class ImapFlow extends EventEmitter {
                 : null
         });
 
-        let lockPromise = new Promise((resolve, reject) => {
+        // Guarded: close() rejects every queued lock synchronously. See guardedPromise().
+        let lockPromise = guardedPromise((resolve, reject) => {
             let lockEntry = { resolve, reject, path, options, lockId };
             this.locks.push(lockEntry);
 
@@ -4737,10 +4722,6 @@ class ImapFlow extends EventEmitter {
             this.processLocks().catch(err => reject(err));
         });
 
-        // Prevent unhandled promise rejection if close() rejects this lock
-        // synchronously. The rejection still propagates to the caller.
-        lockPromise.catch(noop);
-
         return lockPromise;
     }
 

package/lib/tools.js

@@ -69,7 +69,48 @@ class AuthenticationFailure extends Error {
     authenticationFailed = true;
 }
 
+// Deliberate no-op, used as the observer a guarded promise attaches to its own rejection.
+const noop = () => {};
+
 const tools = {
+    noop,
+
+    /**
+     * Creates a promise whose rejection is observed as soon as it exists.
+     *
+     * close() rejects every promise it owns - the in-flight and queued commands, the pending
+     * connect(), the queued mailbox locks, the waiters for an IDLE break - synchronously, from a
+     * socket event. A consumer that only reaches its `await` a microtask later has not attached a
+     * handler yet at the moment Node decides whether the rejection was observed, and the whole
+     * worker dies on the resulting unhandledRejection. The pre-attached observer settles that
+     * question; the rejection still propagates normally to whoever awaits the returned promise.
+     *
+     * Creation and guarding are one call because splitting them is what actually goes wrong: the
+     * guard was hand-attached at three of the four sites and the fourth (the IDLE-break waiter)
+     * went unguarded, on exactly the path a server BYE takes.
+     *
+     * @param {Function} executor - Promise executor, (resolve, reject) => {}
+     * @returns {Promise} The promise, with its rejection already observed
+     */
+    guardedPromise(executor) {
+        let promise = new Promise(executor);
+        promise.catch(noop);
+        return promise;
+    },
+
+    /**
+     * The already-rejected form of guardedPromise(), for a call that has to hand back a rejected
+     * promise rather than throw.
+     *
+     * @param {Error} error - Rejection reason
+     * @returns {Promise} Rejected promise, with its rejection already observed
+     */
+    guardedReject(error) {
+        let promise = Promise.reject(error);
+        promise.catch(noop);
+        return promise;
+    },
+
     /**
      * Detaches a background timer from the event loop, so it cannot keep the process alive on its
      * own. Applied to every background timer (auto-IDLE, IDLE restart, fallback polling, throttle

package/package.json

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

package/test/fetch-generator-test.js

@@ -5,10 +5,12 @@ const { ImapFlow } = require('../lib/imap-flow');
 // Helper: create a minimal mock context with the fetch() generator bound to it.
 // The `run` override controls how untagged FETCH responses are delivered.
 const createFetchContext = runOverride => ({
+    id: 'test-cid',
     mailbox: { path: 'INBOX', exists: 10 },
     isClosed: false,
     socket: { destroyed: false },
     resolveRange: async range => range,
+    createConnectionError: ImapFlow.prototype.createConnectionError,
     run: runOverride
 });
 

package/test/imapflow-test.js

@@ -47,10 +47,12 @@ module.exports['Create imapflow instance with custom logger'] = async test => {
 // Helpers for testing prototype methods on a mock context
 // ---------------------------------------------------------------------------
 const createFetchContext = runOverride => ({
+    id: 'test-cid',
     mailbox: { path: 'INBOX', exists: 10 },
     isClosed: false,
     socket: { destroyed: false },
     resolveRange: async range => range,
+    createConnectionError: ImapFlow.prototype.createConnectionError,
     run: runOverride
 });
 

package/test/unhandled-rejection-test.js

@@ -408,6 +408,98 @@ exports['Unhandled Rejection Prevention'] = {
         });
     },
 
+    'close() stamps the rejection site, command and connection id on the error'(test) {
+        test.expect(5);
+
+        const client = new ImapFlow({
+            host: '127.0.0.1',
+            port: 1,
+            secure: false,
+            logger: false,
+            id: 'test-cid'
+        });
+
+        client.state = client.states.AUTHENTICATED;
+        client.socket = new net.Socket();
+
+        const detector = installRejectionDetector(test);
+
+        let promise = client.exec('NOOP');
+        client.close();
+
+        setTimeout(() => {
+            detector.check();
+            promise.catch(err => {
+                test.equal(err.code, 'NoConnection', 'caller should receive NoConnection error');
+                test.equal(err.rejectedFrom, 'pendingRequest', 'error should name the rejection site');
+                test.equal(err.command, 'NOOP', 'error should name the command it belonged to');
+                test.equal(err.cid, 'test-cid', 'error should carry the connection id');
+                test.done();
+            });
+        }, 100);
+    },
+
+    '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()');
+
+                // 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());
+            }
+        });
+    },
+
     'BAD response to FETCH should not cause unhandled rejection (Death 2)'(test) {
         test.expect(3);