imapflow 1.6.6 → 1.7.1

package/test/idle-polling-test.js

@@ -428,3 +428,91 @@ module.exports['Polling: a break in the initiation tick prevents the first poll'
         test.done();
     });
 };
+
+module.exports['Polling: a restarted session resumes the schedule instead of polling again'] = async test => {
+    await withFakeTimers(async timers => {
+        let connection = createConnection();
+
+        let first = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP'], 'the first session polls immediately');
+
+        await connection.preCheck();
+        await first;
+
+        // Auto-IDLE restarts the loop after every caller command. An unconditional first poll here
+        // would tie the poll rate to how often the caller runs commands instead of to the poll
+        // interval - with a short autoIdleDelay, a command every few seconds means a poll every
+        // few seconds.
+        let second = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP'], 'the restarted session does not poll again');
+        test.equal(timers.count(), 1, 'it waits out the remainder of the interval instead');
+        test.ok(timers.pending()[0].delay <= 60000, 'and never longer than a full interval');
+
+        await connection.preCheck();
+        await second;
+
+        // Once a full interval has elapsed, a fresh session polls at once again
+        connection._lastPollAt = Date.now() - 61000;
+        let third = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP', 'NOOP'], 'a session starting after the interval polls right away');
+
+        await connection.preCheck();
+        await third;
+        test.done();
+    });
+};
+
+module.exports['Polling: a failed poll does not defer the next session'] = async test => {
+    await withFakeTimers(async timers => {
+        let failNext = true;
+        let connection = createConnection({
+            exec: async command => {
+                connection.commands.push(command);
+                if (failNext) {
+                    failNext = false;
+                    throw new Error('poll failed');
+                }
+                return { next: () => {} };
+            }
+        });
+
+        // The failing poll cancels its own session. The attempt checked nothing, so it must not
+        // count as a poll: only a completed poll moves the schedule stamp forward.
+        let first = idleCommand(connection, 60000);
+        await timers.drain();
+        await first;
+        test.deepEqual(connection.commands, ['NOOP'], 'the first poll ran and failed');
+
+        let second = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, ['NOOP', 'NOOP'], 'the next session retries immediately instead of waiting out an interval');
+
+        await connection.preCheck();
+        await second;
+        test.done();
+    });
+};
+
+module.exports['Polling: a backward clock step never defers the next poll past one interval'] = async test => {
+    await withFakeTimers(async timers => {
+        let connection = createConnection();
+
+        // A last-poll stamp in the future is what an NTP step or a VM clock sync leaves behind.
+        // Without the clamp the remainder math would schedule the next poll a full clock jump
+        // plus one interval away.
+        connection._lastPollAt = Date.now() + 60 * 60 * 1000;
+
+        let idlePromise = idleCommand(connection, 60000);
+        await timers.drain();
+        test.deepEqual(connection.commands, [], 'no immediate poll - the schedule is resumed');
+        test.equal(timers.count(), 1, 'a poll timer is armed');
+        test.ok(timers.pending()[0].delay <= 60000, 'and it is never more than one interval away');
+
+        await connection.preCheck();
+        await idlePromise;
+        test.done();
+    });
+};

package/test/imap-flow-coverage-test.js

@@ -5,6 +5,7 @@
 // reader/handler error branches.
 
 const { ImapFlow } = require('../lib/imap-flow');
