@onlineapps/error-handler-core 1.0.0

package/src/ErrorHandlerCore.js

@@ -0,0 +1,329 @@
+/**
+ * Error Handler Core
+ * Main class that orchestrates error handling, logging, retry, circuit breaker, DLQ routing
+ */
+
+const { ErrorClassifier, ErrorTypes } = require('./ErrorClassifier');
+const UnifiedLogSchema = require('./UnifiedLogSchema');
+const RetryHandler = require('./RetryHandler');
+const CircuitBreakerManager = require('./CircuitBreaker');
+const DLQRouter = require('./DLQRouter');
+const CompensationHandler = require('./CompensationHandler');
+
+class ErrorHandlerCore {
+  /**
+   * Create ErrorHandlerCore instance
+   * 
+   * @param {Object} config - Configuration
+   * @param {string} config.serviceName - Service name
+   * @param {string} [config.serviceVersion] - Service version
+   * @param {string} [config.environment] - Environment
+   * @param {Object} config.monitoring - Monitoring instance (monitoring-core)
+   * @param {Object} [config.handling] - Error handling configuration
+   * @param {number} [config.handling.maxRetries=3] - Max retry attempts
+   * @param {number} [config.handling.retryDelay=1000] - Initial retry delay
+   * @param {number} [config.handling.retryMultiplier=2] - Backoff multiplier
+   * @param {boolean} [config.handling.circuitBreakerEnabled=true] - Enable circuit breaker
+   * @param {boolean} [config.handling.dlqEnabled=true] - Enable DLQ routing
+   * @param {Object} [config.handling.mqClient] - MQ client for DLQ
+   * @param {boolean} [config.handling.compensationEnabled=true] - Enable compensation
+   */
+  constructor(config) {
+    if (!config.serviceName) {
+      throw new Error('serviceName is required');
+    }
+    
+    if (!config.monitoring) {
+      throw new Error('monitoring instance is required (monitoring-core)');
+    }
+    
+    this.serviceName = config.serviceName;
+    this.serviceVersion = config.serviceVersion || '0.0.0';
+    this.environment = config.environment || process.env.NODE_ENV || 'development';
+    this.monitoring = config.monitoring;
+    
+    const handling = config.handling || {};
+    
+    // Initialize components
+    this.classifier = new ErrorClassifier();
+    this.logSchema = new UnifiedLogSchema();
+    this.retryHandler = new RetryHandler({
+      maxRetries: handling.maxRetries || 3,
+      retryDelay: handling.retryDelay || 1000,
+      retryMultiplier: handling.retryMultiplier || 2,
+      maxRetryDelay: handling.maxRetryDelay || 30000
+    });
+    this.circuitBreaker = new CircuitBreakerManager({
+      circuitBreakerEnabled: handling.circuitBreakerEnabled !== false,
+      timeout: handling.circuitTimeout || 10000,
+      errorThreshold: handling.errorThreshold || 50,
+      resetTimeout: handling.resetTimeout || 30000
+    });
+    this.dlqRouter = new DLQRouter({
+      dlqEnabled: handling.dlqEnabled !== false,
+      mqClient: handling.mqClient || null
+    });
+    this.compensation = new CompensationHandler({
+      compensationEnabled: handling.compensationEnabled !== false
+    });
+  }
+  
+  /**
+   * Log error using monitoring connector
+   * Always works: console (via monitoring) + RabbitMQ (if available)
+   * 
+   * @param {Object} errorData - Error data
+   * @param {string} errorData.moduleName - Module name
+   * @param {string} errorData.operation - Operation name
+   * @param {Error} errorData.error - Error object
+   * @param {Object} [errorData.context] - Additional context
+   * @returns {Promise<Object>} Unified error log entry
+   */
+  async logError(errorData) {
+    const { moduleName, operation, error, context = {} } = errorData;
+    
+    // Classify error
+    const errorType = this.classifier.classify(error);
+    
+    // Create unified log entry
+    const errorLog = this.logSchema.create({
+      moduleName,
+      operation,
+      error,
+      context,
+      serviceName: this.serviceName,
+      serviceVersion: this.serviceVersion,
+      environment: this.environment,
+      errorType,
+      handling: {} // Will be filled by handleError
+    });
+    
+    // Log via monitoring connector
+    // Monitoring connector has fallback to console if not initialized
+    const logMessage = `[${moduleName}] ${operation} failed: ${error.message}`;
+    
+    try {
+      // Use monitoring logger (monitoring-core returns instance with logger property)
+      // logger.error() always logs to console, optionally to RabbitMQ
+      if (this.monitoring.logger && this.monitoring.logger.error) {
+        this.monitoring.logger.error(logMessage, {
+          ...errorLog,
+          severity: errorLog.metadata.severity
+        });
+      } else if (this.monitoring.error) {
+        // Fallback: direct error method (conn-base-monitoring wrapper)
+        this.monitoring.error(logMessage, {
+          ...errorLog,
+          severity: errorLog.metadata.severity
+        });
+      } else {
+        // Last resort: console
+        console.error(JSON.stringify(errorLog, null, 2));
+      }
+    } catch (logError) {
+      // If monitoring fails, fallback to console
+      console.error('[ErrorHandlerCore] Monitoring log failed, using console:', logError.message);
+      console.error(JSON.stringify(errorLog, null, 2));
+    }
+    
+    return errorLog;
+  }
+  
+  /**
+   * Handle error: classify + log + decide action
+   * 
+   * @param {Object} errorData - Error data
+   * @param {string} errorData.moduleName - Module name
+   * @param {string} errorData.operation - Operation name
+   * @param {Error} errorData.error - Error object
+   * @param {Object} [errorData.context] - Additional context
+   * @param {number} [errorData.context.retryCount] - Current retry count
+   * @param {number} [errorData.context.maxRetries] - Max retries
+   * @returns {Promise<Object>} Handling result
+   */
+  async handleError(errorData) {
+    const { moduleName, operation, error, context = {} } = errorData;
+    
+    // 1. Classify error
+    const errorType = this.classifier.classify(error);
+    
+    // 2. Log error (always)
+    const errorLog = await this.logError({
+      moduleName,
+      operation,
+      error,
+      context
+    });
+    
+    // 3. Determine action based on error type
+    const action = this._determineAction(errorType, context);
+    
+    // 4. Prepare handling result
+    const result = {
+      action: action.type,
+      errorLog,
+      errorType,
+      shouldRetry: action.shouldRetry || false,
+      retryDelay: action.retryDelay || null,
+      retryCount: context.retryCount || 0,
+      maxRetries: context.maxRetries || this.retryHandler.maxRetries
+    };
+    
+    // 5. Execute action
+    if (action.type === 'dlq' && this.dlqRouter.isAvailable()) {
+      await this.dlqRouter.routeToDLQ(
+        context.message || {},
+        error,
+        errorType,
+        context
+      );
+    }
+    
+    if (action.type === 'compensate' && this.compensation.enabled) {
+      const compensationResult = await this.compensation.execute(
+        operation,
+        context
+      );
+      result.compensated = compensationResult !== null;
+    }
+    
+    return result;
+  }
+  
+  /**
+   * Determine action based on error type
+   * @private
+   */
+  _determineAction(errorType, context) {
+    const retryCount = context.retryCount || 0;
+    const maxRetries = context.maxRetries || this.retryHandler.maxRetries;
+    
+    switch (errorType) {
+      case ErrorTypes.TRANSIENT:
+      case ErrorTypes.TIMEOUT:
+      case ErrorTypes.RATE_LIMIT:
+        // Retry if under max retries
+        if (retryCount < maxRetries) {
+          const delay = this.retryHandler.calculateBackoff(retryCount + 1);
+          return {
+            type: 'retry',
+            shouldRetry: true,
+            retryDelay: delay
+          };
+        }
+        // Max retries exceeded, route to DLQ
+        return { type: 'dlq' };
+        
+      case ErrorTypes.BUSINESS:
+      case ErrorTypes.VALIDATION:
+        // Permanent errors, route to DLQ
+        return { type: 'dlq' };
+        
+      case ErrorTypes.FATAL:
+        // Fatal errors, throw immediately
+        return { type: 'throw' };
+        
+      default:
+        // Unknown errors, log and throw
+        return { type: 'throw' };
+    }
+  }
+  
+  /**
+   * Execute function with automatic retry
+   * 
+   * @param {Object} options - Execution options
+   * @param {string} options.moduleName - Module name
+   * @param {string} options.operation - Operation name
+   * @param {Function} options.fn - Async function to execute
+   * @param {Object} [options.context] - Additional context
+   * @returns {Promise<*>} Function result
+   */
+  async executeWithRetry(options) {
+    const { moduleName, operation, fn, context = {} } = options;
+    
+    return await this.retryHandler.executeWithRetry(fn, {
+      maxRetries: context.maxRetries || this.retryHandler.maxRetries,
+      onRetry: async (error, attempt, delay) => {
+        // Log each retry attempt
+        await this.logError({
+          moduleName,
+          operation,
+          error,
+          context: {
+            ...context,
+            retryCount: attempt,
+            maxRetries: context.maxRetries || this.retryHandler.maxRetries
+          }
+        });
+      }
+    });
+  }
+  
+  /**
+   * Execute function with circuit breaker protection
+   * 
+   * @param {Object} options - Execution options
+   * @param {string} options.moduleName - Module name
+   * @param {string} options.operation - Operation name
+   * @param {string} options.circuitName - Circuit breaker name
+   * @param {Function} options.fn - Async function to execute
+   * @param {Object} [options.context] - Additional context
+   * @returns {Promise<*>} Function result
+   */
+  async executeWithCircuitBreaker(options) {
+    const { moduleName, operation, circuitName, fn, context = {} } = options;
+    
+    try {
+      return await this.circuitBreaker.executeWithCircuitBreaker(
+        circuitName,
+        fn,
+        {}
+      );
+    } catch (error) {
+      // Log circuit breaker errors
+      await this.logError({
+        moduleName,
+        operation,
+        error,
+        context: {
+          ...context,
+          circuitName,
+          circuitState: this.circuitBreaker.getState(circuitName)
+        }
+      });
+      throw error;
+    }
+  }
+  
+  /**
+   * Register compensation handler
+   * 
+   * @param {string} operation - Operation name
+   * @param {Function} handler - Compensation handler
+   */
+  registerCompensation(operation, handler) {
+    this.compensation.register(operation, handler);
+  }
+  
+  /**
+   * Get circuit breaker state
+   * 
+   * @param {string} name - Circuit breaker name
+   * @returns {string} State: 'open' | 'half-open' | 'closed'
+   */
+  getCircuitBreakerState(name) {
+    return this.circuitBreaker.getState(name);
+  }
+  
+  /**
+   * Get all circuit breaker states
+   * @returns {Object} Map of circuit breaker states
+   */
+  getAllCircuitBreakerStates() {
+    return this.circuitBreaker.getAllStates();
+  }
+}
+
+module.exports = ErrorHandlerCore;
+

