@naman_deep_singh/communication-core 1.0.0

package/README.md

@@ -0,0 +1,345 @@
+# @naman_deep_singh/communication-core
+
+> Core interfaces and abstract classes for building a comprehensive service-to-service communication layer in TypeScript
+
+## Overview
+
+This package provides the foundational interfaces, abstract base classes, types, and utilities needed to build a complete microservices communication ecosystem. It serves as the architectural foundation for 5 specialized subpackages that handle different aspects of service communication.
+
+## Features
+
+- 🔌 **Protocol Abstraction**: Unified interface for HTTP, gRPC, WebSocket protocols
+- 🛡️ **Resilience Patterns**: Circuit breaker and retry strategy interfaces
+- 🔍 **Service Discovery**: Dynamic service location and health monitoring
+- ⚖️ **Load Balancing**: Traffic distribution strategies
+- 🎯 **Unified Client**: Composable client that orchestrates all components
+- 🔧 **Connection Pooling**: Built-in connection management with health checks
+- 📊 **Observability**: Metrics, events, and health monitoring
+- 🚦 **Interceptors**: Request/response middleware system
+- ⚡ **TypeScript First**: Full type safety with strict import/export patterns
+
+## Installation
+
+```bash
+npm install @naman_deep_singh/communication-core
+```
+
+## Core Interfaces
+
+### Communication Protocols
+- **`IProtocol`**: Base interface for all communication protocols
+- **`IConnectionPool`**: Connection pooling and lifecycle management
+- **`IInterceptor`**: Request/response middleware
+
+### Resilience & Reliability
+- **`ICircuitBreaker`**: Circuit breaker pattern for fault tolerance
+- **`IRetryStrategy`**: Configurable retry mechanisms with backoff
+
+### Service Discovery & Load Balancing
+- **`IServiceDiscoverer`**: Dynamic service instance discovery
+- **`ILoadBalanceStrategy`**: Traffic distribution algorithms
+
+### Client Orchestration
+- **`IClient`**: Main client interface that composes all components
+- **`IClientFactory`**: Factory for creating and managing client instances
+
+## Abstract Base Classes
+
+These classes provide common functionality and enforce consistent patterns:
+
+### Protocol Layer
+- **`BaseProtocol`**: Common protocol functionality (connection pooling, metrics, error handling)
+- **`BaseConnectionPool`**: Connection lifecycle, health checks, and resource management
+
+### Service Discovery
+- **`BaseServiceDiscoverer`**: Caching, health monitoring, and event-driven updates
+
+## Type System
+
+### Core Types
+- **`Request/Response`**: Standardized request/response objects
+- **`ServiceInstance`**: Service endpoint representation
+- **`ClientConfig`**: Comprehensive client configuration
+- **`ConnectionPoolConfig`**: Connection pool settings
+
+### Configuration Types
+- **`ProtocolConfig`**: Protocol-specific settings
+- **`CircuitBreakerConfig`**: Circuit breaker thresholds and timeouts
+- **`RetryConfig`**: Retry policies and backoff strategies
+- **`LoadBalancerConfig`**: Load balancing algorithms and weights
+
+### Error Handling
+- **`CommunicationError`**: Base error class with error codes and context
+- **`ConnectionError`**: Connection-specific errors
+- **`TimeoutError`**: Request timeout errors
+- **`ServiceUnavailableError`**: Service discovery errors
+
+## Subpackage Architecture
+
+This core package enables building 5 specialized subpackages:
+
+### 1. **@naman_deep_singh/communication-protocols**
+
+**Purpose**: Protocol-specific implementations (HTTP, gRPC, WebSocket)
+
+```
+communication-protocols/
+├── src/
+│   ├── http/
+│   │   ├── HttpProtocol.ts          # extends BaseProtocol
+│   │   ├── HttpConnectionPool.ts    # extends BaseConnectionPool
+│   │   └── HttpInterceptor.ts       # implements IInterceptor
+│   ├── grpc/
+│   │   ├── GrpcProtocol.ts          # extends BaseProtocol
+│   │   ├── GrpcConnectionPool.ts    # extends BaseConnectionPool
+│   │   └── GrpcInterceptor.ts       # implements IInterceptor
+│   ├── websocket/
+│   │   ├── WebSocketProtocol.ts     # extends BaseProtocol
+│   │   ├── WebSocketConnectionPool.ts
+│   │   └── WebSocketInterceptor.ts
+│   └── index.ts
+├── package.json
+└── README.md
+```
+
+**Key Dependencies**: `axios`, `@grpc/grpc-js`, `ws`
+
+**Usage**:
+```typescript
+import { HttpProtocol } from '@naman_deep_singh/communication-protocols/http';
+import { GrpcProtocol } from '@naman_deep_singh/communication-protocols/grpc';
+```
+
+### 2. **@naman_deep_singh/communication-resilience**
+
+**Purpose**: Fault tolerance patterns (Circuit Breaker, Retry Strategies)
+
+```
+communication-resilience/
+├── src/
+│   ├── circuit-breaker/
+│   │   ├── CircuitBreakerImpl.ts    # implements ICircuitBreaker
+│   │   ├── CircuitBreakerState.ts   # State management
+│   │   └── CircuitBreakerMetrics.ts # Failure tracking
+│   ├── retry/
+│   │   ├── ExponentialBackoffRetry.ts   # implements IRetryStrategy
+│   │   ├── LinearBackoffRetry.ts        # implements IRetryStrategy
+│   │   ├── FixedDelayRetry.ts           # implements IRetryStrategy
+│   │   └── JitterRetry.ts               # implements IRetryStrategy
+│   ├── policies/
+│   │   ├── RetryPolicy.ts
+│   │   └── CircuitBreakerPolicy.ts
+│   └── index.ts
+├── package.json
+└── README.md
+```
+
+**Usage**:
+```typescript
+import { CircuitBreakerImpl } from '@naman_deep_singh/communication-resilience/circuit-breaker';
+import { ExponentialBackoffRetry } from '@naman_deep_singh/communication-resilience/retry';
+```
+
+### 3. **@naman_deep_singh/communication-discovery**
+
+**Purpose**: Service discovery implementations (Consul, etcd, Kubernetes)
+
+```
+communication-discovery/
+├── src/
+│   ├── consul/
+│   │   ├── ConsulServiceDiscoverer.ts   # extends BaseServiceDiscoverer
+│   │   ├── ConsulHealthChecker.ts
+│   │   └── ConsulWatcher.ts
+│   ├── etcd/
+│   │   ├── EtcdServiceDiscoverer.ts     # extends BaseServiceDiscoverer
+│   │   ├── EtcdHealthChecker.ts
+│   │   └── EtcdWatcher.ts
+│   ├── kubernetes/
+│   │   ├── K8sServiceDiscoverer.ts      # extends BaseServiceDiscoverer
+│   │   ├── K8sHealthChecker.ts
+│   │   └── K8sWatcher.ts
+│   ├── static/
+│   │   └── StaticServiceDiscoverer.ts   # For testing/development
+│   └── index.ts
+├── package.json
+└── README.md
+```
+
+**Key Dependencies**: `consul`, `etcd3`, `@kubernetes/client-node`
+
+**Usage**:
+```typescript
+import { ConsulServiceDiscoverer } from '@naman_deep_singh/communication-discovery/consul';
+import { K8sServiceDiscoverer } from '@naman_deep_singh/communication-discovery/kubernetes';
+```
+
+### 4. **@naman_deep_singh/communication-load-balancing**
+
+**Purpose**: Load balancing strategies for traffic distribution
+
+```
+communication-load-balancing/
+├── src/
+│   ├── strategies/
+│   │   ├── RoundRobinStrategy.ts        # implements ILoadBalanceStrategy
+│   │   ├── WeightedRoundRobinStrategy.ts # implements ILoadBalanceStrategy
+│   │   ├── LeastConnectionsStrategy.ts   # implements ILoadBalanceStrategy
+│   │   ├── RandomStrategy.ts            # implements ILoadBalanceStrategy
+│   │   └── ConsistentHashStrategy.ts    # implements ILoadBalanceStrategy
+│   ├── health/
+│   │   ├── HealthAwareLoadBalancer.ts
+│   │   └── HealthScorer.ts
+│   ├── metrics/
+│   │   ├── LoadBalancerMetrics.ts
+│   │   └── ConnectionTracker.ts
+│   └── index.ts
+├── package.json
+└── README.md
+```
+
+**Usage**:
+```typescript
+import { RoundRobinStrategy } from '@naman_deep_singh/communication-load-balancing/strategies';
+import { WeightedRoundRobinStrategy } from '@naman_deep_singh/communication-load-balancing/strategies';
+```
+
+### 5. **@naman_deep_singh/communication-client**
+
+**Purpose**: Unified client that orchestrates all components
+
+```
+communication-client/
+├── src/
+│   ├── client/
+│   │   ├── CommunicationClient.ts       # implements IClient
+│   │   ├── ClientFactory.ts             # implements IClientFactory
+│   │   └── ClientBuilder.ts             # Fluent builder pattern
+│   ├── pipeline/
+│   │   ├── RequestPipeline.ts
+│   │   ├── ResponsePipeline.ts
+│   │   └── InterceptorChain.ts
+│   ├── middleware/
+│   │   ├── LoggingInterceptor.ts
+│   │   ├── MetricsInterceptor.ts
+│   │   ├── TracingInterceptor.ts
+│   │   └── AuthInterceptor.ts
+│   ├── events/
+│   │   ├── ClientEventEmitter.ts
+│   │   └── ClientEvents.ts
+│   └── index.ts
+├── package.json
+└── README.md
+```
+
+**Usage**:
+```typescript
+import { CommunicationClient, ClientBuilder } from '@naman_deep_singh/communication-client';
+
+// Fluent builder pattern
+const client = new ClientBuilder()
+  .withProtocol(new HttpProtocol())
+  .withServiceDiscovery(new ConsulServiceDiscoverer(consulConfig))
+  .withLoadBalancer(new RoundRobinStrategy())
+  .withCircuitBreaker(new CircuitBreakerImpl(cbConfig))
+  .withRetryStrategy(new ExponentialBackoffRetry(retryConfig))
+  .build('user-service');
+```
+
+## Development Roadmap
+
+### Phase 1: Protocols Foundation (Week 1-2)
+- Implement `HttpProtocol` with connection pooling
+- Add basic interceptor support
+- Create comprehensive tests
+
+### Phase 2: Resilience Layer (Week 3)
+- Implement `CircuitBreakerImpl` with state management
+- Add `ExponentialBackoffRetry` strategy
+- Integration testing with HTTP protocol
+
+### Phase 3: Service Discovery (Week 4)
+- Implement `ConsulServiceDiscoverer`
+- Add health checking and caching
+- Event-driven service updates
+
+### Phase 4: Load Balancing (Week 5)
+- Implement `RoundRobinStrategy`
+- Add health-aware load balancing
+- Performance benchmarking
+
+### Phase 5: Client Orchestration (Week 6)
+- Create unified `CommunicationClient`
+- Implement request pipeline
+- End-to-end integration testing
+
+## Usage Example
+
+```typescript
+import { 
+  IClient, 
+  IProtocol, 
+  IServiceDiscoverer, 
+  ILoadBalanceStrategy,
+  ICircuitBreaker,
+  IRetryStrategy 
+} from '@naman_deep_singh/communication-core';
+
+// This core package provides the contracts
+// Implementations come from subpackages:
+
+// From communication-protocols
+const protocol: IProtocol = new HttpProtocol({
+  timeout: 5000,
+  maxConnections: 100
+});
+
+// From communication-discovery  
+const discovery: IServiceDiscoverer = new ConsulServiceDiscoverer({
+  host: 'localhost',
+  port: 8500
+});
+
+// From communication-load-balancing
+const loadBalancer: ILoadBalanceStrategy = new RoundRobinStrategy();
+
+// From communication-resilience
+const circuitBreaker: ICircuitBreaker = new CircuitBreakerImpl({
+  failureThreshold: 5,
+  timeout: 60000
+});
+
+// From communication-client
+const client: IClient = new CommunicationClient({
+  serviceName: 'user-service',
+  protocol,
+  serviceDiscoverer: discovery,
+  loadBalancer,
+  circuitBreaker
+});
+
+// Make requests
+const response = await client.call('/users/123');
+```
+
+## Key Benefits
+
+- **🔧 Modular Architecture**: Use only the components you need
+- **🔄 Consistent Patterns**: All implementations follow the same interfaces
+- **🧪 Easy Testing**: Mock interfaces for comprehensive unit testing
+- **📈 Extensible**: Add new protocols/strategies without breaking changes
+- **⚡ Performance**: Built-in connection pooling and caching
+- **🛡️ Reliable**: Circuit breakers and retry mechanisms
+- **📊 Observable**: Built-in metrics and event system
+
+## Contributing
+
+This package follows strict TypeScript patterns:
+- No wildcard exports (except root index)
+- Type keyword for all type imports
+- .js extensions in imports
+- Barrel exports in all directories
+
+## License
+
+MIT

