@onlineapps/error-handler-core 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# @onlineapps/error-handler-core
+
+Core error handling functionality for OA Drive microservices. Used by both business services (via `conn-infra-error-handler` wrapper) and infrastructure services (directly).
+
+## Features
+
+- **Error Classification** - Automatic error type detection (TRANSIENT, BUSINESS, FATAL, etc.)
+- **Retry Logic** - Exponential backoff for transient errors
+- **Circuit Breaker** - Protection against cascading failures
+- **DLQ Routing** - Dead letter queue routing for permanent errors
+- **Compensation** - Rollback operations for failed workflows
+- **Unified Logging** - Structured error logging via monitoring-core
+
+## Installation
+
+```bash
+npm install @onlineapps/error-handler-core
+```
+
+## Usage
+
+### Basic Setup
+
+```javascript
+const { init: initMonitoring } = require('@onlineapps/monitoring-core');
+const { ErrorHandlerCore } = require('@onlineapps/error-handler-core');
+
+// Initialize monitoring-core
+const monitoring = await initMonitoring({
+  serviceName: 'my-service',
+  mode: 'light'
+});
+
+// Initialize error handler
+const errorHandler = new ErrorHandlerCore({
+  serviceName: 'my-service',
+  serviceVersion: '1.0.0',
+  environment: process.env.NODE_ENV,
+  monitoring: monitoring,  // monitoring-core instance (required)
+  handling: {
+    maxRetries: 3,
+    retryDelay: 1000,
+    retryMultiplier: 2,
+    circuitBreakerEnabled: true,
+    dlqEnabled: true,
+    mqClient: mqClient  // Optional, for DLQ routing
+  }
+});
+```
+
+### Log Error
+
+```javascript
+await errorHandler.logError({
+  moduleName: 'MyModule',
+  operation: 'myOperation',
+  error: new Error('Something failed'),
+  context: { userId: 123 }
+});
+```
+
+### Handle Error
+
+```javascript
+try {
+  await criticalOperation();
+} catch (error) {
+  const result = await errorHandler.handleError({
+    moduleName: 'MyModule',
+    operation: 'criticalOperation',
+    error: error,
+    context: { operationId: 'op-123' }
+  });
+  
+  // result.action: 'retry' | 'dlq' | 'throw' | 'continue' | 'compensate'
+  if (result.action === 'retry') {
+    await sleep(result.retryDelay);
+    // Retry operation
+  }
+}
+```
+
+### Execute with Retry
+
+```javascript
+const result = await errorHandler.executeWithRetry({
+  moduleName: 'MQClient',
+  operation: 'publish',
+  fn: async () => await mqClient.publish(queue, message),
+  context: { queue, messageId }
+});
+```
+
+### Execute with Circuit Breaker
+
+```javascript
+const result = await errorHandler.executeWithCircuitBreaker({
+  moduleName: 'ExternalAPI',
+  operation: 'getUser',
+  circuitName: 'user-api',
+  fn: async () => await userAPI.getUser(id),
+  context: { userId: id }
+});
+```
+
+## API Reference
+
+See [UNIFIED_ERROR_HANDLING.md](/docs/standards/UNIFIED_ERROR_HANDLING.md) for complete API documentation.
+
+## Architecture
+
+- **Core Library** - Used directly by infrastructure services
+- **Wrapper** - `conn-infra-error-handler` wraps this for business services
+- **Dependencies** - Uses `monitoring-core` for logging
+
+## Related Documentation
+
+- [Unified Error Handling Standard](/docs/standards/UNIFIED_ERROR_HANDLING.md)
+- [Error Handling Architecture](/docs/standards/ERROR_HANDLING_ARCHITECTURE.md)
+- [Error Handling Standard](/docs/standards/ERROR_HANDLING.md)
+
+---
+
+*Version: 1.0.0 | License: MIT*
+

package/jest.config.js

