imapkit 4.3.1 → 5.0.0

package/dist/esm/script.js

@@ -1,10 +1,13 @@
-const EVENTS = ['greeting', 'command', 'input', 'response', 'continuation'];
+import { seededRandom } from './random.js';
+import { MAX_NUMBER } from './numbers.js';
+const EVENTS = ['greeting', 'command', 'input', 'response', 'continuation', 'quiet'];
 const OUTPUT_EVENTS = ['greeting', 'response', 'continuation'];
 // the events where a key is valid, every other key is a typo and refused
 const KEYS = {
     on: EVENTS,
-    command: ['command', 'input', 'response', 'continuation'],
-    tag: ['command', 'input', 'response', 'continuation'],
+    // a quiet event belongs to the command that waits for input (IDLE), if there is one
+    command: ['command', 'input', 'response', 'continuation', 'quiet'],
+    tag: ['command', 'input', 'response', 'continuation', 'quiet'],
     description: ['response', 'continuation'],
     session: EVENTS,
     user: EVENTS,
@@ -15,6 +18,8 @@ const KEYS = {
     when: EVENTS,
     nth: EVENTS,
     times: EVENTS,
+    chance: EVENTS,
+    quietFor: ['quiet'],
     mutate: ['response', 'continuation'],
     literals: ['response'],
     defer: ['response'],
@@ -22,7 +27,7 @@ const KEYS = {
     before: OUTPUT_EVENTS,
     after: OUTPUT_EVENTS,
     run: ['command', 'input'],
-    drop: EVENTS,
+    drop: ['greeting', 'command', 'input', 'response', 'continuation'],
     delay: ['greeting', 'command', 'response', 'continuation'],
     chunk: EVENTS,
     chunkDelay: EVENTS,
@@ -70,6 +75,12 @@ function validateRule(rule) {
             throw new TypeError('Script rule option "' + key + '" can not be used with "on": "' + rule.on + '"');
         }
     }
+    if (rule.on === 'quiet' && !(Number.isInteger(rule.quietFor) && rule.quietFor > 0)) {
+        throw new TypeError('A quiet rule needs "quietFor", a positive number of milliseconds');
+    }
+    if (rule.chance !== undefined && !(typeof rule.chance === 'number' && rule.chance >= 0 && rule.chance <= 1)) {
+        throw new TypeError('Script rule option "chance" must be a number from 0 to 1');
+    }
     if (!ACTIONS.some(key => rule[key] !== undefined && rule[key] !== false)) {
         throw new TypeError('A script rule needs an action (' + ACTIONS.join(', ') + ')');
     }
@@ -92,6 +103,9 @@ function validateRule(rule) {
         }
     }
     for (const key of ['delay', 'chunkDelay', 'truncate']) {
+        if (key === 'chunkDelay' && rule[key] === 'tick') {
+            continue;
+        }
         if (rule[key] !== undefined && !(Number.isInteger(rule[key]) && rule[key] >= 0)) {
             throw new TypeError('Script rule option "' + key + '" must be a non-negative integer');
         }
@@ -150,6 +164,14 @@ export class ServerScript {
     constructor(server, rules) {
         this.server = server;
         this.entries = [];
+        this.ruleCounter = 0;
+        const seed = server.options.scriptSeed;
+        const seedRandom = () => {
+            this.random = seededRandom(typeof seed === 'number' ? seed : Math.floor(Math.random() * MAX_NUMBER));
+        };
+        seedRandom();
+        // control.reset() starts the same random sequence again
+        server.on('reset', seedRandom);
         this.watched = new Set();
         if (rules) {
             this.add(rules);
@@ -199,6 +221,26 @@ export class ServerScript {
     setEntries(entries) {
         this.entries = entries;
         this.watched = new Set(entries.map(entry => entry.rule.on));
+        if (this.watched.has('quiet')) {
+            // sessions that are quiet already start counting now
+            this.server.connections?.forEach(connection => connection.watchQuiet());
+        }
+    }
+    /**
+     * The next quiet time a rule waits for, after the quiet time the rules were checked for already
+     *
+     * @param {Number} checked Milliseconds of quiet the rules were checked for
+     * @return {Number|null} the smallest `quietFor` above it, null if there is none
+     */
+    nextQuiet(checked) {
+        let next = null;
+        for (const entry of this.entries) {
+            const quietFor = entry.rule.quietFor;
+            if (entry.rule.on === 'quiet' && quietFor !== undefined && quietFor > checked && (next === null || quietFor < next)) {
+                next = quietFor;
+            }
+        }
+        return next;
     }
     addEntry(rule, match) {
         // a copy, so that changing the caller's object later does not change the rule
@@ -212,6 +254,7 @@ export class ServerScript {
             }
         }
         const entry = {
+            id: ++this.ruleCounter,
             rule: copy,
             match,
             sets,
@@ -238,6 +281,9 @@ export class ServerScript {
             if (entry.matched < (rule.nth || 1) || (rule.times !== undefined && entry.hits >= rule.times)) {
                 continue;
             }
+            if (rule.chance !== undefined && this.random() >= rule.chance) {
+                continue;
+            }
             entry.hits++;
             this.server.emit('script', { rule, event: context.event, session: context.session, tag: context.tag, command: context.command });
             return rule;
@@ -259,6 +305,9 @@ export class ServerScript {
         if (rule.untagged !== undefined && rule.untagged !== (!context.response || context.response.tag === '*')) {
             return false;
         }
+        if (rule.quietFor !== undefined && (context.quiet || 0) < rule.quietFor) {
+            return false;
+        }
         if (entry.match && !entry.match.test(context.data)) {
             return false;
         }
@@ -452,6 +501,16 @@ function sendBytes(connection, rule, data, delay) {
         close: rule.close || (rule.truncate === undefined ? undefined : true)
     });
 }
+/**
+ * Handles a quiet event with the rule that matched it: sends the bytes of `send` and closes the connection with `close`
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Object} rule Rule that matched
+ * @param {Object} context Event context
+ */
+export function handleQuiet(connection, rule, context) {
+    sendBytes(connection, rule, resolveBytes(rule.send, context) || Buffer.alloc(0));
+}
 /**
  * Handles a command or input line with the rule that matched it: sends the bytes of `send`, closes the connection,
  * and processes the line as usual with `run` (or when the rule only delays it)

package/dist/esm/server.d.ts

@@ -1,12 +1,28 @@
 import { Stream } from 'node:stream';
 import net from 'node:net';
+import http from 'node:http';
 import tls from 'node:tls';
 import type { CompilerOptions, ParserOptions } from 'imap-handler';
 import type { ResolvedCommandOptions } from './command-states.js';
+import { Control } from './control.js';
+import type { SessionInfo } from './control.js';
 import { ServerScript } from './script.js';
 import type { DeferredOutput, OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
 import type { AppendCheck, AppendCheckOptions, AppendDataHandler, AppendMessage, CapabilityCheck, CheckResult, ClosedCheck, CommandCheck, CommandContext, CommandOptions, CommandHandler, ConnectionHandler, ConnectionState, CopyHandler, FetchHandler, IMAPResponse, IMAPServerOptions, ListedMailbox, LiteralFilter, Mailbox, MailboxHandler, MailboxStatus, Message, MessageFilter, MessageHandler, MessageRange, Namespace, Notification, NotifyEvent, NotifyFilter, OutputHandler, ParsedCommand, RangeLimit, Refusal, SearchAccessCheck, SearchHandler, SearchLimit, ServerStorage, StatusHandler, StorageMailbox, StorageMessage, StoreHandler, SubscriptionStandIn, Transport, UrlAccessCheck, UserData } from './types.js';
 declare const TAG_REGEX: RegExp;
+/** The parts of a smtp-server SMTPServer that the server uses, smtp-server is an optional dependency */
+interface SMTPListener {
+    close(callback: () => void): void;
+    once(event: 'error', listener: (err: Error) => void): unknown;
+    removeListener(event: 'error', listener: (err: Error) => void): unknown;
+    server: net.Server;
+}
+/** The command whose tagged response is pending, and the session state before it ran */
+interface CommandStart {
+    tag: string;
+    command: string;
+    state: ConnectionState;
+}
 /**
  * Creates a new IMAP server, call `listen()` on it to start accepting connections
  *
@@ -64,7 +80,58 @@ declare class IMAPServer extends Stream {
     script: ServerScript;
     /** connections accepted so far, the number of a connection is `connection.sessionNumber` */
     sessionCounter: number;
+    /** the control API, see src/control.ts */
+    control: Control;
+    /** the SMTP server that `start()` runs for the `smtp` option */
+    smtpServer: SMTPListener | null;
+    /** the HTTP server of the REST API that `start()` runs for the `rest` option */
+    restServer: http.Server | null;
     constructor(options?: IMAPServerOptions);
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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
+     */
+    start(port?: number, host?: string): Promise<number>;
+    /**
+     * Starts the REST API of the `rest` option, see src/rest.ts
+     *
+     * @return {Promise<Number>} resolves with the HTTP port
+     */
+    startRest(): Promise<number>;
+    /**
+     * 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(): Promise<number>;
+    /**
+     * Loads the SMTP listener, which needs the smtp-server package
+     *
+     * @return {Promise<Object>} the smtp-listener module
+     */
+    loadSmtpListener(): Promise<{
+        startSMTPServer(port: number, server: IMAPServer, callback: (port: number) => void, host?: string): SMTPListener;
+    }>;
+    /**
+     * Stops the server and closes every connection
+     *
+     * @return {Promise} resolves when the server is closed
+     */
+    stop(): Promise<void>;
     /**
      * Starts accepting connections, takes the arguments of `net.Server#listen()`
      */
@@ -72,6 +139,13 @@ declare class IMAPServer extends Stream {
     listen(port: number, hostname: string, listeningListener?: () => void): void;
     listen(options: net.ListenOptions, listeningListener?: () => void): void;
     close(callback?: (err?: Error) => void): void;
+    /**
+     * 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: boolean): void;
     /**
      * Returns TLS key and certificate. Without credentials in the options the
      * bundled self-signed certificate for localhost is used.
@@ -144,13 +218,23 @@ declare 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: string, path: string, details?: {
         oldPath?: string | undefined;
         mailbox?: Mailbox | undefined;
+        created?: string[] | undefined;
     }): void;
+    /**
+     * 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<T>(origin: IMAPConnection | null, fn: () => T): T;
     /**
      * Retrieves the handler of an IMAP command
      *
@@ -286,6 +370,13 @@ declare class IMAPServer extends Stream {
      * @param {Array} flags Flags of a message
      */
     rememberFlags(mailbox: Mailbox, flags: string[]): void;
+    /**
+     * 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(): Date;
     /**
      * Converts a date-time value from storage or a client to the form it is sent in
      *
@@ -510,11 +601,18 @@ declare class IMAPConnection {
     } | undefined;
     /** output that waits behind a delay of a script rule, null when output is written right away */
     _outputQueue: OutputOperation[] | null;
-    _outputTimer: ReturnType<typeof setTimeout> | null;
+    _outputTimer: ReturnType<typeof setTimeout> | ReturnType<typeof setImmediate> | null;
+    /** a piece of a chunked write with chunkDelay 0 or "tick" waits until it was handed to the system */
+    _outputWaiting: boolean | undefined;
     /** untagged responses that `defer` rules hold back, see releaseDeferred in src/script.ts */
     _deferredOutput: DeferredOutput[] | null;
     /** a script rule closes the connection with a RST, see closeNow */
     _resetting: boolean | undefined;
+    /** time of the last input or output, and the timer of the quiet events of script rules, see watchQuiet */
+    _lastActivity: number | undefined;
+    _quietTimer: ReturnType<typeof setTimeout> | null | undefined;
+    /** the command whose tagged response is pending and the session before it ran, see commandCompleted */
+    _commandStart: CommandStart | null | undefined;
     constructor(server: IMAPServer, socket: net.Socket);
     /**
      * Writes protocol output to the client, through the transport layer if there is one
@@ -542,8 +640,9 @@ declare 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: Buffer, transport: Transport | null): void;
+    writeLayer(data: Buffer, transport: Transport | null, callback?: () => void): void;
     /**
      * Sends output through the script rule that handles its event, if there is one
      *
@@ -566,7 +665,19 @@ declare class IMAPConnection {
      *
      * @param {Buffer} data Data to send
      */
-    writeRaw(data: Buffer | string): void;
+    writeRaw(data: Buffer | string, callback?: () => void): void;
+    /**
+     * Notes input or output for the quiet events of script rules (#88)
+     */
+    touch(): void;
+    /**
+     * 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?: number): void;
     /**
      * Handles data from the socket, through the transport layer if there is one
      *
@@ -949,6 +1060,34 @@ declare class IMAPConnection {
      * @param {Boolean} [scripted] The line comes from a script rule with `run`, it is next in the queue
      */
     scheduleCommand(data: string, scripted?: boolean): void;
+    /**
+     * 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: string): void;
+    /**
+     * Emits a `session` event, `{ type, session, ...fields }`
+     *
+     * @param {String} type Event type
+     * @param {Object} [fields] More fields of the event
+     */
+    emitSession(type: string, fields?: Record<string, unknown>): void;
+    /**
+     * 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(): SessionInfo;
+    /**
+     * 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(): boolean;
     /**
      * 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
@@ -963,19 +1102,19 @@ declare class IMAPConnection {
      *
      * @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: Mailbox, ignoreSelf?: boolean, ignoreExists?: boolean): void;
     /**
      * 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
      */