@naman_deep_singh/communication-core 1.0.0

package/dist/esm/abstract/BaseTimeoutManager.js

@@ -0,0 +1,291 @@
+/**
+ * Abstract base timeout manager implementation
+ * @packageDocumentation
+ */
+import { TimeoutError } from '@naman_deep_singh/utils';
+import { CommunicationError } from '../errors/CommunicationError.js';
+/**
+ * Abstract base timeout manager implementation
+ * Provides common functionality for timeout management
+ */
+export class BaseTimeoutManager {
+    /**
+     * Create a new base timeout manager instance
+     * @param name Timeout manager name
+     * @param config Timeout configuration
+     */
+    constructor(name, config) {
+        /** Operation-specific timeouts */
+        this.operationTimeouts = new Map();
+        /** Timeout statistics */
+        this.stats = {
+            totalOperations: 0,
+            timedOutOperations: 0,
+            totalOperationTime: 0,
+            averageOperationTime: 0,
+            timeoutRate: 0,
+            perOperationStats: new Map(),
+        };
+        this.name = name;
+        this.config = { ...config };
+        this.initialize();
+    }
+    /**
+     * Initialize timeout manager
+     */
+    initialize() {
+        // Can be overridden by subclasses
+        // Set up default operation timeouts
+        if (this.config.global) {
+            this.operationTimeouts.set('global', this.config.global);
+        }
+        if (this.config.connection) {
+            this.operationTimeouts.set('connection', this.config.connection);
+        }
+        if (this.config.read) {
+            this.operationTimeouts.set('read', this.config.read);
+        }
+        if (this.config.write) {
+            this.operationTimeouts.set('write', this.config.write);
+        }
+        if (this.config.request) {
+            this.operationTimeouts.set('request', this.config.request);
+        }
+    }
+    /**
+     * Execute a function with timeout
+     * @param fn Function to execute
+     * @param options Timeout options
+     * @returns Promise resolving to function result
+     * @throws {CommunicationError} If timeout occurs
+     */
+    async execute(fn, options) {
+        const operationName = options?.name || 'anonymous';
+        const timeoutMs = options?.timeout || this.getOperationTimeout(operationName) || this.config.global || 30000;
+        const throwOnTimeout = options?.throwOnTimeout !== false;
+        const startTime = Date.now();
+        // Create timeout promise
+        const timeoutPromise = this.createTimeout(timeoutMs, options?.errorMessage || `Operation '${operationName}' timed out after ${timeoutMs}ms`);
+        // Create cleanup function
+        const cleanup = options?.cleanup;
+        try {
+            // Race between function and timeout
+            const result = await Promise.race([
+                fn(),
+                timeoutPromise,
+            ]);
+            const duration = Date.now() - startTime;
+            this.recordSuccess(operationName, duration);
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            // Check if it's a timeout error
+            if (error instanceof TimeoutError || error instanceof CommunicationError) {
+                this.recordTimeout(operationName, duration);
+                // Call cleanup if provided
+                if (cleanup) {
+                    try {
+                        await cleanup();
+                    }
+                    catch (cleanupError) {
+                        // Ignore cleanup errors
+                    }
+                }
+                if (throwOnTimeout) {
+                    throw error;
+                }
+                // If not throwing, return default value
+                return undefined;
+            }
+            // Record failure but not timeout
+            this.recordFailure(operationName, duration, error);
+            throw error;
+        }
+    }
+    /**
+     * Create a timeout promise
+     * @param timeout Timeout in milliseconds
+     * @param message Error message
+     * @returns Promise that rejects after timeout
+     */
+    createTimeout(timeout, message) {
+        return new Promise((_, reject) => {
+            const timer = setTimeout(() => {
+                clearTimeout(timer);
+                reject(new TimeoutError(message || `Operation timed out after ${timeout}ms`, timeout));
+            }, timeout);
+        });
+    }
+    /**
+     * Create an abort signal for timeout
+     * @param timeout Timeout in milliseconds
+     * @returns AbortSignal
+     */
+    createAbortSignal(timeout) {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeout);
+        return controller.signal;
+    }
+    /**
+     * Execute multiple promises with timeout
+     * @param promises Array of promises
+     * @param timeout Timeout in milliseconds
+     * @returns Promise that resolves when first promise resolves or times out
+     */
+    async race(promises, timeout) {
+        const timeoutPromise = this.createTimeout(timeout);
+        return Promise.race([...promises, timeoutPromise]);
+    }
+    /**
+     * Delay execution for specified time
+     * @param delay Delay in milliseconds
+     * @returns Promise that resolves after delay
+     */
+    delay(delay) {
+        return new Promise(resolve => setTimeout(resolve, delay));
+    }
+    /**
+     * Set operation timeout
+     * @param operation Operation identifier
+     * @param timeout Timeout in milliseconds
+     */
+    setOperationTimeout(operation, timeout) {
+        this.operationTimeouts.set(operation, timeout);
+    }
+    /**
+     * Get operation timeout
+     * @param operation Operation identifier
+     * @returns Timeout in milliseconds or undefined
+     */
+    getOperationTimeout(operation) {
+        // Check operation-specific timeout
+        const operationTimeout = this.operationTimeouts.get(operation);
+        if (operationTimeout !== undefined) {
+            return operationTimeout;
+        }
+        // Fall back to global timeout
+        return this.config.global;
+    }
+    /**
+     * Record successful operation
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     */
+    recordSuccess(operation, duration) {
+        this.stats.totalOperations++;
+        this.stats.totalOperationTime += duration;
+        this.stats.averageOperationTime = this.stats.totalOperationTime / this.stats.totalOperations;
+        // Update per-operation stats
+        this.updateOperationStats(operation, duration, false);
+    }
+    /**
+     * Record timed out operation
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     */
+    recordTimeout(operation, duration) {
+        this.stats.totalOperations++;
+        this.stats.timedOutOperations++;
+        this.stats.totalOperationTime += duration;
+        this.stats.averageOperationTime = this.stats.totalOperationTime / this.stats.totalOperations;
+        this.stats.timeoutRate = this.stats.timedOutOperations / this.stats.totalOperations;
+        // Update per-operation stats
+        this.updateOperationStats(operation, duration, true);
+    }
+    /**
+     * Record failed operation (not timeout)
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     * @param error Error that occurred
+     */
+    recordFailure(operation, duration, error) {
+        this.stats.totalOperations++;
+        this.stats.totalOperationTime += duration;
+        this.stats.averageOperationTime = this.stats.totalOperationTime / this.stats.totalOperations;
+        // Update per-operation stats
+        this.updateOperationStats(operation, duration, false);
+    }
+    /**
+     * Update operation-specific statistics
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     * @param isTimeout Whether operation timed out
+     */
+    updateOperationStats(operation, duration, isTimeout) {
+        let opStats = this.stats.perOperationStats.get(operation);
+        if (!opStats) {
+            opStats = {
+                calls: 0,
+                timeouts: 0,
+                totalTime: 0,
+                averageTime: 0,
+            };
+            this.stats.perOperationStats.set(operation, opStats);
+        }
+        opStats.calls++;
+        if (isTimeout) {
+            opStats.timeouts++;
+        }
+        opStats.totalTime += duration;
+        opStats.averageTime = opStats.totalTime / opStats.calls;
+    }
+    /**
+     * Update timeout configuration
+     * @param config New configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        // Re-initialize operation timeouts
+        this.initialize();
+    }
+    /**
+     * Get timeout statistics
+     */
+    getStats() {
+        const perOperationStats = {};
+        for (const [operation, stats] of this.stats.perOperationStats) {
+            perOperationStats[operation] = {
+                calls: stats.calls,
+                timeouts: stats.timeouts,
+                averageTime: stats.averageTime,
+            };
+        }
+        return {
+            totalOperations: this.stats.totalOperations,
+            timedOutOperations: this.stats.timedOutOperations,
+            averageOperationTime: this.stats.averageOperationTime,
+            timeoutRate: this.stats.timeoutRate,
+            perOperationStats,
+        };
+    }
+    /**
+     * Reset timeout statistics
+     */
+    resetStats() {
+        this.stats = {
+            totalOperations: 0,
+            timedOutOperations: 0,
+            totalOperationTime: 0,
+            averageOperationTime: 0,
+            timeoutRate: 0,
+            perOperationStats: new Map(),
+        };
+    }
+    /**
+     * Health check for timeout manager
+     */
+    healthCheck() {
+        const healthy = true; // Timeout manager is always healthy
+        return {
+            healthy,
+            message: 'Timeout manager is operational',
+            details: {
+                name: this.name,
+                config: this.config,
+                operationTimeouts: Object.fromEntries(this.operationTimeouts),
+                statistics: this.getStats(),
+            },
+        };
+    }
+}

