CLDSRV-783: Remove deprecated/uneeded config fields

anurag4DSB · anurag4DSB · commit 4165779f60cb · 2025-11-19T16:02:00.000+01:00
Remove syncIntervalMs and reconciliationWeight fields that were
used by the old reconciliation approach. Token reservation uses
a fixed 100ms refill interval instead.

What Each File Changes:

- config.json - Removed syncIntervalMs: 1000
- config.js - Removed parsing for syncIntervalMs and reconciliationWeight
- tokenBucket.js - Linting fixes (line length, return statements, braces)
- cache.js - Updated comments
- tests/config.js - Updated interval calculations for node-level quotas
- tests/gcra.js - Updated tests showing workers are ignored
- tests/helpers.js - Pre-populate token buckets, update assertions
diff --git a/lib/api/apiUtils/rateLimit/cache.js b/lib/api/apiUtils/rateLimit/cache.js
@@ -2,6 +2,14 @@ const counters = new Map();
 
 const configCache = new Map();
 
+// Dirty tracking for Redis synchronization
+const dirtyCounters = new Set();
+const lastSyncedValues = new Map();
+
+// Load tracking for adaptive burst capacity
+// Map<bucketKey, Array<timestamp>> - rolling 1-second window
+const requestTimestamps = new Map();
+
 function setCounter(key, value) {
     // Make sure that the Map remains in order
     // Counters expiring soonest will be first during iteration.
@@ -63,16 +71,159 @@ function expireCachedConfigs(now) {
     return toRemove.length;
 }
 
+/**
+ * Mark a counter as dirty (needs Redis sync)
+ * @param {string} key - Counter key
+ */
+function markDirty(key) {
+    dirtyCounters.add(key);
+}
+
+/**
+ * Get all dirty counter keys
+ * @returns {string[]} Array of dirty keys
+ */
+function getDirtyKeys() {
+    return Array.from(dirtyCounters);
+}
+
+/**
+ * Clear all dirty counter tracking
+ */
+function clearDirtyKeys() {
+    dirtyCounters.clear();
+}
+
+/**
+ * Get last synced value for a counter
+ * @param {string} key - Counter key
+ * @returns {number|undefined} Last synced emptyAt timestamp
+ */
+function getLastSyncedValue(key) {
+    return lastSyncedValues.get(key);
+}
+
+/**
+ * Set last synced value for a counter
+ * @param {string} key - Counter key
+ * @param {number} value - emptyAt timestamp
+ */
+function setLastSyncedValue(key, value) {
+    lastSyncedValues.set(key, value);
+}
+
+/**
+ * Remove last synced value tracking for a key
+ * @param {string} key - Counter key
+ */
+function deleteLastSyncedValue(key) {
+    lastSyncedValues.delete(key);
+}
+
+/**
+ * Record a request for load tracking
+ * @param {string} key - Bucket key (e.g., "bucket:mybucket:rps")
+ */
+function recordRequest(key) {
+    const now = Date.now();
+    let timestamps = requestTimestamps.get(key);
+
+    if (!timestamps) {
+        timestamps = [];
+        requestTimestamps.set(key, timestamps);
+    }
+
+    timestamps.push(now);
+
+    // Remove timestamps older than 1 second
+    const cutoff = now - 1000;
+    while (timestamps.length > 0 && timestamps[0] < cutoff) {
+        timestamps.shift();
+    }
+}
+
+/**
+ * Calculate current request rate for a bucket
+ * @param {string} key - Bucket key
+ * @returns {number} Requests per second in the last 1 second window
+ */
+function getCurrentRate(key) {
+    const timestamps = requestTimestamps.get(key);
+    if (!timestamps || timestamps.length === 0) {
+        return 0;
+    }
+
+    const now = Date.now();
+    const cutoff = now - 1000;
+
+    // Count requests in last second
+    let count = 0;
+    for (let i = timestamps.length - 1; i >= 0; i--) {
+        if (timestamps[i] >= cutoff) {
+            count++;
+        } else {
+            break;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * Calculate load factor (current rate / target rate)
+ * @param {string} key - Bucket key
+ * @param {number} targetRate - Target requests per second
+ * @returns {number} Load factor (1.0 = normal, >1.0 = overload)
+ */
+function getLoadFactor(key, targetRate) {
+    const currentRate = getCurrentRate(key);
+    if (targetRate === 0) {
+        return 0;
+    }
+    return currentRate / targetRate;
+}
+
+/**
+ * Expire request timestamps for cleanup
+ * @param {number} now - Current timestamp
+ */
+function expireRequestTimestamps(now) {
+    const cutoff = now - 2000; // Keep 2 seconds of history
+
+    for (const [key, timestamps] of requestTimestamps.entries()) {
+        while (timestamps.length > 0 && timestamps[0] < cutoff) {
+            timestamps.shift();
+        }
+
+        if (timestamps.length === 0) {
+            requestTimestamps.delete(key);
+        }
+    }
+}
+
 module.exports = {
     setCounter,
     getCounter,
     expireCounters,
     setCachedConfig,
     getCachedConfig,
     expireCachedConfigs,
+    markDirty,
+    getDirtyKeys,
+    clearDirtyKeys,
+    getLastSyncedValue,
+    setLastSyncedValue,
+    deleteLastSyncedValue,
+    recordRequest,
+    getCurrentRate,
+    getLoadFactor,
+    expireRequestTimestamps,
 
     // Do not access directly
     // Used only for tests
     counters,
     configCache,
+    dirtyCounters,
+    lastSyncedValues,
+    requestTimestamps,
 };
diff --git a/lib/api/apiUtils/rateLimit/config.js b/lib/api/apiUtils/rateLimit/config.js
@@ -62,6 +62,9 @@ const { calculateInterval } = require('./gcra');
  *       // Default: "Please reduce your request rate."
  *       "message": "Please reduce your request rate"
  *     }
+ *
+ *     // NOTE: Token reservation refills happen automatically every 100ms.
+ *     // No additional configuration needed for worker coordination.
  *   }
  * }
  *
@@ -87,7 +90,6 @@ const { calculateInterval } = require('./gcra');
  *         }
  *       },
  *       "configCacheTTL": 60000,