+const { makeSocketStub } = require('./fixtures/test-client');
 
 const makeClient = (overrides = {}) => {
     let client = new ImapFlow({
@@ -293,15 +294,6 @@ module.exports['Coverage: authenticate throws when run yields falsy auth result'
 // Socket event handlers (built by setSocketHandlers)
 // ============================================================================
 
-// Minimal socket stub that records listeners so handlers can be invoked directly.
-const makeSocketStub = () => ({
-    destroyed: false,
-    once() {},
-    on() {},
-    removeListener() {},
-    destroy() {}
-});
-
 module.exports['Coverage: setSocketHandlers removes a lingering connect error handler'] = test => {
     let client = makeClient();
     let removed = null;
@@ -389,7 +381,9 @@ module.exports['Coverage: _socketTimeout recovers an IDLE connection with NOOP']
     await drain();
     await drain();
     test.ok(noopRun, 'NOOP issued to recover IDLE');
-    test.ok(idleResumed, 'IDLE resumed after NOOP');
+    // Restarting IDLE is autoidle()'s decision once the NOOP settles (run() re-arms it);
+    // the watchdog handler itself must not bypass the busy guard by calling idle() directly.
+    test.equal(idleResumed, false, 'the handler does not restart IDLE by itself');
     test.done();
 };
 

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

@@ -9,6 +9,7 @@ const libbase64 = require('libbase64');
 const libqp = require('libqp');
 const libmime = require('libmime');
 const { Writable, finished } = require('stream');
+const { chunkedFetchOne } = require('./fixtures/test-client');
 
 const makeClient = (overrides = {}) => {
     let client = new ImapFlow({
@@ -217,11 +218,7 @@ module.exports['Download: returns empty object without mailbox'] = async test =>
 module.exports['Download: full message in multiple chunks'] = async test => {
     let client = makeClient();
     let body = Buffer.from('A'.repeat(10));
-    client.fetchOne = async (range, query) => {
-        let start = query.source.start;
-        let maxLength = query.source.maxLength;
-        return { uid: 1, size: body.length, source: body.slice(start, start + maxLength) };
-    };
+    client.fetchOne = chunkedFetchOne(body);
     let { meta, content } = await client.download('1', false, { chunkSize: 4 });
     test.equal(meta.contentType, 'message/rfc822');
     test.equal(meta.expectedSize, 10);
@@ -233,11 +230,7 @@ module.exports['Download: full message in multiple chunks'] = async test => {
 module.exports['Download: falls back to default chunkSize/maxBytes when zero'] = async test => {
     let client = makeClient();
     let body = Buffer.from('tiny');
-    client.fetchOne = async (range, query) => {
-        let start = query.source.start;
-        let maxLength = query.source.maxLength;
-        return { uid: 1, size: body.length, source: body.slice(start, start + maxLength) };
-    };
+    client.fetchOne = chunkedFetchOne(body);
     // zero values are falsy -> the (|| default) fallbacks kick in
     let { content } = await client.download('1', false, { chunkSize: 0, maxBytes: 0 });
     let data = await collect(content);

package/test/imap-flow-internals-test.js

@@ -6,17 +6,8 @@
 // and the untaggedFetch flag/modseq branches.
 
 const { ImapFlow } = require('../lib/imap-flow');
-
-const makeClient = (overrides = {}) => {
-    let client = new ImapFlow({
-        host: 'imap.example.com',
-        port: 993,
-        auth: { user: 'test', pass: 'test' },
-        logger: false,
-        ...overrides
-    });
-    return client;
-};
+const { withFakeTimers } = require('./fixtures/fake-timers');
+const { makeClient, makeIdleReadyClient } = require('./fixtures/test-client');
 
 // ============================================================================
 // emitError
@@ -179,27 +170,79 @@ module.exports['Internals: write returns false for non-string non-buffer'] = tes
     test.done();
 };
 
-module.exports['Internals: write logs raw data when logRaw enabled'] = test => {
+// A writable client whose raw traffic log is captured, for the two logRaw branches
+const makeRawLogClient = rawSensitiveCommand => {
     let logs = [];
-    let client = makeClient({ logRaw: true });
-    client.log = {
-        trace: o => logs.push(o),
-        debug: () => {},
-        warn: () => {},
-        error: () => {},
-        info: () => {}
-    };
     let written = [];
+    let client = makeClient({ logRaw: true });
+    client.log = { trace: o => logs.push(o), debug: () => {}, warn: () => {}, error: () => {}, info: () => {} };
     client.socket = { destroyed: false };
     client.writeSocket = { destroyed: false, write: c => written.push(c) };
-    client.state = client.states.AUTHENTICATED;
-    client.commandParts = [];
+    client.rawSensitiveCommand = rawSensitiveCommand;
+    return { client, logs, written };
+};
+
+module.exports['Internals: write logs raw data when logRaw enabled'] = test => {
+    let { client, logs, written } = makeRawLogClient(false);
     client.write('A NOOP');
-    test.ok(logs.some(l => l.src === 'c' && l.msg === 'write to socket'));
+    let entry = logs.find(l => l.src === 'c' && l.msg === 'write to socket');
+    test.ok(entry);
+    test.equal(Buffer.from(entry.data, 'base64').toString(), 'A NOOP\r\n');
+    test.ok(!entry.hidden);
     test.equal(written.length, 1);
     test.done();
 };
 
+module.exports['Internals: write withholds raw data for a credential-bearing command'] = test => {
+    // send() sets this for LOGIN/AUTHENTICATE before the first frame reaches the socket
+    let { client, logs, written } = makeRawLogClient(true);
+    client.write('A1 LOGIN "user" "hunter2"');
+    let entry = logs.find(l => l.src === 'c' && l.msg === 'write to socket');
+    test.ok(entry);
+    test.ok(entry.hidden);
+    // The placeholder is fixed width, so the entry cannot disclose the password length
+    test.equal(Buffer.from(entry.data, 'base64').toString(), '(* value hidden *)\r\n');
+    // The frame itself is still written to the socket unchanged
+    test.equal(written[0].toString(), 'A1 LOGIN "user" "hunter2"\r\n');
+    test.done();
+};
+
+module.exports['Internals: send marks credential-bearing commands for the raw log'] = async test => {
+    let client = makeClient();
+    let written = [];
+    client.socket = { destroyed: false };
+    client.writeSocket = { destroyed: false, write: c => written.push(c) };
+
+    // Lower case on purpose: the wire protocol is case-insensitive and exec() passes the
+    // caller's spelling through unchanged, so the classification must normalize it
+    await client.send({
+        tag: 'A1',
+        command: 'login',
+        attributes: [
+            { type: 'STRING', value: 'user' },
+            { type: 'STRING', value: 'hunter2', sensitive: true }
+        ],
+        options: {}
+    });
+    test.equal(client.rawSensitiveCommand, true);
+
+    await client.send({ tag: 'A2', command: 'NOOP', attributes: [], options: {} });
+    test.equal(client.rawSensitiveCommand, false);
+
+    // A command outside the list still masks if it marks an attribute sensitive, so the
+    // declarative marker alone is enough to keep a new command out of the raw log. Nested
+    // because the command compiler honors the marker at any depth.
+    await client.send({
+        tag: 'A3',
+        command: 'SETMETADATA',
+        attributes: [{ type: 'ATOM', value: 'INBOX' }, [{ type: 'STRING', value: 'token', sensitive: true }]],
+        options: {}
+    });
+    test.equal(client.rawSensitiveCommand, true);
+
+    test.done();
+};
+
 module.exports['Internals: write appends CRLF only on final part'] = test => {
     let client = makeClient();
     let written = [];
@@ -275,29 +318,20 @@ module.exports['Internals: autoidle does nothing when not selected'] = test => {
     test.done();
 };
 
-module.exports['Internals: autoidle schedules idle when selected'] = test => {
-    let client = makeClient();
-    client.state = client.states.SELECTED;
+module.exports['Internals: autoidle schedules idle when selected'] = async test => {
+    await withFakeTimers(async timers => {
+        let client = makeIdleReadyClient();
+
+        let idleCalled = false;
+        client.idle = async () => {
+            idleCalled = true;
+        };
 
-    let realSetTimeout = global.setTimeout;
-    let idleCalled = false;
-    client.idle = async () => {
-        idleCalled = true;
-    };
-    // Intercept the 15s idle timer and fire it synchronously
-    global.setTimeout = (fn, ms) => {
-        if (ms === 15 * 1000) {
-            fn();
-            return { unref() {} };
-        }
-        return realSetTimeout(fn, ms);
-    };
-    try {
         client.autoidle();
-    } finally {
-        global.setTimeout = realSetTimeout;
-    }
-    test.ok(idleCalled);
+        await timers.fire();
+
+        test.ok(idleCalled);
+    });
     test.done();
 };
 
@@ -322,7 +356,7 @@ module.exports['Internals: getLogger uses provided logger object'] = test => {
 };
 
 module.exports['Internals: getLogger falls back to console for missing fatal/error level'] = test => {
-    // Logger object missing the 'error' method -> falls through to console.log
+    // Logger object missing the 'error' method -> falls through to console.error
     let partial = {
         trace() {},
         debug() {},
@@ -331,15 +365,99 @@ module.exports['Internals: getLogger falls back to console for missing fatal/err
         // no error, no fatal
     };
     let client = makeClient({ logger: partial });
-    let origConsoleLog = console.log;
+    let origConsoleError = console.error;
     let logged = [];
-    console.log = (...args) => logged.push(args);
+    console.error = (...args) => logged.push(args);
     try {
-        client.log.error({ msg: 'boom' });
+        let err = new Error('boom failure');
+        err.code = 'XBOOM';
+        // The answer is often one level down: this library attaches the underlying failure
+        // as an enumerable `_err`
+        err._err = Object.assign(new Error('inner failure'), { code: 'ECONNREFUSED' });
+        client.log.error({ msg: 'boom', err });
+        // A circular structure must not throw out of the log call, and must not be dropped
+        let circular = { msg: 'loop' };
+        circular.self = circular;
+        client.log.error(circular);
     } finally {
-        console.log = origConsoleLog;
+        console.error = origConsoleError;
     }
-    test.ok(logged.length >= 1);
+    test.equal(logged.length, 2);
+    // The Error was flattened, so message, stack and enumerable fields survive stringify
+    let entry = JSON.parse(logged[0][0]);
+    test.equal(entry.msg, 'boom');
+    test.equal(entry.err.message, 'boom failure');
+    test.equal(entry.err.code, 'XBOOM');
+    test.ok(entry.err.stack);
+    test.equal(entry.err._err.message, 'inner failure');
+    test.equal(entry.err._err.code, 'ECONNREFUSED');
+    // Unserializable entries still reach console.error, just not as JSON
+    test.equal(logged[1][0].msg, 'loop');
+    test.done();
+};
+
+module.exports['Internals: getLogger keeps cause and AggregateError members'] = test => {
+    let client = makeClient({ emitLogs: true });
+    let entries = [];
+    client.on('log', entry => entries.push(entry));
+
+    let inner = Object.assign(new Error('inner failure'), { code: 'ECONNREFUSED' });
+    client.log.error({ msg: 'wrapped', err: new Error('outer failure', { cause: inner }) });
+    // Node reports a multi-address connect failure as an AggregateError
+    client.log.error({ msg: 'aggregate', err: new AggregateError([inner], 'all attempts failed') });
+
+    test.equal(entries[0].err.cause.message, 'inner failure');
+    test.equal(entries[0].err.cause.code, 'ECONNREFUSED');
+    test.equal(entries[1].err.errors.length, 1);
+    test.equal(entries[1].err.errors[0].message, 'inner failure');
+    test.done();
+};
+
+module.exports['Internals: getLogger bounds a looping and a deep error chain'] = test => {
+    let client = makeClient({ emitLogs: true });
+    let entries = [];
+    client.on('log', entry => entries.push(entry));
+
+    // A chain that loops back must terminate rather than recurse forever
+    let looping = new Error('looping failure');
+    looping._err = looping;
+    client.log.error({ msg: 'loop', err: looping });
+    test.equal(entries[0].err.message, 'looping failure');
+    test.equal(entries[0].err._err, 'looping failure');
+
+    // A chain longer than the depth cap is truncated rather than walked to the end
+    let deep = new Error('level 0');
+    for (let i = 1; i <= 6; i++) {
+        deep = Object.assign(new Error(`level ${i}`), { _err: deep });
+    }
+    client.log.error({ msg: 'deep', err: deep });
+    test.equal(entries[1].err._err._err._err.message, 'level 3');
+    // Past the cap the chain collapses to messages instead of being walked to the end
+    test.equal(entries[1].err._err._err._err._err, 'level 2');
+
+    test.done();
+};
+
+module.exports['Internals: getLogger never throws out of a log call'] = test => {
+    let client = makeClient({ emitLogs: true });
+    let entries = [];
+    client.on('log', entry => entries.push(entry));
+
+    // A throwing property getter on the logged error must not escape
+    let hostile = {
+        get message() {
+            throw new Error('getter blew up');
+        },
+        stack: 'x'
+    };
+    test.doesNotThrow(() => client.log.warn({ msg: 'hostile', err: hostile }));
+
+    // Neither must a throwing 'log' listener
+    client.on('log', () => {
+        throw new Error('listener blew up');
+    });
+    test.doesNotThrow(() => client.log.warn({ msg: 'still fine' }));
+
     test.done();
 };
 

package/test/timer-policy-test.js

@@ -9,9 +9,9 @@
 // Asserted through timer identity and cleanup rather than wall-clock sleeps.
 
 const net = require('net');
-const { ImapFlow } = require('../lib/imap-flow');
 const idleCommand = require('../lib/commands/idle.js');
 const { withFakeTimers } = require('./fixtures/fake-timers');
+const { makeClient, makeIdleReadyClient } = require('./fixtures/test-client');
 
 const CAPS = 'IMAP4rev1 ID ENABLE NAMESPACE IDLE';
 
@@ -52,15 +52,6 @@ const createServer = () =>
 
 const listen = server => new Promise(resolve => server.listen(0, '127.0.0.1', () => resolve(server.address().port)));
 
-const makeClient = (overrides = {}) =>
-    new ImapFlow({
-        host: '127.0.0.1',
-        port: 993,
-        logger: false,
-        auth: { user: 'test', pass: 'secret' },
-        ...overrides
-    });
-
 module.exports['Timers: connection and greeting deadlines keep the process alive'] = async test => {
     let server = createServer();
     let port = await listen(server);
@@ -99,15 +90,13 @@ module.exports['Timers: connection and greeting deadlines keep the process alive
 
 module.exports['Timers: the auto-IDLE timer is unrefd and cleared on close'] = async test => {
     await withFakeTimers(async timers => {
-        let client = makeClient();
-        client.state = client.states.SELECTED;
-        client.idle = async () => {};
+        let client = makeIdleReadyClient();
 
         client.autoidle();
 
         let armed = timers.pending();
         test.equal(armed.length, 1, 'exactly one auto-IDLE timer is armed');
-        test.equal(armed[0].delay, 15 * 1000);
+        test.equal(armed[0].delay, client.autoIdleDelay);
         test.ok(armed[0].unrefd, 'the background auto-IDLE timer does not keep the process alive');
 
         client.close();
@@ -119,9 +108,7 @@ module.exports['Timers: the auto-IDLE timer is unrefd and cleared on close'] = a
 
 module.exports['Timers: a restarted auto-IDLE timer replaces the previous one'] = async test => {
     await withFakeTimers(async timers => {
-        let client = makeClient();
-        client.state = client.states.SELECTED;
-        client.idle = async () => {};
+        let client = makeIdleReadyClient();
 
         client.autoidle();
         client.autoidle();