@bobfrankston/rmfmail 1.2.239 → 1.2.240

package/packages/mailx-imap/index.ts

@@ -282,6 +282,18 @@ export class ImapManager extends EventEmitter {
      *  (rate limits, network) are NOT recorded here — they keep the normal
      *  60s deadman cadence. */
     private watchAuthFailed: Map<string, string> = new Map();
+    /** Accounts the SERVER has told us to back off, with when they may be
+     *  tried again and how many consecutive refusals we've had.
+     *
+     *  AOL/Yahoo answer an over-quota LOGIN with `[LIMIT] LOGIN Rate limit
+     *  hit.` — an explicit instruction, not a transient blip. mailx used to
+     *  treat it as transient and keep the 60 s deadman cadence, so every
+     *  refusal was followed by another LOGIN a minute later: measured on
+     *  2026-08-09, four separate runs of 4–22 minutes, one failed attempt per
+     *  minute throughout, every one of them spending quota that keeps the
+     *  limiter hot. Backing off is not politeness, it is how the account
+     *  becomes usable again sooner. */
+    private rateLimited: Map<string, { until: number; strikes: number }> = new Map();
     private fetchClients: Map<string, any> = new Map();
     /** The Store is the architectural nexus — owner of MailxDB +
      *  FileMessageStore + the event bus. This package (mailx-imap) is a
@@ -340,7 +352,7 @@ export class ImapManager extends EventEmitter {
             if (m) d.lastCommand = m[0].slice(0, 120);
         } else if (/UNAVAILABLE|Maximum number of connections|too many connections/i.test(errMsg)) {
             d.connCapHits++;
-        } else if (/429|rate limit/i.test(errMsg)) {
+        } else if (/429|rate limit|\[LIMIT\]/i.test(errMsg)) {
             d.rateLimitWaits++;
         } else {
             return; // not a known diagnostic class — don't emit
@@ -903,7 +915,46 @@ export class ImapManager extends EventEmitter {
      *  client; the slot is released when logout() or destroy() runs.
      *  `purpose` is a short tag printed alongside the `[conn+]` log so we can
      *  tell which code path (ops/idle/etc.) opened each connection. */
+    /** Remaining cooldown in ms for an account the server rate-limited, or 0. */
+    rateLimitRemaining(accountId: string): number {
+        const e = this.rateLimited.get(accountId);
+        if (!e) return 0;
+        const left = e.until - Date.now();
+        if (left <= 0) { this.rateLimited.delete(accountId); return 0; }
+        return left;
+    }
+
+    /** Record a server rate-limit refusal and widen the cooldown. 5 → 10 → 20
+     *  → 30 min (capped): long enough to actually clear AOL's window, short
+     *  enough that a mistake costs one poll cycle rather than an afternoon. */
+    private noteRateLimited(accountId: string, errMsg: string): void {
+        const prev = this.rateLimited.get(accountId);
+        const strikes = (prev?.strikes || 0) + 1;
+        const mins = Math.min(30, 5 * Math.pow(2, strikes - 1));
+        const until = Date.now() + mins * 60_000;
+        this.rateLimited.set(accountId, { until, strikes });
+        console.warn(`  [rate-limit] ${accountId}: server said "${errMsg.trim().slice(0, 60)}" — pausing ALL lanes for ${mins} min (strike ${strikes})`);
+        this.emit("rateLimited", { accountId, untilMs: until, minutes: mins, strikes });
+    }
+
+    /** Clear the cooldown after a connection succeeds. */
+    private noteRateLimitCleared(accountId: string): void {
+        if (this.rateLimited.delete(accountId)) {
+            console.log(`  [rate-limit] ${accountId}: connection accepted again — cooldown cleared`);
+            this.emit("rateLimitCleared", { accountId });
+        }
+    }
+
     private async newClient(accountId: string, purpose = "?"): Promise<any> {
+        // Refuse to spend a LOGIN the server has already told us it will not
+        // accept. Every lane funnels through newClient, so one check covers
+        // sync, quickCheck, IDLE, outbox and fetch alike — which matters,
+        // because the lanes retry independently and would otherwise take turns
+        // poking the limiter.
+        const cooldown = this.rateLimitRemaining(accountId);
+        if (cooldown > 0) {
+            throw new Error(`rate-limited by server — retrying in ${Math.ceil(cooldown / 60_000)} min (no LOGIN attempted)`);
+        }
         if (this.reauthenticating.has(accountId)) throw new Error(`Account ${accountId} is re-authenticating`);
         const config = this.configs.get(accountId);
         if (!config) throw new Error(`No config for account ${accountId}`);
@@ -991,10 +1042,20 @@ export class ImapManager extends EventEmitter {
                         // both.
                         const sock = client?.native?.transport?.socket;
                         if (typeof sock?.once === "function") sock.once("close", () => markClosed("socket-close"));
+                        // A LOGIN the server accepted is the only proof the
+                        // cooldown is over — clear it here rather than letting
+                        // it lapse on a timer alone.
+                        this.noteRateLimitCleared(accountId);
                         return r;
                     } catch (e: any) {
                         emitPhase("failed", e?.message || String(e));
                         markClosed("connect-failed");
+                        // Every lane (sync, quickCheck, IDLE, outbox, fetch)
+                        // connects through here, so this one line is what makes
+                        // a rate-limit refusal stop ALL of them instead of each
+                        // discovering it separately, once a minute, forever.
+                        const em = e?.message || String(e);
+                        if (/[LIMIT]|rate limit/i.test(em)) this.noteRateLimited(accountId, em);
                         throw e;
                     }
                 };

package/packages/mailx-imap/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bobfrankston/mailx-imap",
-  "version": "0.1.147",
+  "version": "0.1.148",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bobfrankston/mailx-imap",
-      "version": "0.1.147",
+      "version": "0.1.148",
       "license": "ISC",
       "dependencies": {
         "@bobfrankston/iflow-direct": "^0.1.27",

package/packages/mailx-imap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-imap",
-  "version": "0.1.147",
+  "version": "0.1.148",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/packages/mailx-imap/test/rate-limit-backoff.test.mjs

@@ -0,0 +1,61 @@
+/**
+ * AOL/Yahoo answer an over-quota LOGIN with `[LIMIT] LOGIN Rate limit hit.`
+ * Before v1.2.240 every lane treated that as transient and retried on its own
+ * 60 s cadence, so a refusal was followed by another LOGIN a minute later for
+ * as long as it lasted (measured 2026-08-09: four runs, up to 22 minutes,
+ * ~one wasted LOGIN per minute).
+ *
+ * These checks drive the real ImapManager methods over the cooldown state.
+ * Run: node packages/mailx-imap/test/rate-limit-backoff.test.mjs
+ */
+import assert from "node:assert";
+
+const { ImapManager } = await import("file:///Y:/dev/email/mailx/app/packages/mailx-imap/index.js");
+
+const mgr = Object.create(ImapManager.prototype);
+mgr.rateLimited = new Map();
+const events = [];
+mgr.emit = (name, payload) => { events.push({ name, payload }); };
+
+const LIMIT = "Login failed: [LIMIT] LOGIN Rate limit hit.";
+
+// 1. A refusal starts a cooldown, and it is reported (not swallowed).
+assert.strictEqual(mgr.rateLimitRemaining("aol"), 0, "clean account has no cooldown");
+mgr.noteRateLimited("aol", LIMIT);
+const first = mgr.rateLimitRemaining("aol");
+assert.ok(first > 4 * 60_000 && first <= 5 * 60_000, `first cooldown should be ~5 min, got ${Math.round(first / 1000)}s`);
+assert.ok(events.some(e => e.name === "rateLimited" && e.payload.accountId === "aol"),
+    "a cooldown must be announced — a silently paused account looks broken");
+
+// 2. Repeated refusals widen it: 5 → 10 → 20 → 30 (capped).
+const mins = [];
+for (let i = 0; i < 4; i++) { mgr.noteRateLimited("aol", LIMIT); mins.push(Math.round(mgr.rateLimitRemaining("aol") / 60_000)); }
+assert.deepStrictEqual(mins, [10, 20, 30, 30], `backoff should widen and cap at 30, got ${mins.join(",")}`);
+
+// 3. Other accounts are untouched — the limit is per-account, not global.
+assert.strictEqual(mgr.rateLimitRemaining("bobma"), 0, "one account's cooldown must not pause another");
+
+// 4. A successful connection clears it, and says so.
+mgr.noteRateLimitCleared("aol");
+assert.strictEqual(mgr.rateLimitRemaining("aol"), 0, "success must clear the cooldown");
+assert.ok(events.some(e => e.name === "rateLimitCleared"), "recovery must be announced too");
+
+// 5. An expired cooldown lapses on its own (no success needed).
+mgr.rateLimited.set("aol", { until: Date.now() - 1, strikes: 3 });
+assert.strictEqual(mgr.rateLimitRemaining("aol"), 0, "a lapsed cooldown must not block forever");
+assert.ok(!mgr.rateLimited.has("aol"), "lapsed entry should be dropped, not left to accumulate");
+
+// 6. THE POINT: while cooling down, newClient must refuse to spend a LOGIN —
+//    for every lane, since each one used to discover the limit separately.
+mgr.rateLimited.set("aol", { until: Date.now() + 5 * 60_000, strikes: 1 });
+let attempted = 0;
+mgr.acquireHostSlot = async () => { attempted++; return () => {}; };   // reached only if the guard lets it through
+for (const lane of ["sync", "quickCheck", "idle", "outbox", "fetch"]) {
+    await assert.rejects(
+        () => ImapManager.prototype.newClient.call(mgr, "aol", lane),
+        /rate-limited by server/,
+        `lane "${lane}" must be refused while the account is cooling down`);
+}
+assert.strictEqual(attempted, 0, "no lane may reach the connect path during a cooldown");
+
+console.log("rate-limit backoff: 6 scenarios passed");

package/packages/mailx-settings/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-settings",
-  "version": "0.1.50",
+  "version": "0.1.51",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/packages/mailx-types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",