locai 2.1.0

package/dist/utils/rate-limiter.js

@@ -0,0 +1,398 @@
+import { performance } from "perf_hooks";
+/**
+ * Handles API rate limiting and request throttling.
+ * Supports provider-specific limits and adaptive throttling.
+ */
+class RateLimiter {
+    queues;
+    processing;
+    config;
+    metrics;
+    providers;
+    _processingLocks;
+    /**
+     * Create a new RateLimiter.
+     * @param config - Rate limiter configuration.
+     */
+    constructor(config = {}) {
+        this.queues = {};
+        this.processing = {};
+        this.config = {
+            queueStrategy: config.queueStrategy || "fifo",
+            queueTimeout: config.queueTimeout || 15000,
+            adaptiveThrottling: config.adaptiveThrottling !== false,
+        };
+        this.metrics = {
+            responseTimes: {},
+            errorRates: {},
+            adjustments: {},
+            lastMetricsReset: {},
+        };
+        this.providers = {
+            openai: {
+                requestsPerMinute: 300,
+                currentRequests: 0,
+                lastReset: performance.now(),
+                maxConcurrent: 5,
+            },
+            deepseek: {
+                requestsPerMinute: 30,
+                currentRequests: 0,
+                lastReset: performance.now(),
+                maxConcurrent: 2,
+            },
+            gemini: {
+                requestsPerMinute: 300,
+                currentRequests: 0,
+                lastReset: performance.now(),
+                maxConcurrent: 5,
+            },
+            dashscope: {
+                requestsPerMinute: 80,
+                currentRequests: 0,
+                lastReset: performance.now(),
+                maxConcurrent: 6,
+            },
+            xai: {
+                requestsPerMinute: 80,
+                currentRequests: 0,
+                lastReset: performance.now(),
+                maxConcurrent: 8,
+            },
+        };
+        this._processingLocks = {};
+        Object.keys(this.providers).forEach((provider) => {
+            this.queues[provider] = [];
+            this.processing[provider] = 0;
+            this.metrics.responseTimes[provider] = [];
+            this.metrics.errorRates[provider] = [];
+            this.metrics.adjustments[provider] = { rpm: 0, concurrency: 0 };
+            this.metrics.lastMetricsReset[provider] = Date.now();
+        });
+        setInterval(() => this._resetCounters(), 60000);
+        setInterval(() => this._cleanupMetrics(), 2 * 60 * 1000);
+        if (this.config.adaptiveThrottling) {
+            setInterval(() => this._adjustThrottling(), 5 * 60 * 1000);
+        }
+    }
+    /**
+     * Update rate limiter configuration.
+     * @param config - Configuration updates.
+     */
+    updateConfig(config) {
+        if (!config)
+            return;
+        if (config.queueStrategy) {
+            this.config.queueStrategy = config.queueStrategy;
+        }
+        if (config.queueTimeout) {
+            this.config.queueTimeout = config.queueTimeout;
+        }
+        if (config.adaptiveThrottling !== undefined) {
+            this.config.adaptiveThrottling = config.adaptiveThrottling;
+        }
+        if (config.providerLimits && typeof config.providerLimits === "object") {
+            Object.keys(config.providerLimits).forEach((providerName) => {
+                if (this.providers[providerName]) {
+                    const limits = config.providerLimits[providerName];
+                    if (limits.rpm && typeof limits.rpm === "number") {
+                        this.providers[providerName].requestsPerMinute = limits.rpm;
+                    }
+                    if (limits.concurrency && typeof limits.concurrency === "number") {
+                        this.providers[providerName].maxConcurrent = limits.concurrency;
+                    }
+                }
+            });
+            // Only log in debug mode to avoid cluttering output
+            if (process.env.DEBUG) {
+                console.log("Provider limits updated from config");
+            }
+        }
+    }
+    /**
+     * Enqueue a task for execution with rate limiting.
+     * @param provider - Provider name.
+     * @param task - Async task to execute.
+     * @param priority - Task priority (higher is better).
+     * @returns Task result.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async enqueue(provider, task, priority = 0) {
+        provider = provider.toLowerCase();
+        if (!this.providers[provider]) {
+            throw new Error(`Unknown provider: ${provider}`);
+        }
+        return new Promise((resolve, reject) => {
+            const queueItem = {
+                task,
+                resolve,
+                reject,
+                timestamp: Date.now(),
+                priority,
+            };
+            if (this.config.queueStrategy === "priority") {
+                const index = this.queues[provider].findIndex((item) => item.priority < priority);
+                if (index === -1) {
+                    this.queues[provider].push(queueItem);
+                }
+                else {
+                    this.queues[provider].splice(index, 0, queueItem);
+                }
+            }
+            else {
+                this.queues[provider].push(queueItem);
+            }
+            this._processQueue(provider);
+        });
+    }
+    /**
+     * Process the queue for a specific provider.
+     * @param provider - Provider name.
+     */
+    async _processQueue(provider) {
+        if (!provider || typeof provider !== "string") {
+            return;
+        }
+        const queue = this.queues[provider];
+        const limits = this.providers[provider];
+        if (!queue || !Array.isArray(queue) || !limits) {
+            console.warn(`Invalid queue or limits for provider: ${provider}`);
+            return;
+        }
+        const currentProcessing = this.processing[provider] || 0;
+        if (queue.length === 0 || currentProcessing >= limits.maxConcurrent) {
+            return;
+        }
+        if (this._processingLocks[provider]) {
+            return;
+        }
+        this._processingLocks[provider] = true;
+        try {
+            if (queue.length === 0 || this.processing[provider] >= limits.maxConcurrent) {
+                return;
+            }
+            const now = Date.now();
+            const timedOutItems = [];
+            let i = 0;
+            while (i < queue.length &&
+                queue[i] &&
+                now - queue[i].timestamp > this.config.queueTimeout) {
+                timedOutItems.push(queue[i]);
+                i++;
+            }
+            if (timedOutItems.length > 0) {
+                queue.splice(0, timedOutItems.length);
+                setImmediate(() => {
+                    timedOutItems.forEach((item) => {
+                        try {
+                            item.reject(new Error(`Request timed out in queue after ${this.config.queueTimeout}ms`));
+                        }
+                        catch (error) {
+                            console.error(`Failed to reject timed out request: ${error.message}`);
+                        }
+                    });
+                });
+            }
+            if (queue.length === 0) {
+                return;
+            }
+            if (this._shouldThrottle(provider)) {
+                const waitTime = this._calculateWaitTime(provider);
+                setTimeout(() => this._processQueue(provider), waitTime);
+                return;
+            }
+            const queueItem = queue.shift();
+            if (!queueItem) {
+                return; // Queue was emptied by another process or contains invalid item
+            }
+            const { task, resolve, reject, timestamp } = queueItem;
+            const startTime = performance.now();
+            const queueTime = Date.now() - timestamp;
+            if (queueTime > 30000) {
+                console.warn(`Task for ${provider} waited ${queueTime}ms in queue`);
+            }
+            this.processing[provider]++;
+            this.providers[provider].currentRequests++;
+            try {
+                const result = await task();
+                const responseTime = performance.now() - startTime;
+                this._trackResponseTime(provider, responseTime);
+                this._trackErrorRate(provider, false);
+                resolve(result);
+            }
+            catch (error) {
+                this._trackErrorRate(provider, true);
+                console.error(`Provider ${provider} task failed:`, {
+                    error: error.message,
+                    queueTime: queueTime,
+                    processingTime: performance.now() - startTime,
+                    queueSize: queue.length,
+                });
+                reject(error);
+            }
+            finally {
+                this.processing[provider]--;
+                setImmediate(() => this._processQueue(provider));
+            }
+        }
+        finally {
+            this._processingLocks[provider] = false;
+        }
+    }
+    _trackResponseTime(provider, time) {
+        const times = this.metrics.responseTimes[provider];
+        const MAX_RESPONSE_TIMES = 50;
+        times.push(time);
+        if (times.length > MAX_RESPONSE_TIMES) {
+            times.splice(0, times.length - MAX_RESPONSE_TIMES);
+        }
+    }
+    _trackErrorRate(provider, isError) {
+        const errorRates = this.metrics.errorRates[provider];
+        const MAX_ERROR_RATES = 50;
+        errorRates.push(isError ? 1 : 0);
+        if (errorRates.length > MAX_ERROR_RATES) {
+            errorRates.splice(0, errorRates.length - MAX_ERROR_RATES);
+        }
+    }
+    _adjustThrottling() {
+        if (!this.config.adaptiveThrottling)
+            return;
+        Object.keys(this.providers).forEach((provider) => {
+            const errorRates = this.metrics.errorRates[provider];
+            const errorRate = errorRates.length === 0
+                ? 0
+                : errorRates.reduce((a, b) => a + b, 0) / errorRates.length;
+            const respTimes = this.metrics.responseTimes[provider];
+            const avgResponseTime = respTimes.length === 0
+                ? 0
+                : respTimes.reduce((a, b) => a + b, 0) / respTimes.length;
+            let concurrencyAdjustment = 0;
+            let rpmAdjustment = 0;
+            if (errorRate > 0.15) {
+                concurrencyAdjustment = -1;
+                rpmAdjustment = -5;
+            }
+            else if (errorRate < 0.05 &&
+                avgResponseTime < 3000 &&
+                this.queues[provider].length > 0) {
+                concurrencyAdjustment = 1;
+                rpmAdjustment = 5;
+            }
+            if (concurrencyAdjustment !== 0) {
+                const newConcurrency = Math.max(1, this.providers[provider].maxConcurrent + concurrencyAdjustment);
+                this.providers[provider].maxConcurrent = newConcurrency;
+                this.metrics.adjustments[provider].concurrency += concurrencyAdjustment;
+            }
+            if (rpmAdjustment !== 0) {
+                const newRPM = Math.max(10, this.providers[provider].requestsPerMinute + rpmAdjustment);
+                this.providers[provider].requestsPerMinute = newRPM;
+                this.metrics.adjustments[provider].rpm += rpmAdjustment;
+            }
+        });
+    }
+    _shouldThrottle(provider) {
+        const limits = this.providers[provider];
+        const now = performance.now();
+        if (!limits) {
+            throw new Error(`Unknown provider: ${provider}`);
+        }
+        if (now - limits.lastReset >= 60000) {
+            limits.currentRequests = 0;
+            limits.lastReset = now;
+            return false;
+        }
+        return limits.currentRequests >= limits.requestsPerMinute;
+    }
+    _calculateWaitTime(provider) {
+        const limits = this.providers[provider];
+        if (!limits) {
+            throw new Error(`Unknown provider: ${provider}`);
+        }
+        return Math.max(0, 60000 - (performance.now() - limits.lastReset));
+    }
+    _resetCounters() {
+        const now = performance.now();
+        Object.values(this.providers).forEach((provider) => {
+            provider.currentRequests = 0;
+            provider.lastReset = now;
+        });
+    }
+    /**
+     * Get current queue size for a provider.
+     * @param provider - Provider name.
+     * @returns Queue size.
+     */
+    getQueueSize(provider) {
+        provider = provider.toLowerCase();
+        return this.queues[provider]?.length || 0;
+    }
+    /**
+     * Get complete rate limiter status.
+     * @returns Status object including active metrics.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getStatus() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const status = {};
+        Object.entries(this.providers).forEach(([name, config]) => {
+            const errorRates = this.metrics.errorRates[name];
+            const errorRate = errorRates.length === 0
+                ? 0
+                : errorRates.reduce((a, b) => a + b, 0) / errorRates.length;
+            status[name] = {
+                queueSize: this.queues[name]?.length || 0,
+                processing: this.processing[name] || 0,
+                requestsUsed: config.currentRequests,
+                requestsLimit: config.requestsPerMinute,
+                resetIn: Math.max(0, 60000 - (performance.now() - config.lastReset)) / 1000,
+                errorRate: Math.round(errorRate * 100) / 100,
+                adjustments: this.metrics.adjustments[name],
+                config: {
+                    maxConcurrent: config.maxConcurrent,
+                    rpm: config.requestsPerMinute,
+                },
+            };
+        });
+        return status;
+    }
+    /**
+     * Get current configuration.
+     * @returns Configuration object.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Clear all pending queues.
+     */
+    clearAllQueues() {
+        for (const provider in this.queues) {
+            if (this.queues[provider] && this.queues[provider].length > 0) {
+                console.log(`Clearing ${this.queues[provider].length} pending operations for ${provider}`);
+                this.queues[provider].forEach((item) => {
+                    if (item.reject) {
+                        item.reject(new Error("Operation cancelled due to shutdown"));
+                    }
+                });
+                this.queues[provider] = [];
+            }
+            this.processing[provider] = 0;
+        }
+    }
+    _cleanupMetrics() {
+        const now = Date.now();
+        Object.keys(this.providers).forEach((providerName) => {
+            this.metrics.responseTimes[providerName].length = 0;
+            this.metrics.errorRates[providerName].length = 0;
+            this.metrics.adjustments[providerName] = { rpm: 0, concurrency: 0 };
+            this.metrics.lastMetricsReset[providerName] = now;
+        });
+    }
+}
+const config = {
+    queueStrategy: process.env.QUEUE_STRATEGY || "priority",
+    queueTimeout: parseInt(process.env.QUEUE_TIMEOUT || "30000"),
+    adaptiveThrottling: process.env.ADAPTIVE_THROTTLING !== "false",
+};
+export default new RateLimiter(config);

