imapflow 2.4.2 → 2.5.0

package/dist/esm/streams-transport.js

@@ -0,0 +1,278 @@
+// The `transport` option over a socket API built on web streams: the socket opens with a promise
+// that resolves to a ReadableStream and a WritableStream of bytes. `cloudflare:sockets` (celld,
+// Cloudflare Workers) is one, see sockets-transport.ts; Chrome's Direct Sockets and in-memory
+// connections fit the same shape. The streams are wrapped into a Duplex that behaves like the
+// net.Socket ImapFlow drives.
+import { Duplex } from 'node:stream';
+import { clearTimer, noop, unrefTimer } from './tools.js';
+function closeQuietly(socket) {
+    try {
+        Promise.resolve(socket.close()).catch(noop);
+    }
+    catch {
+        // already closed
+    }
+}
+class StreamsDuplex extends Duplex {
+    constructor(api, socket, onConnect, plain) {
+        super({ allowHalfOpen: false });
+        // Taken once the socket is open: locking the streams of a socket returned by startTls()
+        // before its handshake completes stalls the handshake on celld
+        this._reader = null;
+        this._writer = null;
+        this._pumping = false;
+        this._readRequested = false;
+        // A runtime may only start TLS on a socket without a read in flight (with one, celld never
+        // completes the handshake), while the read loop always keeps one. So once the client
+        // announced a STARTTLS (holdAfterStarttls), reading stops after the tagged line that answers
+        // it, the only command in flight then, and resumes only when that line is not an OK.
+        this._awaitingStarttls = false;
+        this._lineTail = '';
+        // Set when the partial line got too long to be the one looked for and was dropped: the rest
+        // of it, up to the next line break, is skipped too
+        this._tailDropped = false;
+        this._readsHeld = false;
+        // Set once startTls() handed the connection to a TLS socket: the read that ends then is not
+        // the end of the connection, and closing this socket would close the TLS one
+        this._upgraded = false;
+        this._timeout = 0;
+        this._timer = null;
+        // Traffic only records the time, the one timer re-arms itself for the rest of the idle period
+        this._lastActivity = 0;
+        this._api = api;
+        this._socket = socket;
+        this._plain = plain || null;
+        socket.opened.then(info => {
+            if (this.destroyed) {
+                return;
+            }
+            try {
+                this._reader = info.readable.getReader();
+                this._writer = info.writable.getWriter();
+            }
+            catch (err) {
+                // streams already locked by someone else
+                this.destroy(err);
+                return;
+            }
+            this.remoteAddress = info.remoteAddress;
+            this.remotePort = info.remotePort;
+            this.localAddress = info.localAddress;
+            this.localPort = info.localPort;
+            const tls = info.tls;
+            if (tls) {
+                this.authorized = tls.authorized;
+                this.getCipher = () => ({ name: tls.name || '', standardName: tls.standardName || tls.name || '', version: tls.version || '' });
+            }
+            this._touch();
+            onConnect();
+            if (this._readRequested) {
+                void this._pump();
+            }
+        }, (err) => this.destroy(err));
+        socket.closed?.catch((err) => {
+            if (!this._upgraded) {
+                this.destroy(err);
+            }
+        });
+    }
+    _read() {
+        if (this._readsHeld) {
+            return;
+        }
+        if (!this._reader) {
+            this._readRequested = true;
+        }
+        else if (!this._pumping) {
+            void this._pump();
+        }
+    }
+    async _pump() {
+        const reader = this._reader;
+        this._pumping = true;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (this._upgraded || this.destroyed) {
+                    return;
+                }
+                if (done || !value) {
+                    this.push(null);
+                    return;
+                }
+                this._touch();
+                const chunk = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+                const pushed = this.push(chunk);
+                if (this._awaitingStarttls && this._starttlsCompleted(chunk)) {
+                    this._readsHeld = true;
+                    return;
+                }
+                if (!pushed) {
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            if (!this._upgraded) {
+                this.destroy(err);
+            }
+        }
+        finally {
+            this._pumping = false;
+        }
+    }
+    // Whether the chunk holds the tagged response of the STARTTLS command and it is an OK. Lines
+    // end with LF, CR is optional, as for the parser
+    _starttlsCompleted(chunk) {
+        const skipFirst = this._tailDropped;
+        const lines = (this._lineTail + chunk.toString('latin1')).split('\n');
+        const tail = lines.pop();
+        if (skipFirst && !lines.length) {
+            // still inside the dropped line
+            return false;
+        }
+        this._tailDropped = tail.length > 1024;
+        this._lineTail = this._tailDropped ? '' : tail;
+        for (let i = skipFirst ? 1 : 0; i < lines.length; i++) {
+            const tagged = /^(?![*+] )\S+ (OK|NO|BAD)\b/i.exec(lines[i]);
+            if (tagged) {
+                this._awaitingStarttls = false;
+                return tagged[1].toUpperCase() === 'OK';
+            }
+        }
+        return false;
+    }
+    /** Stops reading after the tagged response of the STARTTLS command about to be sent, if it is an OK */
+    holdAfterStarttls() {
+        this._awaitingStarttls = true;
+        this._lineTail = '';
+        this._tailDropped = false;
+    }
+    _write(chunk, _encoding, callback) {
+        if (!this._writer) {
+            // ImapFlow writes only after onConnect, this is a misuse
+            callback(new Error('Socket is not open yet'));
+            return;
+        }
+        this._touch();
+        this._writer.write(chunk).then(() => callback(), callback);
+    }
+    _destroy(err, callback) {
+        this._clearTimer();
+        if (!this._upgraded) {
+            this._close();
+        }
+        if (this._plain) {
+            // the plain connection went with the TLS one, unless the API keeps it open
+            this._plain._close();
+            this._plain.destroy();
+        }
+        callback(err);
+    }
+    // Closes the connection. An API that refuses to close while its streams are locked (Direct
+    // Sockets) gets a second attempt with the locks released; releasing them right away would
+    // fail the read in flight, which ends the request on celld
+    _close() {
+        const retry = () => {
+            for (const stream of [this._reader, this._writer]) {
+                try {
+                    stream?.releaseLock();
+                }
+                catch {
+                    // an older streams implementation refuses with a read in flight
+                }
+            }
+            closeQuietly(this._socket);
+        };
+        try {
+            const closing = this._socket.close();
+            if (typeof closing?.then === 'function') {
+                closing.then(undefined, retry);
+            }
+        }
+        catch {
+            retry();
+        }
+    }
+    /** Like net.Socket#setTimeout(): emits 'timeout' after `ms` without traffic, 0 disables */
+    setTimeout(ms) {
+        this._timeout = ms;
+        this._clearTimer();
+        this._touch();
+        return this;
+    }
+    setKeepAlive() {
+        return this;
+    }
+    /** Hands the connection over to a TLS socket, this one only stays as its transport */
+    startTls(options, onSecure) {
+        this._upgraded = true;
+        this._clearTimer();
+        // workerd refuses to start TLS while the streams are locked, nothing is in flight on them
+        this._reader?.releaseLock();
+        this._writer?.releaseLock();
+        let tlsSocket;
+        try {
+            tlsSocket = this._api.upgrade(this._socket, options);
+        }
+        catch (err) {
+            // refused before any handshake, the connection is closed with this socket
+            this._upgraded = false;
+            throw err;
+        }
+        return new StreamsDuplex(this._api, tlsSocket, onSecure, this);
+    }
+    _touch() {
+        this._lastActivity = Date.now();
+        if (!this._timer) {
+            this._arm(this._timeout);
+        }
+    }
+    _arm(ms) {
+        if (this._timeout > 0 && !this.destroyed && !this._upgraded) {
+            this._timer = unrefTimer(setTimeout(() => {
+                this._timer = null;
+                const idle = Date.now() - this._lastActivity;
+                if (idle >= this._timeout) {
+                    this.emit('timeout');
+                }
+                else {
+                    this._arm(this._timeout - idle);
+                }
+            }, ms));
+        }
+    }
+    _clearTimer() {
+        clearTimer(this._timer);
+        this._timer = null;
+    }
+}
+/**
+ * Builds a transport for the `transport` option over a socket API built on web streams. A new
+ * API needs only `open()`, and `upgrade()` if it can start TLS on an open connection:
+ *
+ * ```js
+ * const transport = createStreamsTransport({
+ *     open: ({ host, port, secure }) => {
+ *         const socket = openSomeSocket(host, port, secure);
+ *         return { opened: socket.ready.then(() => ({ readable: socket.readable, writable: socket.writable })), close: () => socket.close() };
+ *     }
+ * });
+ * ```
+ *
+ * The transport stops reading once the server accepted a STARTTLS, so the API never has to start
+ * TLS with a read in flight, and releases the stream locks before `upgrade()` is called.
+ *
+ * @param api - Opens (and upgrades) connections
+ * @returns A transport for the `transport` option
+ */
+export function createStreamsTransport(api) {
+    const transport = {
+        connect: (options, onConnect) => new StreamsDuplex(api, api.open(options), onConnect)
+    };
+    if (api.upgrade) {
+        transport.prepareUpgrade = socket => socket.holdAfterStarttls();
+        transport.upgrade = (socket, options, onSecure) => socket.startTls(options, onSecure);
+    }
+    return transport;
+}

