@onlineapps/conn-infra-error-handler

Overview

Error handling connector for business services. Wraps @onlineapps/error-handler-core and integrates with @onlineapps/conn-base-monitoring for unified error handling and logging.

Note: This connector is for business services using ServiceWrapper. Infrastructure services should use @onlineapps/error-handler-core directly.

Installation

npm install @onlineapps/conn-infra-error-handler

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

Architecture

This connector wraps @onlineapps/error-handler-core and integrates with @onlineapps/conn-base-monitoring:

conn-infra-error-handler (wrapper)
  └─> error-handler-core (core logic)
       └─> monitoring-core (logging)

See Unified Error Handling Standard for complete architecture details.

Usage

Basic Setup (via ServiceWrapper)

The error handler is automatically integrated when using ServiceWrapper:

const { ServiceWrapper } = require('@onlineapps/service-wrapper');

const wrapper = new ServiceWrapper({
  serviceName: 'my-service',
  monitoring: { enabled: true },
  errorHandling: {
    maxRetries: 3,
    retryDelay: 1000
  }
});

// Error handler is available as wrapper.errorHandler

Direct Usage

const { ErrorHandlerConnector } = require('@onlineapps/conn-infra-error-handler');
const { init: initMonitoring } = require('@onlineapps/conn-base-monitoring');

// Initialize monitoring first
const monitoring = await initMonitoring({
  serviceName: 'my-service',
  mode: 'light'
});

// Initialize error handler
const errorHandler = new ErrorHandlerConnector({
  serviceName: 'my-service',
  serviceVersion: '1.0.0',
  environment: 'production',
  monitoring: monitoring,  // Required: conn-base-monitoring instance
  handling: {
    maxRetries: 3,
    retryDelay: 1000,
    retryMultiplier: 2,
    circuitBreakerEnabled: true,
    dlqEnabled: true,
    mqClient: mqClient  // Optional, for DLQ routing
  }
});

Error Classification

try {
  await processMessage(message);
} catch (error) {
  const classified = errorHandler.classify(error);

  if (classified.isTransient) {
    // Retry-able error (network, timeout)
    await errorHandler.handleTransient(error, message);
  } else {
    // Permanent error (validation, business logic)
    await errorHandler.handlePermanent(error, message);
  }
}

Retry Logic

const result = await errorHandler.withRetry(async () => {
  return await externalService.call();
}, {
  maxAttempts: 3,
  backoffMultiplier: 2,
  initialDelay: 100
});

Configuration

Options

{
  serviceName: 'service-name',     // Required
  maxRetries: 3,                    // Default: 3
  retryDelay: 1000,                 // Default: 1000ms
  enableDLQ: true,                  // Default: true
  dlqName: 'workflow.error',        // Default: workflow.error
  logLevel: 'error',                // Default: error
  includeStackTrace: true           // Default: true in dev
}

Environment Variables

ERROR_MAX_RETRIES=3
ERROR_RETRY_DELAY=1000
ERROR_DLQ_ENABLED=true
ERROR_DLQ_NAME=workflow.error

Error Types

Transient Errors

Automatically retried:

• Network errors (ECONNREFUSED, ETIMEDOUT)
• Service unavailable (503)
• Rate limiting (429)
• Temporary database issues

Permanent Errors

Sent to DLQ immediately:

• Validation errors (400)
• Authentication errors (401)
• Not found errors (404)
• Business logic errors

API Reference

ErrorHandler

initialize()

Initializes the error handler with configured options.

classify(error)

Classifies an error as transient or permanent. Returns: { isTransient: boolean, category: string, retryable: boolean }

handleTransient(error, context)

Handles transient errors with retry logic.

handlePermanent(error, context)

Routes permanent errors to DLQ.

withRetry(fn, options)

Wraps a function with retry logic.

enrichError(error, context)

Adds context information to error object.

Error Context

{
  workflowId: 'wf-uuid',
  spanId: 'span-uuid',
  service: 'hello-service',
  operation: 'greet',
  timestamp: 'ISO-8601',
  retryCount: 2,
  maxRetries: 3,
  errorCode: 'NETWORK_ERROR',
  errorMessage: 'Connection refused',
  stackTrace: '...'
}

Integration with Service Wrapper

The error handler is automatically integrated when using service-wrapper:

const { ServiceWrapper } = require('@onlineapps/service-wrapper');

const wrapper = new ServiceWrapper({
  errorHandling: {
    enabled: true,
    maxRetries: 3
  }
});

// Error handling is automatically configured

Testing

npm test                 # Run all tests
npm run test:unit        # Unit tests only
npm run test:component   # Component tests

Dependencies

• @onlineapps/error-handler-core - Core error handling functionality
• @onlineapps/conn-base-monitoring - Monitoring integration for business services

Related Documentation

• Unified Error Handling Standard - Complete error handling architecture
• Error Handling Architecture - Core vs connector distinction
• Error Handling Standard - Fail loudly principle
• Service Wrapper - Integration guide

Version: 1.0.0 | License: MIT