grpc-resilient 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,29 +1,47 @@
-## [1.0.1](https://github.com/berkeerdo/grpc-resilient/compare/v1.0.0...v1.0.1) (2026-01-11)
+## [1.1.0](https://github.com/berkeerdo/grpc-resilient/compare/v1.0.1...v1.1.0) (2026-01-11)
 
-### Bug Fixes
+### Features
 
-* update peer dependencies to support newer versions ([898aabd](https://github.com/berkeerdo/grpc-resilient/commit/898aabd94328c900021da88b7ddbc941d9049e17))
+* **gateway:** add gateway grpc client for api gateway support ([30b560e](https://github.com/berkeerdo/grpc-resilient/commit/30b560eb800f78f2929493a6b4825b91418ef6e4))
 
-## 1.0.0 (2026-01-11)
+# Changelog
 
-### Features
+All notable changes to this project will be documented in this file.
 
-* initial release ([e044636](https://github.com/berkeerdo/grpc-resilient/commit/e044636fbbc66e1ea351e78219eda7fbed5dcb3a))
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 1.0.0 (2026-01-11)
+## [1.1.0] - 2026-01-11
 
-### Features
+### Added
 
-* resilient grpc client with retry, reconnection and fallback cache ([00c0ee1](https://github.com/berkeerdo/grpc-resilient/commit/00c0ee1015905c35656429f4a6a40147ebc3a000))
+- **Gateway Client Module** - New `grpc-resilient/gateway` subpath export for API Gateways and BFF services
+  - `GatewayGrpcClient` - Abstract base class for gateway/proxy clients
+  - `GatewayMetricsTracker` - Metrics tracking for gateway clients
+  - `GatewayCredentialsProvider` - TLS/mTLS credential handling with security validation
+  - `GatewayRetryHandler` - Retry logic with exponential backoff and jitter
+- Full TLS/mTLS support for gateway clients
+  - One-way TLS with system or custom CA
+  - Mutual TLS (mTLS) with client certificates
+  - Secure certificate path validation
+- Additional gRPC metadata support for gateway calls
+- Keepalive configuration options
+- `validateTlsConfig()` utility for validating TLS configuration
+- `getErrorDescription()` utility for human-readable error messages
+- Comprehensive documentation with gateway examples
 
-# Changelog
+### Changed
 
-All notable changes to this project will be documented in this file.
+- Updated package description to include API gateway support
+- Added gateway-related keywords for npm discoverability
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.0.1] - 2026-01-11
+
+### Fixed
+
+- Peer dependency version constraints (`>=1.9.0` for grpc-js, `>=0.7.0` for proto-loader)
 
-## [1.0.0] - 2025-01-11
+## [1.0.0] - 2026-01-11
 
 ### Added
 

package/README.md

@@ -5,18 +5,22 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 
-Production-ready gRPC client for Node.js with built-in resilience patterns.
+Production-ready gRPC client for Node.js with built-in resilience patterns. Perfect for microservices and API gateways.
 
 ## Features
 
 - **Lazy Connection** - Connects on first use, not at startup
 - **Auto-Reconnect** - Exponential backoff reconnection strategy
-- **Retry Logic** - Configurable retry with exponential backoff
+- **Retry Logic** - Configurable retry with jitter to prevent thundering herd
 - **Fallback Cache** - Graceful degradation when service is unavailable
 - **Metrics** - OpenTelemetry-compatible metrics tracking
 - **Health Checks** - Built-in health status reporting
+- **TLS/mTLS** - Full TLS support including mutual TLS
 - **TypeScript** - Full type safety with generics support
 - **ESM** - Native ES modules support
+- **Two Client Types**:
+  - `ResilientGrpcClient` - For microservice-to-microservice communication
+  - `GatewayGrpcClient` - For API Gateways and BFF services
 
 ## Installation
 
@@ -24,7 +28,23 @@ Production-ready gRPC client for Node.js with built-in resilience patterns.
 npm install grpc-resilient @grpc/grpc-js @grpc/proto-loader
 ```
 
-## Quick Start
+## Table of Contents
+
+- [Microservice Client](#microservice-client) - Service-to-service communication
+- [Gateway Client](#gateway-client) - API Gateway / Proxy pattern
+- [Configuration](#configuration)
+- [Health & Metrics](#health--metrics)
+- [Events](#events)
+- [TLS Configuration](#tls-configuration)
+- [Best Practices](#best-practices)
+
+---
+
+## Microservice Client
+
+Use `ResilientGrpcClient` for backend service-to-service communication with fallback cache support.
+
+### Quick Start
 
 ```typescript
 import { ResilientGrpcClient, type GrpcLogger } from 'grpc-resilient';
@@ -74,8 +94,200 @@ const client = UserServiceClient.getInstance('localhost:50051', logger);
 const user = await client.getUser('123');
 ```
 
+### Fallback Cache
+
+Enable graceful degradation when the backend service is temporarily unavailable:
+
+```typescript
+class UserServiceClient extends ResilientGrpcClient {
+  constructor(grpcUrl: string, logger: GrpcLogger) {
+    super({
+      serviceName: 'UserService',
+      grpcUrl,
+      protoFile: 'user.proto',
+      packageName: 'myapp.user',
+      serviceClassName: 'UserService',
+      protosPath: fileURLToPath(new URL('./protos', import.meta.url)),
+      logger,
+      // Fallback cache configuration
+      enableFallbackCache: true,
+      fallbackCacheTtlMs: 60000,  // Cache for 1 minute
+      maxCacheSize: 100,          // Max 100 entries
+    });
+  }
+
+  async getUser(userId: string) {
+    return this.call('GetUser', { userId }, {
+      cacheKey: `user:${userId}`,  // Custom cache key
+    });
+  }
+}
+```
+
+### Call Options
+
+```typescript
+// Per-call options
+const user = await client.call('GetUser', { userId: '123' }, {
+  timeoutMs: 10000,        // Override timeout
+  locale: 'en-US',         // Send locale in metadata
+  skipRetry: true,         // Disable retry for this call
+  cacheKey: 'user:123',    // Custom cache key
+  skipCache: false,        // Use cache if available
+});
+```
+
+---
+
+## Gateway Client
+
+Use `GatewayGrpcClient` for API Gateways, BFF (Backend for Frontend) services, or reverse proxies.
+
+### Quick Start
+
+```typescript
+import {
+  GatewayGrpcClient,
+  type GatewayClientConfig,
+  type GatewayCallOptions,
+  type GatewayLogger,
+} from 'grpc-resilient/gateway';
+import * as grpc from '@grpc/grpc-js';
+
+// Define your typed client interface (optional but recommended)
+interface AuthClient extends grpc.Client {
+  ValidateToken: grpc.MethodDefinition<ValidateRequest, ValidateResponse>;
+  RefreshToken: grpc.MethodDefinition<RefreshRequest, RefreshResponse>;
+}
+
+class AuthServiceProxy extends GatewayGrpcClient<AuthClient> {
+  private static instance: AuthServiceProxy | null = null;
+
+  private constructor(config: GatewayClientConfig, logger: GatewayLogger) {
+    super(config, logger);
+  }
+
+  static getInstance(grpcUrl: string, logger: GatewayLogger): AuthServiceProxy {
+    if (!AuthServiceProxy.instance) {
+      AuthServiceProxy.instance = new AuthServiceProxy(
+        {
+          serviceName: 'AuthService',
+          grpcUrl,
+          protoFile: 'auth.proto',
+          packageName: 'auth',
+          serviceClassName: 'AuthService',
+          protosPath: '/app/protos',
+          timeoutMs: 5000,
+          retryCount: 2,
+        },
+        logger
+      );
+    }
+    return AuthServiceProxy.instance;
+  }
+
+  async validateToken(token: string, options?: GatewayCallOptions) {
+    return this.callWithRetry<ValidateRequest, ValidateResponse>(
+      'ValidateToken',
+      { token },
+      options
+    );
+  }
+
+  async refreshToken(refreshToken: string, options?: GatewayCallOptions) {
+    return this.callWithRetry<RefreshRequest, RefreshResponse>(
+      'RefreshToken',
+      { refreshToken },
+      options
+    );
+  }
+}
+
+// Usage in Express/Fastify route handler
+app.post('/api/auth/validate', async (req, res) => {
+  const client = AuthServiceProxy.getInstance(process.env.AUTH_SERVICE_URL, logger);
+
+  const result = await client.validateToken(req.headers.authorization, {
+    locale: req.headers['accept-language'],
+    clientUrl: req.headers['x-forwarded-for'],
+    metadata: {
+      'x-request-id': req.id,
+    },
+  });
+
+  res.json(result);
+});
+```
+
+### Multiple Backend Services
+
+```typescript
+// Gateway managing multiple backend services
+class GatewayClients {
+  private static authClient: AuthServiceProxy;
+  private static userClient: UserServiceProxy;
+  private static orderClient: OrderServiceProxy;
+
+  static getAuthClient(logger: GatewayLogger): AuthServiceProxy {
+    if (!this.authClient) {
+      this.authClient = AuthServiceProxy.getInstance(
+        process.env.AUTH_SERVICE_URL!,
+        logger
+      );
+    }
+    return this.authClient;
+  }
+
+  static getUserClient(logger: GatewayLogger): UserServiceProxy {
+    if (!this.userClient) {
+      this.userClient = UserServiceProxy.getInstance(
+        process.env.USER_SERVICE_URL!,
+        logger
+      );
+    }
+    return this.userClient;
+  }
+
+  static getOrderClient(logger: GatewayLogger): OrderServiceProxy {
+    if (!this.orderClient) {
+      this.orderClient = OrderServiceProxy.getInstance(
+        process.env.ORDER_SERVICE_URL!,
+        logger
+      );
+    }
+    return this.orderClient;
+  }
+
+  // Graceful shutdown
+  static closeAll(): void {
+    this.authClient?.close();
+    this.userClient?.close();
+    this.orderClient?.close();
+  }
+}
+```
+
+### Gateway Call Options
+
+```typescript
+const result = await client.callWithRetry('GetUser', request, {
+  timeoutMs: 10000,           // Override timeout
+  locale: 'tr-TR',            // Forwarded to backend via accept-language header
+  clientUrl: '192.168.1.1',   // Client IP for logging (x-client-url header)
+  skipRetry: false,           // Enable/disable retry
+  metadata: {                 // Additional gRPC metadata
+    'x-request-id': 'abc123',
+    'x-correlation-id': 'xyz789',
+  },
+});
+```
+
+---
+
 ## Configuration
 
+### Microservice Client Options
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `serviceName` | string | **required** | Name for logging and metrics |
@@ -96,8 +308,35 @@ const user = await client.getUser('123');
 | `fallbackCacheTtlMs` | number | 60000 | Cache TTL in milliseconds |
 | `maxCacheSize` | number | 100 | Maximum cache entries |
 
+### Gateway Client Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceName` | string | **required** | Name for logging and metrics |
+| `grpcUrl` | string | **required** | gRPC server URL (host:port) |
+| `protoFile` | string | **required** | Proto file name |
+| `packageName` | string | **required** | Package name in proto file |
+| `serviceClassName` | string | **required** | Service class name in proto |
+| `protosPath` | string | **required** | Absolute path to protos directory |
+| `timeoutMs` | number | 5000 | Call timeout in milliseconds |
+| `retryCount` | number | 3 | Number of retry attempts |
+| `retryDelayMs` | number | 1000 | Base delay between retries |
+| `maxReconnectAttempts` | number | Infinity | Max reconnection attempts |
+| `maxReconnectDelayMs` | number | 30000 | Max reconnection delay |
+| `initialReconnectDelayMs` | number | 1000 | Initial reconnection delay |
+| `useTls` | boolean | false | Use TLS for connection |
+| `tlsCaCertPath` | string | undefined | CA certificate path |
+| `tlsClientCertPath` | string | undefined | Client cert path (mTLS) |
+| `tlsClientKeyPath` | string | undefined | Client key path (mTLS) |
+| `keepaliveTimeMs` | number | 30000 | Keepalive interval |
+| `keepaliveTimeoutMs` | number | 10000 | Keepalive timeout |
+
+---
+
 ## Health & Metrics
 
+Both client types provide health and metrics APIs:
+
 ```typescript
 // Get health status
 const health = client.getHealth();
@@ -112,7 +351,7 @@ console.log(health);
 //   metrics: { ... }
 // }
 
-// Get metrics for OpenTelemetry
+// Get metrics for OpenTelemetry / Prometheus
 const metrics = client.getMetrics();
 // {
 //   totalCalls: 150,
@@ -120,15 +359,45 @@ const metrics = client.getMetrics();
 //   failedCalls: 2,
 //   totalRetries: 5,
 //   avgLatencyMs: 42,
-//   ...
+//   minLatencyMs: 12,
+//   maxLatencyMs: 234,
+//   lastResetAt: Date
 // }
 
-// Reset metrics
+// Check connection status
+if (client.isConnected()) {
+  // Safe to make calls
+}
+
+// Reset metrics (useful for periodic collection)
 client.resetMetrics();
 ```
 
+### Health Check Endpoint Example
+
+```typescript
+app.get('/health/grpc', (req, res) => {
+  const clients = {
+    auth: GatewayClients.getAuthClient(logger).getHealth(),
+    user: GatewayClients.getUserClient(logger).getHealth(),
+    order: GatewayClients.getOrderClient(logger).getHealth(),
+  };
+
+  const allHealthy = Object.values(clients).every(c => c.healthy);
+
+  res.status(allHealthy ? 200 : 503).json({
+    status: allHealthy ? 'healthy' : 'degraded',
+    services: clients,
+  });
+});
+```
+
+---
+
 ## Events
 
+Both client types emit events for connection lifecycle:
+
 ```typescript
 client.on('connected', () => {
   console.log('gRPC client connected');
@@ -147,19 +416,140 @@ client.on('connecting', () => {
 });
 ```
 
-## Call Options
+---
+
+## TLS Configuration
+
+### One-way TLS (Server Verification)
 
 ```typescript
-// Per-call options
-const user = await client.call('GetUser', { userId: '123' }, {
-  timeoutMs: 10000,        // Override timeout
-  locale: 'en-US',         // Send locale in metadata
-  skipRetry: true,         // Disable retry for this call
-  cacheKey: 'user:123',    // Custom cache key
-  skipCache: false,        // Use cache if available
+// Using system CA certificates
+const client = new MyServiceClient({
+  serviceName: 'MyService',
+  grpcUrl: 'myservice.example.com:443',
+  protoFile: 'service.proto',
+  packageName: 'myapp',
+  serviceClassName: 'MyService',
+  protosPath: '/app/protos',
+  useTls: true,  // Uses system CA
+}, logger);
+
+// Using custom CA certificate
+const client = new MyServiceClient({
+  ...config,
+  useTls: true,
+  tlsCaCertPath: '/etc/certs/ca.pem',
+}, logger);
+```
+
+### Mutual TLS (mTLS)
+
+```typescript
+const client = new MyServiceClient({
+  serviceName: 'MyService',
+  grpcUrl: 'myservice.example.com:443',
+  protoFile: 'service.proto',
+  packageName: 'myapp',
+  serviceClassName: 'MyService',
+  protosPath: '/app/protos',
+  useTls: true,
+  tlsCaCertPath: '/etc/certs/ca.pem',
+  tlsClientCertPath: '/etc/certs/client.pem',
+  tlsClientKeyPath: '/etc/certs/client.key',
+}, logger);
+```
+
+### Validate TLS Configuration
+
+```typescript
+import { validateTlsConfig } from 'grpc-resilient/gateway';
+
+const validation = validateTlsConfig({
+  useTls: true,
+  caCertPath: '/etc/certs/ca.pem',
+  clientCertPath: '/etc/certs/client.pem',
+  clientKeyPath: '/etc/certs/client.key',
+});
+
+if (!validation.valid) {
+  console.error('TLS config error:', validation.error);
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Singleton Pattern
+
+Always use singleton pattern to reuse connections:
+
+```typescript
+class MyServiceClient extends ResilientGrpcClient {
+  private static instance: MyServiceClient | null = null;
+
+  private constructor(grpcUrl: string, logger: GrpcLogger) {
+    super({ ... });
+  }
+
+  static getInstance(grpcUrl: string, logger: GrpcLogger): MyServiceClient {
+    if (!MyServiceClient.instance) {
+      MyServiceClient.instance = new MyServiceClient(grpcUrl, logger);
+    }
+    return MyServiceClient.instance;
+  }
+}
+```
+
+### 2. Graceful Shutdown
+
+Close clients during application shutdown:
+
+```typescript
+process.on('SIGTERM', () => {
+  client.close();
+  process.exit(0);
+});
+```
+
+### 3. Configure Timeouts Appropriately
+
+```typescript
+// Short timeout for auth/validation calls
+const authClient = new AuthServiceClient({
+  ...config,
+  timeoutMs: 2000,  // 2 seconds
+});
+
+// Longer timeout for data-heavy operations
+const reportClient = new ReportServiceClient({
+  ...config,
+  timeoutMs: 30000,  // 30 seconds
 });
 ```
 
+### 4. Use Type-Safe Clients
+
+Define request/response types for better type safety:
+
+```typescript
+interface GetUserRequest {
+  userId: string;
+}
+
+interface GetUserResponse {
+  id: string;
+  name: string;
+  email: string;
+}
+
+async getUser(userId: string): Promise<GetUserResponse> {
+  return this.call<GetUserRequest, GetUserResponse>('GetUser', { userId });
+}
+```
+
+---
+
 ## Logger Interface
 
 Any logger that implements this interface works:
@@ -172,9 +562,38 @@ interface GrpcLogger {
   debug(obj: object, msg?: string): void;
 }
 
-// Examples: pino, winston, bunyan, console
+// Compatible loggers: pino, winston, bunyan, console
 ```
 
+---
+
+## API Reference
+
+### ResilientGrpcClient (Microservice)
+
+| Method | Description |
+|--------|-------------|
+| `call<TReq, TRes>(method, request, options?)` | Make a gRPC call with retry |
+| `getHealth()` | Get health status with metrics |
+| `getMetrics()` | Get metrics only |
+| `resetMetrics()` | Reset all metrics |
+| `isConnected()` | Check connection status |
+| `close()` | Close connection |
+
+### GatewayGrpcClient (Gateway)
+
+| Method | Description |
+|--------|-------------|
+| `callWithRetry<TReq, TRes>(method, request, options?)` | Make a gRPC call with retry |
+| `ensureConnected()` | Ensure connection is established |
+| `getHealth()` | Get health status with metrics |
+| `getMetrics()` | Get metrics only |
+| `resetMetrics()` | Reset all metrics |
+| `isConnected()` | Check connection status |
+| `close()` | Close connection |
+
+---
+
 ## Requirements
 
 - Node.js >= 18.0.0

package/dist/gateway/GatewayCredentialsProvider.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Gateway gRPC Credentials Provider
+ *
+ * Handles TLS/SSL credentials for gRPC connections in API Gateway scenarios.
+ *
+ * Features:
+ * - One-way TLS (server verification only)
+ * - Mutual TLS (mTLS) with client certificates
+ * - System CA or custom CA certificates
+ * - Secure certificate path validation
+ *
+ * @example
+ * ```typescript
+ * // Insecure (development only)
+ * const creds = createGatewayCredentials({
+ *   serviceName: 'AuthService',
+ *   useTls: false,
+ *   logger,
+ * });
+ *
+ * // One-way TLS with system CA
+ * const creds = createGatewayCredentials({
+ *   serviceName: 'AuthService',
+ *   useTls: true,
+ *   logger,
+ * });
+ *
+ * // Mutual TLS with custom CA
+ * const creds = createGatewayCredentials({
+ *   serviceName: 'AuthService',
+ *   useTls: true,
+ *   caCertPath: '/etc/certs/ca.pem',
+ *   clientCertPath: '/etc/certs/client.pem',
+ *   clientKeyPath: '/etc/certs/client.key',
+ *   logger,
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import * as grpc from '@grpc/grpc-js';
+import type { TlsCredentialsOptions } from './types.js';
+/**
+ * Create gRPC client credentials for gateway connections
+ *
+ * Supports:
+ * - Insecure connections (development only)
+ * - One-way TLS with system CA
+ * - One-way TLS with custom CA
+ * - Mutual TLS (mTLS)
+ *
+ * @param options - Credential configuration options
+ * @returns gRPC channel credentials
+ */
+export declare function createGatewayCredentials(options: TlsCredentialsOptions): grpc.ChannelCredentials;
+/**
+ * Check if a TLS configuration is valid
+ *
+ * Useful for validating configuration before creating clients.
+ *
+ * @param options - TLS configuration to validate
+ * @returns Object with validation result and any error message
+ */
+export declare function validateTlsConfig(options: Pick<TlsCredentialsOptions, 'useTls' | 'caCertPath' | 'clientCertPath' | 'clientKeyPath'>): {
+    valid: boolean;
+    error?: string;
+};
+//# sourceMappingURL=GatewayCredentialsProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayCredentialsProvider.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayCredentialsProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAGtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA6DxD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAAC,kBAAkB,CAShG;AA+CD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,YAAY,GAAG,gBAAgB,GAAG,eAAe,CAAC,GACjG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA+CpC"}