package/dist/esm/abstract/index.js

@@ -0,0 +1,11 @@
+export { BaseProtocol } from './BaseProtocol.js';
+export { BaseClient } from './BaseClient.js';
+export { BaseCircuitBreaker } from './BaseCircuitBreaker.js';
+export { BaseRetryStrategy } from './BaseRetryStrategy.js';
+export { BaseLoadBalancer } from './BaseLoadBalancer.js';
+export { BaseSerializer } from './BaseSerializer.js';
+export { BaseServiceDiscoverer } from './BaseServiceDiscoverer.js';
+export { BaseInterceptor } from './BaseInterceptor.js';
+export { BaseTimeoutManager } from './BaseTimeoutManager.js';
+export { BaseConnectionPool } from './BaseConnectionPool.js';
+export { BaseCompressionManager } from './BaseCompressionManager.js';

package/dist/esm/errors/CircuitBreakerError.js

@@ -0,0 +1,12 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Circuit breaker error - when circuit is open
+ */
+export class CircuitBreakerError extends CommunicationError {
+    constructor(details, cause) {
+        super(COMMUNICATION_ERROR_CODES.CIRCUIT_BREAKER_OPEN, 503, // Service Unavailable
+        details, cause);
+        this.name = 'CircuitBreakerError';
+    }
+}