package/src/RetryHandler.js

@@ -0,0 +1,74 @@
+/**
+ * Retry Handler
+ * Implements exponential backoff retry logic
+ */
+
+class RetryHandler {
+  constructor(config = {}) {
+    this.maxRetries = config.maxRetries || 3;
+    this.retryDelay = config.retryDelay || 1000;
+    this.retryMultiplier = config.retryMultiplier || 2;
+    this.maxRetryDelay = config.maxRetryDelay || 30000;
+  }
+  
+  /**
+   * Calculate exponential backoff delay
+   * 
+   * @param {number} attempt - Current attempt number (1-based)
+   * @returns {number} Delay in milliseconds
+   */
+  calculateBackoff(attempt) {
+    const delay = this.retryDelay * Math.pow(this.retryMultiplier, attempt - 1);
+    return Math.min(delay, this.maxRetryDelay);
+  }
+  
+  /**
+   * Sleep for specified milliseconds
+   * @private
+   */
+  async sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+  
+  /**
+   * Execute function with retry
+   * 
+   * @param {Function} fn - Async function to execute
+   * @param {Object} options - Retry options
+   * @param {number} [options.maxRetries] - Override max retries
+   * @param {Function} [options.onRetry] - Callback on retry (error, attempt, delay)
+   * @returns {Promise<*>} Function result
+   * @throws {Error} Last error if all retries fail
+   */
+  async executeWithRetry(fn, options = {}) {
+    const maxAttempts = options.maxRetries || this.maxRetries;
+    let lastError;
+    
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        
+        // If last attempt, throw
+        if (attempt === maxAttempts) {
+          throw error;
+        }
+        
+        // Calculate delay and wait
+        const delay = this.calculateBackoff(attempt);
+        
+        if (options.onRetry) {
+          options.onRetry(error, attempt, delay);
+        }
+        
+        await this.sleep(delay);
+      }
+    }
+    
+    throw lastError;
+  }
+}
+
+module.exports = RetryHandler;
+

