@bobfrankston/iflow-direct 0.1.17 → 0.1.19

package/README.md

@@ -99,7 +99,22 @@ would otherwise issue one SELECT+FETCH per message.
 `appendMessage`, `startIdle`, `logout`. See `imap-native.ts` for signatures.
 
 IDLE auto-suspends when any other command is issued on the same connection and
-re-enters afterwards — safe to interleave commands with a long-running IDLE.
+re-enters afterwards — safe to interleave commands with a long-running IDLE,
+including commands issued from the IDLE `onNewMail` callback itself (e.g. a
+mailpuller-style `pullMail` that reacts to EXISTS by running STATUS + FETCH on
+the same connection). Suspend sends DONE, awaits the tagged OK, runs the
+command, then re-enters IDLE. If the caller stops IDLE (via the `startIdle`
+stop function) during the command, IDLE is not re-entered.
+
+## Connection liveness
+
+`NativeImapClient.connected` (and `CompatImapClient`'s lazy `ensureConnected`
+path, which now delegates to it) is authoritative: it gets cleared on transport
+error, transport close, inactivity-timeout socket kill, and write failure. Any
+of those paths also drops IDLE state so auto-suspend doesn't try to DONE a dead
+socket. Callers that detect connection-style errors (e.g. DNS "hostname not
+known" from a dead Android socket) can safely retry — the next operation will
+reconnect from scratch rather than reusing the dead socket.
 
 ## Configuration
 

package/imap-compat.d.ts

@@ -23,11 +23,15 @@ export interface SpecialFolders {
  */
 export declare class CompatImapClient {
     private native;
-    private _connected;
     constructor(config: ImapClientConfig, transportFactory: TransportFactory);
     /** Connect and authenticate */
     connect(): Promise<void>;
-    /** Ensure connected (lazy connect) */
+    /**
+     * Ensure connected (lazy connect). Delegates to the native client's
+     * `connected` flag, which is cleared by transport close/error, inactivity
+     * timeout, and write failures — so a silently dead socket reconnects on the
+     * next call instead of cascading ENOTFOUND across every folder.
+     */
     private ensureConnected;
     logout(): Promise<void>;
     /** Get folder list */

package/imap-compat.js

@@ -11,22 +11,24 @@ import { FetchedMessage } from "./fetched-message.js";
  */
 export class CompatImapClient {
     native;
-    _connected = false;
     constructor(config, transportFactory) {
         this.native = new NativeImapClient(config, transportFactory);
     }
     /** Connect and authenticate */
     async connect() {
         await this.native.connect();
-        this._connected = true;
     }
-    /** Ensure connected (lazy connect) */
+    /**
+     * Ensure connected (lazy connect). Delegates to the native client's
+     * `connected` flag, which is cleared by transport close/error, inactivity
+     * timeout, and write failures — so a silently dead socket reconnects on the
+     * next call instead of cascading ENOTFOUND across every folder.
+     */
     async ensureConnected() {
-        if (!this._connected)
+        if (!this.native.connected)
             await this.connect();
     }
     async logout() {
-        this._connected = false;
         await this.native.logout();
     }
     /** Get folder list */

package/imap-native.d.ts

@@ -55,6 +55,8 @@ export declare class NativeImapClient {
     private idleTag;
     private idleCallback;
     private idleRefreshTimer;
+    /** Set by startIdle's stop closure so auto-suspend knows not to resume after a command finishes. */
+    private idleStopped;
     private verbose;
     private selectedMailbox;
     private mailboxInfo;
@@ -135,6 +137,19 @@ export declare class NativeImapClient {
     /** Append a message to a mailbox */
     appendMessage(mailbox: string, message: string | Uint8Array, flags?: string[]): Promise<number | null>;
     startIdle(onNewMail: (count: number) => void): Promise<() => Promise<void>>;
+    /**
+     * If IDLE is currently active, send DONE and wait for its tagged OK so the
+     * connection is free to accept a new command. Saves the active callback so
+     * the companion `resumeIdleAfterCommand` can re-enter IDLE on the same
+     * mailbox afterwards. Returns the saved state, or null if IDLE was not active.
+     *
+     * Called automatically at the top of `sendCommand` whenever the caller issues
+     * an interleaved command on an IDLE-holding connection (e.g. pullMail reacting
+     * to an EXISTS notification).
+     */
+    private suspendIdleForCommand;
+    /** Re-enter IDLE with the saved callback after an auto-suspended command completes. */
+    private resumeIdleAfterCommand;
     /** Send DONE + re-IDLE. Called by the 28-minute refresh timer. */
     private refreshIdle;
     getMessageCount(mailbox: string): Promise<number>;
@@ -151,7 +166,17 @@ export declare class NativeImapClient {
     private fetchChunkSizeMax;
     /** Active command timer — reset by handleData on every data arrival */
     private commandTimer;
+    /**
+     * Issue an IMAP command and await its tagged response.
+     *
+     * If IDLE is currently active on this connection, DONE it first (and wait
+     * for its tagged OK) before writing the new command; re-enter IDLE after
+     * the command finishes. Without this, commands issued from within an IDLE
+     * EXISTS callback (e.g. mailpuller's pullMail) would be ignored by the
+     * server until the inactivity timer killed the socket.
+     */
     private sendCommand;
+    private sendCommandCore;
     private waitForContinuation;
     private waitForTagged;
     private handleData;

package/imap-native.js

@@ -18,6 +18,8 @@ export class NativeImapClient {
     idleTag = null;
     idleCallback = null;
     idleRefreshTimer = null;
+    /** Set by startIdle's stop closure so auto-suspend knows not to resume after a command finishes. */
+    idleStopped = true;
     verbose;
     selectedMailbox = null;
     mailboxInfo = { exists: 0, recent: 0, uidNext: 0, uidValidity: 0, flags: [], permanentFlags: [] };
@@ -40,7 +42,14 @@ export class NativeImapClient {
         this.transport.onData((data) => this.handleData(data));
         this.transport.onClose(() => {
             this._connected = false;
-            // Reject any pending command so it doesn't hang forever
+            // Drop stale IDLE state — the socket is gone.
+            this.idleTag = null;
+            this.idleCallback = null;
+            this.idleStopped = true;
+            if (this.idleRefreshTimer) {
+                clearTimeout(this.idleRefreshTimer);
+                this.idleRefreshTimer = null;
+            }
             if (this.pendingCommand) {
                 const { reject } = this.pendingCommand;
                 this.pendingCommand = null;
@@ -50,7 +59,18 @@ export class NativeImapClient {
         this.transport.onError((err) => {
             if (this.verbose)
                 console.error(`  [imap] Transport error: ${err.message}`);
-            // Reject any pending command on transport error
+            // Transport errors (DNS failure, ECONNRESET, TLS failure, etc.) mean
+            // the connection is dead — clear the flag so ensureConnected() will
+            // reconnect on the next call, and drop the stale IDLE state so we
+            // don't try to DONE a dead socket during auto-suspend.
+            this._connected = false;
+            this.idleTag = null;
+            this.idleCallback = null;
+            this.idleStopped = true;
+            if (this.idleRefreshTimer) {
+                clearTimeout(this.idleRefreshTimer);
+                this.idleRefreshTimer = null;
+            }
             if (this.pendingCommand) {
                 const { reject } = this.pendingCommand;
                 this.pendingCommand = null;
@@ -480,17 +500,20 @@ export class NativeImapClient {
     // ── IDLE ──
     async startIdle(onNewMail) {
         this.idleCallback = onNewMail;
-        let stopped = false;
+        this.idleStopped = false;
         const beginIdleCycle = async () => {
             const tag = proto.nextTag();
             this.idleTag = tag;
+            // Arm continuation listener BEFORE writing — some servers reply fast enough
+            // that data can arrive in the same tick.
+            const waitCont = this.waitForContinuation(tag);
             await this.transport.write(proto.idleCommand(tag));
-            await this.waitForContinuation(tag);
+            await waitCont;
             // RFC 2177: re-IDLE every ~28 minutes to avoid servers that terminate
             // idle sessions at the 29-minute mark, and to give us a steady
             // application-level keepalive that detects silently-dropped sockets.
             this.idleRefreshTimer = setTimeout(() => {
-                if (stopped)
+                if (this.idleStopped)
                     return;
                 this.refreshIdle().catch(err => {
                     if (this.verbose)
@@ -500,7 +523,7 @@ export class NativeImapClient {
         };
         await beginIdleCycle();
         return async () => {
-            stopped = true;
+            this.idleStopped = true;
             if (this.idleRefreshTimer) {
                 clearTimeout(this.idleRefreshTimer);
                 this.idleRefreshTimer = null;
@@ -508,40 +531,108 @@ export class NativeImapClient {
             const tag = this.idleTag;
             this.idleTag = null;
             this.idleCallback = null;
-            try {
-                await this.transport.write(proto.doneCommand());
-            }
-            catch { /* ignore */ }
             if (tag) {
+                // Arm tagged-wait BEFORE DONE — avoid missing the OK.
+                const waitTag = this.waitForTagged(tag);
                 try {
-                    await this.waitForTagged(tag);
+                    await this.transport.write(proto.doneCommand());
+                }
+                catch { /* ignore */ }
+                try {
+                    await waitTag;
                 }
                 catch { /* ignore */ }
             }
         };
     }
+    /**
+     * If IDLE is currently active, send DONE and wait for its tagged OK so the
+     * connection is free to accept a new command. Saves the active callback so
+     * the companion `resumeIdleAfterCommand` can re-enter IDLE on the same
+     * mailbox afterwards. Returns the saved state, or null if IDLE was not active.
+     *
+     * Called automatically at the top of `sendCommand` whenever the caller issues
+     * an interleaved command on an IDLE-holding connection (e.g. pullMail reacting
+     * to an EXISTS notification).
+     */
+    async suspendIdleForCommand() {
+        const oldTag = this.idleTag;
+        const cb = this.idleCallback;
+        if (!oldTag || !cb)
+            return null;
+        if (this.idleRefreshTimer) {
+            clearTimeout(this.idleRefreshTimer);
+            this.idleRefreshTimer = null;
+        }
+        this.idleTag = null;
+        this.idleCallback = null;
+        if (this.verbose)
+            console.log(`  [imap] IDLE auto-suspending for interleaved command`);
+        // Arm tagged listener BEFORE DONE so we don't miss the OK if the server is fast.
+        const waitTag = this.waitForTagged(oldTag);
+        try {
+            await this.transport.write(proto.doneCommand());
+        }
+        catch (err) {
+            // Write failure — pendingCommand is still set by waitForTagged; clear it to prevent hang.
+            this.pendingCommand = null;
+            throw err;
+        }
+        try {
+            await waitTag;
+        }
+        catch { /* best-effort — proceed even if OK was lost */ }
+        return { callback: cb };
+    }
+    /** Re-enter IDLE with the saved callback after an auto-suspended command completes. */
+    async resumeIdleAfterCommand(info) {
+        // The caller may have stopped IDLE during the command window — respect that.
+        if (this.idleStopped)
+            return;
+        const newTag = proto.nextTag();
+        this.idleTag = newTag;
+        this.idleCallback = info.callback;
+        // Arm continuation listener BEFORE writing IDLE.
+        const waitCont = this.waitForContinuation(newTag);
+        await this.transport.write(proto.idleCommand(newTag));
+        await waitCont;
+        if (this.verbose)
+            console.log(`  [imap] IDLE auto-resumed (${newTag})`);
+        this.idleRefreshTimer = setTimeout(() => {
+            if (this.idleStopped)
+                return;
+            this.refreshIdle().catch(err => {
+                if (this.verbose)
+                    console.error(`  [imap] IDLE refresh failed: ${err.message}`);
+            });
+        }, 28 * 60 * 1000);
+    }
     /** Send DONE + re-IDLE. Called by the 28-minute refresh timer. */
     async refreshIdle() {
         const oldTag = this.idleTag;
         if (!oldTag || !this.idleCallback)
             return;
         const cb = this.idleCallback;
-        // DONE the current IDLE
+        // Arm tagged listener BEFORE writing DONE to avoid missing a fast OK.
+        const waitTag = this.waitForTagged(oldTag);
         await this.transport.write(proto.doneCommand());
         try {
-            await this.waitForTagged(oldTag);
+            await waitTag;
         }
         catch { /* best-effort */ }
         // Re-IDLE with a new tag
         this.idleCallback = cb; // waitForTagged resolved pendingCommand, reinstall callback
         const newTag = proto.nextTag();
         this.idleTag = newTag;
+        const waitCont = this.waitForContinuation(newTag);
         await this.transport.write(proto.idleCommand(newTag));
-        await this.waitForContinuation(newTag);
+        await waitCont;
         if (this.verbose)
             console.log(`  [imap] IDLE refreshed (${newTag})`);
         // Schedule the next refresh
         this.idleRefreshTimer = setTimeout(() => {
+            if (this.idleStopped)
+                return;
             this.refreshIdle().catch(err => {
                 if (this.verbose)
                     console.error(`  [imap] IDLE refresh failed: ${err.message}`);
@@ -567,7 +658,33 @@ export class NativeImapClient {
     fetchChunkSizeMax;
     /** Active command timer — reset by handleData on every data arrival */
     commandTimer = null;
-    sendCommand(tag, command, onUntagged) {
+    /**
+     * Issue an IMAP command and await its tagged response.
+     *
+     * If IDLE is currently active on this connection, DONE it first (and wait
+     * for its tagged OK) before writing the new command; re-enter IDLE after
+     * the command finishes. Without this, commands issued from within an IDLE
+     * EXISTS callback (e.g. mailpuller's pullMail) would be ignored by the
+     * server until the inactivity timer killed the socket.
+     */
+    async sendCommand(tag, command, onUntagged) {
+        const idleState = await this.suspendIdleForCommand();
+        try {
+            return await this.sendCommandCore(tag, command, onUntagged);
+        }
+        finally {
+            if (idleState) {
+                try {
+                    await this.resumeIdleAfterCommand(idleState);
+                }
+                catch (err) {
+                    if (this.verbose)
+                        console.error(`  [imap] IDLE auto-resume failed: ${err.message}`);
+                }
+            }
+        }
+    }
+    sendCommandCore(tag, command, onUntagged) {
         return new Promise((resolve, reject) => {
             if (this.verbose && !command.includes("LOGIN") && !command.includes("AUTHENTICATE")) {
                 console.log(`  [imap] > ${command.trimEnd()}`);
@@ -575,7 +692,10 @@ export class NativeImapClient {
             const onTimeout = () => {
                 this.commandTimer = null;
                 this.pendingCommand = null;
-                // Kill the connection — a timed-out connection has stale data in the pipe
+                // Kill the connection — a timed-out connection has stale data in the pipe.
+                // Mark disconnected so ensureConnected() reconnects on the next call —
+                // transport.close() may or may not fire onClose synchronously.
+                this._connected = false;
                 this.transport.close?.();
                 reject(new Error(`IMAP inactivity timeout (${this.inactivityTimeout / 1000}s): ${command.split("\r")[0].substring(0, 80)}`));
             };
@@ -588,8 +708,18 @@ export class NativeImapClient {
                     clearTimeout(this.commandTimer); this.commandTimer = null; reject(err); },
                 onUntagged,
             };
-            this.transport.write(command).catch((err) => { if (this.commandTimer)
-                clearTimeout(this.commandTimer); this.commandTimer = null; reject(err); });
+            this.transport.write(command).catch((err) => {
+                if (this.commandTimer)
+                    clearTimeout(this.commandTimer);
+                this.commandTimer = null;
+                // Write failure = dead socket. Clear pendingCommand + disconnect flag
+                // so the next ensureConnected() does a fresh connect instead of
+                // reusing a socket that the OS layer has already declared dead
+                // (the source of the "hostname nor servname provided" cascade).
+                this.pendingCommand = null;
+                this._connected = false;
+                reject(err);
+            });
         });
     }
     waitForContinuation(tag) {
@@ -619,6 +749,7 @@ export class NativeImapClient {
                 if (this.pendingCommand) {
                     const cmd = this.pendingCommand;
                     this.pendingCommand = null;
+                    this._connected = false;
                     this.transport.close?.();
                     cmd.reject(new Error(`IMAP inactivity timeout (${this.inactivityTimeout / 1000}s)`));
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/iflow-direct",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",