package/dist/esm/tools.d.ts

@@ -7,6 +7,15 @@ export { AuthenticationFailure } from './errors.js';
 export declare const EXPANDED_RANGE_LIMIT = 16777216;
 export declare const MAX_UINT32_DIGITS = 10;
 export declare const noop: () => void;
+/**
+ * Tells an IP literal from a hostname without `node:net`, which some runtimes do not implement.
+ * Only used to decide whether a host can be a TLS servername: a dotted quad, or anything with a
+ * colon (an IPv6 literal, a hostname never contains one).
+ *
+ * @param host - Hostname or IP address
+ * @returns true for an IP literal
+ */
+export declare function isIpLiteral(host: string): boolean;
 /**
  * A stream decoder returned by getDecoder(). The Japanese decoder reports the `limited`
  * flag once it has buffered all it will accept; a streaming iconv decoder never sets it.

package/dist/esm/tools.js

@@ -64,6 +64,17 @@ const IMAP4REV2_FOLDED_CAPABILITIES = new Set([
 ]);
 // Deliberate no-op, used as the observer a guarded promise attaches to its own rejection.
 export const noop = () => { };
+/**
+ * Tells an IP literal from a hostname without `node:net`, which some runtimes do not implement.
+ * Only used to decide whether a host can be a TLS servername: a dotted quad, or anything with a
+ * colon (an IPv6 literal, a hostname never contains one).
+ *
+ * @param host - Hostname or IP address
+ * @returns true for an IP literal
+ */
+export function isIpLiteral(host) {
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(':');
+}
 // The fields buildConnectionError() stamps to say *where* a connection error was rejected, as
 // opposed to what went wrong. restampConnectionError() clears them, because they belong to the
 // site that built the error rather than to the failure it describes.

