nexus-fca 2.1.5 → 2.1.6

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.1.6] - 2025-08-31 - Memory Guard & Queue Sweeping
+### Added
+- Central lightweight memory guard sweeps: group queue pruning (idle >30m, overflow trim) and pendingEdits TTL sweeper (every 4m).
+- Health metrics extended: memoryGuardRuns, memoryGuardActions, groupQueueDroppedMessages, groupQueueExpiredQueues, groupQueuePrunedThreads, pendingEditSweeps.
+- API: `api.getMemoryMetrics()` returns focused memory-related counters.
+- Typings updated (`EditOptions`, new API methods) in `index.d.ts`.
+
+### Improved
+- Group queue now tracks `lastActive` and enforces idle purge + overflow protection with metrics.
+- Pending edits TTL enforcement separated from resend watchdog for deterministic expiry.
+
+### Notes
+- All guards are low-frequency, low-impact; no change to delivery reliability or safety – only prevention of unbounded growth.
+
+---
+
 ## [2.1.5] - 2025-08-28 - PendingEdits & ACK Metrics
 ### Added
 - PendingEdits buffer with cap (default 200) + TTL (5m) + resend attempts (2) + ACK timeout (12s).

package/index.d.ts

@@ -395,6 +395,11 @@ declare module 'nexus-fca' {
         setMessageReaction: (reaction: string, messageID: string, callback?: (err?: Error) => void, forceCustomReaction?: boolean) => Promise<void>,
         setMessageReactionMqtt: (reaction: string, messageID: string, threadID: string, callback?: (err?: Error) => void) => Promise<void>,
         setOptions: (options: Partial<IFCAU_Options>) => void,
+        setEditOptions: (opts: EditOptions) => void,
+        setBackoffOptions: (opts: { base?: number; max?: number; factor?: number; jitter?: number }) => void,
+        enableLazyPreflight: (enable?: boolean) => void,
+        getHealthMetrics: () => any,
+        getMemoryMetrics: () => { pendingEdits: number; pendingEditsDropped: number; pendingEditsExpired: number; outboundQueueDepth: number; groupQueueDroppedMessages: number; memoryGuardRuns: number; memoryGuardActions: number } | null,
         setTitle: (newTitle: string, threadID: string, callback?: (err?: Error) => void) => Promise<void>,
         setTheme: (themeID?: string, threadID: string, callback?: (err?: Error) => void) => Promise<void>,
         unsendMessage: (messageID: string, callback?: (err?: Error) => void) => Promise<void>,

package/index.js

@@ -273,7 +273,20 @@ function buildAPI(globalOptions, html, jar) {
     getHealthMetrics: function(){ return ctx.health ? ctx.health.snapshot() : null; },
     enableLazyPreflight(enable=true){ ctx.globalOptions.disablePreflight = !enable; },
     setBackoffOptions(opts={}){ ctx.globalOptions.backoff = Object.assign(ctx.globalOptions.backoff||{}, opts); },
-    setEditOptions(opts={}){ Object.assign(ctx.globalOptions.editSettings, opts); }
+    setEditOptions(opts={}){ Object.assign(ctx.globalOptions.editSettings, opts); },
+    getMemoryMetrics(){
+      if(!ctx.health) return null;
+      const snap = ctx.health.snapshot();
+      return {
+        pendingEdits: snap.pendingEdits,
+        pendingEditsDropped: snap.pendingEditsDropped,
+        pendingEditsExpired: snap.pendingEditsExpired,
+        outboundQueueDepth: snap.outboundQueueDepth,
+        groupQueueDroppedMessages: snap.groupQueueDroppedMessages,
+        memoryGuardRuns: snap.memoryGuardRuns,
+        memoryGuardActions: snap.memoryGuardActions
+      };
+    }
   };
   const defaultFuncs = utils.makeDefaults(html, i_userID || userID, ctx);
   require("fs")
@@ -315,7 +328,7 @@ function buildAPI(globalOptions, html, jar) {
   }, 1000 * 60 * 60 * 24);
   // === Group Queue (No Cooldown, Sequential per group) ===
   (function initGroupQueue(){
-    const groupQueues = new Map(); // threadID -> { q: [], sending: false }
+    const groupQueues = new Map(); // threadID -> { q: [], sending: false, lastActive: number }
     const isGroupThread = (tid) => typeof tid === 'string' && tid.length >= 15; // simple heuristic
     const DIRECT_FN = api.sendMessage; // original
 
@@ -325,6 +338,8 @@ function buildAPI(globalOptions, html, jar) {
     api.setGroupQueueCapacity = function(n){ globalOptions.groupQueueMax = n; };
     api.enableGroupQueue(true);
     api.setGroupQueueCapacity(100); // allow up to 100 pending per group
+    // New: group queue retention policy
+    globalOptions.groupQueueIdleMs = 30*60*1000; // 30m idle purge
 
     api._sendMessageDirect = DIRECT_FN;
     api.sendMessage = function(message, threadID, cb){
@@ -332,10 +347,12 @@ function buildAPI(globalOptions, html, jar) {
         return api._sendMessageDirect(message, threadID, cb);
       }
       let entry = groupQueues.get(threadID);
-      if(!entry){ entry = { q: [], sending: false }; groupQueues.set(threadID, entry); }
+      if(!entry){ entry = { q: [], sending: false, lastActive: Date.now() }; groupQueues.set(threadID, entry); }
+      entry.lastActive = Date.now();
       if(entry.q.length >= (globalOptions.groupQueueMax||100)) {
         // drop oldest (keep newest) to avoid unbounded growth
         entry.q.shift();
+        if(ctx.health) ctx.health.recordGroupQueuePrune(0,0,1);
       }
       entry.q.push({ message, threadID, cb });
       processQueue(threadID, entry);
@@ -364,6 +381,33 @@ function buildAPI(globalOptions, html, jar) {
       }
       entry.sending = false;
     };
+
+    // Memory guard sweeper (lightweight)
+    if(!globalOptions._groupQueueSweeper){
+      globalOptions._groupQueueSweeper = setInterval(()=>{
+        const now = Date.now();
+        let prunedThreads = 0; let expiredQueues = 0; let dropped = 0; let actions = 0;
+        for(const [tid, entry] of groupQueues.entries()){
+          // Idle purge
+            if(now - entry.lastActive > (globalOptions.groupQueueIdleMs||1800000) && !entry.sending){
+              if(entry.q.length){ dropped += entry.q.length; }
+              groupQueues.delete(tid); expiredQueues++; actions++;
+              continue;
+            }
+          // Hard cap queue length (just in case capacity changed lower)
+          const cap = globalOptions.groupQueueMax||100;
+          if(entry.q.length > cap){
+            const overflow = entry.q.length - cap;
+            entry.q.splice(0, overflow); // drop oldest overflow
+            dropped += overflow; actions++;
+          }
+        }
+        if((prunedThreads||expiredQueues||dropped) && ctx.health){
+          ctx.health.recordGroupQueuePrune(prunedThreads, expiredQueues, dropped);
+          ctx.health.recordMemoryGuardRun(actions);
+        }
+      }, 5*60*1000); // every 5 minutes
+    }
   })();
   // === End Group Queue ===
   return {

package/lib/health/HealthMetrics.js

@@ -1,5 +1,5 @@
 "use strict";
-// Lightweight health & metrics tracker for Nexus-FCA (extended Stage 2)
+// Lightweight health & metrics tracker for Nexus-FCA (extended Stage 2 + Memory Guard)
 class HealthMetrics {
   constructor() {
     const now = Date.now();
@@ -26,6 +26,14 @@ class HealthMetrics {
     this.p95AckLatencyMs = null;
     this.editResends = 0;
     this.editFailed = 0;
+    // Memory / queue guard metrics (Stage 3)
+    this.memoryGuardRuns = 0;
+    this.memoryGuardLastRun = 0;
+    this.memoryGuardActions = 0;
+    this.groupQueuePrunedThreads = 0;
+    this.groupQueueExpiredQueues = 0;
+    this.groupQueueDroppedMessages = 0;
+    this.pendingEditSweeps = 0;
   }
   onConnect() { this.lastConnectTs = Date.now(); this.consecutiveFailures = 0; }
   onDisconnect() { this.lastDisconnectTs = Date.now(); }
@@ -64,9 +72,16 @@ class HealthMetrics {
     for(const [mid, val] of this.pendingEditMap.entries()){
       if(now - val.ts > ttlMs){ this.pendingEditMap.delete(mid); expired++; }
     }
-    if(expired) { this.incPendingEditExpired(expired); }
+    if(expired) { this.incPendingEditExpired(expired); this.pendingEditSweeps++; }
     this.pendingEdits = this.pendingEditMap.size;
   }
+  // Memory guard helpers
+  recordMemoryGuardRun(actions=0){ this.memoryGuardRuns++; this.memoryGuardLastRun = Date.now(); this.memoryGuardActions += actions; }
+  recordGroupQueuePrune(threads, expiredQueues, droppedMsgs){
+    if(threads) this.groupQueuePrunedThreads += threads;
+    if(expiredQueues) this.groupQueueExpiredQueues += expiredQueues;
+    if(droppedMsgs) this.groupQueueDroppedMessages += droppedMsgs;
+  }
   snapshot(){
     const now = Date.now();
     const idleMs = now - (this.lastMessageTs || this.lastConnectTs || now);
@@ -92,6 +107,13 @@ class HealthMetrics {
       editFailed: this.editFailed,
       outboundQueueDepth: this.outboundQueueDepth,
       outboundQueueDropped: this.outboundQueueDropped,
+      memoryGuardRuns: this.memoryGuardRuns,
+      memoryGuardLastRun: this.memoryGuardLastRun,
+      memoryGuardActions: this.memoryGuardActions,
+      groupQueuePrunedThreads: this.groupQueuePrunedThreads,
+      groupQueueExpiredQueues: this.groupQueueExpiredQueues,
+      groupQueueDroppedMessages: this.groupQueueDroppedMessages,
+      pendingEditSweeps: this.pendingEditSweeps,
       healthy: this.isHealthy(idleMs)
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-fca",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "description": "A modern, safe, and advanced Facebook Chat API for Node.js with fully integrated Nexus Login System. NPM-ready with ID/password/2FA support, ultra-low ban rate protection, and zero external dependencies.",
   "main": "index.js",
   "repository": {