@juspay/neurolink 4.0.0 → 4.1.0

package/dist/lib/mcp/error-recovery.js

@@ -0,0 +1,405 @@
+/**
+ * NeuroLink Error Recovery System
+ * Implements circuit breaker, retry strategies, and pattern detection
+ * Based on resilience patterns from reference implementations
+ */
+/**
+ * Circuit breaker states
+ */
+export var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "CLOSED";
+    CircuitState["OPEN"] = "OPEN";
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+/**
+ * Circuit breaker instance
+ */
+class CircuitBreaker {
+    config;
+    state = CircuitState.CLOSED;
+    failures = 0;
+    successes = 0;
+    lastFailureTime = 0;
+    nextAttemptTime = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Check if request should be allowed
+     */
+    canExecute() {
+        const now = Date.now();
+        switch (this.state) {
+            case CircuitState.CLOSED:
+                return true;
+            case CircuitState.OPEN:
+                if (now >= this.nextAttemptTime) {
+                    this.state = CircuitState.HALF_OPEN;
+                    this.successes = 0;
+                    return true;
+                }
+                return false;
+            case CircuitState.HALF_OPEN:
+                return true;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Record success
+     */
+    recordSuccess() {
+        this.failures = 0;
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successes++;
+            if (this.successes >= this.config.successThreshold) {
+                this.state = CircuitState.CLOSED;
+            }
+        }
+    }
+    /**
+     * Record failure
+     */
+    recordFailure() {
+        const now = Date.now();
+        // Reset failure count if outside monitoring period
+        if (now - this.lastFailureTime > this.config.monitoringPeriod) {
+            this.failures = 0;
+        }
+        this.failures++;
+        this.lastFailureTime = now;
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.state = CircuitState.OPEN;
+            this.nextAttemptTime = now + this.config.resetTimeout;
+        }
+        else if (this.failures >= this.config.failureThreshold) {
+            this.state = CircuitState.OPEN;
+            this.nextAttemptTime = now + this.config.resetTimeout;
+        }
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return this.state;
+    }
+}
+/**
+ * Error Recovery Manager
+ */
+export class ErrorRecovery {
+    circuitBreakers = new Map();
+    errorPatterns = [];
+    recoveryHistory = new Map();
+    defaultRetryConfig = {
+        maxAttempts: 3,
+        initialDelay: 1000,
+        maxDelay: 30000,
+        backoffMultiplier: 2,
+        jitter: true,
+    };
+    defaultCircuitConfig = {
+        failureThreshold: 5,
+        resetTimeout: 60000,
+        successThreshold: 2,
+        monitoringPeriod: 60000,
+    };
+    constructor() {
+        this.initializeDefaultPatterns();
+    }
+    /**
+     * Initialize default error patterns
+     */
+    initializeDefaultPatterns() {
+        // Network timeout pattern
+        this.addPattern({
+            id: "network-timeout",
+            name: "Network Timeout Pattern",
+            description: "Repeated network timeouts indicating connectivity issues",
+            matcher: (errors) => {
+                const recentErrors = errors.slice(-5);
+                return (recentErrors.length >= 3 &&
+                    recentErrors.every((e) => e.category === "TIMEOUT_ERROR"));
+            },
+            severity: "HIGH",
+            recoveryStrategy: {
+                type: "retry",
+                config: {
+                    maxAttempts: 5,
+                    initialDelay: 2000,
+                    maxDelay: 60000,
+                    backoffMultiplier: 3,
+                    jitter: true,
+                },
+            },
+        });
+        // Rate limit pattern
+        this.addPattern({
+            id: "rate-limit",
+            name: "Rate Limit Pattern",
+            description: "API rate limit errors",
+            matcher: (errors) => {
+                const lastError = errors[errors.length - 1];
+                return (lastError &&
+                    (lastError.error.message.includes("429") ||
+                        lastError.error.message.toLowerCase().includes("rate limit")));
+            },
+            severity: "MEDIUM",
+            recoveryStrategy: {
+                type: "circuit-breaker",
+                config: {
+                    failureThreshold: 3,
+                    resetTimeout: 120000, // 2 minutes
+                    successThreshold: 1,
+                    monitoringPeriod: 60000,
+                },
+            },
+        });
+        // Configuration error pattern
+        this.addPattern({
+            id: "config-error",
+            name: "Configuration Error Pattern",
+            description: "Missing or invalid configuration",
+            matcher: (errors) => {
+                const lastError = errors[errors.length - 1];
+                return lastError?.category === "CONFIGURATION_ERROR";
+            },
+            severity: "CRITICAL",
+            recoveryStrategy: {
+                type: "manual",
+                action: async (context) => ({
+                    success: false,
+                    message: "Configuration error requires manual intervention. Check environment variables and config files.",
+                }),
+            },
+        });
+    }
+    /**
+     * Add error pattern
+     */
+    addPattern(pattern) {
+        this.errorPatterns.push(pattern);
+    }
+    /**
+     * Detect patterns in error history
+     */
+    detectPatterns(errors) {
+        return this.errorPatterns.filter((pattern) => pattern.matcher(errors));
+    }
+    /**
+     * Get circuit breaker for resource
+     */
+    getCircuitBreaker(resourceId, config) {
+        if (!this.circuitBreakers.has(resourceId)) {
+            this.circuitBreakers.set(resourceId, new CircuitBreaker(config || this.defaultCircuitConfig));
+        }
+        return this.circuitBreakers.get(resourceId);
+    }
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    calculateRetryDelay(attemptNumber, config) {
+        const exponentialDelay = config.initialDelay *
+            Math.pow(config.backoffMultiplier, attemptNumber - 1);
+        const delay = Math.min(exponentialDelay, config.maxDelay);
+        if (config.jitter) {
+            // Add random jitter (±25%)
+            const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+            return Math.floor(delay + jitter);
+        }
+        return delay;
+    }
+    /**
+     * Attempt recovery for an error
+     */
+    async attemptRecovery(error, context) {
+        // Detect patterns
+        const patterns = this.detectPatterns([error]);
+        const pattern = patterns[0]; // Use first matching pattern
+        // Get recovery history
+        const historyKey = `${error.context.toolName || "unknown"}-${error.category}`;
+        const history = this.recoveryHistory.get(historyKey) || [];
+        // Build recovery context
+        const recoveryContext = {
+            error,
+            pattern,
+            attemptNumber: history.length + 1,
+            totalAttempts: 0,
+            previousAttempts: history,
+            executionContext: context,
+        };
+        // Determine recovery strategy
+        const strategy = pattern?.recoveryStrategy || this.getDefaultStrategy(error);
+        // Execute recovery
+        const startTime = Date.now();
+        let result;
+        try {
+            switch (strategy.type) {
+                case "retry":
+                    result = await this.executeRetryStrategy(recoveryContext, strategy.config);
+                    break;
+                case "circuit-breaker":
+                    result = await this.executeCircuitBreakerStrategy(recoveryContext, strategy.config);
+                    break;
+                case "fallback":
+                    result = await this.executeFallbackStrategy(recoveryContext, strategy.config);
+                    break;
+                case "manual":
+                    result = strategy.action
+                        ? await strategy.action(recoveryContext)
+                        : { success: false, message: "Manual intervention required" };
+                    break;
+                default:
+                    result = {
+                        success: false,
+                        message: "No recovery strategy available",
+                    };
+            }
+        }
+        catch (recoveryError) {
+            result = {
+                success: false,
+                message: `Recovery failed: ${recoveryError instanceof Error ? recoveryError.message : "Unknown error"}`,
+            };
+        }
+        // Record attempt
+        const attempt = {
+            timestamp: Date.now(),
+            strategy: strategy.type,
+            successful: result.success,
+            duration: Date.now() - startTime,
+            error: result.success
+                ? undefined
+                : new Error(result.message || "Recovery failed"),
+        };
+        history.push(attempt);
+        this.recoveryHistory.set(historyKey, history.slice(-10)); // Keep last 10 attempts
+        return result;
+    }
+    /**
+     * Execute retry strategy
+     */
+    async executeRetryStrategy(context, config) {
+        const retryConfig = config || this.defaultRetryConfig;
+        if (context.attemptNumber > retryConfig.maxAttempts) {
+            return {
+                success: false,
+                message: `Maximum retry attempts (${retryConfig.maxAttempts}) exceeded`,
+            };
+        }
+        const delay = this.calculateRetryDelay(context.attemptNumber, retryConfig);
+        return {
+            success: true,
+            nextAction: "retry",
+            delay,
+            message: `Retry attempt ${context.attemptNumber}/${retryConfig.maxAttempts} after ${delay}ms`,
+        };
+    }
+    /**
+     * Execute circuit breaker strategy
+     */
+    async executeCircuitBreakerStrategy(context, config) {
+        const resourceId = context.error.context.toolName || "default";
+        const circuitBreaker = this.getCircuitBreaker(resourceId, config);
+        if (!circuitBreaker.canExecute()) {
+            return {
+                success: false,
+                message: `Circuit breaker OPEN for ${resourceId}. Service temporarily unavailable.`,
+            };
+        }
+        // Record the failure for circuit breaker
+        circuitBreaker.recordFailure();
+        return {
+            success: true,
+            nextAction: circuitBreaker.getState() === CircuitState.OPEN ? "fail" : "retry",
+            message: `Circuit breaker state: ${circuitBreaker.getState()}`,
+        };
+    }
+    /**
+     * Execute fallback strategy
+     */
+    async executeFallbackStrategy(context, config) {
+        // In a real implementation, this would execute fallback logic
+        // For now, just indicate fallback should be used
+        return {
+            success: true,
+            fallbackUsed: true,
+            message: "Fallback strategy activated",
+        };
+    }
+    /**
+     * Get default recovery strategy based on error
+     */
+    getDefaultStrategy(error) {
+        switch (error.category) {
+            case "NETWORK_ERROR":
+            case "TIMEOUT_ERROR":
+                return {
+                    type: "retry",
+                    config: this.defaultRetryConfig,
+                };
+            case "CONFIGURATION_ERROR":
+            case "PERMISSION_ERROR":
+                return {
+                    type: "manual",
+                };
+            default:
+                return {
+                    type: "retry",
+                    config: {
+                        ...this.defaultRetryConfig,
+                        maxAttempts: 2,
+                    },
+                };
+        }
+    }
+    /**
+     * Get recovery statistics
+     */
+    getRecoveryStats() {
+        let totalAttempts = 0;
+        let successfulRecoveries = 0;
+        let failedRecoveries = 0;
+        // Calculate from history
+        for (const attempts of this.recoveryHistory.values()) {
+            for (const attempt of attempts) {
+                totalAttempts++;
+                if (attempt.successful) {
+                    successfulRecoveries++;
+                }
+                else {
+                    failedRecoveries++;
+                }
+            }
+        }
+        // Get circuit breaker states
+        const circuitBreakerStates = {};
+        for (const [id, breaker] of this.circuitBreakers) {
+            circuitBreakerStates[id] = breaker.getState();
+        }
+        return {
+            totalAttempts,
+            successfulRecoveries,
+            failedRecoveries,
+            circuitBreakerStates,
+            patternMatches: {}, // TODO: Track pattern matches
+        };
+    }
+    /**
+     * Reset circuit breaker
+     */
+    resetCircuitBreaker(resourceId) {
+        this.circuitBreakers.delete(resourceId);
+    }
+    /**
+     * Clear recovery history
+     */
+    clearHistory() {
+        this.recoveryHistory.clear();
+    }
+}
+/**
+ * Default error recovery instance
+ */
+export const defaultErrorRecovery = new ErrorRecovery();