package/src/UnifiedLogSchema.js

@@ -0,0 +1,105 @@
+/**
+ * Unified Error Log Schema
+ * Creates structured error log entries following unified schema
+ */
+
+const os = require('os');
+
+class UnifiedLogSchema {
+  /**
+   * Create unified error log entry
+   * 
+   * @param {Object} params - Error data
+   * @param {string} params.moduleName - Module/component name
+   * @param {string} params.operation - Operation that failed
+   * @param {Error} params.error - Error object
+   * @param {Object} params.context - Additional context
+   * @param {string} params.serviceName - Service name
+   * @param {string} params.serviceVersion - Service version
+   * @param {string} params.environment - Environment (production, staging, etc.)
+   * @param {string} params.errorType - Classified error type
+   * @param {Object} params.handling - Handling decision
+   * @returns {Object} Unified error log entry
+   */
+  create(params) {
+    const {
+      moduleName,
+      operation,
+      error,
+      context = {},
+      serviceName,
+      serviceVersion,
+      environment,
+      errorType,
+      handling = {}
+    } = params;
+    
+    // Extract error details
+    const errorDetails = {
+      message: error?.message || 'Unknown error',
+      code: error?.code || null,
+      type: errorType || 'UNKNOWN',
+      stack: error?.stack || null
+    };
+    
+    // Build unified log entry
+    return {
+      // Core identification
+      timestamp: new Date().toISOString(),
+      serviceName: serviceName || 'unknown-service',
+      moduleName: moduleName || 'unknown-module',
+      operation: operation || 'unknown-operation',
+      
+      // Error details
+      error: errorDetails,
+      
+      // Context
+      context: {
+        workflowId: context.workflowId || null,
+        userId: context.userId || null,
+        requestId: context.requestId || null,
+        ...context
+      },
+      
+      // Handling decision
+      handling: {
+        action: handling.action || 'throw',
+        retryCount: handling.retryCount || null,
+        maxRetries: handling.maxRetries || null,
+        retryDelay: handling.retryDelay || null,
+        circuitBreakerState: handling.circuitBreakerState || null,
+        circuitName: handling.circuitName || null
+      },
+      
+      // Metadata
+      metadata: {
+        severity: this._determineSeverity(errorType),
+        environment: environment || process.env.NODE_ENV || 'development',
+        version: serviceVersion || '0.0.0',
+        hostname: os.hostname(),
+        pid: process.pid
+      }
+    };
+  }
+  
+  /**
+   * Determine severity from error type
+   * @private
+   */
+  _determineSeverity(errorType) {
+    const severityMap = {
+      FATAL: 'fatal',
+      BUSINESS: 'error',
+      VALIDATION: 'warn',
+      TRANSIENT: 'error',
+      TIMEOUT: 'error',
+      RATE_LIMIT: 'warn',
+      UNKNOWN: 'error'
+    };
+    
+    return severityMap[errorType] || 'error';
+  }
+}
+
+module.exports = UnifiedLogSchema;
+

