imapkit 4.3.0 → 5.0.0

package/dist/esm/server.js

@@ -13,8 +13,13 @@ import { hasSequenceSetKey } from './commands/handlers/search.js';
 import { isSequenceSet } from './numbers.js';
 import { restoreNilAtoms } from './arguments.js';
 import { refuseMissingTarget } from './commands/append.js';
+import { DEFAULT_SESSION_TIMEOUT, storeError, expungeMessages, notifyFlagChanges } from './store-operations.js';
+import { Control } from './control.js';
+import { resolveQuirks } from './quirks.js';
+import { validateStorage } from './storage-schema.js';
+import { createRestServer } from './rest.js';
 import * as bundledCert from './cert.js';
-import { ServerScript, sendOutput, handleLine, literalResponse, releaseDeferred } from './script.js';
+import { ServerScript, sendOutput, handleLine, handleQuiet, literalResponse, releaseDeferred } from './script.js';
 // longest command line (not counting literals) accepted from a client
 const MAX_LINE_LENGTH = 1024 * 1024;
 // milliseconds between the last output and the RST of a script rule with `close: 'reset'`
@@ -59,18 +64,6 @@ function getResponseTag(line) {
 function stateError(command, state) {
     return command + ' is not allowed in the ' + state + ' state';
 }
-/**
- * Creates an error for a failed mailbox operation, with a RFC 5530 response code
- *
- * @param {String} message Error message
- * @param {String} code Response code, e.g. "ALREADYEXISTS"
- * @return {Error} Error object
- */
-function mailboxError(message, code) {
-    const err = new Error(message);
-    err.code = code;
-    return err;
-}
 /**
  * Creates a new IMAP server, call `listen()` on it to start accepting connections
  *
@@ -159,11 +152,33 @@ class IMAPServer extends Stream {
         // the session whose command is running, see IMAPServer#notify
         this.activeConnection = null;
         this.sessionCounter = 0;
-        // rules that make the server misbehave on purpose, from the script option or server.script.add()
+        // rules that make the server misbehave on purpose, from the script option or server.script.add(), and the rules
+        // of the quirk presets after them
         this.script = new ServerScript(this, this.options.script);
-        // users and storage are deep copied, so that runtime changes never leak into
-        // the caller's objects or into other servers built from the same fixture.
-        // Without a prototype, user names like "__proto__" or "toString" are plain keys
+        const quirks = resolveQuirks(this.options.quirks);
+        if (quirks.rules.length) {
+            this.script.add(quirks.rules);
+        }
+        this.loadUsers();
+        // plugins register their control operations
+        this.control = new Control(this);
+        // a quirk preset can leave plugins out (no-move, no-uidplus)
+        loadPlugins(this, this.options.plugins, [...quirks.removePlugins]);
+        if (this.options.storage) {
+            // a typo in a fixture fails here with the path of the problem
+            validateStorage(this.options.storage);
+        }
+        this.systemFlags = [].concat(this.options.systemFlags || ['\\Answered', '\\Flagged', '\\Draft', '\\Deleted', '\\Seen']);
+        this.loadStorage();
+        this.smtpServer = null;
+        this.restServer = null;
+    }
+    /**
+     * Sets the users from the `users` option, or the default user. The users are deep copied, so that runtime changes
+     * never leak into the caller's objects or into other servers built from the same fixture. Without a prototype,
+     * user names like "__proto__" or "toString" are plain keys
+     */
+    loadUsers() {
         this.users = Object.assign(Object.create(null), this.options.users
             ? structuredClone(this.options.users)
             : {
@@ -171,12 +186,16 @@ class IMAPServer extends Stream {
                     password: 'testpass',
                     xoauth2: {
                         accessToken: 'testtoken',
-                        sessionTimeout: 3600 * 1000
+                        sessionTimeout: DEFAULT_SESSION_TIMEOUT
                     }
                 }
             });
-        loadPlugins(this, this.options.plugins);
-        this.systemFlags = [].concat(this.options.systemFlags || ['\\Answered', '\\Flagged', '\\Draft', '\\Deleted', '\\Seen']);
+    }
+    /**
+     * Builds the mailboxes from the `storage` option, a deep copy of it. Message and mailbox handlers of plugins run
+     * on every message and mailbox
+     */
+    loadStorage() {
         // indexFolders() below turns the storage option into namespaces and mailboxes in place
         this.storage = (this.options.storage
             ? structuredClone(this.options.storage)
@@ -184,6 +203,7 @@ class IMAPServer extends Stream {
                 INBOX: {},
                 '': {}
             });
+        this.referenceNamespace = false;
         this.uidvalidityCounter = 0; // highest UIDVALIDITY in use, new mailboxes get a higher one
         // subscribed mailbox names (RFC 3501 section 6.3.6). Names, not mailboxes: a subscription outlives
         // DELETE and stays with the old name on RENAME (RFC 9051 section 6.3.6), see trackSubscription
@@ -191,10 +211,67 @@ class IMAPServer extends Stream {
         this.folderCache = Object.create(null);
         this.indexFolders(true);
     }
+    /**
+     * Starts accepting connections
+     *
+     * @param {Number} [port] Port to listen on, a free port if not set
+     * @param {String} [host] Address to listen on, all addresses if not set
+     * @return {Promise<Number>} resolves with the port the server listens on
+     */
+    async start(port, host) {
+        const imapPort = await listenOn(this.server, port, host);
+        await Promise.all([this.options.smtp ? this.startSmtp() : null, this.options.rest ? this.startRest() : null]);
+        return imapPort;
+    }
+    /**
+     * Starts the REST API of the `rest` option, see src/rest.ts
+     *
+     * @return {Promise<Number>} resolves with the HTTP port
+     */
+    async startRest() {
+        const { port, host, token } = this.options.rest || {};
+        this.restServer = createRestServer(this, { host, token });
+        return listenOn(this.restServer, port, host || '127.0.0.1');
+    }
+    /**
+     * Starts the SMTP server of the `smtp` option. smtp-server is an optional dependency, loaded only here
+     *
+     * @return {Promise<Number>} resolves with the SMTP port
+     */
+    startSmtp() {
+        const { port, host } = this.options.smtp || {};
+        return this.loadSmtpListener().then(({ startSMTPServer }) => new Promise((resolve, reject) => {
+            const smtp = startSMTPServer(port || 0, this, smtpPort => {
+                smtp.removeListener('error', reject);
+                resolve(smtpPort);
+            }, host);
+            smtp.once('error', reject);
+            this.smtpServer = smtp;
+        }));
+    }
+    /**
+     * Loads the SMTP listener, which needs the smtp-server package
+     *
+     * @return {Promise<Object>} the smtp-listener module
+     */
+    loadSmtpListener() {
+        return import('./smtp-listener.js').catch((err) => {
+            throw new Error('The smtp option needs the smtp-server package, install it with: npm install smtp-server (' + err.message + ')');
+        });
+    }
+    /**
+     * Stops the server and closes every connection
+     *
+     * @return {Promise} resolves when the server is closed
+     */
+    stop() {
+        return this.control.shutdown({ graceful: false });
+    }
     listen(...args) {
         this.server.listen.apply(this.server, args);
     }
     close(callback) {
+        this.closeListeners(true);
         this.server.close(callback);
         // close() only completes once all connections are gone
         this.connections.forEach((connection) => {
@@ -203,6 +280,29 @@ class IMAPServer extends Stream {
             }
         });
     }
+    /**
+     * Stops the SMTP and REST listeners of `start()`
+     *
+     * @param {Boolean} force true closes the open REST connections too, otherwise only the idle ones (a request that
+     *   is answered, like POST /v1/shutdown, finishes first)
+     */
+    closeListeners(force) {
+        if (this.smtpServer) {
+            this.smtpServer.close(() => false);
+            this.smtpServer = null;
+        }
+        if (this.restServer) {
+            this.restServer.close();
+            // keep-alive connections would hold the server open
+            if (force) {
+                this.restServer.closeAllConnections?.();
+            }
+            else {
+                this.restServer.closeIdleConnections?.();
+            }
+            this.restServer = null;
+        }
+    }
     /**
      * Returns TLS key and certificate. Without credentials in the options the
      * bundled self-signed certificate for localhost is used.
@@ -322,13 +422,31 @@ class IMAPServer extends Stream {
      *
      * @param {String} type Kind of change
      * @param {String} path Storage name of the mailbox
-     * @param {Object} [details] `{ oldPath, mailbox }`: the earlier name of a renamed mailbox, the mailbox
-     *   object that a DELETE removed
+     * @param {Object} [details] `{ oldPath, mailbox, created }`: the earlier name of a renamed mailbox, the mailbox
+     *   object that a DELETE removed, the mailboxes a CREATE made (superior levels first)
      */
     mailboxChanged(type, path, details) {
         const event = Object.assign({ type, path, oldPath: null, mailbox: null }, details, { origin: this.activeConnection });
         this.emit('mailbox', event);
     }
+    /**
+     * Runs a change with `origin` as the session that caused it, the `origin` of the notifications and events it
+     * makes. Commands run with their session, the control API with null
+     *
+     * @param {Object|null} origin Session, or null for a change from outside
+     * @param {Function} fn Change
+     * @return {*} the result of fn
+     */
+    withOrigin(origin, fn) {
+        const previous = this.activeConnection;
+        this.activeConnection = origin;
+        try {
+            return fn();
+        }
+        finally {
+            this.activeConnection = previous;
+        }
+    }
     /**
      * Retrieves the handler of an IMAP command
      *
@@ -461,22 +579,22 @@ class IMAPServer extends Stream {
      */
     createMailbox(path, defaultMailbox) {
         if (!path) {
-            throw mailboxError('Invalid mailbox name', 'CANNOT');
+            throw storeError('Invalid mailbox name', 'CANNOT');
         }
         // Ensure case insensitive INBOX
         if (path.toUpperCase() === 'INBOX') {
-            throw mailboxError('INBOX can not be modified', 'ALREADYEXISTS');
+            throw storeError('INBOX can not be modified', 'ALREADYEXISTS');
         }
         const { namespace, storage } = this.getPersonalNamespace(path);
         path = this.stripSeparator(path, storage.separator);
         if (this.folderCache[path] && this.folderCache[path].flags.indexOf('\\Noselect') < 0) {
-            throw mailboxError('Mailbox already exists', 'ALREADYEXISTS');
+            throw storeError('Mailbox already exists', 'ALREADYEXISTS');
         }
         const folderPath = path.substr(namespace.length).split(storage.separator);
         if (folderPath.some(name => !name)) {
             // an empty hierarchy level ("foo//bar", "/foo", "foo//"). RFC 5530 section 3 has this very case as the
             // example of CANNOT, Dovecot refuses it too
-            throw mailboxError('Mailbox names can not have empty hierarchy levels', 'CANNOT');
+            throw storeError('Mailbox names can not have empty hierarchy levels', 'CANNOT');
         }
         let parent = storage;
         let curPath = namespace;
@@ -487,7 +605,7 @@ class IMAPServer extends Stream {
             curPath += (curPath.length ? storage.separator : '') + folderName;
             let folder = this.getMailbox(curPath) || false;
             if (folder && folder.flags && folder.flags.indexOf('\\Noinferiors') >= 0) {
-                throw mailboxError('Can not create subfolders for ' + folder.path, 'CANNOT');
+                throw storeError('Can not create subfolders for ' + folder.path, 'CANNOT');
             }
             // a \Noselect placeholder that is created again is replaced with a new mailbox that only keeps
             // the children, nothing else of a deleted mailbox may come back (RFC 3501 section 6.3.3)
@@ -529,17 +647,17 @@ class IMAPServer extends Stream {
     deleteMailbox(path, keepContents) {
         // Ensure case insensitive INBOX
         if (path.toUpperCase() === 'INBOX') {
-            throw mailboxError('INBOX can not be modified', 'CANNOT');
+            throw storeError('INBOX can not be modified', 'CANNOT');
         }
         const { namespace, storage } = this.getPersonalNamespace(path);
         const mailbox = this.folderCache[this.stripSeparator(path, storage.separator)];
         if (!mailbox) {
-            throw mailboxError('Mailbox does not exist', 'NONEXISTENT');
+            throw storeError('Mailbox does not exist', 'NONEXISTENT');
         }
         if (mailbox.flags.indexOf('\\Noselect') >= 0 && Object.keys(mailbox.folders || {}).length) {
             // RFC 9051 section 6.3.5: deleting a \Noselect name that has inferior names is an error, the RFC 5530
             // section 3 HASCHILDREN response code tells the client to delete the children first
-            throw mailboxError('Mailbox has children, delete them first', 'HASCHILDREN');
+            throw storeError('Mailbox has children, delete them first', 'HASCHILDREN');
         }
         const levels = mailbox.path.split(storage.separator);
         const folderName = levels.pop();
@@ -589,7 +707,7 @@ class IMAPServer extends Stream {
             const prefix = key.length ? key.substr(0, key.length - this.storage[key].separator.length) : key;
             if (key.length && (path === prefix || path.substr(0, key.length) === key)) {
                 if (path === prefix) {
-                    throw mailboxError('Used mailbox name is a namespace value', 'CANNOT');
+                    throw storeError('Used mailbox name is a namespace value', 'CANNOT');
                 }
                 namespace = key;
             }
@@ -599,10 +717,10 @@ class IMAPServer extends Stream {
         });
         const storage = this.storage[namespace];
         if (!storage) {
-            throw mailboxError('Unknown namespace', 'CANNOT');
+            throw storeError('Unknown namespace', 'CANNOT');
         }
         if (storage.type !== 'personal') {
-            throw mailboxError('Permission denied', 'NOPERM');
+            throw storeError('Permission denied', 'NOPERM');
         }
         return { namespace, storage };
     }
@@ -843,6 +961,17 @@ class IMAPServer extends Stream {
         const knownFlags = (mailbox.knownFlags = mailbox.knownFlags || []);
         flags.forEach(flag => this.ensureFlag(knownFlags, flag));
     }
+    /**
+     * The current time for dates the server sets itself (INTERNALDATE of a message without one, SAVEDATE). The `now`
+     * option fixes it for repeatable tests: a Date, a timestamp, or a function that returns one
+     *
+     * @return {Date} current time
+     */
+    now() {
+        const now = this.options.now;
+        const value = typeof now === 'function' ? now() : now;
+        return value === undefined || value === null ? new Date() : new Date(value);
+    }
     normalizeDateTime(value) {
         if (value instanceof Date) {
             return this.formatInternalDate(value);
@@ -861,7 +990,7 @@ class IMAPServer extends Stream {
      * @param mailbox Mailbox of the message
      */
     processMessage(message, mailbox) {
-        message.internaldate = this.normalizeDateTime(message.internaldate || new Date());
+        message.internaldate = this.normalizeDateTime(message.internaldate || this.now());
         message.flags = [].concat(message.flags || []);
         if (message.flags.indexOf('\\Recent') >= 0) {
             // \Recent is not a stored flag, it belongs to the first session that selects the mailbox
@@ -1251,6 +1380,7 @@ class IMAPConnection {
         this.notificationQueue = [];
         this.server.on('notify', this._notificationCallback);
         this.server.connections.add(this);
+        this.emitSession('open');
         this.scriptOutput('greeting', '* OK ImapKit ready for rumble\r\n', {});
     }
     /**
@@ -1285,7 +1415,7 @@ class IMAPConnection {
         }
         this._outputQueue = this._outputQueue || [];
         this._outputQueue.push(Object.assign({}, operation, { transport: this.transport }));
-        if (!this._outputTimer) {
+        if (!this._outputTimer && !this._outputWaiting) {
             this.flushOutput();
         }
     }
@@ -1306,10 +1436,28 @@ class IMAPConnection {
                 return;
             }
             if (operation.data && operation.chunk && operation.data.length > operation.chunk) {
-                // the rest waits for chunkDelay, like a delay of its own
-                this.writeLayer(operation.data.subarray(0, operation.chunk), operation.transport || null);
+                // the rest waits for chunkDelay, like a delay of its own. Without a delay each piece waits for the next
+                // event loop turn, and Nagle's algorithm must not hold it back to merge it with the next one
+                const piece = operation.data.subarray(0, operation.chunk);
                 operation.data = operation.data.subarray(operation.chunk);
+                if (!operation.chunkDelay || operation.chunkDelay === 'tick') {
+                    // the next piece waits until this one was handed to the system, and one more event loop turn, so
+                    // the pieces leave as separate segments without a wall clock delay (#89)
+                    this.socket?.setNoDelay?.(true);
+                    this._outputWaiting = true;
+                    this.writeLayer(piece, operation.transport || null, () => {
+                        if (this._outputWaiting && this._outputQueue === queue) {
+                            this._outputTimer = nextTurn(() => {
+                                this._outputTimer = null;
+                                this._outputWaiting = false;
+                                this.flushOutput();
+                            });
+                        }
+                    });
+                    return;
+                }
                 operation.delay = operation.chunkDelay;
+                this.writeLayer(piece, operation.transport || null);
                 continue;
             }
             if (operation.data) {
@@ -1329,8 +1477,10 @@ class IMAPConnection {
     clearOutputQueue() {
         if (this._outputTimer) {
             clearTimeout(this._outputTimer);
+            clearImmediate(this._outputTimer);
             this._outputTimer = null;
         }
+        this._outputWaiting = false;
         this._outputQueue = null;
         this._deferredOutput = null;
     }
@@ -1339,13 +1489,17 @@ class IMAPConnection {
      *
      * @param {Buffer} data Output
      * @param {Object|null} transport Transport layer
+     * @param {Function} [callback] Called once the data was handed to the system (a transport: on the next turn)
      */
-    writeLayer(data, transport) {
+    writeLayer(data, transport, callback) {
         if (transport) {
             transport.write(data);
+            if (callback) {
+                setImmediate(callback);
+            }
         }
         else {
-            this.writeRaw(data);
+            this.writeRaw(data, callback);
         }
     }
     /**
@@ -1399,17 +1553,70 @@ class IMAPConnection {
      *
      * @param {Buffer} data Data to send
      */
-    writeRaw(data) {
+    writeRaw(data, callback) {
         if (this.socket && !this.socket.destroyed) {
-            this.socket.write(data);
+            this.socket.write(data, callback);
+            this.touch();
         }
     }
+    /**
+     * Notes input or output for the quiet events of script rules (#88)
+     */
+    touch() {
+        if (!this.server.script.watches('quiet')) {
+            // nothing waits for quiet sessions, a rule added later counts from then on
+            this._lastActivity = undefined;
+            return;
+        }
+        this._lastActivity = Date.now();
+        if (!this._quietTimer) {
+            this.watchQuiet();
+        }
+    }
+    /**
+     * Starts waiting for the next quiet event, if a rule waits for one and the session is not waiting already. When
+     * the time is up, the first rule that matches handles the event (`send`, `close`), the output it sends starts
+     * the next quiet time
+     *
+     * @param {Number} [checked] Quiet time the rules were checked for already, only longer ones are waited for
+     */
+    watchQuiet(checked = 0) {
+        if (this._quietTimer || !this.socket || this._closing) {
+            return;
+        }
+        const last = this._lastActivity || Date.now();
+        this._lastActivity = last;
+        // the time is measured from the last activity, a rule whose time is up already fires right away
+        const next = this.server.script.nextQuiet(checked);
+        if (next === null) {
+            return;
+        }
+        this._quietTimer = setTimeout(() => {
+            this._quietTimer = null;
+            if (!this.isOpen() || this._lastActivity !== last) {
+                // there was activity in between, it started a new wait
+                return this.watchQuiet();
+            }
+            // a timer can fire a millisecond before Date.now() says the time is up
+            const quiet = Math.max(Date.now() - last, next);
+            const found = this.server.script.check(this, 'quiet', { data: '', quiet });
+            if (found) {
+                handleQuiet(this, found.rule, found.context);
+            }
+            if (this._lastActivity === last) {
+                // nothing was sent, wait for the rules with a longer quiet time
+                this.watchQuiet(quiet);
+            }
+        }, Math.max(0, next - (Date.now() - last)));
+        this._quietTimer.unref();
+    }
     /**
      * Handles data from the socket, through the transport layer if there is one
      *
      * @param {Buffer} chunk Received data
      */
     receive(chunk) {
+        this.touch();
         if (this.transport) {
             this.transport.receive(chunk);
         }
@@ -1449,16 +1656,10 @@ class IMAPConnection {
             socket.pause();
             // a RST sent in the same tick as the last output can get lost: on macOS the client received the output but
             // never the RST (#81). Node has no signal for output that reached the peer, so the RST waits a little
+            const tcpSocket = this.tcpSocket;
             setTimeout(() => {
-                if (socket.destroyed) {
-                    return;
-                }
-                // resetAndDestroy sends a TCP RST (Node 16.17), not every runtime has it
-                if (typeof socket.resetAndDestroy === 'function') {
-                    socket.resetAndDestroy();
-                }
-                else {
-                    socket.destroy();
+                if (!socket.destroyed) {
+                    resetSocket(socket, tcpSocket);
                 }
             }, RESET_DELAY);
         }
@@ -1548,11 +1749,15 @@ class IMAPConnection {
      * notifications that were not sent yet are dropped. Sends nothing, the caller answers the command
      */
     closeMailbox() {
+        const wasSelected = !!this.selectedMailbox;
         this.state = 'Authenticated';
         this.selectedMailbox = false;
         this.readOnly = false;
         this.recent = null;
         this.notificationQueue = [];
+        if (wasSelected) {
+            this.emitSession('unselect');
+        }
     }
     onClose() {
         if (this.socket) {
@@ -1564,8 +1769,14 @@ class IMAPConnection {
             this.transport = null;
         }
         this.clearOutputQueue();
+        if (this._quietTimer) {
+            clearTimeout(this._quietTimer);
+            this._quietTimer = null;
+        }
         this.server.removeListener('notify', this._notificationCallback);
-        this.server.connections.delete(this);
+        if (this.server.connections.delete(this)) {
+            this.emitSession('close');
+        }
     }
     onError(err) {
         if (this.options.debug) {
@@ -1917,8 +2128,8 @@ class IMAPConnection {
      * @param {Array} messages Messages with changed flags
      */
     notifyFlagChanges(messages) {
-        if (messages.length && this.selectedMailbox) {
-            this.server.notify({ tag: '*', flagUpdate: messages }, this.selectedMailbox, this);
+        if (this.selectedMailbox) {
+            notifyFlagChanges(this.server, this.selectedMailbox, messages, this);
         }
     }
     /**
@@ -2079,6 +2290,9 @@ class IMAPConnection {
         };
         // STARTTLS runs on a live connection
         const socket = this.socket;
+        // the RST of a script rule goes to the TCP socket under the TLS layer, see resetSocket. Node also has it as the
+        // _parent of the TLS socket, Bun does not
+        this.tcpSocket = socket;
         // remove all listeners from the original socket besides the error handler
         socket.removeAllListeners();
         socket.on('error', this.onError.bind(this));
@@ -2171,7 +2385,7 @@ class IMAPConnection {
      */
     send(response, description, parsed, data, ...extra) {
         // nothing goes out once the connection is closing (RFC 3501 section 7.1.5)
-        if (!this.socket || this.socket.destroyed || this._closing) {
+        if (!this.isOpen()) {
             return;
         }
         if (!response.notification && response.tag !== '*') {
@@ -2181,6 +2395,9 @@ class IMAPConnection {
         this.server.outputHandlers.forEach(handler => {
             handler(this, response, description, parsed, data, ...extra);
         });
+        if (this._commandStart && parsed && response.tag === this._commandStart.tag && parsed.tag === response.tag) {
+            this.commandCompleted(String(response.command || '').toUpperCase());
+        }
         // No need to display this response to user
         if (response.skipResponse) {
             return;
@@ -2556,6 +2773,64 @@ class IMAPConnection {
             }, 'UNKNOWN COMMAND', parsed, data);
         }
     }
+    /**
+     * Emits the `command` event when the tagged response of a command goes out, and the `session` events "login"
+     * (the command authenticated the session) and "logout" (back to Not Authenticated, UNAUTHENTICATE). Every command
+     * that changes these does so before its tagged response. "select" and "unselect" come from SELECT and
+     * closeMailbox(). Tests wait for these instead of polling
+     *
+     * @param {String} status OK, NO or BAD
+     */
+    commandCompleted(status) {
+        const start = this._commandStart;
+        this._commandStart = null;
+        const server = this.server;
+        if (!server.listenerCount('command') && !server.listenerCount('session')) {
+            return;
+        }
+        server.emit('command', { session: this.sessionNumber, tag: start.tag, command: start.command, status, user: this.username || null });
+        const authenticated = (state) => state === 'Authenticated' || state === 'Selected';
+        if (authenticated(start.state) !== authenticated(this.state) && this.state !== 'Logout') {
+            this.emitSession(authenticated(this.state) ? 'login' : 'logout');
+        }
+    }
+    /**
+     * Emits a `session` event, `{ type, session, ...fields }`
+     *
+     * @param {String} type Event type
+     * @param {Object} [fields] More fields of the event
+     */
+    emitSession(type, fields) {
+        if (this.server.listenerCount('session')) {
+            this.server.emit('session', Object.assign({ type, session: this.describe() }, fields));
+        }
+    }
+    /**
+     * Describes the session without credentials or sockets, for the control API and the `session` events
+     *
+     * @return {Object} `{ session, user, state, mailbox, readOnly, enabled, secure, compressed, remoteAddress }`
+     */
+    describe() {
+        return {
+            session: this.sessionNumber,
+            user: this.username || null,
+            state: this.state,
+            mailbox: this.selectedMailbox ? this.selectedMailbox.path : null,
+            readOnly: !!this.selectedMailbox && !!this.readOnly,
+            enabled: Array.isArray(this.enabled) ? this.enabled.slice() : [],
+            secure: !!this.secureConnection,
+            compressed: !!this.transport,
+            remoteAddress: (this.socket && this.socket.remoteAddress) || null
+        };
+    }
+    /**
+     * Checks if output can still be sent: the socket is open and the connection is not closing (BYE, LOGOUT)
+     *
+     * @return {Boolean} true for a live session
+     */
+    isOpen() {
+        return !!this.socket && !this.socket.destroyed && !this._closing;
+    }
     /**
      * Handles a command line with the script rule that matched it, after the rule's delay. With `run` the line
      * goes through the parser and the command handler as usual afterwards
@@ -2596,6 +2871,8 @@ class IMAPConnection {
         const command = element.parsed.command.toUpperCase();
         this._runningCommand = element;
         const options = this.server.getCommandOptions(command);
+        // the session events of the command are worked out when its tagged response goes out, see commandCompleted
+        this._commandStart = { tag: element.parsed.tag, command, state: this.state };
         let done = false;
         const next = () => {
             if (done) {
@@ -2658,53 +2935,52 @@ class IMAPConnection {
             // criteria, processNotifications knows when EXPUNGE must wait
             this.processNotifications(element.parsed);
         }
-        try {
-            // changes made while the handler runs are attributed to this session (the `origin` of notifications)
-            this.server.activeConnection = this;
-            const inputHandler = this.inputHandler;
-            this.server.getCommandHandler(element.parsed.command)(this, element.parsed, element.data, next);
-            if (this.inputHandler && this.inputHandler !== inputHandler) {
-                // the command reads the lines that follow (IDLE, AUTHENTICATE), script rules match them with it
-                this.inputCommand = { tag: element.parsed.tag, command: element.parsed.command };
+        // changes made while the handler runs are attributed to this session (the `origin` of notifications)
+        this.server.withOrigin(this, () => {
+            try {
+                const inputHandler = this.inputHandler;
+                this.server.getCommandHandler(element.parsed.command)(this, element.parsed, element.data, next);
+                if (this.inputHandler && this.inputHandler !== inputHandler) {
+                    // the command reads the lines that follow (IDLE, AUTHENTICATE), script rules match them with it
+                    this.inputCommand = { tag: element.parsed.tag, command: element.parsed.command };
+                    this.emitSession('waiting', { command });
+                }
             }
-        }
-        catch (E) {
-            const ex = E;
-            const badInput = ex.imapResponse === 'BAD';
-            if (!badInput && this.options.debug) {
-                console.error('Error processing command:', ex, '\n', ex.stack);
+            catch (E) {
+                const ex = E;
+                const badInput = ex.imapResponse === 'BAD';
+                if (!badInput && this.options.debug) {
+                    console.error('Error processing command:', ex, '\n', ex.stack);
+                }
+                this.send({
+                    tag: element.parsed.tag,
+                    command: badInput ? 'BAD' : 'NO',
+                    attributes: [].concat(badInput
+                        ? []
+                        : {
+                            type: 'SECTION',
+                            section: [
+                                {
+                                    type: 'ATOM',
+                                    value: 'SERVERBUG'
+                                }
+                            ]
+                        }, {
+                        type: 'TEXT',
+                        value: badInput ? ex.message : 'Server error: ' + ex.message
+                    })
+                }, badInput ? 'INVALID COMMAND' : 'SERVER ERROR', element.parsed, element.data);
+                // keep the connection usable, otherwise every later command would hang
+                next();
             }
-            this.send({
-                tag: element.parsed.tag,
-                command: badInput ? 'BAD' : 'NO',
-                attributes: [].concat(badInput
-                    ? []
-                    : {
-                        type: 'SECTION',
-                        section: [
-                            {
-                                type: 'ATOM',
-                                value: 'SERVERBUG'
-                            }
-                        ]
-                    }, {
-                    type: 'TEXT',
-                    value: badInput ? ex.message : 'Server error: ' + ex.message
-                })
-            }, badInput ? 'INVALID COMMAND' : 'SERVER ERROR', element.parsed, element.data);
-            // keep the connection usable, otherwise every later command would hang
-            next();
-        }
-        finally {
-            this.server.activeConnection = null;
-        }
+        });
     }
     /**
      * Removes messages with \Deleted flag
      *
      * @param {Object} mailbox Mailbox to check for
      * @param {Boolean} [ignoreSelf] If set to true, does not send any notices to itself
-     * @param {Boolean} [ignoreSelf] If set to true, does not send EXISTS notice to itself
+     * @param {Boolean} [ignoreExists] If set to true, does not send EXISTS notice to itself
      */
     expungeDeleted(mailbox, ignoreSelf, ignoreExists) {
         this.expungeSpecificMessages(mailbox, (message) => {
@@ -2713,79 +2989,80 @@ class IMAPConnection {
     }
     /**
      * Given a set of messages in a mailbox (possibly via getMessageRange), remove
-     * them from the mailbox and generate EXPUNGE notifications.
+     * them from the mailbox and generate EXPUNGE notifications, see expungeMessages() in store-operations.ts
      *
      * @param {Object} mailbox Mailbox to check for
      * @param {Function|Array} messagesOrFilterFunc An Array of messages in the
      *     folder that should be removed or a filtering function that indicates
      *     messages to be removed by returning true.
      * @param {Boolean} [ignoreSelf] If set to true, does not send any notices to itself
-     * @param {Boolean} [ignoreSelf] If set to true, does not send EXISTS notice to itself
+     * @param {Boolean} [ignoreExists] If set to true, does not send EXISTS notice to itself
      * @param {Boolean} [highestFirst] If set to true, the EXPUNGE responses go from the highest UID to the lowest
      *     (MESSAGELIMIT, RFC 9738 section 3.1), otherwise from the lowest
      */
     expungeSpecificMessages(mailbox, messagesOrFilterFunc, ignoreSelf, ignoreExists, highestFirst) {
-        let filterFunc;
-        if (Array.isArray(messagesOrFilterFunc)) {
-            const messageSet = new Set(messagesOrFilterFunc);
-            filterFunc = (message) => messageSet.has(message);
-        }
-        else {
-            filterFunc = messagesOrFilterFunc;
-        }
-        // sequence numbers of the removed messages, each one as it is after the earlier EXPUNGE responses. From the
-        // highest message down, the earlier responses do not change the sequence numbers of the later ones
-        const expunged = [];
-        const kept = [];
-        mailbox.messages.forEach((message, i) => {
-            if (filterFunc(message)) {
-                message.ghost = true;
-                expunged.push({ seq: highestFirst ? i + 1 : kept.length + 1, message });
+        expungeMessages(this.server, mailbox, messagesOrFilterFunc, {
+            origin: this,
+            skip: ignoreSelf ? this : null,
+            skipExists: ignoreExists ? this : null,
+            highestFirst: !!highestFirst
+        });
+    }
+}
+// setImmediate does not let Deno send what sockets were given, see nextTurn
+const IS_DENO = 'Deno' in globalThis;
+/**
+ * Runs a function on the next event loop turn that also handles network I/O: setImmediate on Node and Bun, a zero
+ * timer on Deno, where setImmediate runs before the sockets send what was written (#89)
+ *
+ * @param {Function} fn Function to run
+ * @return {Object} the timer, clearOutputQueue clears it
+ */
+function nextTurn(fn) {
+    return IS_DENO ? setTimeout(fn, 0) : setImmediate(fn);
+}
+/**
+ * Starts listening, resolves with the port or rejects with the listen error (EADDRINUSE)
+ *
+ * @param {Object} server net, tls or http server
+ * @param {Number} [port] Port, a free one if not set
+ * @param {String} [host] Address, all addresses if not set
+ * @return {Promise<Number>} the port
+ */
+function listenOn(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen({ port: port || 0, host }, () => {
+            server.removeListener('error', reject);
+            resolve(server.address().port);
+        });
+    });
+}
+/**
+ * Destroys a socket with a TCP RST (`close: 'reset'` of a script rule). resetAndDestroy (Node 16.17) needs a socket with
+ * a TCP handle, a TLS socket throws ERR_INVALID_HANDLE_TYPE (#84), so the RST goes to the TCP socket under the TLS
+ * layer: the plain socket of STARTTLS, or the parent socket of implicit TLS (Node). A runtime without resetAndDestroy,
+ * or a socket that can not be reset, is destroyed without a RST
+ *
+ * @param {Object} socket The socket of the connection
+ * @param {Object} [tcpSocket] The plain socket that STARTTLS wrapped
+ */
+function resetSocket(socket, tcpSocket) {
+    const parent = socket._parent;
+    const candidates = [tcpSocket, parent instanceof net.Socket ? parent : null, socket];
+    for (const candidate of candidates) {
+        if (candidate && !candidate.destroyed && typeof candidate.resetAndDestroy === 'function') {
+            try {
+                candidate.resetAndDestroy();
+                break;
             }
-            else {
-                kept.push(message);
+            catch {
+                // not a TCP handle, try the next one
             }
-        });
-        if (!expunged.length) {
-            return;
         }
-        // old copy is required for those sessions that run FETCH before
-        // displaying the EXPUNGE notice
-        const mailboxCopy = mailbox.messages.slice();
-        // update the list in place, other code might hold a reference to it
-        kept.forEach((message, i) => {
-            mailbox.messages[i] = message;
-        });
-        mailbox.messages.length = kept.length;
-        // lets plugins track the removal (e.g. mod-sequences of CONDSTORE and QRESYNC) before any notification
-        this.server.emit('expunge', mailbox, expunged.map(entry => entry.message), this);
-        (highestFirst ? expunged.slice().reverse() : expunged).forEach(entry => {
-            this.server.notify({
-                tag: '*',
-                attributes: [
-                    entry.seq,
-                    {
-                        type: 'ATOM',
-                        value: 'EXPUNGE'
-                    }
-                ],
-                // the removed message, for plugins that report it differently (e.g. VANISHED of QRESYNC)
-                message: entry.message
-            }, mailbox, ignoreSelf ? this : false);
-        });
-        this.server.notify({
-            tag: '*',
-            attributes: [
-                mailbox.messages.length,
-                {
-                    type: 'ATOM',
-                    value: 'EXISTS'
-                }
-            ],
-            // distribute the old mailbox data with the notification
-            mailboxCopy: mailboxCopy
-        }, mailbox, ignoreSelf || ignoreExists ? this : false);
     }
+    // the TLS socket closes with the TCP socket under it, and emits close for the connection
+    socket.destroy();
 }
 /**
  * Copies a response tree for the `mutate` action of a script rule: arrays and plain objects are copied,