package/dist/esm/errors/CommunicationError.js

@@ -0,0 +1,11 @@
+import { AppError } from "@naman_deep_singh/errors";
+/**
+ * Base communication error class
+ * Extends AppError from errors package
+ */
+export class CommunicationError extends AppError {
+    constructor(code, statusCode = 500, details, cause) {
+        super(code, statusCode, details, cause);
+        this.name = 'CommunicationError';
+    }
+}

package/dist/esm/errors/ConnectionError.js

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Connection error - when connection fails
+ */
+export class ConnectionError extends CommunicationError {
+    constructor(code = COMMUNICATION_ERROR_CODES.CONNECTION_ERROR, details, cause) {
+        super(code, 503, details, cause);
+        this.name = 'ConnectionError';
+    }
+}

package/dist/esm/errors/DiscoveryError.js

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Service discovery error
+ */
+export class DiscoveryError extends CommunicationError {
+    constructor(code = COMMUNICATION_ERROR_CODES.DISCOVERY_ERROR, details, cause) {
+        super(code, 503, details, cause); // 503 Service Unavailable
+        this.name = 'DiscoveryError';
+    }
+}

package/dist/esm/errors/LoadBalancerError.js

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Load balancer error - when load balancing fails
+ */
+export class LoadBalancerError extends CommunicationError {
+    constructor(code = COMMUNICATION_ERROR_CODES.LOAD_BALANCER_ERROR, details, cause) {
+        super(code, 503, details, cause);
+        this.name = 'LoadBalancerError';
+    }
+}

package/dist/esm/errors/ProtocolError.js

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Protocol error - when protocol communication fails
+ */
+export class ProtocolError extends CommunicationError {
+    constructor(code = COMMUNICATION_ERROR_CODES.PROTOCOL_ERROR, details, cause) {
+        super(code, 502, details, cause); // 502 Bad Gateway
+        this.name = 'ProtocolError';
+    }
+}

package/dist/esm/errors/RetryError.js

@@ -0,0 +1,12 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Retry exhausted error - when all retry attempts fail
+ */
+export class RetryError extends CommunicationError {
+    constructor(details, cause) {
+        super(COMMUNICATION_ERROR_CODES.RETRY_EXHAUSTED, 503, // Service Unavailable
+        details, cause);
+        this.name = 'RetryError';
+    }
+}

package/dist/esm/errors/SerializationError.js

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Serialization error - when serialization/deserialization fails
+ */
+export class SerializationError extends CommunicationError {
+    constructor(code = COMMUNICATION_ERROR_CODES.SERIALIZATION_ERROR, details, cause) {
+        super(code, 500, details, cause);
+        this.name = 'SerializationError';
+    }
+}

package/dist/esm/errors/ServiceUnavailableError.js

@@ -0,0 +1,11 @@
+import { ServiceUnavailableError as BaseServiceUnavailableError, } from '@naman_deep_singh/errors';
+/**
+ * Service unavailable error for communication layer
+ * Extends the existing ServiceUnavailableError
+ */
+export class ServiceUnavailableError extends BaseServiceUnavailableError {
+    constructor(details, cause) {
+        super(details, cause);
+        this.name = 'ServiceUnavailableError';
+    }
+}

package/dist/esm/errors/TimeoutError.js

@@ -0,0 +1,12 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+/**
+ * Timeout error - when operation times out
+ */
+export class TimeoutError extends CommunicationError {
+    constructor(details, cause) {
+        super(COMMUNICATION_ERROR_CODES.TIMEOUT_EXHAUSTED, 504, // Gateway Timeout
+        details, cause);
+        this.name = 'TimeoutError';
+    }
+}

package/dist/esm/errors/communicationErrorCodes.js