@@ -0,0 +1,23 @@
+module.exports = {
+  testEnvironment: 'node',
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/tests/'
+  ],
+  testMatch: [
+    '**/tests/**/*.test.js'
+  ],
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/**/*.test.js'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70
+    }
+  }
+};
+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@onlineapps/error-handler-core",
+  "version": "1.0.0",
+  "description": "Core error handling functionality for OA Drive microservices - classification, retry, circuit breaker, DLQ routing",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
+    "test:unit": "jest tests/unit",
+    "test:component": "jest tests/component"
+  },
+  "keywords": [
+    "error-handling",
+    "retry",
+    "circuit-breaker",
+    "dlq",
+    "microservices"
+  ],
+  "author": "OnlineApps",
+  "license": "MIT",
+  "dependencies": {
+    "@onlineapps/monitoring-core": "^1.0.0",
+    "opossum": "^7.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}
+

package/src/CircuitBreaker.js

@@ -0,0 +1,110 @@
+/**
+ * Circuit Breaker
+ * Protects against cascading failures
+ */
+
+const CircuitBreaker = require('opossum');
+
+class CircuitBreakerManager {
+  constructor(config = {}) {
+    this.enabled = config.circuitBreakerEnabled !== false;
+    this.options = {
+      timeout: config.timeout || 10000,
+      errorThresholdPercentage: config.errorThreshold || 50,
+      resetTimeout: config.resetTimeout || 30000,
+      rollingCountTimeout: config.rollingCountTimeout || 10000,
+      rollingCountBuckets: config.rollingCountBuckets || 10,
+      ...config.circuitBreakerOptions
+    };
+    
+    // Registry of circuit breakers
+    this.breakers = new Map();
+  }
+  
+  /**
+   * Get or create circuit breaker for operation
+   * 
+   * @param {string} name - Operation name
+   * @param {Function} fn - Function to protect
+   * @param {Object} options - Circuit breaker options
+   * @returns {CircuitBreaker} Circuit breaker instance
+   */
+  getCircuitBreaker(name, fn, options = {}) {
+    if (!this.enabled) {
+      // Return pass-through if disabled
+      return {
+        fire: () => fn(),
+        opened: false,
+        halfOpen: false
+      };
+    }
+    
+    if (!this.breakers.has(name)) {
+      const breaker = new CircuitBreaker(fn, {
+        ...this.options,
+        ...options
+      });
+      
+      this.breakers.set(name, breaker);
+    }
+    
+    return this.breakers.get(name);
+  }
+  
+  /**
+   * Execute function with circuit breaker protection
+   * 
+   * @param {string} name - Operation name
+   * @param {Function} fn - Async function to execute
+   * @param {Object} options - Circuit breaker options
+   * @returns {Promise<*>} Function result
+   * @throws {Error} If circuit is open or operation fails
+   */
+  async executeWithCircuitBreaker(name, fn, options = {}) {
+    const breaker = this.getCircuitBreaker(name, fn, options);
+    
+    try {
+      return await breaker.fire();
+    } catch (error) {
+      if (error.code === 'EOPENBREAKER') {
+        throw new Error(`Service unavailable: ${name} circuit is open`);
+      }
+      throw error;
+    }
+  }
+  
+  /**
+   * Get circuit breaker state
+   * 
+   * @param {string} name - Circuit breaker name
+   * @returns {string} State: 'open' | 'half-open' | 'closed'
+   */
+  getState(name) {
+    if (!this.breakers.has(name)) {
+      return 'closed';
+    }
+    
+    const breaker = this.breakers.get(name);
+    if (breaker.opened) return 'open';
+    if (breaker.halfOpen) return 'half-open';
+    return 'closed';
+  }
+  
+  /**
+   * Get all circuit breaker states
+   * @returns {Object} Map of circuit breaker states
+   */
+  getAllStates() {
+    const states = {};
+    this.breakers.forEach((breaker, name) => {
+      states[name] = {
+        state: this.getState(name),
+        stats: breaker.stats || {}
+      };
+    });
+    return states;
+  }
+}
+
+module.exports = CircuitBreakerManager;
+

package/src/CompensationHandler.js

@@ -0,0 +1,104 @@
+/**
+ * Compensation Handler
+ * Executes rollback operations for failed workflow steps
+ */
+
+class CompensationHandler {
+  constructor(config = {}) {
+    this.enabled = config.compensationEnabled !== false;
+    this.handlers = new Map();
+  }
+  
+  /**
+   * Register compensation handler for operation
+   * 
+   * @param {string} operation - Operation name
+   * @param {Function} handler - Compensation handler function
+   */
+  register(operation, handler) {
+    if (typeof handler !== 'function') {
+      throw new Error(`Compensation handler for ${operation} must be a function`);
+    }
+    
+    this.handlers.set(operation, handler);
+  }
+  
+  /**
+   * Execute compensation for failed operation
+   * 
+   * @param {string} operation - Operation that failed
+   * @param {Object} context - Operation context for compensation
+   * @returns {Promise<*>} Compensation result or null if no handler
+   * @throws {Error} If compensation fails
+   */
+  async execute(operation, context) {
+    if (!this.enabled) {
+      return null;
+    }
+    
+    const handler = this.handlers.get(operation);
+    
+    if (!handler) {
+      return null; // No compensation handler registered
+    }
+    
+    try {
+      return await handler(context);
+    } catch (error) {
+      throw new Error(`Compensation failed for ${operation}: ${error.message}`);
+    }
+  }
+  
+  /**
+   * Execute compensations in reverse order
+   * Used for workflow rollback
+   * 
+   * @param {Array<string>} operations - Operations executed (in order)
+   * @param {Object} context - Shared context for all compensations
+   * @returns {Promise<Array>} Results of all compensations
+   */
+  async executeReverse(operations, context) {
+    if (!this.enabled || !operations || operations.length === 0) {
+      return [];
+    }
+    
+    const results = [];
+    
+    // Execute in reverse order
+    for (let i = operations.length - 1; i >= 0; i--) {
+      const operation = operations[i];
+      try {
+        const result = await this.execute(operation, context);
+        if (result !== null) {
+          results.push({ operation, success: true, result });
+        }
+      } catch (error) {
+        results.push({ operation, success: false, error: error.message });
+        // Continue with other compensations even if one fails
+      }
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Check if compensation handler exists for operation
+   * 
+   * @param {string} operation - Operation name
+   * @returns {boolean} True if handler exists
+   */
+  hasHandler(operation) {
+    return this.handlers.has(operation);
+  }
+  
+  /**
+   * Get all registered operations
+   * @returns {Array<string>} List of operation names with handlers
+   */
+  getRegisteredOperations() {
+    return Array.from(this.handlers.keys());
+  }
+}
+
+module.exports = CompensationHandler;
+

package/src/DLQRouter.js

@@ -0,0 +1,98 @@
+/**
+ * Dead Letter Queue Router
+ * Routes failed messages to DLQ for manual inspection
+ */
+
+class DLQRouter {
+  constructor(config = {}) {
+    this.enabled = config.dlqEnabled !== false;
+    this.mqClient = config.mqClient || null;
+    this.dlqNamePattern = config.dlqNamePattern || '{queue}.dlq';
+  }
+  
+  /**
+   * Route message to DLQ
+   * 
+   * @param {Object} message - Original message
+   * @param {Error} error - Error that occurred
+   * @param {string} errorType - Classified error type
+   * @param {Object} context - Additional context
+   * @returns {Promise<void>}
+   */
+  async routeToDLQ(message, error, errorType, context = {}) {
+    if (!this.enabled || !this.mqClient) {
+      return; // DLQ disabled or no MQ client
+    }
+    
+    const originalQueue = message.queue || context.queue || 'unknown';
+    const dlqName = this._generateDLQName(originalQueue);
+    
+    const dlqMessage = {
+      // Original message
+      ...message,
+      
+      // Error details
+      error: {
+        message: error.message,
+        stack: error.stack,
+        code: error.code || null,
+        type: errorType,
+        timestamp: new Date().toISOString()
+      },
+      
+      // Routing metadata
+      originalQueue: originalQueue,
+      retryCount: message.retryCount || context.retryCount || 0,
+      routedAt: new Date().toISOString(),
+      routingReason: this._determineRoutingReason(errorType, context)
+    };
+    
+    try {
+      await this.mqClient.publish(dlqName, dlqMessage, {
+        persistent: true
+      });
+    } catch (dlqError) {
+      // If DLQ routing fails, log but don't throw
+      // (we don't want DLQ failures to break error handling)
+      console.error(`[DLQRouter] Failed to route to DLQ ${dlqName}:`, dlqError.message);
+    }
+  }
+  
+  /**
+   * Generate DLQ name from original queue name
+   * @private
+   */
+  _generateDLQName(originalQueue) {
+    if (this.dlqNamePattern.includes('{queue}')) {
+      return this.dlqNamePattern.replace('{queue}', originalQueue);
+    }
+    return this.dlqNamePattern;
+  }
+  
+  /**
+   * Determine routing reason
+   * @private
+   */
+  _determineRoutingReason(errorType, context) {
+    if (context.retryCount >= context.maxRetries) {
+      return 'max_retries_exceeded';
+    }
+    
+    if (['BUSINESS', 'VALIDATION'].includes(errorType)) {
+      return 'permanent_error';
+    }
+    
+    return 'error_handling_decision';
+  }
+  
+  /**
+   * Check if DLQ routing is available
+   * @returns {boolean} True if DLQ is enabled and MQ client available
+   */
+  isAvailable() {
+    return this.enabled && this.mqClient !== null;
+  }
+}
+
+module.exports = DLQRouter;
+

package/src/ErrorClassifier.js

@@ -0,0 +1,142 @@
+/**
+ * Error Classifier
+ * Classifies errors into types for appropriate handling strategy
+ */
+
+// Error types enum
+const ErrorTypes = {
+  TRANSIENT: 'TRANSIENT',      // Network, temporary failures - RETRY
+  BUSINESS: 'BUSINESS',        // Business logic errors - DLQ
+  FATAL: 'FATAL',              // Critical failures - THROW immediately
+  VALIDATION: 'VALIDATION',    // Input validation - DLQ
+  TIMEOUT: 'TIMEOUT',          // Operation timeout - RETRY
+  RATE_LIMIT: 'RATE_LIMIT',    // Rate limiting - RETRY with backoff
+  UNKNOWN: 'UNKNOWN'           // Unclassified - LOG and THROW
+};
+
+// Error code mappings
+const ErrorCodes = {
+  // Network errors → TRANSIENT
+  ECONNREFUSED: ErrorTypes.TRANSIENT,
+  ENOTFOUND: ErrorTypes.TRANSIENT,
+  ETIMEDOUT: ErrorTypes.TRANSIENT,
+  ECONNRESET: ErrorTypes.TRANSIENT,
+  EPIPE: ErrorTypes.TRANSIENT,
+  
+  // HTTP status codes
+  408: ErrorTypes.TIMEOUT,
+  429: ErrorTypes.RATE_LIMIT,
+  500: ErrorTypes.TRANSIENT,
+  502: ErrorTypes.TRANSIENT,
+  503: ErrorTypes.TRANSIENT,
+  504: ErrorTypes.TIMEOUT,
+  
+  // Business errors
+  400: ErrorTypes.VALIDATION,
+  401: ErrorTypes.BUSINESS,
+  403: ErrorTypes.BUSINESS,
+  404: ErrorTypes.BUSINESS,
+  409: ErrorTypes.BUSINESS,
+  422: ErrorTypes.VALIDATION
+};
+
+class ErrorClassifier {
+  /**
+   * Classify error into type for appropriate handling
+   * 
+   * @param {Error} error - Error to classify
+   * @returns {string} Error type from ErrorTypes enum
+   */
+  classify(error) {
+    if (!error) {
+      return ErrorTypes.UNKNOWN;
+    }
+    
+    // 1. Check explicit type
+    if (error.type && ErrorTypes[error.type]) {
+      return error.type;
+    }
+    
+    // 2. Check error code
+    if (error.code && ErrorCodes[error.code]) {
+      return ErrorCodes[error.code];
+    }
+    
+    // 3. Check HTTP status
+    if (error.statusCode && ErrorCodes[error.statusCode]) {
+      return ErrorCodes[error.statusCode];
+    }
+    
+    // 4. Check message patterns
+    const message = (error.message || '').toLowerCase();
+    
+    if (message.includes('timeout')) {
+      return ErrorTypes.TIMEOUT;
+    }
+    
+    if (message.includes('rate limit') || message.includes('rate_limit')) {
+      return ErrorTypes.RATE_LIMIT;
+    }
+    
+    if (message.includes('validation') || message.includes('invalid')) {
+      return ErrorTypes.VALIDATION;
+    }
+    
+    if (message.includes('fatal') || message.includes('critical')) {
+      return ErrorTypes.FATAL;
+    }
+    
+    if (message.includes('connection') || message.includes('network') || message.includes('econn')) {
+      return ErrorTypes.TRANSIENT;
+    }
+    
+    // 5. Default
+    return ErrorTypes.UNKNOWN;
+  }
+  
+  /**
+   * Determine if error should be retried
+   * 
+   * @param {Error} error - Error to check
+   * @param {number} attempts - Current attempt count
+   * @param {number} maxRetries - Maximum retry attempts
+   * @returns {boolean} True if should retry
+   */
+  shouldRetry(error, attempts = 0, maxRetries = 3) {
+    if (attempts >= maxRetries) {
+      return false;
+    }
+    
+    const errorType = this.classify(error);
+    
+    // Only retry transient, timeout, and rate limit errors
+    return [
+      ErrorTypes.TRANSIENT,
+      ErrorTypes.TIMEOUT,
+      ErrorTypes.RATE_LIMIT
+    ].includes(errorType);
+  }
+  
+  /**
+   * Get error types enum
+   * @returns {Object} ErrorTypes enum
+   */
+  static getErrorTypes() {
+    return ErrorTypes;
+  }
+  
+  /**
+   * Get error codes mapping
+   * @returns {Object} ErrorCodes mapping
+   */
+  static getErrorCodes() {
+    return ErrorCodes;
+  }
+}
+
+module.exports = {
+  ErrorClassifier,
+  ErrorTypes,
+  ErrorCodes
+};
+