package/dist/utils/retry-helper.js

@@ -0,0 +1,166 @@
+/**
+ * Retry helper for API operations with exponential backoff
+ */
+/**
+ * Retry helper for API operations with exponential backoff.
+ */
+class RetryHelper {
+    /**
+     * Retry an operation with configurable backoff strategy.
+     * Supports per-provider retry configuration.
+     */
+    static async withRetry(operation, options = {}) {
+        const providerName = options.provider?.toLowerCase();
+        const perProviderRetry = options.perProviderRetry || {};
+        const retryableErrors = options.retryableErrors || [
+            "rate_limit",
+            "timeout",
+            "network",
+            "server",
+            "unknown",
+        ];
+        // Get provider-specific retry settings or use defaults
+        let maxRetries = options.maxRetries ?? 2;
+        let initialDelay = options.initialDelay ?? 1000;
+        let maxDelay = options.maxDelay ?? 10000;
+        // Override with provider-specific settings if available
+        if (providerName && perProviderRetry[providerName]) {
+            const providerConfig = perProviderRetry[providerName];
+            maxRetries = providerConfig.maxRetries ?? maxRetries;
+            initialDelay = providerConfig.initialDelay ?? initialDelay;
+            maxDelay = providerConfig.maxDelay ?? maxDelay;
+        }
+        const context = options.context ?? "Operation";
+        const logContext = options.logContext ?? {};
+        const retryCondition = options.retryCondition ??
+            ((error) => this.defaultRetryCondition(error, retryableErrors));
+        let lastError = null;
+        let attempts = 0;
+        const startTime = Date.now();
+        const retryStats = { attempts: 0, totalTime: 0, provider: providerName };
+        while (attempts <= maxRetries) {
+            try {
+                retryStats.attempts = attempts;
+                if (attempts > 0) {
+                    const delay = this.calculateBackoff(attempts, initialDelay, maxDelay);
+                    if (process.env.DEBUG) {
+                        const providerInfo = providerName ? ` [${providerName}]` : "";
+                        console.log(`${context}${providerInfo}: Retrying attempt ${attempts}/${maxRetries} after ${delay}ms delay`);
+                    }
+                    await this.delay(delay);
+                }
+                const result = await operation();
+                // Track time if this was a retry
+                if (attempts > 0) {
+                    retryStats.totalTime = Date.now() - startTime;
+                    retryStats.success = true;
+                    if (process.env.DEBUG) {
+                        console.log(`${context}: Succeeded after ${attempts} retries (${retryStats.totalTime}ms)`);
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                attempts++;
+                lastError = error;
+                if (!error.retryInfo) {
+                    error.retryInfo = {
+                        attemptNumber: attempts,
+                        maxRetries,
+                        willRetry: attempts <= maxRetries,
+                        context: logContext,
+                        provider: providerName,
+                    };
+                }
+                const shouldRetry = attempts <= maxRetries && (await retryCondition(error, attempts, maxRetries));
+                if (process.env.DEBUG) {
+                    const providerInfo = providerName ? ` [${providerName}]` : "";
+                    console.warn(`Warning: ${context}${providerInfo}: Error on attempt ${attempts}/${maxRetries + 1}: ${error.message}` +
+                        (error.code ? ` [${error.code}]` : ""));
+                }
+                if (!shouldRetry) {
+                    break;
+                }
+            }
+        }
+        retryStats.totalTime = Date.now() - startTime;
+        retryStats.success = false;
+        if (lastError) {
+            lastError.retryStats = retryStats;
+            lastError.message = `${lastError.message} (after ${attempts} attempts over ${retryStats.totalTime}ms)`;
+        }
+        throw lastError;
+    }
+    /**
+     * Calculate exponential backoff with jitter.
+     */
+    static calculateBackoff(attempt, initialDelay, maxDelay) {
+        const expBackoff = Math.min(maxDelay, initialDelay * Math.pow(2, attempt - 1));
+        return Math.floor(Math.random() * expBackoff);
+    }
+    /**
+     * Default retry condition based on error type.
+     * Checks against retryableErrors list.
+     */
+    static defaultRetryCondition(error, retryableErrors = []) {
+        // Check for rate_limit errors
+        if (retryableErrors.includes("rate_limit") &&
+            (error.status === 429 || error.code === "ERR_RATE_LIMIT")) {
+            return true;
+        }
+        // Check for timeout errors
+        if (retryableErrors.includes("timeout") &&
+            (error.code === "ETIMEDOUT" ||
+                error.code === "ECONNABORTED" ||
+                error.message?.includes("timeout"))) {
+            return true;
+        }
+        // Check for network errors
+        if (retryableErrors.includes("network") &&
+            (error.code === "ECONNRESET" ||
+                error.code === "ECONNREFUSED" ||
+                error.code === "ENOTFOUND" ||
+                error.code === "ERR_NETWORK" ||
+                error.message?.includes("network") ||
+                error.message?.includes("connection"))) {
+            return true;
+        }
+        // Check for server errors (5xx)
+        if (retryableErrors.includes("server") && error.status >= 500 && error.status < 600) {
+            return true;
+        }
+        // Check for unknown/general errors
+        if (retryableErrors.includes("unknown") && !error.status) {
+            return true;
+        }
+        // Legacy fallback for backward compatibility
+        if (retryableErrors.length === 0) {
+            // Old behavior when no retryableErrors specified
+            if (error.status && error.status >= 400 && error.status < 500) {
+                if (error.status === 429)
+                    return true;
+                if ([408, 425, 449].includes(error.status))
+                    return true;
+                return false;
+            }
+            if (error.code === "ECONNRESET" ||
+                error.code === "ETIMEDOUT" ||
+                error.code === "ECONNREFUSED" ||
+                error.code === "ENOTFOUND" ||
+                error.message?.includes("network") ||
+                error.message?.includes("timeout") ||
+                error.message?.includes("connection")) {
+                return true;
+            }
+            return error.status >= 500 || !error.status;
+        }
+        return false;
+    }
+    /**
+     * Promise-based delay.
+     */
+    static delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+export default RetryHelper;