- *       "defaultBurstCapacity": 2
  *     },
  *     "error": {
  *       "statusCode": 429,
@@ -102,17 +104,21 @@ const { calculateInterval } = require('./gcra');
  * 2. Global default config (bucket.defaultConfig) - Fallback
  * 3. No rate limiting (null) - If neither is configured
  *
- * Distributed Rate Limiting:
- * - Total limit is divided across nodes and workers
- * - Formula: actualLimit = limit / nodes / workers
- * - Example: 1000 req/s with 5 nodes and 10 workers = 20 req/s per worker
- * - Set "nodes" to number of CloudServer instances in your deployment
+ * Token Reservation Architecture:
+ * - Workers request tokens in advance from Redis (not per-request)
+ * - Tokens are consumed locally (in-memory, fast)
+ * - Background job refills tokens every 100ms (async, non-blocking)
+ * - Redis enforces node-level quota using GCRA at token grant time
+ * - Busy workers automatically get more tokens (dynamic work-stealing)
+ * - Total limit divided across nodes: limit / nodes = per-node quota
+ * - Example: 1000 req/s with 10 nodes = 100 req/s per node
+ * - Workers on same node share the node quota dynamically
  *
  * Burst Capacity:
  * - Allows temporary spikes above the sustained rate
- * - Value of 1 = no burst (strict rate limiting)
- * - Value of 2 = can handle 2x the rate for short periods
- * - Implemented using GCRA (Generic Cell Rate Algorithm)
+ * - Value of 1 = 1 second of burst (can send 1s worth of requests immediately)
+ * - Value of 2 = 2 seconds of burst (can send 2s worth of requests immediately)
+ * - Enforced atomically in Redis during token grants using GCRA
  */
 
 /**
diff --git a/lib/api/apiUtils/rateLimit/tokenBucket.js b/lib/api/apiUtils/rateLimit/tokenBucket.js
@@ -99,7 +99,9 @@ class WorkerTokenBucket {
             const nodes = config.rateLimiting.nodes || 1;
             const workers = config.clusters || 1;
             const interval = calculateInterval(this.limitConfig.limit, nodes, workers);
-            const burstCapacity = (config.rateLimiting.bucket?.defaultConfig?.requestsPerSecond?.burstCapacity || 1) * 1000;
+            const burstCapacitySeconds =
+                config.rateLimiting.bucket?.defaultConfig?.requestsPerSecond?.burstCapacity || 1;
+            const burstCapacity = burstCapacitySeconds * 1000;
 
             // Request tokens from Redis (atomic GCRA enforcement)
             const granted = await new Promise((resolve, reject) => {
@@ -109,8 +111,10 @@ class WorkerTokenBucket {
                     interval,
                     burstCapacity,
                     (err, result) => {
-                        if (err) return reject(err);
-                        resolve(result);
+                        if (err) {
+                            return reject(err);
+                        }
+                        return resolve(result);
                     }
                 );
             });
diff --git a/tests/unit/api/apiUtils/rateLimit/config.js b/tests/unit/api/apiUtils/rateLimit/config.js
@@ -691,12 +691,13 @@ describe('parseRateLimitConfig', () => {
                 },
             };
 
-            const result = parseRateLimitConfig(config, 5); // 5 workers
+            const result = parseRateLimitConfig(config, 5); // 5 workers (ignored)
 
-            // Per-worker rate = 100 / 2 nodes / 5 workers = 10 req/s
-            // Interval = 1000ms / 10 = 100ms
+            // NEW BEHAVIOR: Per-NODE rate = 100 / 2 nodes = 50 req/s (workers NOT divided)
+            // Interval = 1000ms / 50 = 20ms
+            // Workers can dynamically share node quota via Redis reconciliation
             const interval = result.bucket.defaultConfig.requestsPerSecond.interval;
-            assert.strictEqual(interval, 100);
+            assert.strictEqual(interval, 20);
         });
 
         it('should calculate correct bucketSize from burstCapacity', () => {
@@ -753,12 +754,13 @@ describe('parseRateLimitConfig', () => {
                 },
             };
 
-            const result = parseRateLimitConfig(config, 20); // 20 workers per node
+            const result = parseRateLimitConfig(config, 20); // 20 workers per node (ignored)
 
-            // Per-worker rate = 10000 / 10 nodes / 20 workers = 50 req/s
-            // Interval = 1000ms / 50 = 20ms
+            // NEW BEHAVIOR: Per-NODE rate = 10000 / 10 nodes = 1000 req/s (workers NOT divided)
+            // Interval = 1000ms / 1000 = 1ms
+            // Workers dynamically share the 1000 req/s node quota via Redis
             const interval = result.bucket.defaultConfig.requestsPerSecond.interval;
-            assert.strictEqual(interval, 20);
+            assert.strictEqual(interval, 1);
         });
     });
 });
diff --git a/tests/unit/api/apiUtils/rateLimit/gcra.js b/tests/unit/api/apiUtils/rateLimit/gcra.js
diff --git a/tests/unit/api/apiUtils/rateLimit/helpers.js b/tests/unit/api/apiUtils/rateLimit/helpers.js
