grpc-resilient

Production-ready gRPC client for Node.js with built-in resilience patterns.

Features

• Lazy Connection - Connects on first use, not at startup
• Auto-Reconnect - Exponential backoff reconnection strategy
• Retry Logic - Configurable retry with exponential backoff
• Fallback Cache - Graceful degradation when service is unavailable
• Metrics - OpenTelemetry-compatible metrics tracking
• Health Checks - Built-in health status reporting
• TLS/mTLS - Full TLS and mutual TLS support
• TypeScript - Full type safety with generics support
• ESM - Native ES modules support

Installation

npm install grpc-resilient @grpc/grpc-js @grpc/proto-loader

Quick Start

Microservice Client

import { ResilientGrpcClient, type GrpcLogger } from 'grpc-resilient';
import { fileURLToPath } from 'url';

const logger: GrpcLogger = console;

class UserServiceClient extends ResilientGrpcClient {
  private static instance: UserServiceClient | null = null;

  private 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,
      timeoutMs: 5000,
      retryCount: 3,
      enableFallbackCache: true,
    });
  }

  static getInstance(grpcUrl: string, logger: GrpcLogger): UserServiceClient {
    if (!UserServiceClient.instance) {
      UserServiceClient.instance = new UserServiceClient(grpcUrl, logger);
    }
    return UserServiceClient.instance;
  }

  async getUser(userId: string) {
    return this.call<{ userId: string }, { id: string; name: string }>('GetUser', { userId });
  }
}

const client = UserServiceClient.getInstance('localhost:50051', logger);
const user = await client.getUser('123');

Gateway Client

For API Gateways and BFF services:

import { GatewayGrpcClient, type GatewayClientConfig, type GatewayLogger } from 'grpc-resilient/gateway';

class AuthServiceProxy extends GatewayGrpcClient {
  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: 3000,
        retryCount: 2,
        useTls: true,
      }, logger);
    }
    return AuthServiceProxy.instance;
  }

  async validateToken(token: string) {
    return this.callWithRetry('ValidateToken', { token });
  }
}

Configuration

| 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 | | logger | GrpcLogger | required | Logger instance | | 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 | | enableFallbackCache | boolean | false | Enable fallback cache | | fallbackCacheTtlMs | number | 60000 | Cache TTL in milliseconds | | maxCacheSize | number | 100 | Maximum cache entries |

TLS Configuration

// One-way TLS
{
  useTls: true,
}

// Mutual TLS (mTLS)
{
  useTls: true,
  tlsCaCertPath: '/etc/ssl/ca.pem',
  tlsClientCertPath: '/etc/ssl/client.pem',
  tlsClientKeyPath: '/etc/ssl/client.key',
}

Health & Metrics

// Get health status
const health = client.getHealth();
// {
//   state: 'CONNECTED',
//   healthy: true,
//   lastConnectedAt: Date,
//   lastErrorAt: null,
//   reconnectAttempts: 0,
//   latencyMs: 45,
//   metrics: { ... }
// }

// Get metrics for OpenTelemetry
const metrics = client.getMetrics();
// {
//   totalCalls: 150,
//   successfulCalls: 148,
//   failedCalls: 2,
//   totalRetries: 5,
//   avgLatencyMs: 42,
//   ...
// }

// Reset metrics
client.resetMetrics();

Events

client.on('connected', () => {
  console.log('gRPC client connected');
});

client.on('disconnected', () => {
  console.log('gRPC client disconnected');
});

client.on('error', (error) => {
  console.error('Connection error:', error);
});

client.on('connecting', () => {
  console.log('Connecting...');
});

Call Options

// 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
});

Logger Interface

Any logger that implements this interface works:

interface GrpcLogger {
  info(obj: object, msg?: string): void;
  warn(obj: object, msg?: string): void;
  error(obj: object, msg?: string): void;
  debug(obj: object, msg?: string): void;
}

// Examples: pino, winston, bunyan, console

Gateway Client Features

The grpc-resilient/gateway module provides additional features for API Gateways:

• No Fallback Cache - Gateways should fail fast, not serve stale data
• TLS/mTLS Built-in - Secure certificate handling with path validation
• Metadata Forwarding - Forward request context (locale, client IP, custom headers)
• Keepalive Configuration - Prevent idle connection drops

import {
  GatewayGrpcClient,
  validateTlsConfig,
  type GatewayClientConfig,
  type GatewayCallOptions,
} from 'grpc-resilient/gateway';

// Validate TLS config at startup
const validation = validateTlsConfig({
  useTls: true,
  caCertPath: process.env.TLS_CA_PATH,
});

if (!validation.valid) {
  throw new Error(`TLS config error: ${validation.error}`);
}

// Forward request context
const user = await client.callWithRetry('GetUser', { userId }, {
  locale: req.headers['accept-language'],
  metadata: {
    'x-request-id': req.id,
    'x-correlation-id': req.headers['x-correlation-id'],
  },
});

Requirements

• Node.js >= 18.0.0
• @grpc/grpc-js >= 1.9.0
• @grpc/proto-loader >= 0.7.0

License

MIT © berkeerdo