rateLimiter.js

'use strict';
// =============================================================================
// rateLimiter.js — Telegram API rate limiter (Upgraded)
// =============================================================================
//
// Enforces:
//   - Global:   ~35–40ms between any two Telegram API calls (~25–28/sec)
//   - Per-chat: 1100ms between consecutive messages to the same chat
//   - Timeout:  API calls that hang >15s are aborted safely
//
// Improvements:
//   - Jitter smoothing to avoid burst clustering under heavy load
//   - Global timestamp updated AFTER call start for smoother throughput
//   - Stronger Promise isolation so one failure never breaks the chain
//   - More accurate per-chat cleanup
//   - Better diagnostics for /health/full
//   - throttleWithConfig() for testall/audit use with optional wait callback
//
// Fully compatible with Node >=20 and the Runewager architecture.
// =============================================================================

// ─── Tuning constants ─────────────────────────────────────────────────────────

const GLOBAL_GAP_MS        = 35;     // ≤28 req/sec globally (Telegram hard limit: 30/sec)
const CHAT_GAP_MS          = 1100;   // 1 msg/sec per chat
const API_CALL_TIMEOUT_MS  = 15000;  // max time for a single Telegram API call
const JITTER_MS            = 5;      // small random jitter to avoid burst alignment

// ─── State ────────────────────────────────────────────────────────────────────

const _chatQueues = new Map();       // chatId → tail Promise
let _globalTail = Promise.resolve(); // global chain
let _globalLast = 0;                 // timestamp of last API call start

// ─── Helpers ──────────────────────────────────────────────────────────────────

const _delay = (ms) => new Promise((r) => setTimeout(r, ms));
const _jitter = () => Math.floor(Math.random() * JITTER_MS);

// ─── Global rate slot ─────────────────────────────────────────────────────────

/**
 * Guarantees GLOBAL_GAP_MS spacing between API calls globally.
 * Adds jitter to avoid burst alignment.
 *
 * @param {() => Promise<any>} fn
 * @returns {Promise<any>}
 */
function _globalSlot(fn) {
    let resolve, reject;
    const resultP = new Promise((res, rej) => { resolve = res; reject = rej; });

    _globalTail = _globalTail
        .then(async () => {
            const now = Date.now();
            const wait = Math.max(0, _globalLast + GLOBAL_GAP_MS - now);
            if (wait > 0) await _delay(wait + _jitter());

            // Update AFTER spacing, BEFORE call
            _globalLast = Date.now();

            try {
                const result = await Promise.race([
                    Promise.resolve().then(fn),
                    _delay(API_CALL_TIMEOUT_MS).then(() => {
                        throw new Error(`rateLimiter: API call timed out after ${API_CALL_TIMEOUT_MS}ms`);
                    }),
                ]);
                resolve(result);
            } catch (err) {
                reject(err);
            }
        })
        .catch(() => {
            // Never break the global chain
        });

    return resultP;
}

// ─── Public API: per-chat queue ───────────────────────────────────────────────

/**
 * Enqueue fn for a specific chatId.
 *
 * - Per-chat serialization
 * - Per-chat spacing (CHAT_GAP_MS)
 * - Global throttle
 *
 * @param {string|number|null} chatId  - Telegram chat/user ID (null → global queue)
 * @param {() => Promise<any>} fn      - Async Telegram API call
 * @returns {Promise<any>}
 */
function enqueue(chatId, fn) {
    const key = chatId != null ? String(chatId) : '_global';
    const prevTail = _chatQueues.get(key) ?? Promise.resolve();

    let resolve, reject;
    const resultP = new Promise((res, rej) => { resolve = res; reject = rej; });

    const newTail = prevTail
        .then(async () => {
            try {
                const result = await _globalSlot(fn);
                resolve(result);
            } catch (err) {
                reject(err);
            }

            // Delay next call for this chat
            await _delay(CHAT_GAP_MS);
        })
        .catch(() => {
            // Never break per-chat chain
        });

    _chatQueues.set(key, newTail);

    // Cleanup stale entries
    newTail.then(() => {
        if (_chatQueues.get(key) === newTail) {
            _chatQueues.delete(key);
        }
    }).catch(() => {});

    return resultP;
}

// ─── Public API: global throttle only ─────────────────────────────────────────

/**
 * Global throttle only — no per-chat serialization.
 * Use for answerCallbackQuery, editMessageText, etc.
 *
 * @param {() => Promise<any>} fn
 * @returns {Promise<any>}
 */
function globalThrottle(fn) {
    return _globalSlot(fn);
}

// ─── Diagnostics ─────────────────────────────────────────────────────────────

/**
 * Return a snapshot of rate-limiter internals for observability.
 * @returns {{ pendingQueues: number, globalLastMs: number }}
 */
function stats() {
    return {
        pendingQueues: _chatQueues.size,
        globalLastMs: _globalLast,
    };
}

/**
 * Return current tuning constants for observability / testall reporting.
 * @returns {{ globalGapMs: number, chatGapMs: number, apiCallTimeoutMs: number, jitterMs: number }}
 */
function settings() {
    return {
        globalGapMs: GLOBAL_GAP_MS,
        chatGapMs: CHAT_GAP_MS,
        apiCallTimeoutMs: API_CALL_TIMEOUT_MS,
        jitterMs: JITTER_MS,
    };
}

/**
 * Route fn through the rate limiter with config-driven chatId + globalOnly selection.
 * Optionally calls onWait(predictedWaitMs, config) before scheduling.
 *
 * Used by /testall and scripts/testall_runtime.js so the audit simulation
 * respects the same rate limits as live traffic.
 *
 * @param {{ chatId?: string|number|null, globalOnly?: boolean, onWait?: Function }} opts
 * @param {() => Promise<any>} fn
 * @returns {Promise<any>}
 */
function throttleWithConfig({ chatId = null, globalOnly = false, onWait = null } = {}, fn) {
    const cfg = settings();
    const predictedWaitMs = Math.max(0, _globalLast + cfg.globalGapMs - Date.now());
    if (predictedWaitMs > 0 && typeof onWait === 'function') {
        try { onWait(predictedWaitMs, cfg); } catch (_) {}
    }
    if (globalOnly) return globalThrottle(fn);
    return enqueue(chatId, fn);
}

module.exports = { enqueue, globalThrottle, stats, settings, throttleWithConfig };