imapkit 4.1.1 → 4.2.0

package/dist/esm/server.js

@@ -14,6 +14,7 @@ import { isSequenceSet } from './numbers.js';
 import { restoreNilAtoms } from './arguments.js';
 import { refuseMissingTarget } from './commands/append.js';
 import * as bundledCert from './cert.js';
+import { ServerScript, sendOutput, handleLine } from './script.js';
 // longest command line (not counting literals) accepted from a client
 const MAX_LINE_LENGTH = 1024 * 1024;
 // largest literal accepted after login, override with the maxLiteralSize option
@@ -155,6 +156,9 @@ class IMAPServer extends Stream {
         this.referenceNamespace = false;
         // 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()
+        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
@@ -1212,6 +1216,9 @@ class IMAPConnection {
         this.socket = socket;
         this.options = this.server.options;
         this.state = 'Not Authenticated';
+        this.sessionNumber = ++this.server.sessionCounter;
+        this._outputQueue = null;
+        this._outputTimer = null;
         this.secureConnection = !!this.options.secureConnection;
         this._remainder = '';
         this._command = '';
@@ -1241,7 +1248,7 @@ class IMAPConnection {
         this.notificationQueue = [];
         this.server.on('notify', this._notificationCallback);
         this.server.connections.add(this);
-        this.write('* OK ImapKit ready for rumble\r\n');
+        this.scriptOutput('greeting', '* OK ImapKit ready for rumble\r\n', {});
     }
     /**
      * Writes protocol output to the client, through the transport layer if there is one
@@ -1250,12 +1257,134 @@ class IMAPConnection {
      */
     write(data) {
         const buffer = typeof data === 'string' ? Buffer.from(data, 'binary') : data;
-        if (this.transport) {
-            this.transport.write(buffer);
+        if (this._outputQueue) {
+            this._outputQueue.push({ data: buffer, transport: this.transport });
+        }
+        else {
+            this.writeLayer(buffer, this.transport);
+        }
+    }
+    /**
+     * Writes output, or puts it in the output queue while earlier output waits for a delay of a script rule.
+     * The transport layer is taken when the output is queued, so output from before COMPRESS is not compressed
+     *
+     * @param {Object} operation `{ data, delay, chunk, chunkDelay, close }`, see OutputOperation in src/script.ts
+     */
+    queueOutput(operation) {
+        if (!this._outputQueue && !operation.delay && !operation.chunk) {
+            if (operation.data) {
+                this.writeLayer(operation.data, this.transport);
+            }
+            if (operation.close) {
+                this.closeNow(operation.close);
+            }
+            return;
+        }
+        this._outputQueue = this._outputQueue || [];
+        this._outputQueue.push(Object.assign({}, operation, { transport: this.transport }));
+        if (!this._outputTimer) {
+            this.flushOutput();
+        }
+    }
+    /**
+     * Writes the output queue until it is empty or a delay stops it
+     */
+    flushOutput() {
+        const queue = this._outputQueue || [];
+        while (queue.length) {
+            const operation = queue[0];
+            if (operation.delay) {
+                const delay = operation.delay;
+                operation.delay = 0;
+                this._outputTimer = setTimeout(() => {
+                    this._outputTimer = null;
+                    this.flushOutput();
+                }, delay);
+                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);
+                operation.data = operation.data.subarray(operation.chunk);
+                operation.delay = operation.chunkDelay;
+                continue;
+            }
+            if (operation.data) {
+                this.writeLayer(operation.data, operation.transport || null);
+            }
+            queue.shift();
+            if (operation.close) {
+                this.closeNow(operation.close);
+                return;
+            }
+        }
+        this._outputQueue = null;
+    }
+    /**
+     * Drops the output that waits for a delay of a script rule
+     */
+    clearOutputQueue() {
+        if (this._outputTimer) {
+            clearTimeout(this._outputTimer);
+            this._outputTimer = null;
+        }
+        this._outputQueue = null;
+    }
+    /**
+     * Writes output through a transport layer, or to the socket
+     *
+     * @param {Buffer} data Output
+     * @param {Object|null} transport Transport layer
+     */
+    writeLayer(data, transport) {
+        if (transport) {
+            transport.write(data);
         }
         else {
-            this.writeRaw(buffer);
+            this.writeRaw(data);
+        }
+    }
+    /**
+     * Sends output through the script rule that handles its event, if there is one
+     *
+     * @param {String} event Event name: greeting, response or continuation
+     * @param {String} output The output as a binary string
+     * @param {Object} fields Context fields of the event (tag, command, description, response)
+     * @param {Function} [compile] Compiles the response that a `mutate` action changed, null drops the output
+     */
+    scriptOutput(event, output, fields, compile) {
+        const found = this.server.script.check(this, event, Object.assign({}, fields, { data: output }));
+        if (!found) {
+            this.write(output);
+            return;
+        }
+        const { rule, context } = found;
+        if (rule.mutate && compile && context.response) {
+            // a copy, a notification object is shared by every session
+            const copy = cloneResponse(context.response);
+            const changed = compile(rule.mutate(copy, context) || copy);
+            if (changed === null) {
+                return;
+            }
+            context.data = changed;
+        }
+        sendOutput(this, rule, context, Buffer.from(context.data, 'binary'));
+    }
+    /**
+     * Sends a continuation request, `+ text`
+     *
+     * @param {String} text Human readable text, can be empty (SASL)
+     * @param {String} description Description for script rules
+     * @param {Function} [getLine] Returns the command line received so far, for the tag and the command of a literal continuation
+     */
+    sendContinuation(text, description, getLine) {
+        const output = '+ ' + text + '\r\n';
+        if (!this.server.script.watches('continuation')) {
+            this.write(output);
+            return;
         }
+        const line = getLine ? getLine() : null;
+        this.scriptOutput('continuation', output, line === null ? { description } : { description, tag: getResponseTag(line), command: getLineCommand(line) });
     }
     /**
      * Writes data to the socket, below the transport layer
@@ -1285,12 +1414,37 @@ class IMAPConnection {
      * holds, is written out
      */
     end() {
+        if (this._outputQueue && this.socket) {
+            // output still waits for a delay of a script rule
+            this._closing = true;
+            this._outputQueue.push({ close: true });
+            return;
+        }
+        this.closeNow(true);
+    }
+    /**
+     * Closes the connection now, after the output written so far
+     *
+     * @param {Boolean|String} mode true ends the connection gracefully, "reset" destroys the socket (script rules)
+     */
+    closeNow(mode) {
         const socket = this.socket;
         if (!socket) {
             return;
         }
         this._closing = true;
-        if (this.transport) {
+        this.clearOutputQueue();
+        if (mode === 'reset') {
+            this.discardInput();
+            // resetAndDestroy sends a TCP RST (Node 16.17), not every runtime has it
+            if (typeof socket.resetAndDestroy === 'function') {
+                socket.resetAndDestroy();
+            }
+            else {
+                socket.destroy();
+            }
+        }
+        else if (this.transport) {
             this.transport.end(() => socket.end());
         }
         else {
@@ -1391,6 +1545,7 @@ class IMAPConnection {
             this.transport.destroy();
             this.transport = null;
         }
+        this.clearOutputQueue();
         this.server.removeListener('notify', this._notificationCallback);
         this.server.connections.delete(this);
     }
@@ -1406,6 +1561,21 @@ class IMAPConnection {
             // socket is already gone
         }
     }
+    /**
+     * Passes a line to the input handler (IDLE, AUTHENTICATE), unless a script rule handles it
+     *
+     * @param {String} line Input line without CRLF
+     */
+    handleInput(line) {
+        const inputHandler = this.inputHandler;
+        const found = this.server.script.check(this, 'input', { data: line });
+        if (found) {
+            handleLine(this, found.rule, found.context, () => inputHandler(line));
+        }
+        else {
+            inputHandler(line);
+        }
+    }
     onData(chunk) {
         let match;
         let str;
@@ -1477,7 +1647,7 @@ class IMAPConnection {
                     this.sendBad(getResponseTag(line), 'Literal data must wait for the continuation request', 'LITERAL TOO EARLY', line);
                 }
                 else if (this.inputHandler) {
-                    this.inputHandler(line);
+                    this.handleInput(line);
                 }
                 else {
                     this.scheduleCommand(line);
@@ -1526,7 +1696,9 @@ class IMAPConnection {
                     this._earlyLiteral = true;
                 }
                 else if (!this._earlyLiteral) {
-                    this.write('+ Go ahead\r\n');
+                    // the line is needed only by script rules that watch continuations
+                    const head = str.substr(0, match.index) + marker;
+                    this.sendContinuation('Go ahead', 'LITERAL', () => this._command + head);
                 }
             }
             this._remainder = '';
@@ -1602,12 +1774,7 @@ class IMAPConnection {
             // not a command, e.g. a SASL response
             return literal8 ? refuse('Literal8 is not allowed here') : false;
         }
-        // tag SP command, and for UID and AUTHENTICATE the word that follows
-        const words = line.match(/^[^ ]* ([^ ]*)(?: ([^ ]*))?/);
-        let command = ((words && words[1]) || '').toUpperCase();
-        if (command === 'UID' || command === 'AUTHENTICATE') {
-            command += ' ' + ((words && words[2]) || '').toUpperCase();
-        }
+        const command = getLineCommand(line);
         if (!COMMAND_REGEX.test(command) || !this.server.getCommandHandler(command)) {
             return refuse('Unknown command');
         }
@@ -2027,6 +2194,26 @@ class IMAPConnection {
                 });
             }
         }
+        const compiled = this.compileResponse(response);
+        if (compiled === null) {
+            return;
+        }
+        const event = response.tag === '+' ? 'continuation' : 'response';
+        if (!this.server.script.watches(event)) {
+            this.write(compiled);
+            return;
+        }
+        // script rules see the response after every plugin and the core changed it. Without a command, an
+        // unsolicited response belongs to the command that runs or idles
+        this.scriptOutput(event, compiled, Object.assign({ description: description || null, response }, parsed && parsed.command ? { tag: parsed.tag || null, command: String(parsed.command).toUpperCase() } : {}), output => this.compileResponse(output));
+    }
+    /**
+     * Compiles a response for the wire
+     *
+     * @param {Object} response Response object
+     * @return {String|null} the response with its CRLF as a binary string, or null for an untagged response that does not compile
+     */
+    compileResponse(response) {
         let compiled;
         try {
             compiled = imapHandler.compiler(response, this.compilerOptions);
@@ -2037,14 +2224,14 @@ class IMAPConnection {
                 console.log('Failed to compile response: %s', err.message);
             }
             if (response.tag === '*') {
-                return;
+                return null;
             }
             compiled = response.tag + ' NO [SERVERBUG] Failed to compile response';
         }
         if (this.options.debug) {
             console.log('SEND: %s', compiled);
         }
-        this.write(compiled + '\r\n');
+        return compiled + '\r\n';
     }
     /**
      * Sends a tagged status response to a command
@@ -2231,9 +2418,23 @@ class IMAPConnection {
     exportMailboxName(path) {
         return path;
     }
-    scheduleCommand(data) {
+    /**
+     * Parses a command line and queues the command, or answers it right away when it can not run
+     *
+     * @param {String} data Command line with its literals, without the final CRLF
+     * @param {Boolean} [scripted] The line comes from a script rule with `run`, it is next in the queue
+     */
+    scheduleCommand(data, scripted) {
         let parsed;
         const tag = getResponseTag(data);
+        // the rule is chosen when the line arrives, the state it matches is the state at that moment. The rule
+        // acts when the command's turn comes, so that its output keeps the order of the responses
+        const found = !scripted && this.server.script.watches('command') ? this.server.script.check(this, 'command', { data, tag, command: getLineCommand(data) }) : null;
+        if (found) {
+            this._commandQueue.push({ parsed: { tag, command: found.context.command || '' }, data, script: found });
+            this.processQueue();
+            return;
+        }
         try {
             // server.parserOptions are the defaults of plugins, connection.parserOptions win
             parsed = imapHandler.parser(data, Object.assign({ literalPlus: this.server.literalPlus }, this.server.parserOptions, this.parserOptions));
@@ -2280,10 +2481,14 @@ class IMAPConnection {
                 this.sendStatus(parsed, data, 'BAD', 'Commands with message sequence numbers must wait for the completion of earlier commands');
                 return;
             }
-            this._commandQueue.push({
-                parsed: parsed,
-                data: data
-            });
+            const element = { parsed, data };
+            if (scripted) {
+                // processQueue runs it once the script rule released the queue
+                this._commandQueue.unshift(element);
+            }
+            else {
+                this._commandQueue.push(element);
+            }
             this.processQueue();
         }
         else if (/^AUTHENTICATE /i.test(parsed.command)) {
@@ -2312,6 +2517,33 @@ class IMAPConnection {
             }, 'UNKNOWN COMMAND', parsed, data);
         }
     }