package/dist/esm/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionOptions, CipherNameAndProtocol } from 'node:tls';
-import type { Readable } from 'node:stream';
+import type { Duplex, Readable } from 'node:stream';
 /**
  * Logger interface. Any object with `debug`, `info`, `warn` and `error` methods can be used,
  * for example a pino or bunyan instance. `trace` and `fatal` are used when present.
@@ -95,6 +95,14 @@ export interface ImapFlowOptions {
      * Node as-is. Proxy DNS and negotiation run inside `connectionTimeout`.
      */
     proxy?: string | undefined;
+    /**
+     * Opens the connection through this transport instead of `node:net` and `node:tls`, for
+     * runtimes without those modules. `createSocketsTransport()` builds one from the
+     * `connect()` of the `cloudflare:sockets` API (celld, Cloudflare Workers),
+     * `createStreamsTransport()` from any socket API built on web streams. Can not be combined
+     * with `proxy`.
+     */
+    transport?: ImapTransport | undefined;
     /** If true, then use QRESYNC instead of CONDSTORE. EXPUNGE notifications will include UID instead of sequence number */
     qresync?: boolean | undefined;
     /** If set, then breaks and restarts IDLE every maxIdleTime ms */
@@ -882,3 +890,70 @@ export interface ImapFlowEvents {
     /** The server sent an ALERT: text meant for the user, such as a planned shutdown or an account problem */
     alert: [alert: AlertEvent];
 }
