@bobfrankston/iflow-direct 0.1.31 → 0.1.33

package/imap-native.d.ts

@@ -173,6 +173,11 @@ export declare class NativeImapClient {
      *  60s accommodates Gmail which is slow on SEARCH for large folders.
      *  Overridable via ImapClientConfig.inactivityTimeout — slow Dovecot servers need 180s+. */
     private inactivityTimeout;
+    /** Hard wall-clock cap per command (independent of inactivityTimeout).
+     *  A pathological server that returns one byte every (inactivityTimeout-1)
+     *  seconds would otherwise defer the inactivity timer forever; this is
+     *  the absolute deadline that always fires. Default 5 minutes. */
+    private commandWallClockTimeout;
     /** Server-greeting timeout in ms — how long to wait for the server's
      *  initial banner after TCP/TLS connects. Default 10s; bumped to 30s
      *  for slow shared-hosting Dovecot in mailx-imap. */

package/imap-native.js

@@ -32,6 +32,10 @@ export class NativeImapClient {
         this.transport = transportFactory();
         this.verbose = config.verbose || false;
         this.inactivityTimeout = config.inactivityTimeout ?? 60000;
+        // Hard wall-clock deadline per command (default 5 min). Distinct
+        // from inactivityTimeout — that one resets on each data chunk and
+        // can be deferred indefinitely by a slow-trickling server.
+        this.commandWallClockTimeout = config.commandWallClockTimeout ?? 300_000;
         this.fetchChunkSize = config.fetchChunkSize ?? 25;
         this.fetchChunkSizeMax = config.fetchChunkSizeMax ?? 500;
         this.greetingTimeout = config.greetingTimeout ?? 10000;
@@ -729,6 +733,11 @@ export class NativeImapClient {
      *  60s accommodates Gmail which is slow on SEARCH for large folders.
      *  Overridable via ImapClientConfig.inactivityTimeout — slow Dovecot servers need 180s+. */
     inactivityTimeout;
+    /** Hard wall-clock cap per command (independent of inactivityTimeout).
+     *  A pathological server that returns one byte every (inactivityTimeout-1)
+     *  seconds would otherwise defer the inactivity timer forever; this is
+     *  the absolute deadline that always fires. Default 5 minutes. */
+    commandWallClockTimeout;
     /** Server-greeting timeout in ms — how long to wait for the server's
      *  initial banner after TCP/TLS connects. Default 10s; bumped to 30s
      *  for slow shared-hosting Dovecot in mailx-imap. */
@@ -771,43 +780,101 @@ export class NativeImapClient {
             if (this.verbose && !command.includes("LOGIN") && !command.includes("AUTHENTICATE")) {
                 console.log(`  [imap] > ${command.trimEnd()}`);
             }
-            const onTimeout = () => {
+            // Snapshot transport diagnostics — used by both heartbeat and timeout.
+            const transportDiag = () => {
+                try {
+                    const d = this.transport?.diagnostics;
+                    if (!d)
+                        return "";
+                    const sinceRead = d.lastReadAt ? Date.now() - d.lastReadAt : -1;
+                    return ` [conn#${d.connId} r=${d.bytesRead}B w=${d.bytesWritten}B writes=${d.writeCount} sinceLastRead=${sinceRead}ms]`;
+                }
+                catch {
+                    return "";
+                }
+            };
+            // HEARTBEAT_INTERVAL_MS — periodic progress log while a command
+            // is pending. Catches wedges in flight rather than only at the
+            // 300s timeout edge. Key signal: if `sinceLastRead` keeps
+            // climbing, the socket is silently dead. If reads are happening
+            // but the tagged OK never arrives, the parser is stuck.
+            const HEARTBEAT_INTERVAL_MS = 30_000;
+            const cmdStart = Date.now();
+            const cmdSummary = command.split("\r")[0].substring(0, 80);
+            let heartbeatTimer = setInterval(() => {
+                const waited = Date.now() - cmdStart;
+                console.log(`  [imap] still waiting for tag ${tag} after ${(waited / 1000).toFixed(1)}s — ${cmdSummary}${transportDiag()}`);
+            }, HEARTBEAT_INTERVAL_MS);
+            const onTimeout = (kind) => {
                 this.commandTimer = null;
                 this.pendingCommand = null;
+                if (heartbeatTimer) {
+                    clearInterval(heartbeatTimer);
+                    heartbeatTimer = null;
+                }
+                if (wallClockTimer) {
+                    clearTimeout(wallClockTimer);
+                    wallClockTimer = null;
+                }
                 // 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;
-                // Surface transport-level diagnostics if available — bytes
-                // written/read, time since last read, write count, conn id.
-                // Tells us whether the connection was silently dead
-                // (no reads, no writes acked) or genuinely waiting on a
-                // server reply that never came.
-                let diag = "";
-                try {
-                    const d = this.transport?.diagnostics;
-                    if (d) {
-                        const sinceRead = d.lastReadAt ? Date.now() - d.lastReadAt : -1;
-                        diag = ` [conn#${d.connId} r=${d.bytesRead}B w=${d.bytesWritten}B writes=${d.writeCount} sinceLastRead=${sinceRead}ms]`;
-                    }
-                }
-                catch { /* ignore */ }
                 this.transport.close?.();
-                reject(new Error(`IMAP inactivity timeout (${this.inactivityTimeout / 1000}s): ${command.split("\r")[0].substring(0, 80)}${diag}`));
+                reject(new Error(`${kind}: ${cmdSummary}${transportDiag()}`));
+            };
+            // Two timers, two responsibilities:
+            //   commandTimer = "no bytes for N seconds" — handleData resets it
+            //                  on every chunk so a steadily-streaming FETCH
+            //                  doesn't get killed mid-flight.
+            //   wallClockTimer = "this command has been pending too long
+            //                  total" — fires regardless of trickling bytes.
+            //                  Catches the pathological case where a server
+            //                  drips one byte every <inactivityTimeout> seconds
+            //                  for hours (real bobma bug we hit overnight:
+            //                  3 connections wedged 2-3 hours each because
+            //                  the inactivity reset kept deferring the only
+            //                  timer in play).
+            this.commandTimer = setTimeout(() => onTimeout(`IMAP inactivity timeout (${this.inactivityTimeout / 1000}s)`), this.inactivityTimeout);
+            const COMMAND_WALL_CLOCK_TIMEOUT_MS = this.commandWallClockTimeout;
+            let wallClockTimer = setTimeout(() => onTimeout(`IMAP command wall-clock timeout (${COMMAND_WALL_CLOCK_TIMEOUT_MS / 1000}s)`), COMMAND_WALL_CLOCK_TIMEOUT_MS);
+            const clearTimers = () => {
+                if (this.commandTimer) {
+                    clearTimeout(this.commandTimer);
+                    this.commandTimer = null;
+                }
+                if (heartbeatTimer) {
+                    clearInterval(heartbeatTimer);
+                    heartbeatTimer = null;
+                }
+                if (wallClockTimer) {
+                    clearTimeout(wallClockTimer);
+                    wallClockTimer = null;
+                }
             };
-            this.commandTimer = setTimeout(onTimeout, this.inactivityTimeout);
             this.pendingCommand = {
                 tag, responses: [],
-                resolve: (responses) => { if (this.commandTimer)
-                    clearTimeout(this.commandTimer); this.commandTimer = null; resolve(responses); },
-                reject: (err) => { if (this.commandTimer)
-                    clearTimeout(this.commandTimer); this.commandTimer = null; reject(err); },
+                resolve: (responses) => { clearTimers(); resolve(responses); },
+                reject: (err) => { clearTimers(); reject(err); },
                 onUntagged,
             };
+            // PRE-WRITE HEALTH CHECK — verify the socket is in a writable
+            // state BEFORE we burn the inactivityTimeout window waiting for
+            // a reply that can't come. socket-half-closed (peer FIN'd) and
+            // destroyed states both fail fast here instead of after 300s.
+            try {
+                const h = this.transport?.socketHealth;
+                if (h && (h.destroyed || h.writableEnded || !h.writable)) {
+                    clearTimers();
+                    this.pendingCommand = null;
+                    this._connected = false;
+                    reject(new Error(`IMAP socket dead before write: destroyed=${h.destroyed} writableEnded=${h.writableEnded} writable=${h.writable}${transportDiag()}`));
+                    return;
+                }
+            }
+            catch { /* transport may not expose socketHealth — fall through */ }
             this.transport.write(command).catch((err) => {
-                if (this.commandTimer)
-                    clearTimeout(this.commandTimer);
-                this.commandTimer = null;
+                clearTimers();
                 // 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

package/package.json

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

package/types.d.ts

@@ -11,6 +11,7 @@ export interface ImapClientConfig {
     verbose?: boolean;
     rejectUnauthorized?: boolean;
     inactivityTimeout?: number;
+    commandWallClockTimeout?: number;
     fetchChunkSize?: number;
     fetchChunkSizeMax?: number;
     greetingTimeout?: number;