package/dist/lib/mcp/health-monitor.d.ts

@@ -0,0 +1,256 @@
+/**
+ * NeuroLink MCP Health Monitoring System
+ * Provides periodic health checks, connection status tracking, and auto-recovery
+ * Based on health monitoring patterns from Cline
+ */
+import type { MCPRegistry } from "./registry.js";
+import { ErrorManager } from "./error-manager.js";
+/**
+ * Connection status states
+ */
+export declare enum ConnectionStatus {
+    DISCONNECTED = "DISCONNECTED",
+    CONNECTING = "CONNECTING",
+    CONNECTED = "CONNECTED",
+    CHECKING = "CHECKING",
+    ERROR = "ERROR",
+    RECOVERING = "RECOVERING"
+}
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    success: boolean;
+    status: ConnectionStatus;
+    message?: string;
+    latency?: number;
+    error?: Error;
+    timestamp: number;
+}
+/**
+ * Server health information
+ */
+export interface ServerHealth {
+    serverId: string;
+    status: ConnectionStatus;
+    lastCheck?: HealthCheckResult;
+    checkCount: number;
+    errorCount: number;
+    lastSuccessfulCheck?: number;
+    recoveryAttempts: number;
+    nextCheckTime?: number;
+}
+/**
+ * Health monitor configuration
+ */
+export interface HealthMonitorOptions {
+    checkInterval?: number;
+    checkTimeout?: number;
+    maxRecoveryAttempts?: number;
+    recoveryDelay?: number;
+    enableAutoRecovery?: boolean;
+}
+/**
+ * Health check strategy interface
+ */
+export interface HealthCheckStrategy {
+    name: string;
+    check(serverId: string, registry: MCPRegistry): Promise<HealthCheckResult>;
+}
+/**
+ * Ping health check - Simple availability check
+ */
+export declare class PingHealthCheck implements HealthCheckStrategy {
+    name: string;
+    check(serverId: string, registry: MCPRegistry): Promise<HealthCheckResult>;
+}
+/**
+ * Tool list validation check - Ensures tools are accessible
+ */
+export declare class ToolListValidationCheck implements HealthCheckStrategy {
+    name: string;
+    check(serverId: string, registry: MCPRegistry): Promise<HealthCheckResult>;
+}
+/**
+ * Performance baseline check - Monitors response times
+ */
+export declare class PerformanceCheck implements HealthCheckStrategy {
+    name: string;
+    private performanceThreshold;
+    constructor(thresholdMs?: number);
+    check(serverId: string, registry: MCPRegistry): Promise<HealthCheckResult>;
+}
+/**
+ * Health Monitor for MCP connections
+ */
+export declare class HealthMonitor {
+    private registry;
+    private errorManager;
+    private serverHealth;
+    private checkInterval;
+    private checkTimeout;
+    private maxRecoveryAttempts;
+    private recoveryDelay;
+    private enableAutoRecovery;
+    private checkTimers;
+    private strategies;
+    private isMonitoring;
+    private recoveryCallbacks;
+    constructor(registry: MCPRegistry, errorManager: ErrorManager, options?: HealthMonitorOptions);
+    /**
+     * Start monitoring all registered servers
+     */
+    startMonitoring(): void;
+    /**
+     * Stop monitoring all servers
+     */
+    stopMonitoring(): void;
+    /**
+     * Perform health check for a specific server
+     *
+     * @param serverId Server to check
+     * @param strategy Strategy name to use (default: "ping")
+     * @returns Health check result
+     */
+    checkServerHealth(serverId: string, strategy?: string): Promise<HealthCheckResult>;
+    /**
+     * Get health status for all servers
+     *
+     * @returns Map of server health information
+     */
+    getHealthStatus(): Map<string, ServerHealth>;
+    /**
+     * Get health status for a specific server
+     *
+     * @param serverId Server ID
+     * @returns Server health information or null
+     */
+    getServerHealth(serverId: string): ServerHealth | null;
+    /**
+     * Register a recovery callback for a server
+     *
+     * @param serverId Server ID
+     * @param callback Recovery callback function
+     */
+    registerRecoveryCallback(serverId: string, callback: (serverId: string) => Promise<void>): void;
+    /**
+     * Add a custom health check strategy
+     *
+     * @param strategy Health check strategy
+     */
+    addStrategy(strategy: HealthCheckStrategy): void;
+    /**
+     * Schedule periodic health check for a server
+     *
+     * @private
+     */
+    private scheduleHealthCheck;
+    /**
+     * Trigger recovery for a server
+     *
+     * @private
+     */
+    private triggerRecovery;
+    /**
+     * Generate comprehensive health report
+     *
+     * @returns Health report with server statuses and metrics
+     */
+    generateHealthReport(): {
+        summary: {
+            totalServers: number;
+            healthyServers: number;
+            unhealthyServers: number;
+            recoveringServers: number;
+            overallHealth: number;
+        };
+        servers: Array<{
+            serverId: string;
+            status: ConnectionStatus;
+            health: number;
+            uptime: number;
+            avgLatency: number;
+            lastError?: string;
+            metrics: {
+                totalChecks: number;
+                successfulChecks: number;
+                failedChecks: number;
+                recoveryAttempts: number;
+            };
+        }>;
+        trends: {
+            healthHistory: Array<{
+                timestamp: number;
+                health: number;
+            }>;
+            errorRate: number;
+            avgRecoveryTime: number;
+        };
+        recommendations: string[];
+    };
+    /**
+     * Get health metrics for monitoring dashboards
+     *
+     * @returns Simplified metrics for real-time monitoring
+     */
+    getHealthMetrics(): {
+        status: "healthy" | "degraded" | "critical";
+        healthScore: number;
+        activeAlerts: Array<{
+            serverId: string;
+            severity: "low" | "medium" | "high" | "critical";
+            message: string;
+            timestamp: number;
+        }>;
+        serverStatuses: Record<string, ConnectionStatus>;
+        performance: {
+            avgLatency: number;
+            maxLatency: number;
+            successRate: number;
+        };
+    };
+    /**
+     * Subscribe to health events
+     *
+     * @param event Event type to subscribe to
+     * @param callback Callback function
+     */
+    on(event: "health-change" | "recovery-started" | "recovery-failed" | "critical-error", callback: (data: any) => void): void;
+    /**
+     * Get health history for trend analysis
+     *
+     * @private
+     */
+    private getHealthHistory;
+    /**
+     * Calculate error rate
+     *
+     * @private
+     */
+    private calculateErrorRate;
+    /**
+     * Calculate average recovery time
+     *
+     * @private
+     */
+    private calculateAvgRecoveryTime;
+    /**
+     * Generate health recommendations
+     *
+     * @private
+     */
+    private generateRecommendations;
+}
+/**
+ * Default health monitor instance (to be initialized with registry and error manager)
+ */
+export declare let defaultHealthMonitor: HealthMonitor | null;
+/**
+ * Initialize default health monitor
+ *
+ * @param registry Tool registry
+ * @param errorManager Error manager
+ * @param options Health monitor options
+ * @returns Health monitor instance
+ */
+export declare function initializeHealthMonitor(registry: MCPRegistry, errorManager: ErrorManager, options?: HealthMonitorOptions): HealthMonitor;