package/dist/cjs/abstract/BaseCircuitBreaker.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Abstract base circuit breaker implementation
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCircuitBreaker = void 0;
+/**
+ * Abstract base circuit breaker implementation
+ * Provides common functionality for all circuit breaker implementations
+ */
+class BaseCircuitBreaker {
+    /**
+     * Create a new base circuit breaker instance
+     * @param name Circuit breaker name
+     * @param config Circuit breaker configuration
+     */
+    constructor(name, config) {
+        /** Current state */
+        this.state = 'closed';
+        /** Failure count */
+        this.failureCount = 0;
+        /** Success count */
+        this.successCount = 0;
+        /** Circuit breaker statistics */
+        this.stats = {
+            totalExecutions: 0,
+            totalSuccesses: 0,
+            totalFailures: 0,
+            successRate: 0,
+            failureRate: 0,
+            totalTimeOpen: 0,
+            totalTimeClosed: 0,
+            lastStateChange: Date.now(),
+        };
+        /** Time when current state was entered */
+        this.stateEnteredTime = Date.now();
+        this.name = name;
+        this.config = { ...config };
+        this.initialize();
+    }
+    /**
+     * Initialize circuit breaker
+     */
+    initialize() {
+        // Can be overridden by subclasses
+    }
+    /**
+     * Check if circuit breaker should allow execution
+     * @returns True if execution is allowed
+     */
+    shouldAllowExecution() {
+        switch (this.state) {
+            case 'closed':
+                return true;
+            case 'open':
+                if (this.nextResetTime && Date.now() >= this.nextResetTime) {
+                    this.transitionToHalfOpen();
+                    return true;
+                }
+                return false;
+            case 'half-open':
+                return this.failureCount < (this.config.halfOpenMaxAttempts || 1);
+            default:
+                return false;
+        }
+    }
+    /**
+     * Transition circuit breaker to closed state
+     */
+    transitionToClosed() {
+        const previousState = this.state;
+        this.state = 'closed';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.nextResetTime = undefined;
+        this.updateStateTime(previousState);
+        this.onStateChange('closed', previousState);
+    }
+    /**
+     * Transition circuit breaker to open state
+     * @param error Optional error that caused the transition
+     */
+    transitionToOpen(error) {
+        const previousState = this.state;
+        this.state = 'open';
+        this.nextResetTime = Date.now() + (this.config.resetTimeout || 30000);
+        this.updateStateTime(previousState);
+        this.onStateChange('open', previousState, error);
+    }
+    /**
+     * Transition circuit breaker to half-open state
+     */
+    transitionToHalfOpen() {
+        const previousState = this.state;
+        this.state = 'half-open';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.updateStateTime(previousState);
+        this.onStateChange('half-open', previousState);
+    }
+    /**
+     * Update state timing statistics
+     * @param previousState Previous state
+     */
+    updateStateTime(previousState) {
+        const now = Date.now();
+        const timeInState = now - this.stateEnteredTime;
+        if (previousState === 'open') {
+            this.stats.totalTimeOpen += timeInState;
+        }
+        else if (previousState === 'closed') {
+            this.stats.totalTimeClosed += timeInState;
+        }
+        this.stateEnteredTime = now;
+        this.stats.lastStateChange = now;
+    }
+    /**
+     * Hook for state changes
+     * @param newState New state
+     * @param previousState Previous state
+     * @param error Optional error that caused state change
+     */
+    onStateChange(newState, previousState, error) {
+        // Can be overridden by subclasses
+        // Emit events, log, etc.
+    }
+    /**
+     * Check if failure threshold is reached
+     * @returns True if failure threshold reached
+     */
+    isFailureThresholdReached() {
+        return this.failureCount >= (this.config.failureThreshold || 5);
+    }
+    /**
+     * Check if success threshold is reached
+     * @returns True if success threshold reached
+     */
+    isSuccessThresholdReached() {
+        return this.successCount >= (this.config.successThreshold || 1);
+    }
+    /**
+     * Manually trip the circuit breaker to open state
+     * @param error Error that caused the trip
+     */
+    trip(error) {
+        this.transitionToOpen(error);
+    }
+    /**
+     * Manually reset the circuit breaker to closed state
+     */
+    reset() {
+        this.transitionToClosed();
+    }
+    /**
+     * Check if circuit breaker is currently open
+     */
+    isOpen() {
+        return this.state === 'open';
+    }
+    /**
+     * Check if circuit breaker is currently closed
+     */
+    isClosed() {
+        return this.state === 'closed';
+    }
+    /**
+     * Check if circuit breaker is in half-open state
+     */
+    isHalfOpen() {
+        return this.state === 'half-open';
+    }
+    /**
+     * Record a successful execution
+     */
+    recordSuccess() {
+        this.successCount++;
+        this.lastSuccessTime = Date.now();
+        this.stats.totalSuccesses++;
+        if (this.state === 'half-open' && this.isSuccessThresholdReached()) {
+            this.transitionToClosed();
+        }
+    }
+    /**
+     * Record a failed execution
+     * @param error Error that occurred
+     */
+    recordFailure(error) {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        this.stats.totalFailures++;
+        if (this.state === 'half-open') {
+            this.transitionToOpen(error);
+        }
+        else if (this.state === 'closed' && this.isFailureThresholdReached()) {
+            this.transitionToOpen(error);
+        }
+    }
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats() {
+        const total = this.stats.totalSuccesses + this.stats.totalFailures;
+        return {
+            ...this.stats,
+            successRate: total > 0 ? this.stats.totalSuccesses / total : 0,
+            failureRate: total > 0 ? this.stats.totalFailures / total : 0,
+        };
+    }
+    /**
+     * Reset circuit breaker statistics
+     */
+    resetStats() {
+        this.stats = {
+            totalExecutions: 0,
+            totalSuccesses: 0,
+            totalFailures: 0,
+            successRate: 0,
+            failureRate: 0,
+            totalTimeOpen: 0,
+            totalTimeClosed: 0,
+            lastStateChange: Date.now(),
+        };
+    }
+    /**
+     * Update circuit breaker configuration
+     * @param config New configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Health check for the circuit breaker
+     */
+    healthCheck() {
+        const healthy = this.state === 'closed' || this.state === 'half-open';
+        return {
+            healthy,
+            state: this.state,
+            message: healthy ? 'Circuit breaker is operational' : 'Circuit breaker is open',
+            details: {
+                name: this.name,
+                failureCount: this.failureCount,
+                successCount: this.successCount,
+                lastFailureTime: this.lastFailureTime,
+                lastSuccessTime: this.lastSuccessTime,
+                nextResetTime: this.nextResetTime,
+                config: this.config,
+            },
+        };
+    }
+}
+exports.BaseCircuitBreaker = BaseCircuitBreaker;