grpc-resilient 1.0.1 → 1.1.0

package/dist/gateway/GatewayMetricsTracker.js

@@ -0,0 +1,135 @@
+/**
+ * Gateway gRPC Metrics Tracker
+ *
+ * Tracks gRPC client metrics for monitoring and OpenTelemetry integration.
+ * Designed specifically for API Gateway/Proxy scenarios.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new GatewayMetricsTracker();
+ *
+ * tracker.recordCallStart();
+ * const startTime = Date.now();
+ * // ... make call ...
+ * tracker.recordSuccess(Date.now() - startTime);
+ *
+ * console.log(tracker.getMetrics());
+ * console.log(`Success rate: ${tracker.getSuccessRate()}%`);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { GATEWAY_DEFAULT_METRICS } from './types.js';
+/**
+ * Metrics tracker for Gateway gRPC clients
+ *
+ * Thread-safe metrics collection with:
+ * - Call counting (total, success, failure)
+ * - Latency tracking (min, max, average)
+ * - Retry counting
+ * - Success rate calculation
+ */
+export class GatewayMetricsTracker {
+    metrics;
+    latencySum = 0;
+    constructor() {
+        this.metrics = { ...GATEWAY_DEFAULT_METRICS, lastResetAt: new Date() };
+    }
+    /**
+     * Record a call start
+     *
+     * Call this at the beginning of each gRPC call attempt.
+     */
+    recordCallStart() {
+        this.metrics.totalCalls++;
+    }
+    /**
+     * Record a successful call with latency
+     *
+     * @param latencyMs - The call latency in milliseconds
+     */
+    recordSuccess(latencyMs) {
+        this.metrics.successfulCalls++;
+        this.updateLatency(latencyMs);
+    }
+    /**
+     * Record a failed call
+     *
+     * Call this when a gRPC call fails after all retry attempts.
+     */
+    recordFailure() {
+        this.metrics.failedCalls++;
+    }
+    /**
+     * Record a retry attempt
+     *
+     * Call this for each retry attempt (not the initial attempt).
+     */
+    recordRetry() {
+        this.metrics.totalRetries++;
+    }
+    /**
+     * Update latency metrics
+     */
+    updateLatency(latencyMs) {
+        this.latencySum += latencyMs;
+        if (latencyMs > this.metrics.maxLatencyMs) {
+            this.metrics.maxLatencyMs = latencyMs;
+        }
+        if (latencyMs < this.metrics.minLatencyMs) {
+            this.metrics.minLatencyMs = latencyMs;
+        }
+        this.metrics.avgLatencyMs = Math.round(this.latencySum / this.metrics.successfulCalls);
+    }
+    /**
+     * Get current metrics snapshot
+     *
+     * Returns a copy of the current metrics state.
+     *
+     * @returns Current metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Reset all metrics to initial values
+     *
+     * Useful for periodic metric collection windows.
+     */
+    reset() {
+        this.metrics = { ...GATEWAY_DEFAULT_METRICS, lastResetAt: new Date() };
+        this.latencySum = 0;
+    }
+    /**
+     * Get success rate as a percentage (0-100)
+     *
+     * @returns Success rate percentage
+     */
+    getSuccessRate() {
+        if (this.metrics.totalCalls === 0) {
+            return 100;
+        }
+        return Math.round((this.metrics.successfulCalls / this.metrics.totalCalls) * 100);
+    }
+    /**
+     * Get failure rate as a percentage (0-100)
+     *
+     * @returns Failure rate percentage
+     */
+    getFailureRate() {
+        if (this.metrics.totalCalls === 0) {
+            return 0;
+        }
+        return Math.round((this.metrics.failedCalls / this.metrics.totalCalls) * 100);
+    }
+    /**
+     * Check if the client is healthy based on success rate
+     *
+     * @param threshold - Minimum success rate to be considered healthy (default: 90)
+     * @returns true if success rate is above threshold
+     */
+    isHealthy(threshold = 90) {
+        return this.getSuccessRate() >= threshold;
+    }
+}
+//# sourceMappingURL=GatewayMetricsTracker.js.map

