@hazeljs/discovery

Microservices that find each other.

Service registry, health checks, load balancing. Round Robin, Least Connections, Zone Aware — 6 strategies. Memory, Redis, Consul, or Kubernetes. Eureka-style, without the Java.

Features

• Service Registration & Discovery - Automatic service registration with health checks
• Load Balancing - 6 built-in strategies (Round Robin, Random, Least Connections, Weighted Round Robin, IP Hash, Zone Aware)
• Health Checks - Automatic health monitoring with heartbeat
• Service Filtering - Filter by zone, tags, metadata, and status
• Multiple Backends - Memory (dev), Redis, Consul, Kubernetes
• Decorator Support - Clean integration with HazelJS apps
• Caching - Built-in service discovery caching with auto-refresh
• Auto-Cleanup - Automatic removal of expired instances
• Smart Retries - Only retries on transient/network errors, not client errors
• Pluggable Logging - Bring your own logger or use the built-in console logger
• Config Validation - Runtime validation of all configuration objects
• Graceful Shutdown - Proper cleanup of intervals, connections, and resources

Installation

npm install @hazeljs/discovery

Optional peer dependencies

Install the backend you need:

# Redis backend
npm install ioredis

# Consul backend
npm install consul

# Kubernetes backend
npm install @kubernetes/client-node

Quick Start

1. Register a Service

import { ServiceRegistry } from '@hazeljs/discovery';

const registry = new ServiceRegistry({
  name: 'user-service',
  port: 3000,
  host: 'localhost',
  healthCheckPath: '/health',
  healthCheckInterval: 30000,
  metadata: { version: '1.0.0' },
  zone: 'us-east-1',
  tags: ['api', 'users'],
});

await registry.register();

// On shutdown
await registry.deregister();

2. Discover Services

import { DiscoveryClient } from '@hazeljs/discovery';

const client = new DiscoveryClient({
  cacheEnabled: true,
  cacheTTL: 30000,
  refreshInterval: 15000, // auto-refresh cache every 15s
});

// Get all instances
const instances = await client.getInstances('user-service');

// Get one instance with load balancing
const instance = await client.getInstance('user-service', 'round-robin');

// On shutdown
client.close();

3. Call Services

import { ServiceClient } from '@hazeljs/discovery';

const serviceClient = new ServiceClient(discoveryClient, {
  serviceName: 'user-service',
  loadBalancingStrategy: 'round-robin',
  timeout: 5000,
  retries: 3,
  retryDelay: 1000,
});

// Automatic service discovery + load balancing + smart retries
const user = await serviceClient.get('/users/123');
const created = await serviceClient.post('/users', { name: 'John' });

4. With HazelJS Decorators

import { ServiceRegistryDecorator, InjectServiceClient } from '@hazeljs/discovery';

@ServiceRegistryDecorator({
  name: 'order-service',
  port: 3001,
  healthCheckPath: '/health',
})
export class AppModule {}

@Injectable()
export class OrderService {
  constructor(
    @InjectServiceClient('user-service')
    private userClient: ServiceClient
  ) {}

  async createOrder(userId: string) {
    const user = await this.userClient.get(`/users/${userId}`);
    // ... create order
  }
}

Load Balancing Strategies

Round Robin

const instance = await client.getInstance('service-name', 'round-robin');

Random

const instance = await client.getInstance('service-name', 'random');

Least Connections

Tracks active connections per instance. When used with ServiceClient, connection counts are automatically incremented/decremented on each request.

const instance = await client.getInstance('service-name', 'least-connections');

Weighted Round Robin

// Set weight in service metadata
const registry = new ServiceRegistry({
  name: 'api-service',
  port: 3000,
  metadata: { weight: 5 }, // Higher weight = more traffic
});

IP Hash (Sticky Sessions)

const instance = await client.getInstance('service-name', 'ip-hash');

Zone Aware

const factory = client.getLoadBalancerFactory();
const strategy = factory.create('zone-aware', { zone: 'us-east-1' });

Service Filtering

import { ServiceStatus } from '@hazeljs/discovery';

const instances = await client.getInstances('user-service', {
  zone: 'us-east-1',
  status: ServiceStatus.UP,
  tags: ['api', 'production'],
  metadata: { version: '2.0.0' },
});

The applyServiceFilter utility is also exported for use in custom backends or application code:

import { applyServiceFilter } from '@hazeljs/discovery';

const filtered = applyServiceFilter(instances, { zone: 'us-east-1' });

Registry Backends

Memory (Development)

The default backend. Stores everything in-process memory -- suitable for development and testing.

import { MemoryRegistryBackend } from '@hazeljs/discovery';

const backend = new MemoryRegistryBackend(90000); // optional expiration in ms
const registry = new ServiceRegistry(config, backend);

Redis (Production)

Distributed registry using Redis with TTL-based expiration. Uses SCAN (not KEYS) for production safety and MGET for efficient batch lookups. Includes connection error handling with automatic reconnection support.

npm install ioredis

import Redis from 'ioredis';
import { RedisRegistryBackend } from '@hazeljs/discovery';

const redis = new Redis({
  host: 'localhost',
  port: 6379,
  password: 'your-password',
});

const backend = new RedisRegistryBackend(redis, {
  keyPrefix: 'myapp:discovery:', // default: 'hazeljs:discovery:'
  ttl: 90, // seconds, default: 90
});

