@poolzin/pool-bot 2026.2.19 → 2026.2.21

package/dist/agents/provider/rate-limits.js

@@ -0,0 +1,458 @@
+/**
+ * Rate Limit Tracker
+ *
+ * Proactively tracks rate limit states for API keys across providers.
+ * Enables intelligent key rotation by avoiding known-limited keys before making requests.
+ *
+ * @module provider/rate-limits
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+export var RateLimits;
+(function (RateLimits) {
+    const log = createSubsystemLogger("provider/rate-limits");
+    /**
+     * Standard HTTP headers used by AI providers for rate limit information.
+     * Each provider may use different subsets of these headers.
+     */
+    RateLimits.RATE_LIMIT_HEADERS = {
+        /** Unix timestamp or seconds until reset */
+        reset: [
+            "x-ratelimit-reset",
+            "x-ratelimit-reset-requests",
+            "x-ratelimit-reset-tokens",
+            "retry-after",
+            "retry-after-ms",
+        ],
+        /** Remaining requests in current window */
+        remainingRequests: ["x-ratelimit-remaining", "x-ratelimit-remaining-requests"],
+        /** Remaining tokens in current window */
+        remainingTokens: ["x-ratelimit-remaining-tokens"],
+        /** Rate limit tier/limit info */
+        limit: ["x-ratelimit-limit", "x-ratelimit-limit-requests", "x-ratelimit-limit-tokens"],
+    };
+    /**
+     * HTTP status codes that indicate rate limiting or temporary unavailability.
+     */
+    RateLimits.RATE_LIMIT_STATUS_CODES = {
+        /** Standard rate limit exceeded */
+        TOO_MANY_REQUESTS: 429,
+        /** Service temporarily unavailable (often due to overload) */
+        SERVICE_UNAVAILABLE: 503,
+        /** Site is overloaded (Cloudflare) */
+        SITE_OVERLOADED: 529,
+    };
+    /**
+     * In-memory store for rate limit states.
+     * Key format: "providerID" or "providerID:keyID"
+     */
+    const states = new Map();
+    /**
+     * Maximum number of rate limit states to prevent unbounded memory growth.
+     * States are cleaned up on expiry, but this provides a hard cap.
+     */
+    const MAX_STATES = 500;
+    /**
+     * Interval handle for cleanup task.
+     */
+    let cleanupInterval = null;
+    /**
+     * Generates a unique key for the rate limit state map.
+     */
+    function getStateKey(providerID, keyID) {
+        return keyID ? `${providerID}:${keyID}` : providerID;
+    }
+    /**
+     * Parses rate limit information from HTTP response headers.
+     *
+     * @param headers - Response headers (can be Headers object or plain object)
+     * @returns Parsed rate limit information
+     *
+     * @example
+     * ```typescript
+     * const headers = new Headers({
+     *   'x-ratelimit-remaining-requests': '100',
+     *   'x-ratelimit-reset': '1704067200'
+     * })
+     * const parsed = RateLimits.parseHeaders(headers)
+     * // { remainingRequests: 100, resetAt: 1704067200000 }
+     * ```
+     */
+    function parseHeaders(headers) {
+        const result = {};
+        const get = (name) => {
+            if (headers instanceof Headers) {
+                return headers.get(name) ?? undefined;
+            }
+            return headers[name] ?? headers[name.toLowerCase()];
+        };
+        // Parse reset time
+        for (const header of RateLimits.RATE_LIMIT_HEADERS.reset) {
+            const value = get(header);
+            if (value === undefined)
+                continue;
+            if (header === "retry-after-ms") {
+                const ms = Number.parseFloat(value);
+                if (!Number.isNaN(ms)) {
+                    result.resetAt = Date.now() + ms;
+                    break;
+                }
+            }
+            else if (header === "retry-after") {
+                const seconds = Number.parseFloat(value);
+                if (!Number.isNaN(seconds)) {
+                    result.resetAt = Date.now() + seconds * 1000;
+                    break;
+                }
+                // Try HTTP date format
+                const date = Date.parse(value);
+                if (!Number.isNaN(date)) {
+                    result.resetAt = date;
+                    break;
+                }
+            }
+            else {
+                // x-ratelimit-reset headers are typically Unix timestamps in seconds
+                const timestamp = Number.parseFloat(value);
+                if (!Number.isNaN(timestamp)) {
+                    // If timestamp is small, it's likely seconds from now
+                    // If large, it's a Unix timestamp
+                    result.resetAt = timestamp < 1e10 ? Date.now() + timestamp * 1000 : timestamp * 1000;
+                    break;
+                }
+            }
+        }
+        // Parse remaining requests
+        for (const header of RateLimits.RATE_LIMIT_HEADERS.remainingRequests) {
+            const value = get(header);
+            if (value !== undefined) {
+                const parsed = Number.parseInt(value, 10);
+                if (!Number.isNaN(parsed)) {
+                    result.remainingRequests = parsed;
+                    break;
+                }
+            }
+        }
+        // Parse remaining tokens
+        for (const header of RateLimits.RATE_LIMIT_HEADERS.remainingTokens) {
+            const value = get(header);
+            if (value !== undefined) {
+                const parsed = Number.parseInt(value, 10);
+                if (!Number.isNaN(parsed)) {
+                    result.remainingTokens = parsed;
+                    break;
+                }
+            }
+        }
+        // Parse limits
+        for (const header of RateLimits.RATE_LIMIT_HEADERS.limit) {
+            const value = get(header);
+            if (value !== undefined) {
+                const parsed = Number.parseInt(value, 10);
+                if (!Number.isNaN(parsed)) {
+                    if (header.includes("tokens")) {
+                        result.limitTokens = parsed;
+                    }
+                    else {
+                        result.limitRequests = parsed;
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    RateLimits.parseHeaders = parseHeaders;
+    /**
+     * Marks a key as rate limited.
+     *
+     * @param providerID - Provider identifier
+     * @param statusCode - HTTP status code that triggered the limit
+     * @param reason - Human-readable reason
+     * @param options - Additional options
+     *
+     * @example
+     * ```typescript
+     * RateLimits.markLimited("anthropic", 429, "Too Many Requests", {
+     *   keyID: "key-1",
+     *   resetAt: Date.now() + 60000,
+     *   remainingRequests: 0
+     * })
+     * ```
+     */
+    function markLimited(providerID, statusCode, reason, options = {}) {
+        const key = getStateKey(providerID, options.keyID);
+        const now = Date.now();
+        if (states.size >= MAX_STATES && !states.has(key)) {
+            evictExpiredOrOldestStates();
+        }
+        const defaultResetMs = statusCode === RateLimits.RATE_LIMIT_STATUS_CODES.TOO_MANY_REQUESTS ? 60_000 : 30_000;
+        const state = {
+            id: key,
+            providerID,
+            keyID: options.keyID,
+            resetAt: options.resetAt ?? now + defaultResetMs,
+            remainingRequests: options.remainingRequests,
+            remainingTokens: options.remainingTokens,
+            statusCode,
+            reason,
+            recordedAt: now,
+        };
+        states.set(key, state);
+        log.info("rate-limited", {
+            providerID,
+            keyID: options.keyID,
+            statusCode,
+            reason,
+            resetIn: Math.round((state.resetAt - now) / 1000) + "s",
+        });
+    }
+    RateLimits.markLimited = markLimited;
+    function evictExpiredOrOldestStates() {
+        const now = Date.now();
+        let evicted = 0;
+        for (const [key, state] of states.entries()) {
+            if (state.resetAt <= now) {
+                states.delete(key);
+                evicted++;
+            }
+        }
+        if (evicted > 0) {
+            log.debug("evicted-expired-states", { count: evicted });
+            return;
+        }
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, state] of states.entries()) {
+            if (state.recordedAt < oldestTime) {
+                oldestTime = state.recordedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            states.delete(oldestKey);
+            log.debug("evicted-oldest-state", { key: oldestKey });
+        }
+    }
+    /**
+     * Marks a key as rate limited from response headers.
+     * Convenience method that combines parseHeaders and markLimited.
+     *
+     * @param providerID - Provider identifier
+     * @param statusCode - HTTP status code
+     * @param headers - Response headers
+     * @param keyID - Optional key identifier
+     */
+    function markLimitedFromResponse(providerID, statusCode, headers, keyID) {
+        const parsed = parseHeaders(headers);
+        const reason = getReasonFromStatusCode(statusCode);
+        markLimited(providerID, statusCode, reason, {
+            keyID,
+            resetAt: parsed.resetAt,
+            remainingRequests: parsed.remainingRequests,
+            remainingTokens: parsed.remainingTokens,
+        });
+    }
+    RateLimits.markLimitedFromResponse = markLimitedFromResponse;
+    /**
+     * Gets a human-readable reason for a rate limit status code.
+     */
+    function getReasonFromStatusCode(statusCode) {
+        switch (statusCode) {
+            case RateLimits.RATE_LIMIT_STATUS_CODES.TOO_MANY_REQUESTS:
+                return "Too Many Requests";
+            case RateLimits.RATE_LIMIT_STATUS_CODES.SERVICE_UNAVAILABLE:
+                return "Service Unavailable";
+            case RateLimits.RATE_LIMIT_STATUS_CODES.SITE_OVERLOADED:
+                return "Service Overloaded";
+            default:
+                return `HTTP ${statusCode}`;
+        }
+    }
+    /**
+     * Checks if a key is currently rate limited.
+     *
+     * @param providerID - Provider identifier
+     * @param keyID - Optional key identifier
+     * @returns Check result with limit status and wait time
+     *
+     * @example
+     * ```typescript
+     * const result = RateLimits.isLimited("anthropic", "key-1")
+     * if (result.isLimited) {
+     *   console.log(`Wait ${result.waitTimeMs}ms before retrying`)
+     * }
+     * ```
+     */
+    function isLimited(providerID, keyID) {
+        const key = getStateKey(providerID, keyID);
+        const state = states.get(key);
+        if (!state) {
+            return { isLimited: false, waitTimeMs: 0 };
+        }
+        const now = Date.now();
+        const waitTimeMs = Math.max(0, state.resetAt - now);
+        if (waitTimeMs <= 0) {
+            // Rate limit has expired, clean it up
+            states.delete(key);
+            return { isLimited: false, waitTimeMs: 0 };
+        }
+        return {
+            isLimited: true,
+            waitTimeMs,
+            state,
+        };
+    }
+    RateLimits.isLimited = isLimited;
+    /**
+     * Gets the rate limit state for a key without checking expiration.
+     *
+     * @param providerID - Provider identifier
+     * @param keyID - Optional key identifier
+     * @returns The state or undefined if not limited
+     */
+    function getState(providerID, keyID) {
+        const key = getStateKey(providerID, keyID);
+        return states.get(key);
+    }
+    RateLimits.getState = getState;
+    /**
+     * Clears the rate limit state for a key.
+     *
+     * @param providerID - Provider identifier
+     * @param keyID - Optional key identifier
+     */
+    function clear(providerID, keyID) {
+        const key = getStateKey(providerID, keyID);
+        const existed = states.delete(key);
+        if (existed) {
+            log.info("cleared", { providerID, keyID });
+        }
+    }
+    RateLimits.clear = clear;
+    /**
+     * Clears all rate limit states for a provider.
+     *
+     * @param providerID - Provider identifier
+     */
+    function clearProvider(providerID) {
+        let count = 0;
+        for (const key of states.keys()) {
+            if (key === providerID || key.startsWith(`${providerID}:`)) {
+                states.delete(key);
+                count++;
+            }
+        }
+        if (count > 0) {
+            log.info("cleared-provider", { providerID, count });
+        }
+    }
+    RateLimits.clearProvider = clearProvider;
+    /**
+     * Clears all rate limit states.
+     */
+    function clearAll() {
+        const count = states.size;
+        states.clear();
+        if (count > 0) {
+            log.info("cleared-all", { count });
+        }
+    }
+    RateLimits.clearAll = clearAll;
+    /**
+     * Removes expired rate limit states.
+     * Called automatically by the cleanup interval.
+     */
+    function cleanupExpired() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, state] of states.entries()) {
+            if (state.resetAt <= now) {
+                states.delete(key);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            log.info("cleanup", { removed });
+        }
+        return removed;
+    }
+    RateLimits.cleanupExpired = cleanupExpired;
+    /**
+     * Gets all current rate limit states.
+     * Useful for monitoring and debugging.
+     *
+     * @returns Array of all rate limit states
+     */
+    function getAll() {
+        return Array.from(states.values());
+    }
+    RateLimits.getAll = getAll;
+    /**
+     * Gets all limited keys for a provider.
+     *
+     * @param providerID - Provider identifier
+     * @returns Array of rate limit states for the provider
+     */
+    function getProviderStates(providerID) {
+        const result = [];
+        const now = Date.now();
+        for (const [key, state] of states.entries()) {
+            if ((key === providerID || key.startsWith(`${providerID}:`)) && state.resetAt > now) {
+                result.push(state);
+            }
+        }
+        return result;
+    }
+    RateLimits.getProviderStates = getProviderStates;
+    /**
+     * Gets summary statistics for rate limits.
+     *
+     * @returns Summary object with counts and details
+     */
+    function getSummary() {
+        const now = Date.now();
+        const byProvider = {};
+        const byStatusCode = {};
+        let totalLimited = 0;
+        for (const state of states.values()) {
+            if (state.resetAt > now) {
+                totalLimited++;
+                byProvider[state.providerID] = (byProvider[state.providerID] ?? 0) + 1;
+                byStatusCode[state.statusCode] = (byStatusCode[state.statusCode] ?? 0) + 1;
+            }
+        }
+        return { totalLimited, byProvider, byStatusCode };
+    }
+    RateLimits.getSummary = getSummary;
+    /**
+     * Starts the automatic cleanup interval.
+     * Called automatically on first use.
+     *
+     * @param intervalMs - Cleanup interval in milliseconds (default: 60000)
+     */
+    function startCleanup(intervalMs = 60_000) {
+        if (cleanupInterval)
+            return;
+        cleanupInterval = setInterval(() => {
+            cleanupExpired();
+        }, intervalMs);
+        // Don't keep the process alive just for cleanup
+        if (typeof cleanupInterval.unref === "function") {
+            cleanupInterval.unref();
+        }
+        log.debug("cleanup-started", { intervalMs });
+    }
+    RateLimits.startCleanup = startCleanup;
+    /**
+     * Stops the automatic cleanup interval.
+     */
+    function stopCleanup() {
+        if (cleanupInterval) {
+            clearInterval(cleanupInterval);
+            cleanupInterval = null;
+            log.info("cleanup-stopped");
+        }
+    }
+    RateLimits.stopCleanup = stopCleanup;
+    // Start cleanup on module load
+    startCleanup();
+})(RateLimits || (RateLimits = {}));