@unidev-hub/http-client

A standardized HTTP client for service-to-service communication with built-in resilience features:

• 🔄 Circuit breaking - Prevents cascading failures by failing fast when a service is unavailable
• 🔁 Retry mechanisms - Automatically retry failed requests with configurable strategies
• ⏱️ Timeouts and backoff - Adaptive timeouts and configurable backoff strategies
• 📝 Request/response logging - Comprehensive logging with sensitive data masking
• 🔍 Distributed tracing - OpenTracing integration for distributed tracing
• 💾 Response caching - Configurable response caching for improved performance

Installation

npm install @unidev-hub/http-client

Quick Start

import { createClient } from '@unidev-hub/http-client';

// Create a client with default configuration
const client = createClient({
  baseURL: 'https://api.example.com',
  timeout: 5000
});

// Make a request
async function fetchData() {
  try {
    const response = await client.get('/users');
    console.log(response.data);
  } catch (error) {
    console.error('Failed to fetch users:', error.message);
  }
}

Features

Circuit Breaking

Circuit breaking prevents cascading failures in distributed systems by failing fast when a service is repeatedly failing.

const client = createClient({
  baseURL: 'https://api.example.com',
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5, // Number of failures before opening circuit
    resetTimeout: 30000, // Time before attempting to close circuit (ms)
    fallbackResponse: null // Optional fallback response when circuit is open
  }
});

Retry Mechanisms

Automatically retry failed requests with configurable strategies.

const client = createClient({
  retry: {
    enabled: true,
    maxRetries: 3,
    retryDelay: 1000, // Base delay in ms
    backoffType: 'exponential', // 'fixed', 'linear', or 'exponential'
    retryCondition: (error) => error.isRetryableError // Custom retry condition
  }
});

Response Caching

Cache responses to improve performance and reduce load on services.

const client = createClient({
  cache: {
    enabled: true,
    ttl: 60, // Time-to-live in seconds
    methods: ['GET'], // HTTP methods to cache
    maxSize: 100 // Maximum number of cached responses
  }
});

Request/Response Logging

Comprehensive logging with sensitive data masking.

const client = createClient({
  logging: {
    enabled: true,
    logLevel: 'info', // 'debug', 'info', 'warn', or 'error'
    maskSensitiveData: true,
    sensitiveHeaders: ['Authorization', 'Cookie', 'Set-Cookie']
  }
});

Distributed Tracing

OpenTracing integration for distributed tracing.

const client = createClient({
  tracing: {
    enabled: true,
    serviceName: 'my-service'
  }
});

API Reference

HttpClient

The main client class for making HTTP requests.

class HttpClient {
  constructor(config?: Partial<ClientConfig>);
  
  request<T = any>(method: HttpMethod, url: string, options?: RequestOptions): Promise<HttpResponse<T>>;
  get<T = any>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>;
  post<T = any>(url: string, data?: any, options?: RequestOptions): Promise<HttpResponse<T>>;
  put<T = any>(url: string, data?: any, options?: RequestOptions): Promise<HttpResponse<T>>;
  patch<T = any>(url: string, data?: any, options?: RequestOptions): Promise<HttpResponse<T>>;
  delete<T = any>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>;
  head<T = any>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>;
  options<T = any>(url: string, options?: RequestOptions): Promise<HttpResponse<T>>;
}

Configuration

interface ClientConfig {
  timeout: number;
  baseURL: string;
  headers: Record<string, string>;
  retry: RetryConfig;
  circuitBreaker: CircuitBreakerConfig;
  logging: LoggingConfig;
  tracing: TracingConfig;
  cache: CacheConfig;
}

Advanced Usage

Request-Specific Configuration

You can override global configuration for specific requests:

// Override retry settings for a specific request
const response = await client.get('/users', {
  retry: {
    maxRetries: 5,
    backoffType: 'linear'
  }
});

// Disable caching for a specific request
const response = await client.get('/users/current', {
  cache: {
    enabled: false
  }
});

Error Handling

The client standardizes errors for easier handling:

try {
  const response = await client.get('/users');
  // Handle successful response
} catch (error) {
  if (error.isNetworkError) {
    // Handle network error
  } else if (error.isTimeoutError) {
    // Handle timeout
  } else if (error.isServerError) {
    // Handle server error (5xx)
  } else if (error.isClientError) {
    // Handle client error (4xx)
  } else {
    // Handle other errors
  }
}

Integration with Other @unidev-hub Packages

This package integrates with other @unidev-hub packages:

• @unidev-hub/logger: For enhanced logging capabilities
• @unidev-hub/config: For configuration management

License

MIT