@@ -0,0 +1,32 @@
+/**
+ * Communication-specific error codes
+ * Extends the existing ERROR_CODES
+ */
+export const COMMUNICATION_ERROR_CODES = {
+    // Protocol errors
+    PROTOCOL_ERROR: 'Protocol communication failed',
+    HTTP_PROTOCOL_ERROR: 'HTTP protocol error occurred',
+    GRPC_PROTOCOL_ERROR: 'gRPC protocol error occurred',
+    WEBSOCKET_PROTOCOL_ERROR: 'WebSocket protocol error occurred',
+    // Discovery errors
+    DISCOVERY_ERROR: 'Service discovery failed',
+    SERVICE_NOT_FOUND: 'Service not found in registry',
+    NO_AVAILABLE_INSTANCES: 'No available service instances',
+    DISCOVERY_TIMEOUT: 'Service discovery timed out',
+    // Resilience errors
+    CIRCUIT_BREAKER_OPEN: 'Circuit breaker is open, request blocked',
+    CIRCUIT_BREAKER_ERROR: 'Circuit breaker encountered an error',
+    RETRY_EXHAUSTED: 'Retry attempts exhausted',
+    BULKHEAD_FULL: 'Bulkhead is full, request rejected',
+    TIMEOUT_EXHAUSTED: 'Operation timeout exceeded',
+    // Load balancing errors
+    LOAD_BALANCER_ERROR: 'Load balancing failed',
+    NO_HEALTHY_INSTANCES: 'No healthy instances available',
+    // Serialization errors
+    SERIALIZATION_ERROR: 'Serialization failed',
+    DESERIALIZATION_ERROR: 'Deserialization failed',
+    // Connection errors
+    CONNECTION_ERROR: 'Connection failed',
+    CONNECTION_TIMEOUT: 'Connection timeout',
+    CONNECTION_REFUSED: 'Connection refused',
+};

package/dist/esm/errors/index.js

@@ -0,0 +1,17 @@
+import { errorMessageRegistry } from "@naman_deep_singh/errors";
+import { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";
+// Register communication error messages with the global registry
+errorMessageRegistry.register(COMMUNICATION_ERROR_CODES);
+// Export error classes
+export { CircuitBreakerError } from "./CircuitBreakerError.js";
+export { CommunicationError } from "./CommunicationError.js";
+export { ConnectionError } from "./ConnectionError.js";
+export { DiscoveryError } from "./DiscoveryError.js";
+export { LoadBalancerError } from "./LoadBalancerError.js";
+export { ProtocolError } from "./ProtocolError.js";
+export { RetryError } from "./RetryError.js";
+export { SerializationError } from "./SerializationError.js";
+export { ServiceUnavailableError } from "./ServiceUnavailableError.js";
+export { TimeoutError } from "./TimeoutError.js";
+// Also export error codes for convenience
+export { COMMUNICATION_ERROR_CODES } from "./communicationErrorCodes.js";

package/dist/esm/index.js

@@ -0,0 +1,18 @@
+/**
+ * Communication Core Package
+ * @packageDocumentation
+ *
+ * Core interfaces and abstract implementations for service-to-service communication.
+ * This package provides the foundation for communication protocols, resilience patterns,
+ * service discovery, load balancing, and interceptors.
+ */
+// Core interfaces
+export * from './interfaces/index.js';
+// Abstract base implementations
+export * from './abstract/index.js';
+// Type definitions
+export * from './types/index.js';
+// Error classes
+export * from './errors/index.js';
+// Utilities (excluding ConnectionPoolConfig to avoid duplicate)
+export { TimeoutUtils, ConnectionPoolUtils, CompressionUtils, } from './utils.js';

package/dist/esm/interfaces/CircuitBreaker.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Circuit breaker interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/Client.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Client interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/Compression.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Compression interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/ConnectionPool.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Connection pool interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/Interceptor.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Interceptor interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/LoadBalancer.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/interfaces/Protocol.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Protocol interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/RetryStrategy.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Retry strategy interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/Serializer.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/interfaces/ServiceDiscovery.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Service discovery interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/Timeout.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Timeout interface for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/interfaces/index.js

@@ -0,0 +1,5 @@
+/**
+ * Interface definitions for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/types/config.js

@@ -0,0 +1,5 @@
+/**
+ * Configuration types for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/types/events.js

@@ -0,0 +1,5 @@
+/**
+ * Event types for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/types/request.js

@@ -0,0 +1,5 @@
+/**
+ * Request types and interfaces for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/types/response.js

@@ -0,0 +1,5 @@
+/**
+ * Response types and interfaces for communication layer
+ * @packageDocumentation
+ */
+export {};

package/dist/esm/types/service.js

@@ -0,0 +1,5 @@
+/**
+ * Service discovery and instance types
+ * @packageDocumentation
+ */
+export {};