const registry = new ServiceRegistry(config, backend);

// On shutdown
await backend.close();

Consul

Integrates with HashiCorp Consul using TTL-based health checks.

npm install consul

import Consul from 'consul';
import { ConsulRegistryBackend } from '@hazeljs/discovery';

const consul = new Consul({
  host: 'localhost',
  port: 8500,
});

const backend = new ConsulRegistryBackend(consul, {
  ttl: '30s', // TTL check interval (supports "30s", "5m", "1h")
  datacenter: 'dc1',
});

const registry = new ServiceRegistry(config, backend);

// On shutdown
await backend.close();

Kubernetes

Read-only discovery backend that integrates with Kubernetes Endpoints API. Registration, deregistration, heartbeat, and status updates are no-ops since Kubernetes manages these through its own primitives (Services, Endpoints, probes).

npm install @kubernetes/client-node

import { KubeConfig } from '@kubernetes/client-node';
import { KubernetesRegistryBackend } from '@hazeljs/discovery';

const kubeConfig = new KubeConfig();
kubeConfig.loadFromDefault();

const backend = new KubernetesRegistryBackend(kubeConfig, {
  namespace: 'default',
  labelSelector: 'app.kubernetes.io/managed-by=hazeljs',
});

// Use the backend for service discovery only
const client = new DiscoveryClient({}, backend);

Smart Retry Logic

ServiceClient only retries on transient errors. Client errors (4xx) are thrown immediately without wasting retries:

| Error Type | Retried? | | -------------------------------------- | -------- | | Network errors (ECONNREFUSED, timeout) | Yes | | 502 Bad Gateway | Yes | | 503 Service Unavailable | Yes | | 504 Gateway Timeout | Yes | | 408 Request Timeout | Yes | | 429 Too Many Requests | Yes | | 400 Bad Request | No | | 401 Unauthorized | No | | 403 Forbidden | No | | 404 Not Found | No | | Other 4xx | No |

Custom Logging

By default, the package logs to the console with a [discovery] prefix. You can plug in your own logger (e.g., Winston, Pino, Bunyan):

import { DiscoveryLogger } from '@hazeljs/discovery';

DiscoveryLogger.setLogger({
  debug: (msg, ...args) => myLogger.debug(msg, ...args),
  info: (msg, ...args) => myLogger.info(msg, ...args),
  warn: (msg, ...args) => myLogger.warn(msg, ...args),
  error: (msg, ...args) => myLogger.error(msg, ...args),
});

// Reset to default console logger
DiscoveryLogger.resetLogger();

Config Validation

All configuration objects are validated at construction time. Invalid configs throw a ConfigValidationError with a descriptive message:

import { ServiceRegistry, ConfigValidationError } from '@hazeljs/discovery';

try {
  const registry = new ServiceRegistry({
    name: '', // invalid: empty string
    port: -1, // invalid: negative port
  });
} catch (error) {
  if (error instanceof ConfigValidationError) {
    console.error(error.message);
    // => 'ServiceRegistryConfig: "name" is required and must be a non-empty string'
  }
}

API Reference

ServiceRegistry

class ServiceRegistry {
  constructor(config: ServiceRegistryConfig, backend?: RegistryBackend);
  register(): Promise<void>;
  deregister(): Promise<void>;
  getInstance(): ServiceInstance | null;
  getBackend(): RegistryBackend;
}

DiscoveryClient

class DiscoveryClient {
  constructor(config?: DiscoveryClientConfig, backend?: RegistryBackend);
  getInstances(serviceName: string, filter?: ServiceFilter): Promise<ServiceInstance[]>;
  getInstance(
    serviceName: string,
    strategy?: string,
    filter?: ServiceFilter
  ): Promise<ServiceInstance | null>;
  getAllServices(): Promise<string[]>;
  clearCache(serviceName?: string): void;
  getLoadBalancerFactory(): LoadBalancerFactory;
  close(): void;
}

ServiceClient

class ServiceClient {
  constructor(discoveryClient: DiscoveryClient, config: ServiceClientConfig);
  get<T>(path: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
  post<T>(path: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
  put<T>(path: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
  delete<T>(path: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
  patch<T>(path: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
}

Configuration Types

interface ServiceRegistryConfig {
  name: string;
  port: number;
  host?: string;
  protocol?: 'http' | 'https' | 'grpc';
  healthCheckPath?: string; // default: '/health'
  healthCheckInterval?: number; // default: 30000 (ms)
  metadata?: Record<string, unknown>;
  zone?: string;
  tags?: string[];
}

interface DiscoveryClientConfig {
  cacheEnabled?: boolean;
  cacheTTL?: number; // default: 30000 (ms)
  refreshInterval?: number; // auto-refresh cache interval (ms)
}

interface ServiceClientConfig {
  serviceName: string;
  loadBalancingStrategy?: string; // default: 'round-robin'
  filter?: ServiceFilter;
  timeout?: number; // default: 5000 (ms)
  retries?: number; // default: 3
  retryDelay?: number; // default: 1000 (ms)
}

Examples

See the examples directory for complete working examples.

Testing

npm test

The package includes 145+ unit tests across 9 test suites with 85%+ code coverage.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

Apache 2.0 © HazelJS

Links

• Documentation
• GitHub
• Issues
• Roadmap