@bobfrankston/iflow-direct 0.1.17 → 0.1.18

package/README.md

@@ -99,7 +99,12 @@ 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.
 
 ## Configuration
 

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: [] };
@@ -480,17 +482,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 +505,7 @@ export class NativeImapClient {
         };
         await beginIdleCycle();
         return async () => {
-            stopped = true;
+            this.idleStopped = true;
             if (this.idleRefreshTimer) {
                 clearTimeout(this.idleRefreshTimer);
                 this.idleRefreshTimer = null;
@@ -508,40 +513,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.transport.write(proto.doneCommand());
+                }
+                catch { /* ignore */ }
                 try {
-                    await this.waitForTagged(tag);
+                    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 +640,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()}`);

package/package.json

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