imapkit 4.3.1 → 5.0.0

package/dist/esm/quirks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Quirk presets (#87): named sets of script rules (and plugins to leave out) that make the server behave like a known
+ * real server, so a client test reproduces the bug of that server in every run, without the server itself. The
+ * `quirks` option turns them on, the rules come after the rules of the `script` option. The probabilistic ones use
+ * the random numbers of the `scriptSeed` option, so a run can be repeated. The presets are exported as data, copy
+ * and adjust one as script rules when it does not fit
+ */
+import type { ScriptRule } from './script.js';
+/** A quirk preset */
+export interface Quirk {
+    description: string;
+    /** script rules, see README "Scripted faults" */
+    rules?: ScriptRule[] | undefined;
+    /** plugins that are not loaded even when the `plugins` option lists them */
+    removePlugins?: string[] | undefined;
+}
+export declare const quirks: Record<string, Quirk>;
+/**
+ * Resolves the `quirks` option
+ *
+ * @param {Array|String} names Quirk names
+ * @return {Object} `{ rules, removePlugins }` of all of them
+ * @throws {Error} for an unknown name
+ */
+export declare function resolveQuirks(names: string[] | string | null | undefined): {
+    rules: ScriptRule[];
+    removePlugins: Set<string>;
+};

package/dist/esm/quirks.js

@@ -0,0 +1,120 @@
+/**
+ * Quirk presets (#87): named sets of script rules (and plugins to leave out) that make the server behave like a known
+ * real server, so a client test reproduces the bug of that server in every run, without the server itself. The
+ * `quirks` option turns them on, the rules come after the rules of the `script` option. The probabilistic ones use
+ * the random numbers of the `scriptSeed` option, so a run can be repeated. The presets are exported as data, copy
+ * and adjust one as script rules when it does not fit
+ */
+const FETCH_COMMANDS = ['FETCH', 'UID FETCH'];
+/**
+ * The part a body section belongs to: "2.MIME", "2.HEADER" and "2" all belong to part 2, "HEADER" and "TEXT" to the
+ * message itself
+ *
+ * @param {Array} section Section of a BODY item, its first entry is the section spec
+ * @return {String} part path, "" for the message
+ */
+function partPath(section) {
+    const spec = String((section[0] && section[0].value) || '').toUpperCase();
+    return spec.replace(/(^|\.)(MIME|HEADER(\.FIELDS(\.NOT)?)?|TEXT)$/, '');
+}
+/**
+ * Changes the BODY[...] values of an untagged FETCH response
+ *
+ * @param {Object} response Untagged FETCH response
+ * @param {Function} change `(name, value, index)` returns the new value
+ * @return {Object|undefined} the changed response, nothing for other responses
+ */
+function changeBodyValues(response, change) {
+    const items = response.attributes && response.attributes[2];
+    if (!Array.isArray(items) || !response.attributes[1] || response.attributes[1].value !== 'FETCH') {
+        return undefined;
+    }
+    const changed = items.slice();
+    for (let i = 0; i < changed.length - 1; i += 2) {
+        const name = changed[i];
+        if (name && name.type === 'ATOM' && String(name.value).toUpperCase() === 'BODY' && Array.isArray(name.section)) {
+            changed[i + 1] = change(name, changed[i + 1]);
+        }
+    }
+    return Object.assign({}, response, { attributes: [response.attributes[0], response.attributes[1], changed] });
+}
+export const quirks = {
+    'james-fetchgroup': {
+        description: 'Apache James FetchGroup: only the first section asked for a part in one FETCH is answered, later ones for the same ' +
+            'part come back empty. BODY[2.MIME] BODY[2] gives a zero-length body, the reverse order loses the headers',
+        rules: [
+            {
+                on: 'response',
+                command: FETCH_COMMANDS,
+                untagged: true,
+                mutate: response => {
+                    const seen = new Set();
+                    return changeBodyValues(response, (name, value) => {
+                        const path = partPath(name.section);
+                        if (seen.has(path)) {
+                            return { type: 'LITERAL', value: '' };
+                        }
+                        seen.add(path);
+                        return value;
+                    });
+                }
+            }
+        ]
+    },
+    'james-late-fetch': {
+        description: 'Apache James: now and then (1 in 4) a FETCH response comes after the tagged OK of its command',
+        rules: [{ on: 'response', command: FETCH_COMMANDS, untagged: true, chance: 0.25, defer: 'tagged' }]
+    },
+    'yahoo-quoted-sections': {
+        description: 'Yahoo: short body sections (up to 100 octets without line breaks) are quoted strings instead of literals',
+        rules: [
+            {
+                on: 'response',
+                command: FETCH_COMMANDS,
+                untagged: true,
+                mutate: response => changeBodyValues(response, (name, value) => value && value.type === 'LITERAL' && typeof value.value === 'string' && value.value.length <= 100 && /^[\x20-\x7e]*$/.test(value.value)
+                    ? { type: 'STRING', value: value.value }
+                    : value)
+            }
+        ]
+    },
+    'm365-throttle': {
+        description: 'Microsoft 365: 1 in 10 commands (not LOGOUT) is refused with "BAD Request is throttled. Suggested Backoff Time: 1000 milliseconds"',
+        rules: [
+            {
+                on: 'command',
+                chance: 0.1,
+                when: context => context.command !== 'LOGOUT',
+                send: '$TAG BAD Request is throttled. Suggested Backoff Time: 1000 milliseconds\r\n'
+            }
+        ]
+    },
+    'no-uidplus': {
+        description: 'A server without UIDPLUS: no APPENDUID, COPYUID or UID EXPUNGE, even when the plugins list it',
+        removePlugins: ['UIDPLUS']
+    },
+    'no-move': {
+        description: 'A server without MOVE, clients have to COPY, STORE \\Deleted and EXPUNGE',
+        removePlugins: ['MOVE']
+    }
+};
+/**
+ * Resolves the `quirks` option
+ *
+ * @param {Array|String} names Quirk names
+ * @return {Object} `{ rules, removePlugins }` of all of them
+ * @throws {Error} for an unknown name
+ */
+export function resolveQuirks(names) {
+    const rules = [];
+    const removePlugins = new Set();
+    [].concat(names || []).forEach(name => {
+        const quirk = Object.hasOwn(quirks, String(name).toLowerCase()) ? quirks[String(name).toLowerCase()] : null;
+        if (!quirk) {
+            throw new Error('Unknown quirk "' + name + '". Available quirks: ' + Object.keys(quirks).join(', '));
+        }
+        rules.push(...(quirk.rules || []));
+        (quirk.removePlugins || []).forEach(plugin => removePlugins.add(plugin));
+    });
+    return { rules, removePlugins };
+}

package/dist/esm/random.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Seeded random numbers, so that randomized test behavior (UID shuffles, script rule chances) can be repeated
+ */
+/**
+ * A small seeded random number generator (mulberry32), for repeatable "shuffle" orders
+ *
+ * @param {Number} seed Seed
+ * @return {Function} returns numbers from 0 (inclusive) to 1 (exclusive)
+ */
+export declare function seededRandom(seed: number): () => number;

package/dist/esm/random.js

@@ -0,0 +1,19 @@
+/**
+ * Seeded random numbers, so that randomized test behavior (UID shuffles, script rule chances) can be repeated
+ */
+/**
+ * A small seeded random number generator (mulberry32), for repeatable "shuffle" orders
+ *
+ * @param {Number} seed Seed
+ * @return {Function} returns numbers from 0 (inclusive) to 1 (exclusive)
+ */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/esm/rest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The REST API: the control API over HTTP, for tests written in any language. Off unless the `rest` option (or
+ * `--rest-port`) turns it on. It is full control over the server, including the mail of every user, so it listens
+ * on 127.0.0.1 by default, needs a bearer token on any other address, sends no CORS headers, takes JSON bodies
+ * only (a browser can not send them cross-origin without a CORS preflight) and, without a token, only answers
+ * requests for a loopback host name (DNS rebinding). Built on node:http only.
+ */
+import http from 'node:http';
+import type { IMAPServer } from './types.js';
+import type { ControlRoute as Route } from './control.js';
+/** Options of the REST API, the `rest` server option */
+interface RestOptions {
+    port?: number | undefined;
+    /** address to listen on, 127.0.0.1 by default. Any other than a loopback address needs a token */
+    host?: string | undefined;
+    /** bearer token that every request must send in `Authorization: Bearer <token>` */
+    token?: string | undefined;
+}
+/**
+ * Checks if a host name or address is a loopback one
+ *
+ * @param {String} host Host name or address, can be in brackets
+ * @return {Boolean} true for localhost, 127.0.0.0/8 and ::1
+ */
+declare function isLoopback(host: string): boolean;
+/**
+ * Builds the route table of a server
+ *
+ * @param {Object} server IMAP server
+ * @return {Array} routes
+ */
+declare function getRoutes(server: IMAPServer): Route[];
+/**
+ * Describes the routes as an OpenAPI 3.1 document
+ *
+ * @param {Array} routes Route table
+ * @return {Object} OpenAPI document
+ */
+declare function openApi(routes: Route[]): Record<string, unknown>;
+/**
+ * Creates the HTTP server of the REST API, it does not listen yet
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} options `{ host, token }`
+ * @return {Object} HTTP server
+ * @throws {Error} for a host that is not a loopback address without a token
+ */
+declare function createRestServer(server: IMAPServer, options: RestOptions): http.Server;
+export { createRestServer, isLoopback, getRoutes, openApi };
+export type { RestOptions };