package/src/index.js

@@ -0,0 +1,30 @@
+/**
+ * @onlineapps/error-handler-core
+ * Core error handling functionality for OA Drive microservices
+ */
+
+const ErrorHandlerCore = require('./ErrorHandlerCore');
+const { ErrorClassifier, ErrorTypes, ErrorCodes } = require('./ErrorClassifier');
+const UnifiedLogSchema = require('./UnifiedLogSchema');
+const RetryHandler = require('./RetryHandler');
+const CircuitBreakerManager = require('./CircuitBreaker');
+const DLQRouter = require('./DLQRouter');
+const CompensationHandler = require('./CompensationHandler');
+
+module.exports = {
+  // Main class
+  ErrorHandlerCore,
+  
+  // Components (for advanced usage)
+  ErrorClassifier,
+  UnifiedLogSchema,
+  RetryHandler,
+  CircuitBreakerManager,
+  DLQRouter,
+  CompensationHandler,
+  
+  // Constants
+  ErrorTypes,
+  ErrorCodes
+};
+

package/tests/unit/DLQRouter.test.js

@@ -0,0 +1,94 @@
+/**
+ * DLQRouter Unit Tests
+ */
+
+const DLQRouter = require('../../src/DLQRouter');
+
+describe('DLQRouter @unit', () => {
+  let dlqRouter;
+  let mockMQClient;
+  
+  beforeEach(() => {
+    mockMQClient = {
+      publish: jest.fn().mockResolvedValue()
+    };
+    
+    dlqRouter = new DLQRouter({
+      dlqEnabled: true,
+      mqClient: mockMQClient,
+      dlqNamePattern: '{queue}.dlq'
+    });
+  });
+  
+  describe('routeToDLQ', () => {
+    test('should route message to DLQ', async () => {
+      const message = { id: 'msg-123', data: 'test' };
+      const error = new Error('Test error');
+      const context = { queue: 'test.queue' };
+      
+      await dlqRouter.routeToDLQ(message, error, 'BUSINESS', context);
+      
+      expect(mockMQClient.publish).toHaveBeenCalledWith(
+        'test.queue.dlq',
+        expect.objectContaining({
+          id: 'msg-123',
+          error: expect.objectContaining({
+            message: 'Test error',
+            type: 'BUSINESS'
+          }),
+          originalQueue: 'test.queue'
+        }),
+        { persistent: true }
+      );
+    });
+    
+    test('should not route if DLQ disabled', async () => {
+      const disabledRouter = new DLQRouter({
+        dlqEnabled: false,
+        mqClient: mockMQClient
+      });
+      
+      await disabledRouter.routeToDLQ({}, new Error('Test'), 'BUSINESS', {});
+      
+      expect(mockMQClient.publish).not.toHaveBeenCalled();
+    });
+    
+    test('should not route if no MQ client', async () => {
+      const noClientRouter = new DLQRouter({
+        dlqEnabled: true,
+        mqClient: null
+      });
+      
+      await noClientRouter.routeToDLQ({}, new Error('Test'), 'BUSINESS', {});
+      
+      expect(mockMQClient.publish).not.toHaveBeenCalled();
+    });
+    
+    test('should handle DLQ routing failure gracefully', async () => {
+      mockMQClient.publish.mockRejectedValue(new Error('DLQ failed'));
+      const consoleSpy = jest.spyOn(console, 'error').mockImplementation();
+      
+      await dlqRouter.routeToDLQ({}, new Error('Test'), 'BUSINESS', { queue: 'test' });
+      
+      expect(consoleSpy).toHaveBeenCalled();
+      consoleSpy.mockRestore();
+    });
+  });
+  
+  describe('isAvailable', () => {
+    test('should return true if enabled and client available', () => {
+      expect(dlqRouter.isAvailable()).toBe(true);
+    });
+    
+    test('should return false if disabled', () => {
+      const disabledRouter = new DLQRouter({ dlqEnabled: false });
+      expect(disabledRouter.isAvailable()).toBe(false);
+    });
+    
+    test('should return false if no client', () => {
+      const noClientRouter = new DLQRouter({ mqClient: null });
+      expect(noClientRouter.isAvailable()).toBe(false);
+    });
+  });
+});
+