+    /**
+     * 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
+     *
+     * @param {Object} element Queued command with the rule
+     * @param {Function} next Releases the queue
+     */
+    runScriptedCommand(element, next) {
+        const { rule, context } = element.script;
+        const act = () => {
+            if (!this.socket || this._closing) {
+                return next();
+            }
+            handleLine(this, rule, context, () => {
+                // the line is not running yet, it must not count as an earlier command (RFC 3501 section 5.5)
+                this._runningCommand = null;
+                this.scheduleCommand(element.data, true);
+            });
+            next();
+        };
+        if (rule.delay) {
+            setTimeout(act, rule.delay);
+        }
+        else {
+            act();
+        }
+    }
     processQueue(force) {
         if (!force && this._processing) {
             return;
@@ -2344,6 +2576,10 @@ class IMAPConnection {
                 this.processQueue(true);
             }
         };
+        if (element.script) {
+            this.runScriptedCommand(element, next);
+            return;
+        }
         if (options.states && options.states.indexOf(this.state) < 0) {
             this.sendStatus(element.parsed, element.data, 'BAD', stateError(command, this.state));
             return next();
@@ -2386,7 +2622,12 @@ class IMAPConnection {
         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 };
+            }
         }
         catch (E) {
             const ex = E;
@@ -2507,6 +2748,41 @@ class IMAPConnection {
         }, mailbox, ignoreSelf || ignoreExists ? this : false);
     }
 }
