imapflow 1.7.7 → 1.7.8

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.7.7"
+    ".": "1.7.8"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.7.8](https://github.com/postalsys/imapflow/compare/v1.7.7...v1.7.8) (2026-09-01)
+
+
+### Bug Fixes
+
+* **download:** keep the pipeline error forwarder across a backpressure wait ([c6b2ed7](https://github.com/postalsys/imapflow/commit/c6b2ed7f2ffb598dad0d7a4beb915055c3cfbef6))
+
 ## [1.7.7](https://github.com/postalsys/imapflow/compare/v1.7.6...v1.7.7) (2026-08-31)
 
 

package/lib/imap-flow.js

@@ -2673,6 +2673,10 @@ class ImapFlow extends EventEmitter {
             // 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.
+            //
+            // The error travels on, though, through await chains and .then() links that
+            // guardedPromise() knows nothing about. Read a crash stack ending here as "this is
+            // the value that escaped", never as "this is the promise that escaped".
             let byeReason = this.byeReason;
 
             for (let request of pendingRequests) {
@@ -4124,17 +4128,17 @@ class ImapFlow extends EventEmitter {
                     // Wait for drain event before continuing
                     try {
                         await new Promise((resolve, reject) => {
-                            let resolved = false;
-
+                            // 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 => {
-                                /* c8 ignore next */ // the first call removes all three listeners, so a later drain/error/close can't re-enter finish; this guard is belt-and-suspenders
-                                if (resolved) return;
-                                resolved = true;
-
-                                // Remove all listeners
-                                stream.removeAllListeners('drain');
-                                stream.removeAllListeners('error');
-                                stream.removeAllListeners('close');
+                                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) {
@@ -4144,9 +4148,9 @@ class ImapFlow extends EventEmitter {
                                 }
                             };
 
-                            stream.once('drain', () => finish());
-                            stream.once('error', err => finish(err));
-                            stream.once('close', () => finish());
+                            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) {
@@ -4210,7 +4214,14 @@ class ImapFlow extends EventEmitter {
                     if (!fetchAborted && stream && !stream.destroyed) {
                         stream.end();
                     }
-                });
+                })
+                // Terminal guard: nothing consumes this chain, so a throw from either handler
+                // above rejects a promise nobody holds and takes the process down on
+                // unhandledRejection. Reaching it always means an invariant broke - the head
+                // stream kept pipeStage()'s error forwarder for the life of the download, so
+                // emit('error') above has somewhere to go - which is why it logs at error even
+                // for a routine-looking connection code.
+                .catch(err => this.log.error({ msg: 'Failed to fail the download stream', err, cid: this.id }));
         };
 
         setImmediate(() => {

package/package.json

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

package/test/fixtures/test-client.js

@@ -4,6 +4,8 @@
 // One definition instead of a per-file copy, so a change to what the constructor needs lands
 // in one place and cannot drift between suites.
 
+const { Writable } = require('node:stream');
+
 const { ImapFlow } = require('../../lib/imap-flow');
 
 // A socket stub complete enough for setSocketHandlers(), clearSocketHandlers() and close() to
@@ -54,4 +56,46 @@ const chunkedFetchOne = body => async (range, query) => {
     return { uid: 1, size: body.length, source: body.subarray(start, start + maxLength) };
 };
 
-module.exports = { makeClient, makeIdleReadyClient, makeSocketStub, chunkedFetchOne };
+// Installs a process-level unhandledRejection detector for one test. Shared because getting the
+// teardown wrong leaks a process listener into every test that runs after it, and because the
+// assertion has to read the same way wherever a suite checks that nothing escaped.
+const installRejectionDetector = test => {
+    // Tracked as a separate flag rather than by testing the reason: a rejection can carry a falsy
+    // value, and that is still an escaped rejection.
+    let unhandled = false;
+    let unhandledReason = null;
+    const handler = reason => {
+        unhandled = true;
+        unhandledReason = reason;
+    };
+    process.on('unhandledRejection', handler);
+
+    return {
+        check() {
+            process.removeListener('unhandledRejection', handler);
+            test.equal(unhandled, false, 'no unhandledRejection should fire' + (unhandledReason ? ': ' + unhandledReason.message : ''));
+        }
+    };
+};
+
+// A Writable that always defers its callback, so writing to a stream piped into it fills the
+// pipeline and forces the producer into backpressure. `delay` is only for tests that also need
+// wall-clock time to pass; deferring at all is what triggers the drain wait.
+const slowConsumer = (options = {}) => {
+    let { delay = 0, onChunk } = options;
+    return new Writable({
+        highWaterMark: 1,
+        write(chunk, enc, cb) {
+            if (typeof onChunk === 'function') {
+                onChunk(chunk);
+            }
+            if (delay) {
+                setTimeout(cb, delay);
+            } else {
+                setImmediate(cb);
+            }
+        }
+    });
+};
+
+module.exports = { makeClient, makeIdleReadyClient, makeSocketStub, chunkedFetchOne, installRejectionDetector, slowConsumer };

package/test/imap-flow-fetch-download-test.js

@@ -8,8 +8,8 @@ const { ImapFlow } = require('../lib/imap-flow');
 const libbase64 = require('libbase64');
 const libqp = require('libqp');
 const libmime = require('libmime');
-const { Writable, finished } = require('stream');
-const { chunkedFetchOne } = require('./fixtures/test-client');
+const { finished } = require('stream');
+const { chunkedFetchOne, installRejectionDetector, slowConsumer } = require('./fixtures/test-client');
 
 const makeClient = (overrides = {}) => {
     let client = new ImapFlow({
@@ -547,13 +547,7 @@ module.exports['Download: in-loop backpressure waits for drain'] = async test =>
     // one buffer down) but subsequent loop writes return false while the consumer
     // is still draining the previous chunk, exercising the in-loop drain wait.
     let received = 0;
-    let slow = new Writable({
-        highWaterMark: 1,
-        write(chunk, enc, cb) {
-            received += chunk.length;
-            setTimeout(cb, 40);
-        }
-    });
+    let slow = slowConsumer({ delay: 40, onChunk: chunk => (received += chunk.length) });
     content.pipe(slow);
     await new Promise(resolve => slow.on('finish', resolve));
 
@@ -587,6 +581,53 @@ module.exports['Download: error during streaming surfaces on content stream'] =
     test.done();
 };
 
+module.exports['Download: a chunk failure after a backpressure wait reaches the stream'] = async test => {
+    // Regression: the drain wait cleared the head stream's listeners with
+    // removeAllListeners('error'), which also removed the error forwarder the decoder pipeline
+    // attached to it. From the first backpressure wait onwards a later chunk failure was emitted
+    // onto a listener-less stream, so emit() threw inside the .catch() handler and the rejection
+    // escaped as an unhandledRejection instead of reaching the consumer.
+    let client = makeClient();
+    let big = Buffer.alloc(64 * 1024, 0x61);
+    let calls = 0;
+    client.fetchOne = async () => {
+        calls++;
+        if (calls <= 3) {
+            return { uid: 1, size: 400 * 1024, source: big };
+        }
+        let err = new Error('Connection not available');
+        err.code = 'NoConnection';
+        throw err;
+    };
+
+    const detector = installRejectionDetector(test);
+
+    let received = 0;
+    let streamErr;
+    try {
+        let { content } = await client.download('1', false, { uid: true, chunkSize: 64 * 1024 });
+
+        // Backpressure comes from the deferred callback, not from wall-clock delay
+        content.pipe(slowConsumer({ onChunk: chunk => (received += chunk.length) }));
+        await new Promise(resolve =>
+            finished(content, err => {
+                streamErr = err;
+                resolve();
+            })
+        );
+    } finally {
+        detector.check();
+    }
+
+    // Without a completed drain wait the regression is not exercised at all, so assert the
+    // pipeline actually drained a chunk before the failing fetch rather than inferring it
+    test.ok(received >= 64 * 1024, 'a chunk drained through the consumer before the failure');
+    test.equal(calls, 4, 'the failing chunk was reached');
+    test.ok(streamErr, 'error surfaced on content stream');
+    test.equal(streamErr && streamErr.code, 'NoConnection');
+    test.done();
+};
+
 module.exports['Download: write error on initial chunk surfaces on stream'] = async test => {
     let client = makeClient();
     // a non-Buffer source makes stream.write throw inside the setImmediate try/catch
@@ -634,12 +675,7 @@ module.exports['Download: aborting mid-backpressure stops the fetch loop'] = asy
 
     // Slow consumer to force backpressure, then destroy mid-stream so the loop
     // aborts during a drain wait.
-    let slow = new Writable({
-        highWaterMark: 1,
-        write(chunk, enc, cb) {
-            setTimeout(cb, 50);
-        }
-    });
+    let slow = slowConsumer({ delay: 50 });
     content.pipe(slow);
     setTimeout(() => content.destroy(), 70);
     await new Promise(resolve => {

package/test/unhandled-rejection-test.js

@@ -18,6 +18,7 @@
 
 const net = require('net');
 const { ImapFlow } = require('../lib/imap-flow');
+const { installRejectionDetector, slowConsumer } = require('./fixtures/test-client');
 
 // Create a mock IMAP server with optional custom behavior.
 // options.extraCapabilities - additional capabilities (e.g., 'IDLE')
@@ -83,24 +84,6 @@ function createMockServer(options) {
     return server;
 }
 
-// Helper: install an unhandledRejection detector
-function installRejectionDetector(test) {
-    let unhandled = false;
-    let unhandledReason = null;
-    const handler = reason => {
-        unhandled = true;
-        unhandledReason = reason;
-    };
-    process.on('unhandledRejection', handler);
-
-    return {
-        check() {
-            process.removeListener('unhandledRejection', handler);
-            test.equal(unhandled, false, 'no unhandledRejection should fire' + (unhandledReason ? ': ' + unhandledReason.message : ''));
-        }
-    };
-}
-
 // 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
@@ -581,6 +564,91 @@ exports['Unhandled Rejection Prevention'] = {
                 await new Promise(r => setTimeout(r, 100));
                 detector.check();
 
+                client.close();
+            } catch (err) {
+                detector.check();
+                test.ok(false, 'Unexpected error: ' + err.message);
+            } finally {
+                server.close(() => test.done());
+            }
+        });
+    },
+
+    'a download losing its connection mid-chunk should not cause unhandled rejection (Death 3)'(test) {
+        // The reported production crash, end to end over a real socket: a chunked download whose
+        // consumer is applying backpressure, and a connection that goes away with the next
+        // UID FETCH in flight. close() rejects that pending request, and the rejection has to
+        // reach the content stream rather than a promise nobody holds.
+        test.expect(4);
+
+        const CHUNK = 64 * 1024;
+        const TOTAL = CHUNK * 8;
+        let fetchCount = 0;
+
+        const server = createMockServer({
+            onCommand(socket, tag, command) {
+                if (command !== 'UID') {
+                    return;
+                }
+
+                fetchCount++;
+                if (fetchCount > 3) {
+                    // the production event: the socket ends with a UID FETCH pending
+                    socket.destroy();
+                    return true;
+                }
+
+                // one BODY[]<offset> chunk, in the literal form download() asks for
+                socket.write(`* 1 FETCH (UID 1 RFC822.SIZE ${TOTAL} BODY[]<${(fetchCount - 1) * CHUNK}> {${CHUNK}}\r\n`);
+                socket.write(Buffer.alloc(CHUNK, 0x61));
+                socket.write(')\r\n');
+                socket.write(`${tag} OK FETCH completed\r\n`);
+                return true;
+            }
+        });
+
+        server.listen(0, '127.0.0.1', async () => {
+            const client = new ImapFlow({
+                host: '127.0.0.1',
+                port: server.address().port,
+                secure: false,
+                logger: false,
+                disableAutoIdle: true,
+                auth: { user: 'test', pass: 'test' }
+            });
+
+            // the connection is destroyed under the client on purpose
+            client.on('error', () => false);
+
+            const detector = installRejectionDetector(test);
+
+            try {
+                await client.connect();
+                await client.mailboxOpen('INBOX');
+
+                let { content } = await client.download('1', false, { uid: true, chunkSize: CHUNK });
+
+                let received = 0;
+                let streamErr = null;
+                content.on('error', err => {
+                    streamErr = err;
+                });
+                // The delay is load-bearing: it has to outlast a loopback round trip, or the
+                // pipeline drains between chunks, writeChunk() never returns false, and the
+                // backpressure wait this test exists for is never entered
+                content.pipe(slowConsumer({ delay: 30, onChunk: chunk => (received += chunk.length) }));
+
+                await new Promise(resolve => {
+                    content.on('close', resolve);
+                    content.on('error', resolve);
+                });
+                await new Promise(r => setTimeout(r, 100));
+                detector.check();
+
+                test.ok(received >= CHUNK, 'a chunk drained through the consumer before the connection went away');
+                test.ok(streamErr, 'the failure surfaced on the content stream');
+                test.equal(streamErr && streamErr.code, 'NoConnection', 'the caller gets the connection error');
+
                 client.close();
             } catch (err) {
                 detector.check();