package/dist/gateway/GatewayMetricsTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayMetricsTracker.js","sourceRoot":"","sources":["../../src/gateway/GatewayMetricsTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAqB;IACxB,OAAO,CAAuB;IAC9B,UAAU,GAAG,CAAC,CAAC;IAEvB;QACE,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,uBAAuB,EAAE,WAAW,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,SAAiB;QAC7B,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,WAAW;QACT,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,SAAiB;QACrC,IAAI,CAAC,UAAU,IAAI,SAAS,CAAC;QAE7B,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;QACxC,CAAC;QACD,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;QACxC,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;OAMG;IACH,UAAU;QACR,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,uBAAuB,EAAE,WAAW,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;QACvE,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;IACpF,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;IAChF,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,SAAS,GAAG,EAAE;QACtB,OAAO,IAAI,CAAC,cAAc,EAAE,IAAI,SAAS,CAAC;IAC5C,CAAC;CACF"}

package/dist/gateway/GatewayRetryHandler.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Gateway gRPC Retry Handler
+ *
+ * Handles retry logic for gRPC calls with:
+ * - Exponential backoff
+ * - Jitter to prevent thundering herd
+ * - Retryable error detection
+ * - Connection error detection
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   isRetryableError,
+ *   isConnectionError,
+ *   calculateBackoffDelay,
+ *   sleep,
+ * } from 'grpc-resilient/gateway';
+ *
+ * if (isRetryableError(error)) {
+ *   const delay = calculateBackoffDelay(1000, attempt);
+ *   await sleep(delay);
+ *   // retry...
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Check if the error is retryable based on gRPC status code
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable
+ */
+export declare function isRetryableError(error: Error): boolean;
+/**
+ * Check if the error indicates a connection problem
+ *
+ * Connection errors trigger reconnection logic in addition to retry.
+ *
+ * @param error - The error to check
+ * @returns true if the error indicates a connection issue
+ */
+export declare function isConnectionError(error: Error): boolean;
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * Uses the formula: delay = baseDelay * 2^attempt + jitter
+ * Where jitter is +/- 25% of the exponential delay.
+ *
+ * This prevents the "thundering herd" problem where many clients
+ * retry at exactly the same time after a failure.
+ *
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param attempt - Current attempt number (0-indexed)
+ * @param maxDelayMs - Maximum delay cap (optional, default: 30000ms)
+ * @returns Calculated delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // attempt 0: ~1000ms (base)
+ * // attempt 1: ~2000ms
+ * // attempt 2: ~4000ms
+ * // attempt 3: ~8000ms
+ * // etc. (capped at maxDelayMs)
+ * const delay = calculateBackoffDelay(1000, attempt, 30000);
+ * ```
+ */
+export declare function calculateBackoffDelay(baseDelayMs: number, attempt: number, maxDelayMs?: number): number;
+/**
+ * Sleep for a specified duration
+ *
+ * Promisified setTimeout for use with async/await.
+ *
+ * @param ms - Duration to sleep in milliseconds
+ * @returns Promise that resolves after the specified duration
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Get human-readable error description for logging
+ *
+ * @param error - The gRPC error
+ * @returns Human-readable description
+ */
+export declare function getErrorDescription(error: Error): string;
+//# sourceMappingURL=GatewayRetryHandler.d.ts.map

package/dist/gateway/GatewayRetryHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayRetryHandler.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayRetryHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAmBH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAGtD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAGvD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,SAAQ,GACjB,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAwBxD"}

package/dist/gateway/GatewayRetryHandler.js

@@ -0,0 +1,137 @@
+/**
+ * Gateway gRPC Retry Handler
+ *
+ * Handles retry logic for gRPC calls with:
+ * - Exponential backoff
+ * - Jitter to prevent thundering herd
+ * - Retryable error detection
+ * - Connection error detection
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   isRetryableError,
+ *   isConnectionError,
+ *   calculateBackoffDelay,
+ *   sleep,
+ * } from 'grpc-resilient/gateway';
+ *
+ * if (isRetryableError(error)) {
+ *   const delay = calculateBackoffDelay(1000, attempt);
+ *   await sleep(delay);
+ *   // retry...
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import * as grpc from '@grpc/grpc-js';
+/**
+ * gRPC status codes that are considered retryable
+ *
+ * - UNAVAILABLE: Server is temporarily unavailable
+ * - DEADLINE_EXCEEDED: Call timed out
+ * - RESOURCE_EXHAUSTED: Rate limiting or resource constraints
+ * - ABORTED: Operation was aborted, can be retried
+ */
+const RETRYABLE_CODES = [
+    grpc.status.UNAVAILABLE,
+    grpc.status.DEADLINE_EXCEEDED,
+    grpc.status.RESOURCE_EXHAUSTED,
+    grpc.status.ABORTED,
+];
+/**
+ * Check if the error is retryable based on gRPC status code
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable
+ */
+export function isRetryableError(error) {
+    const grpcError = error;
+    return RETRYABLE_CODES.includes(grpcError.code);
+}
+/**
+ * Check if the error indicates a connection problem
+ *
+ * Connection errors trigger reconnection logic in addition to retry.
+ *
+ * @param error - The error to check
+ * @returns true if the error indicates a connection issue
+ */
+export function isConnectionError(error) {
+    const grpcError = error;
+    return grpcError.code === grpc.status.UNAVAILABLE;
+}
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * Uses the formula: delay = baseDelay * 2^attempt + jitter
+ * Where jitter is +/- 25% of the exponential delay.
+ *
+ * This prevents the "thundering herd" problem where many clients
+ * retry at exactly the same time after a failure.
+ *
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param attempt - Current attempt number (0-indexed)
+ * @param maxDelayMs - Maximum delay cap (optional, default: 30000ms)
+ * @returns Calculated delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // attempt 0: ~1000ms (base)
+ * // attempt 1: ~2000ms
+ * // attempt 2: ~4000ms
+ * // attempt 3: ~8000ms
+ * // etc. (capped at maxDelayMs)
+ * const delay = calculateBackoffDelay(1000, attempt, 30000);
+ * ```
+ */
+export function calculateBackoffDelay(baseDelayMs, attempt, maxDelayMs = 30000) {
+    const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+    // Add jitter (+/- 25% of the delay) to prevent thundering herd
+    const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
+    const delay = exponentialDelay + jitter;
+    return Math.min(delay, maxDelayMs);
+}
+/**
+ * Sleep for a specified duration
+ *
+ * Promisified setTimeout for use with async/await.
+ *
+ * @param ms - Duration to sleep in milliseconds
+ * @returns Promise that resolves after the specified duration
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Get human-readable error description for logging
+ *
+ * @param error - The gRPC error
+ * @returns Human-readable description
+ */
+export function getErrorDescription(error) {
+    const grpcError = error;
+    const codeDescriptions = {
+        [grpc.status.OK]: 'OK',
+        [grpc.status.CANCELLED]: 'Cancelled',
+        [grpc.status.UNKNOWN]: 'Unknown error',
+        [grpc.status.INVALID_ARGUMENT]: 'Invalid argument',
+        [grpc.status.DEADLINE_EXCEEDED]: 'Deadline exceeded',
+        [grpc.status.NOT_FOUND]: 'Not found',
+        [grpc.status.ALREADY_EXISTS]: 'Already exists',
+        [grpc.status.PERMISSION_DENIED]: 'Permission denied',
+        [grpc.status.RESOURCE_EXHAUSTED]: 'Resource exhausted',
+        [grpc.status.FAILED_PRECONDITION]: 'Failed precondition',
+        [grpc.status.ABORTED]: 'Aborted',
+        [grpc.status.OUT_OF_RANGE]: 'Out of range',
+        [grpc.status.UNIMPLEMENTED]: 'Unimplemented',
+        [grpc.status.INTERNAL]: 'Internal error',
+        [grpc.status.UNAVAILABLE]: 'Service unavailable',
+        [grpc.status.DATA_LOSS]: 'Data loss',
+        [grpc.status.UNAUTHENTICATED]: 'Unauthenticated',
+    };
+    const description = codeDescriptions[grpcError.code] ?? 'Unknown';
+    return `${description} (code: ${grpcError.code})`;
+}
+//# sourceMappingURL=GatewayRetryHandler.js.map

package/dist/gateway/GatewayRetryHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayRetryHandler.js","sourceRoot":"","sources":["../../src/gateway/GatewayRetryHandler.ts"],"names":[],"mappings":"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"}

package/dist/gateway/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Gateway gRPC Client Module
+ *
+ * Provides resilient gRPC client infrastructure for API Gateway/Proxy services.
+ *
+ * Use this module when building:
+ * - API Gateways that proxy requests to microservices
+ * - BFF (Backend for Frontend) services
+ * - Service mesh proxies
+ * - Load balancers with gRPC support
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   GatewayGrpcClient,
+ *   type GatewayClientConfig,
+ *   type GatewayCallOptions,
+ *   type GatewayLogger,
+ * } from 'grpc-resilient/gateway';
+ *
+ * class AuthServiceProxy extends GatewayGrpcClient<AuthClient> {
+ *   constructor(config: GatewayClientConfig, logger: GatewayLogger) {
+ *     super(config, logger);
+ *   }
+ *
+ *   async validateToken(request: ValidateRequest) {
+ *     return this.callWithRetry('ValidateToken', request);
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ * @module gateway
+ */
+export { GatewayGrpcClient } from './GatewayGrpcClient.js';
+export { GatewayMetricsTracker } from './GatewayMetricsTracker.js';
+export { createGatewayCredentials, validateTlsConfig } from './GatewayCredentialsProvider.js';
+export { isRetryableError, isConnectionError, calculateBackoffDelay, sleep, getErrorDescription, } from './GatewayRetryHandler.js';
+export { GatewayConnectionState, GATEWAY_DEFAULT_CONFIG, GATEWAY_DEFAULT_METRICS, type GatewayClientConfig, type GatewayCallOptions, type GatewayServiceHealth, type GatewayClientMetrics, type GatewayLogger, type TlsCredentialsOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAC9F,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,EACL,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC"}

package/dist/gateway/index.js

@@ -0,0 +1,43 @@
+/**
+ * Gateway gRPC Client Module
+ *
+ * Provides resilient gRPC client infrastructure for API Gateway/Proxy services.
+ *
+ * Use this module when building:
+ * - API Gateways that proxy requests to microservices
+ * - BFF (Backend for Frontend) services
+ * - Service mesh proxies
+ * - Load balancers with gRPC support
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   GatewayGrpcClient,
+ *   type GatewayClientConfig,
+ *   type GatewayCallOptions,
+ *   type GatewayLogger,
+ * } from 'grpc-resilient/gateway';
+ *
+ * class AuthServiceProxy extends GatewayGrpcClient<AuthClient> {
+ *   constructor(config: GatewayClientConfig, logger: GatewayLogger) {
+ *     super(config, logger);
+ *   }
+ *
+ *   async validateToken(request: ValidateRequest) {
+ *     return this.callWithRetry('ValidateToken', request);
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ * @module gateway
+ */
+// Main client class
+export { GatewayGrpcClient } from './GatewayGrpcClient.js';
+// Supporting modules
+export { GatewayMetricsTracker } from './GatewayMetricsTracker.js';
+export { createGatewayCredentials, validateTlsConfig } from './GatewayCredentialsProvider.js';
+export { isRetryableError, isConnectionError, calculateBackoffDelay, sleep, getErrorDescription, } from './GatewayRetryHandler.js';
+// Types
+export { GatewayConnectionState, GATEWAY_DEFAULT_CONFIG, GATEWAY_DEFAULT_METRICS, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/gateway/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,oBAAoB;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,qBAAqB;AACrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAC9F,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,EACL,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC,QAAQ;AACR,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,GAOxB,MAAM,YAAY,CAAC"}

package/dist/gateway/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Gateway gRPC Client Types
+ *
+ * Type definitions for API Gateway/Proxy gRPC client infrastructure.
+ * Designed for services that act as reverse proxies to multiple backend services.
+ *
+ * @packageDocumentation
+ */
+import type { Options as ProtoLoaderOptions } from '@grpc/proto-loader';
+/**
+ * Connection state for gateway clients
+ * @category Gateway
+ */
+export declare enum GatewayConnectionState {
+    /** Not connected to the backend service */
+    DISCONNECTED = "DISCONNECTED",
+    /** Initial connection attempt in progress */
+    CONNECTING = "CONNECTING",
+    /** Successfully connected and ready */
+    CONNECTED = "CONNECTED",
+    /** Reconnecting after connection loss */
+    RECONNECTING = "RECONNECTING"
+}
+/**
+ * Metrics for gateway gRPC clients (OpenTelemetry-compatible)
+ * @category Gateway
+ */
+export interface GatewayClientMetrics {
+    /** Total number of calls made */
+    totalCalls: number;
+    /** Number of successful calls */
+    successfulCalls: number;
+    /** Number of failed calls */
+    failedCalls: number;
+    /** Total retry attempts */
+    totalRetries: number;
+    /** Average latency in milliseconds */
+    avgLatencyMs: number;
+    /** Maximum latency recorded */
+    maxLatencyMs: number;
+    /** Minimum latency recorded */
+    minLatencyMs: number;
+    /** Last metrics reset timestamp */
+    lastResetAt: Date;
+}
+/**
+ * Configuration for gateway gRPC client
+ * @category Gateway
+ */
+export interface GatewayClientConfig {
+    /** Service name for logging and metrics */
+    serviceName: string;
+    /** gRPC server URL (host:port) */
+    grpcUrl: string;
+    /** Proto file name (relative to protosPath) */
+    protoFile: string;
+    /** Package name in proto file */
+    packageName: string;
+    /** Service class name in proto file */
+    serviceClassName: string;
+    /** Absolute path to protos directory */
+    protosPath: string;
+    /** Call timeout in milliseconds @default 5000 */
+    timeoutMs?: number;
+    /** Number of retry attempts @default 3 */
+    retryCount?: number;
+    /** Base delay between retries in ms @default 1000 */
+    retryDelayMs?: number;
+    /** Maximum reconnection attempts @default Infinity */
+    maxReconnectAttempts?: number;
+    /** Maximum delay between reconnects in ms @default 30000 */
+    maxReconnectDelayMs?: number;
+    /** Initial delay for reconnection in ms @default 1000 */
+    initialReconnectDelayMs?: number;
+    /** Custom proto loader options */
+    protoOptions?: ProtoLoaderOptions;
+    /** Use TLS for connection @default false */
+    useTls?: boolean;
+    /** CA certificate path for TLS */
+    tlsCaCertPath?: string;
+    /** Client certificate path for mutual TLS */
+    tlsClientCertPath?: string;
+    /** Client key path for mutual TLS */
+    tlsClientKeyPath?: string;
+    /** Keepalive time in ms @default 30000 */
+    keepaliveTimeMs?: number;
+    /** Keepalive timeout in ms @default 10000 */
+    keepaliveTimeoutMs?: number;
+}
+/**
+ * Health status for gateway client
+ * @category Gateway
+ */
+export interface GatewayServiceHealth {
+    /** Current connection state */
+    state: GatewayConnectionState;
+    /** Whether the service is healthy and connected */
+    healthy: boolean;
+    /** Last recorded latency in milliseconds */
+    latencyMs: number;
+    /** Timestamp of last health check */
+    lastCheck: Date;
+    /** Timestamp of last successful connection */
+    lastConnectedAt: Date | null;
+    /** Timestamp of last error */
+    lastErrorAt: Date | null;
+    /** Last error message if any */
+    error?: string;
+    /** Number of reconnection attempts */
+    reconnectAttempts: number;
+    /** Current metrics snapshot */
+    metrics: GatewayClientMetrics;
+}
+/**
+ * Per-call options for gateway gRPC calls
+ * @category Gateway
+ */
+export interface GatewayCallOptions {
+    /** Timeout override for this specific call (in milliseconds) */
+    timeoutMs?: number;
+    /** Locale for i18n (sent via gRPC metadata as accept-language) */
+    locale?: string;
+    /** Client URL for callbacks (sent via gRPC metadata as x-client-url) */
+    clientUrl?: string;
+    /** Skip retry for this call */
+    skipRetry?: boolean;
+    /** Additional metadata to send with the call */
+    metadata?: Record<string, string>;
+}
+/**
+ * Logger interface for gateway clients
+ * @category Gateway
+ */
+export interface GatewayLogger {
+    info(obj: object, msg?: string): void;
+    warn(obj: object, msg?: string): void;
+    error(obj: object, msg?: string): void;
+    debug(obj: object, msg?: string): void;
+}
+/**
+ * TLS/SSL credential options
+ * @category Gateway
+ */
+export interface TlsCredentialsOptions {
+    /** Service name for logging */
+    serviceName: string;
+    /** Use TLS encryption */
+    useTls: boolean;
+    /** CA certificate path */
+    caCertPath?: string;
+    /** Client certificate path (for mutual TLS) */
+    clientCertPath?: string;
+    /** Client key path (for mutual TLS) */
+    clientKeyPath?: string;
+    /** Logger instance */
+    logger: GatewayLogger;
+}
+/**
+ * Default configuration values for gateway clients
+ * @category Gateway
+ */
+export declare const GATEWAY_DEFAULT_CONFIG: {
+    readonly timeoutMs: 5000;
+    readonly retryCount: 3;
+    readonly retryDelayMs: 1000;
+    readonly maxReconnectAttempts: number;
+    readonly maxReconnectDelayMs: 30000;
+    readonly initialReconnectDelayMs: 1000;
+    readonly useTls: false;
+    readonly keepaliveTimeMs: 30000;
+    readonly keepaliveTimeoutMs: 10000;
+};
+/**
+ * Default metrics values
+ * @category Gateway
+ */
+export declare const GATEWAY_DEFAULT_METRICS: GatewayClientMetrics;
+//# sourceMappingURL=types.d.ts.map

package/dist/gateway/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/gateway/types.ts"],"names":[],"mappings":"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"}