+/**
+ * Copies a response tree for the `mutate` action of a script rule: arrays and plain objects are copied,
+ * other values (Buffers) are shared
+ *
+ * @param {*} value Response or a part of it
+ * @return {*} Copy
+ */
+function cloneResponse(value) {
+    if (Array.isArray(value)) {
+        return value.map(cloneResponse);
+    }
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        const copy = {};
+        for (const key of Object.keys(value)) {
+            copy[key] = cloneResponse(value[key]);
+        }
+        return copy;
+    }
+    return value;
+}
+/**
+ * Finds the command name in a command line that may not parse: tag SP command, and for UID and AUTHENTICATE
+ * the word that follows
+ *
+ * @param {String} line Command line
+ * @return {String} Command name in upper case, can be empty
+ */
+function getLineCommand(line) {
+    const words = line.match(/^[^ ]* ([^ ]*)(?: ([^ ]*))?/);
+    let command = ((words && words[1]) || '').toUpperCase();
+    if (command === 'UID' || command === 'AUTHENTICATE') {
+        command += ' ' + ((words && words[2]) || '').toUpperCase();
+    }
+    return command;
+}
 /**
  * Formats a mailbox name for a response: an atom when possible, otherwise a string. NIL and names
  * like \\Foo would not read back as mailbox names, so these are strings as well

package/dist/esm/types.d.ts

@@ -1,4 +1,5 @@
 import type { IMAPServer, IMAPConnection } from './server.js';
+import type { ScriptRule } from './script.js';
 export type { IMAPServer, IMAPConnection };
 /**
  * A value of the parsed command or of a response, as imap-handler parses and compiles it: an
@@ -229,6 +230,8 @@ export interface IMAPServerOptions {
     systemFlags?: string[] | undefined;
     /** largest literal accepted after login, in octets */
     maxLiteralSize?: number | undefined;
+    /** script rules that make the server misbehave on purpose, see src/script.ts and README "Scripted faults" */
+    script?: ScriptRule | ScriptRule[] | undefined;
     [key: string]: any;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapkit",
-    "version": "4.1.1",
+    "version": "4.2.0",
     "description": "Scriptable, strictly RFC compliant in-memory IMAP server for testing IMAP clients",
     "type": "module",
     "main": "./dist/cjs/index.js",
@@ -93,7 +93,7 @@
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.13.0",
-        "imapflow": "2.2.8",
+        "imapflow": "2.2.9",
         "prettier": "3.9.9",
         "tsx": "4.23.15",
         "typescript": "6.0.3",