+/** Where {@link ImapTransport} connects to, and the `tls` options of the client */
+export interface ImapTransportOptions {
+    host: string;
+    port: number;
+    /** The SNI name, absent for an IP literal host without the `servername` option */
+    servername?: string | undefined;
+    /** The `tls` option of the client */
+    tls?: ConnectionOptions | undefined;
+}
+/** What {@link ImapTransport.connect} gets: the destination, and whether to open a TLS connection */
+export interface ImapTransportConnectOptions extends ImapTransportOptions {
+    /** Open a TLS connection (the `secure` option), otherwise a cleartext one */
+    secure: boolean;
+}
+/**
+ * The socket a {@link ImapTransport} returns: a Duplex stream of Buffers that emits `error`,
+ * `end` and `close`, and `timeout` once `setTimeout(ms)` was called and `ms` passed without
+ * traffic (0 disables it, like `net.Socket#setTimeout()`), the watchdog behind the
+ * `socketTimeout` option. The rest of what a `net.Socket` has is optional; ImapFlow uses it when
+ * it is there (the addresses for logging, the cipher of a TLS connection for `client.tls`).
+ */
+export type ImapTransportSocket = Duplex & {
+    setTimeout(ms: number): unknown;
+    setKeepAlive?: ((enable?: boolean, initialDelay?: number) => unknown) | undefined;
+    remoteAddress?: string | undefined;
+    remotePort?: number | undefined;
+    localAddress?: string | undefined;
+    localPort?: number | undefined;
+    getCipher?: (() => CipherNameAndProtocol | null) | undefined;
+    authorized?: boolean | undefined;
+};
+/**
+ * Opens and upgrades the socket carrying the session, see the `transport` option.
+ * `createStreamsTransport()` builds one over any socket API built on web streams,
+ * `createSocketsTransport()` over `cloudflare:sockets`.
+ */
+export interface ImapTransport {
+    /**
+     * Opens a connection, cleartext or TLS. Connection errors are emitted on the returned
+     * socket; a connection refused up front (an option the transport can not honor) may throw.
+     *
+     * @param options - Destination, TLS options and whether to open a TLS connection
+     * @param onConnect - Called once the connection (and the TLS handshake) is established
+     */
+    connect(options: ImapTransportConnectOptions, onConnect: () => void): ImapTransportSocket;
+    /**
+     * Called right before the STARTTLS command is sent on the cleartext socket, so a transport
+     * that can only start TLS without a read in flight can stop reading once it is answered.
+     * STARTTLS is the only command in flight then: the next tagged response line (one that does
+     * not start with `* ` or `+ `) answers it, and if it is an OK, the server sends nothing more
+     * before the TLS handshake.
+     *
+     * @param socket - The cleartext socket returned by connect()
+     */
+    prepareUpgrade?: ((socket: ImapTransportSocket) => void) | undefined;
+    /**
+     * Starts TLS on a connected cleartext socket after STARTTLS. May throw if the upgrade is
+     * refused before any handshake, handshake errors are emitted on the returned socket. A
+     * transport that can not start TLS leaves it out: ImapFlow then treats the server as one
+     * without STARTTLS (see the `doSTARTTLS` option).
+     *
+     * @param socket - The cleartext socket returned by connect()
+     * @param options - Destination and TLS options
+     * @param onSecure - Called once the TLS handshake is complete
+     */
+    upgrade?: ((socket: ImapTransportSocket, options: ImapTransportOptions, onSecure: () => void) => ImapTransportSocket) | undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.4.2",
+    "version": "2.5.0",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -37,13 +37,17 @@
         "build": "node scripts/build.js",
         "typecheck": "node scripts/build.js --generate-only && tsc -p tsconfig.json",
         "pretest": "npm run build",
-        "test": "node --import tsx --test --test-force-exit --test-concurrency=1 $(find test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*')",
+        "test": "node --import tsx --test --test-force-exit --test-concurrency=1 $(find test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*' -not -path '*/celld/*' -not -path '*/browser/*')",
         "pretest:coverage": "npm run build",
-        "test:coverage": "c8 node --import tsx --test --test-force-exit --test-concurrency=1 $(find test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*')",
+        "test:coverage": "c8 node --import tsx --test --test-force-exit --test-concurrency=1 $(find test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*' -not -path '*/celld/*' -not -path '*/browser/*')",
         "pretest:bun": "npm run build",
-        "test:bun": "bun test --timeout 60000 $(find ./test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*')",
+        "test:bun": "bun test --timeout 60000 $(find ./test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*' -not -path '*/celld/*' -not -path '*/browser/*')",
         "pretest:workers": "npm run build",
         "test:workers": "node --import tsx --test test/cloudflare/cloudflare-test.ts",
+        "pretest:celld": "npm run build",
+        "test:celld": "node --import tsx --test --test-force-exit test/celld/celld-test.ts",
+        "pretest:browser": "npm run build",
+        "test:browser": "node --import tsx --test --test-force-exit test/browser/browser-test.ts",
         "test:rev2": "bash test/integration/run-rev2-tests.sh",
         "test:mutation": "node scripts/mutation-test.js",
         "format": "prettier --write \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
@@ -71,12 +75,19 @@
     "homepage": "https://imapflow.com/",
     "devDependencies": {
         "@types/node": "20.19.43",
+        "buffer": "6.0.3",
         "c8": "12.0.0",
+        "esbuild": "0.28.2",
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
+        "events": "3.3.0",
         "globals": "17.13.0",
-        "imapkit": "5.0.1",
+        "imapkit": "5.1.0",
+        "playwright-core": "1.64.1",
         "prettier": "3.9.10",
+        "process": "0.11.10",
+        "readable-stream": "4.8.0",
+        "string_decoder": "1.3.0",
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",