imapflow 2.5.8 → 2.6.0

package/dist/esm/imap-flow.js

@@ -168,6 +168,18 @@ export class ImapFlow extends EventEmitter {
      * Current module version as a static class property
      */
     static { this.version = packageInfo.version; }
+    /**
+     * The mailboxes a `verifyOnly` connection with `includeMailboxes` listed before it logged out,
+     * `undefined` otherwise
+     *
+     * @example
+     * let client = new ImapFlow({ ..., verifyOnly: true, includeMailboxes: true });
+     * await client.connect();
+     * console.log(client.mailboxList.map(mailbox => mailbox.path));
+     */
+    get mailboxList() {
+        return this._mailboxList;
+    }
     /**
      * Creates a client for one IMAP connection. Nothing is sent before `connect()` is called
      */
@@ -219,6 +231,7 @@ export class ImapFlow extends EventEmitter {
         this._throttleWaits = new Set();
         this._upgradeReject = null;
         this.isClosed = false;
+        this._errorReported = false;
         this.states = states;
         this.state = this.states.NOT_AUTHENTICATED;
         this.lockCounter = 0;
@@ -243,6 +256,9 @@ export class ImapFlow extends EventEmitter {
         this.mailbox = false;
         this.currentSelectCommand = false;
         this.idling = false;
+        this.context = this.options.context;
+        this.connectedAt = null;
+        this.lastClientWrite = null;
         this.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
         this.untaggedHandlers = {};
@@ -288,6 +304,15 @@ export class ImapFlow extends EventEmitter {
             return;
         }
         err._connId = err._connId || this.id;
+        // One error per connection: emitError() closes the connection, and until the deferred
+        // close() runs a second socket, deflate or parser error may still arrive. Emitting it as
+        // well would reach a consumer that removed its listener after the first one, or one that
+        // only awaited connect(), as an unhandled 'error' that throws.
+        if (this._errorReported) {
+            this.log.debug({ msg: 'Suppressed error after the connection already reported one', err, cid: this.id });
+            this.closeAfter();
+            return;
+        }
         // During a STARTTLS handshake the upgrade owns the single error path (its settle()
         // helper). Route the error there so a streamer-originated failure is surfaced with its
         // real code (instead of a generic ClosedAfterConnect*) and cannot hang a verifyOnly
@@ -298,6 +323,7 @@ export class ImapFlow extends EventEmitter {
             this._upgradeReject = null;
             if (typeof reject === 'function') {
                 // settle() clears the upgrade timer and flags, and closes the connection
+                this._errorReported = true;
                 reject(err);
                 return;
             }
@@ -312,10 +338,12 @@ export class ImapFlow extends EventEmitter {
             let reject = this.initialReject;
             this.initialResolve = false;
             this.initialReject = false;
+            this._errorReported = true;
             this.closeAfter();
             reject(err);
             return;
         }
+        this._errorReported = true;
         this.closeAfter();
         this.emit('error', err);
     }
@@ -369,6 +397,7 @@ export class ImapFlow extends EventEmitter {
         else {
             return false;
         }
+        this.lastClientWrite = Date.now();
         for (let data of frames) {
             if (this.logRaw) {
                 // Client frames of an authentication exchange carry credentials: the LOGIN
@@ -827,9 +856,17 @@ export class ImapFlow extends EventEmitter {
     async handleResponse(data) {
         let parsed;
         try {
-            parsed = await parser(data.payload, { literals: data.literals });
+            parsed = await parser(data.payload, { literals: data.literals, maxResponseTokens: this.options.maxResponseTokens });
         }
         catch (err) {
+            if (err.code === 'TooManyTokens') {
+                // A size limit, so as terminal as the ones ImapStream enforces: the server is
+                // flooding responses, and skipping the line would only invite the next one
+                this.log.error({ msg: 'Response exceeded the token limit', payloadBytes: data.payload.length, err, cid: this.id });
+                this.rejectCurrentRequest(err);
+                this.failProtocol(err);
+                return false;
+            }
             // can not make sense of this. The payload can be up to the configured line
             // cap (1GB by default), so log only a bounded prefix: a server looping
             // unparseable garbage would otherwise turn this error log into a disk filler.
@@ -1251,7 +1288,9 @@ export class ImapFlow extends EventEmitter {
                     }
                 });
         const socket = this.socket;
-        socket.once('error', this._socketError);
+        // on(), not once(): with compression the deflate and writeSocket errors are forwarded
+        // onto this socket, and a second one before close() must not find it without a listener
+        socket.on('error', this._socketError);
         socket.once('close', this._socketClose);
         socket.once('end', this._socketEnd);
         socket.on('tlsClientError', this._socketError);
@@ -2230,6 +2269,7 @@ export class ImapFlow extends EventEmitter {
                 }
                 try {
                     clearTimer(this.connectTimeout);
+                    this.connectedAt = Date.now();
                     // ImapFlow now owns the socket; drop the proxy's early error handler
                     // (its "before connection setup" message no longer applies).
                     detachEarlyErrorHandler(socket);
@@ -2355,6 +2395,15 @@ export class ImapFlow extends EventEmitter {
         }
         return error;
     }
+    // What a message command called without a selected mailbox rejects with: NoMailboxSelected,
+    // or NoConnection once the connection is gone, as that is why the mailbox is missing then
+    /** @internal */
+    createNoMailboxError(command) {
+        if (!this.usable) {
+            return this.createNoConnectionError(this.byeReason, { rejectedFrom: 'noMailbox', command });
+        }
+        return createImapError('No mailbox is selected', 'NoMailboxSelected', { command });
+    }
     /**
      * Closes TCP connection without notifying the server.
      *
@@ -2795,8 +2844,14 @@ export class ImapFlow extends EventEmitter {
                 // LIST. This sets mailboxMissing on the error so the caller can distinguish
                 // "doesn't exist" from other failures, for getMailboxLock() callers as well.
                 try {
-                    let folders = await this.run('LIST', '', normalizePath(this, path), { listOnly: true });
-                    if (!folders || !folders.length) {
+                    let normalized = normalizePath(this, path);
+                    let folders = await this.run('LIST', '', normalized, { listOnly: true });
+                    // The path is the LIST pattern, so a % or * in a name also matches other
+                    // mailboxes, and an entry marked \NonExistent (RFC 5258) does not exist either
+                    let exists = Array.isArray(folders) &&
+                        folders.some(entry => comparePaths(this, entry.path, normalized) &&
+                            ![...(entry.flags || [])].some(flag => typeof flag === 'string' && flag.toUpperCase() === '\\NONEXISTENT'));
+                    if (!exists) {
                         err.mailboxMissing = true;
                     }
                 }
@@ -2839,6 +2894,9 @@ export class ImapFlow extends EventEmitter {
      * otherwise IDLE is started by default on connection inactivity. NB! If `idle()` is called manually then it does not
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
+     * Unlike auto-IDLE, a direct call does not wait for the connection to be free: a mailbox lock
+     * holder may idle inside its own lock, and idle() can not tell it from another caller.
+     *
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -3092,6 +3150,9 @@ export class ImapFlow extends EventEmitter {
      * @param query Fetch query
      * @param options Fetch options
      * @yields Message data object
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected (for example
+     *   after `mailboxClose()` or a failed `mailboxOpen()`), or `NoConnection` once the connection
+     *   is gone. Earlier releases yielded nothing in that case, as for an empty mailbox
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -3105,8 +3166,8 @@ export class ImapFlow extends EventEmitter {
     async *fetch(range, query, options) {
         options = options || {};
         if (!this.mailbox) {
-            // no mailbox selected, nothing to do
-            return;
+            // an empty result would look like an empty mailbox, for example right after close()
+            throw this.createNoMailboxError('FETCH');
         }
         let resolved = await this.resolveRange(range, options);
         if (!resolved) {
@@ -3216,6 +3277,7 @@ export class ImapFlow extends EventEmitter {
      * @param query Fetch query
      * @param options Fetch options
      * @returns Array of Message data object
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected, see fetch()
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -3239,7 +3301,9 @@ export class ImapFlow extends EventEmitter {
      * @param seq Single UID or sequence number of the message to fetch for
      * @param query Fetch query
      * @param options Fetch options
-     * @returns Message data object
+     * @returns Message data object, `false` when the message was not found
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected, see fetch().
+     *   Earlier releases resolved `undefined` then
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -3249,8 +3313,9 @@ export class ImapFlow extends EventEmitter {
      */
     async fetchOne(seq, query, options) {
         if (!this.mailbox) {
-            // no mailbox selected, nothing to do
-            return;
+            // undefined used to be returned here, indistinguishable from a missing message for a
+            // caller that only tests the result
+            throw this.createNoMailboxError('FETCH');
         }
         if (seq === '*') {
             if (!this.mailbox.exists) {
@@ -3428,6 +3493,9 @@ export class ImapFlow extends EventEmitter {
             return;
         }
         this.processingLock = true;
+        // The lock taken off the queue and not settled yet. A pass that throws out of its loop
+        // rejects it, its caller would wait forever otherwise: it is in the queue no longer.
+        let unsettled = null;
         try {
             // Process all locks in queue until empty
             let processedCount = 0;
@@ -3444,6 +3512,7 @@ export class ImapFlow extends EventEmitter {
                     await new Promise(resolve => setImmediate(resolve));
                 }
                 const lock = this.locks.shift();
+                unsettled = lock;
                 const { resolve, reject, path, options, lockId } = lock;
                 // From here on the grant/reject path owns the outcome; the acquire
                 // timer must not race with resolution.
@@ -3509,6 +3578,7 @@ export 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 });
+                    unsettled = null;
                     reject(this.createNoConnectionError(false, { rejectedFrom: 'mailboxLock', path }));
                     continue; // Process next lock in queue
                 }
@@ -3521,6 +3591,7 @@ export class ImapFlow extends EventEmitter {
                     this.currentLock = lock;
                     armHeldTimer();
                     this.autoidle();
+                    unsettled = null;
                     resolve({ path, release });
                 };
                 if (this.mailbox && this.mailbox.path === path && !!this.mailbox.readOnly === !!options.readOnly) {
@@ -3563,23 +3634,35 @@ export class ImapFlow extends EventEmitter {
                         ...(options.description && { description: options.description }),
                         err
                     });
+                    unsettled = null;
                     reject(err);
                     // Continue to next lock in queue
                 }
             }
         }
+        catch (err) {
+            if (unsettled) {
+                let lock = unsettled;
+                unsettled = null;
+                // granted but not handed out (the grant itself failed): nobody can release it
+                if (this.currentLock === lock) {
+                    clearTimer(lock.heldWarnTimer);
+                    lock.heldWarnTimer = null;
+                    this.currentLock = false;
+                }
+                lock.reject(err);
+            }
+            throw err;
+        }
         finally {
             this.processingLock = false;
-            // New locks may have been queued while we were processing (e.g.,
-            // a lock that failed immediately and the next getMailboxLock call
-            // arrived before we finished). Schedule another run if needed.
-            /* c8 ignore start */ // requires a lock to be enqueued during an in-flight processLocks pass; not reproducible deterministically
+            // A pass that ended with locks queued and none held (it threw out of its loop) would
+            // leave them waiting with nothing to start another pass. Schedule one.
             if (this.locks.length && !this.currentLock) {
                 setImmediate(() => {
                     this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
                 });
             }
-            /* c8 ignore stop */
         }
     }
     /**
@@ -3773,7 +3856,8 @@ export class ImapFlow extends EventEmitter {
  */
 /**
  * Error event. In most cases getting an error event also means that connection is closed
- * and pending operations should return with a failure.
+ * and pending operations should return with a failure. Emitted at most once per connection,
+ * later errors while the connection is closing are only logged.
  *
  * @event ImapFlow#error
  * @example

package/dist/esm/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.5.8";
+export declare const version = "2.6.0";
 export declare const homepage = "https://imapflow.com/";

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.5.8";
+export const version = "2.6.0";
 export const homepage = "https://imapflow.com/";

package/dist/esm/types.d.ts

@@ -76,8 +76,13 @@ export interface ImapFlowOptions {
     emitLogs?: boolean | undefined;
     /** If true, then logs out automatically after successful authentication */
     verifyOnly?: boolean | undefined;
-    /** If true and verifyOnly is set, lists mailboxes */
+    /** If true and verifyOnly is set, lists mailboxes. The listing is in `client.mailboxList` once `connect()` resolved */
     includeMailboxes?: boolean | undefined;
+    /**
+     * Data of the application's own to keep with the client, such as the account the connection
+     * belongs to. ImapFlow never reads it, it is the initial value of `client.context`
+     */
+    context?: unknown;
     /**
      * Proxy URL. Supports HTTP CONNECT (http:, https:) and SOCKS (socks:, socks4:, socks4a:,
      * socks5:) proxies. IPv6 proxy endpoints are given in URL form, e.g. `socks5://[2001:db8::1]:1080`.
@@ -133,8 +138,9 @@ export interface ImapFlowOptions {
      * whatever is left of `maxResponseSize`, so lowering that also bounds line buffering.
      * Exceeding it is terminal: the connection fails with error code `LineTooLarge` and
      * no further input is parsed. The limit bounds the bytes of a line, not the memory its parse
-     * takes, which is several times the line size for a line of many small tokens. A SEARCH
-     * answer of plain numbers is read into an array of about the size of the line.
+     * takes, which is several times the line size for a line of many small tokens, see
+     * `maxResponseTokens`. A SEARCH answer of plain numbers is read into an array of about the
+     * size of the line.
      */
     maxLineLength?: number | undefined;
     /**
@@ -159,6 +165,16 @@ export interface ImapFlowOptions {
      * no further input is parsed.
      */
     maxResponseSize?: number | undefined;
+    /**
+     * Maximum number of tokens (atoms, strings, literals, lists and other parse tree nodes) in a
+     * single IMAP response. The byte limits bound what a server sends, this bounds what parsing it
+     * costs: each token takes around a hundred bytes of heap while the response is parsed, so a
+     * response of many small tokens costs about fifty times its size. Defaults to 1000000, far
+     * above any legitimate response (a SEARCH answer of plain numbers is not tokenized and does
+     * not count). Lower it in a memory-limited runtime. `Infinity` disables the limit. Exceeding it
+     * is terminal: the connection fails with error code `TooManyTokens`.
+     */
+    maxResponseTokens?: number | undefined;
     /**
      * Threshold in milliseconds for warning that a mailbox lock has been held
      * for a long time (diagnostic for forgotten release() calls). Defaults to
@@ -681,9 +697,12 @@ export type DownloadManyResult = {
 export interface AppendResponseObject {
     /** Full mailbox path where the message was uploaded to */
     destination: string;
-    /** Mailbox UIDVALIDITY if server has UIDPLUS extension enabled */
+    /** Mailbox UIDVALIDITY if server has UIDPLUS extension enabled, only set together with the `uid` it reported */
     uidValidity?: bigint | undefined;
-    /** UID of the uploaded message if server has UIDPLUS extension enabled */
+    /**
+     * UID of the uploaded message if server has UIDPLUS extension enabled. Without a usable APPENDUID,
+     * an append to the selected mailbox looks it up by sequence number instead, and `uidValidity` is not set
+     */
     uid?: number | undefined;
     /** Sequence number of the uploaded message if path is currently selected mailbox */
     seq?: number | undefined;
@@ -775,6 +794,22 @@ export interface ExistsEvent {
     /** Message count before this update */
     prevCount: number;
 }
+/**
+ * Payload of the `highestModseq` event: the HIGHESTMODSEQ of the selected mailbox changed (RFC
+ * 7162), so flags or other message metadata changed on the server. Emitted when a poll on a
+ * server without IDLE (`missingIdleCommand` STATUS or SELECT) or a STATUS or re-SELECT of the
+ * open mailbox reports a new value, which is when the changes themselves are not delivered as
+ * `flags` events. A consumer resynchronizes with `fetch(range, { flags: true }, { changedSince:
+ * prevHighestModseq })`.
+ */
+export interface HighestModseqEvent {
+    /** Mailbox path */
+    path: string;
+    /** The new HIGHESTMODSEQ value */
+    highestModseq: bigint;
+    /** The value before this update, undefined when none was known */
+    prevHighestModseq?: bigint | undefined;
+}
 export interface FlagsEvent {
     /** Mailbox path */
     path: string;
@@ -874,7 +909,10 @@ export interface TlsInfo extends CipherNameAndProtocol {
 export interface ImapFlowEvents {
     /** Connection close event */
     close: [];
-    /** Error event */
+    /**
+     * Error event. Emitted at most once per connection, the connection closes after it. An error
+     * while `connect()` is pending rejects `connect()` instead and is not emitted
+     */
     error: [error: Error];
     /** Message count in currently opened mailbox changed */
     exists: [data: ExistsEvent];
@@ -882,7 +920,13 @@ export interface ImapFlowEvents {
     expunge: [data: ExpungeEvent];
     /** Flags were updated for a message */
     flags: [data: FlagsEvent];
-    /** Mailbox was opened */
+    /** The HIGHESTMODSEQ of the selected mailbox changed without the changes being reported, see {@link HighestModseqEvent} */
+    highestModseq: [data: HighestModseqEvent];
+    /**
+     * Mailbox was opened. Also emitted, after `mailboxClose` for the old mailbox object, when the
+     * open mailbox turned out to have a new UIDVALIDITY (a re-SELECT, or a STATUS poll on a server
+     * without IDLE, which then selects the mailbox again): every cached UID of it is invalid
+     */
     mailboxOpen: [mailbox: MailboxObject];
     /** Mailbox was closed, either explicitly or because the connection went away while a mailbox was still selected */
     mailboxClose: [mailbox: MailboxObject];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.5.8",
+    "version": "2.6.0",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -93,8 +93,8 @@
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
-        "typescript-eslint": "8.71.2",
-        "wrangler": "4.151.2"
+        "typescript-eslint": "8.72.0",
+        "wrangler": "4.151.3"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.27",