@hazeljs/discovery 0.2.0-beta.16 → 0.2.0-beta.18

package/README.md

@@ -7,14 +7,18 @@ Service Discovery and Registry for HazelJS microservices - inspired by Netflix E
 
 ## Features
 
-- 🔍 **Service Registration & Discovery** - Automatic service registration with health checks
-- ⚖️ **Load Balancing** - 6 built-in strategies (Round Robin, Random, Least Connections, etc.)
-- 🏥 **Health Checks** - Automatic health monitoring with heartbeat
-- 🎯 **Service Filtering** - Filter by zone, tags, metadata, and status
-- 💾 **Multiple Backends** - Memory (dev), Redis, Consul, etcd, Kubernetes
-- 🎨 **Decorator Support** - Clean integration with HazelJS apps
-- 📊 **Caching** - Built-in service discovery caching
-- 🔄 **Auto-Cleanup** - Automatic removal of expired instances
+- **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
 
@@ -22,6 +26,21 @@ Service Discovery and Registry for HazelJS microservices - inspired by Netflix E
 npm install @hazeljs/discovery
 ```
 
+### Optional peer dependencies
+
+Install the backend you need:
+
+```bash
+# Redis backend
+npm install ioredis
+
+# Consul backend
+npm install consul
+
+# Kubernetes backend
+npm install @kubernetes/client-node
+```
+
 ## Quick Start
 
 ### 1. Register a Service
@@ -41,6 +60,9 @@ const registry = new ServiceRegistry({
 });
 
 await registry.register();
+
+// On shutdown
+await registry.deregister();
 ```
 
 ### 2. Discover Services
@@ -51,6 +73,7 @@ import { DiscoveryClient } from '@hazeljs/discovery';
 const client = new DiscoveryClient({
   cacheEnabled: true,
   cacheTTL: 30000,
+  refreshInterval: 15000, // auto-refresh cache every 15s
 });
 
 // Get all instances
@@ -58,6 +81,9 @@ 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
@@ -70,10 +96,12 @@ const serviceClient = new ServiceClient(discoveryClient, {
   loadBalancingStrategy: 'round-robin',
   timeout: 5000,
   retries: 3,
+  retryDelay: 1000,
 });
 
-// Automatic service discovery + load balancing
+// 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
@@ -105,36 +133,44 @@ export class OrderService {
 ## Load Balancing Strategies
 
 ### Round Robin
+
 ```typescript
 const instance = await client.getInstance('service-name', 'round-robin');
 ```
 
 ### Random
+
 ```typescript
 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.
+
 ```typescript
 const instance = await client.getInstance('service-name', 'least-connections');
 ```
 
 ### Weighted Round Robin
+
 ```typescript
 // 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)
+
 ```typescript
 const instance = await client.getInstance('service-name', 'ip-hash');
 ```
 
 ### Zone Aware
+
 ```typescript
 const factory = client.getLoadBalancerFactory();
 const strategy = factory.create('zone-aware', { zone: 'us-east-1' });
@@ -143,6 +179,8 @@ const strategy = factory.create('zone-aware', { zone: 'us-east-1' });
 ## Service Filtering
 
 ```typescript
+import { ServiceStatus } from '@hazeljs/discovery';
+
 const instances = await client.getInstances('user-service', {
   zone: 'us-east-1',
   status: ServiceStatus.UP,
@@ -151,17 +189,35 @@ const instances = await client.getInstances('user-service', {
 });
 ```
 
+The `applyServiceFilter` utility is also exported for use in custom backends or application code:
+
+```typescript
+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.
+
 ```typescript
 import { MemoryRegistryBackend } from '@hazeljs/discovery';
 
-const backend = new MemoryRegistryBackend();
+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.
+
+```bash
+npm install ioredis
+```
+
 ```typescript
 import Redis from 'ioredis';
 import { RedisRegistryBackend } from '@hazeljs/discovery';
@@ -173,14 +229,24 @@ const redis = new Redis({
 });
 
 const backend = new RedisRegistryBackend(redis, {
-  keyPrefix: 'myapp:discovery:',
-  ttl: 90, // seconds
+  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.
+
+```bash
+npm install consul
+```
+
 ```typescript
 import Consul from 'consul';
 import { ConsulRegistryBackend } from '@hazeljs/discovery';
@@ -191,14 +257,24 @@ const consul = new Consul({
 });
 
 const backend = new ConsulRegistryBackend(consul, {
-  ttl: '30s',
+  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).
+
+```bash
+npm install @kubernetes/client-node
+```
+
 ```typescript
 import { KubeConfig } from '@kubernetes/client-node';
 import { KubernetesRegistryBackend } from '@hazeljs/discovery';
@@ -211,11 +287,66 @@ const backend = new KubernetesRegistryBackend(kubeConfig, {
   labelSelector: 'app.kubernetes.io/managed-by=hazeljs',
 });
 
-// In Kubernetes, service registration is handled by the platform
 // 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):
+
+```typescript
+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:
+
+```typescript
+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
@@ -239,6 +370,8 @@ class DiscoveryClient {
   getInstance(serviceName: string, strategy?: string, filter?: ServiceFilter): Promise<ServiceInstance | null>;
   getAllServices(): Promise<string[]>;
   clearCache(serviceName?: string): void;
+  getLoadBalancerFactory(): LoadBalancerFactory;
+  close(): void;
 }
 ```
 
@@ -248,10 +381,41 @@ class DiscoveryClient {
 class ServiceClient {
   constructor(discoveryClient: DiscoveryClient, config: ServiceClientConfig);
   get<T>(path: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
-  post<T>(path: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
-  put<T>(path: string, data?: any, 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?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+  patch<T>(path: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+}
+```
+
+### Configuration Types
+
+```typescript
+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)
 }
 ```
 
@@ -265,13 +429,15 @@ See the [examples](./examples) directory for complete working examples.
 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](../../CONTRIBUTING.md) for details.
 
 ## License
 
-MIT © [HazelJS](https://hazeljs.com)
+MIT &copy; [HazelJS](https://hazeljs.com)
 
 ## Links
 

package/dist/__tests__/consul-backend.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Consul Backend Tests
+ * Uses mocked Consul client
+ */
+export {};
+//# sourceMappingURL=consul-backend.test.d.ts.map

package/dist/__tests__/consul-backend.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consul-backend.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/consul-backend.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/consul-backend.test.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * Consul Backend Tests
+ * Uses mocked Consul client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const consul_backend_1 = require("../backends/consul-backend");
+const types_1 = require("../types");
+const logger_1 = require("../utils/logger");
+// Suppress console logs during tests
+beforeAll(() => {
+    logger_1.DiscoveryLogger.setLogger({
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    });
+});
+afterAll(() => {
+    logger_1.DiscoveryLogger.resetLogger();
+});
+function createMockConsul() {
+    return {
+        agent: {
+            service: {
+                register: jest.fn().mockResolvedValue(undefined),
+                deregister: jest.fn().mockResolvedValue(undefined),
+                list: jest.fn().mockResolvedValue({}),
+            },
+            check: {
+                pass: jest.fn().mockResolvedValue(undefined),
+                fail: jest.fn().mockResolvedValue(undefined),
+                warn: jest.fn().mockResolvedValue(undefined),
+                list: jest.fn().mockResolvedValue({}),
+            },
+        },
+        health: {
+            service: jest.fn().mockResolvedValue([]),
+        },
+        catalog: {
+            service: {
+                list: jest.fn().mockResolvedValue({}),
+            },
+        },
+    };
+}
+function createInstance(id, name = 'test-service', overrides = {}) {
+    return {
+        id,
+        name,
+        host: 'localhost',
+        port: 3000,
+        status: types_1.ServiceStatus.UP,
+        lastHeartbeat: new Date('2025-01-01T00:00:00Z'),
+        registeredAt: new Date('2025-01-01T00:00:00Z'),
+        tags: ['web'],
+        metadata: { version: '1.0' },
+        zone: 'us-east-1',
+        ...overrides,
+    };
+}
+describe('ConsulRegistryBackend', () => {
+    let consul;
+    let backend;
+    beforeEach(() => {
+        jest.useFakeTimers();
+        consul = createMockConsul();
+        backend = new consul_backend_1.ConsulRegistryBackend(consul);
+    });
+    afterEach(async () => {
+        await backend.close();
+        jest.useRealTimers();
+    });
+    describe('constructor', () => {
+        it('should use default TTL of 30s', () => {
+            expect(backend).toBeDefined();
+        });
+        it('should accept custom config', () => {
+            const b = new consul_backend_1.ConsulRegistryBackend(consul, { ttl: '60s' });
+            expect(b).toBeDefined();
+        });
+        it('should throw on invalid TTL format', () => {
+            expect(() => {
+                new consul_backend_1.ConsulRegistryBackend(consul, { ttl: 'invalid' });
+            }).toThrow();
+        });
+    });
+    describe('register', () => {
+        it('should call consul agent service register', async () => {
+            const instance = createInstance('svc-1', 'my-service');
+            await backend.register(instance);
+            expect(consul.agent.service.register).toHaveBeenCalledWith(expect.objectContaining({
+                id: 'svc-1',
+                name: 'my-service',
+                address: 'localhost',
+                port: 3000,
+            }));
+        });
+        it('should start TTL check interval', async () => {
+            const instance = createInstance('svc-1');
+            await backend.register(instance);
+            // Advance timers past the TTL check interval (2/3 of 30s = 20s)
+            jest.advanceTimersByTime(21000);
+            expect(consul.agent.check.pass).toHaveBeenCalledWith('service:svc-1');
+        });
+    });
+    describe('deregister', () => {
+        it('should call consul agent service deregister', async () => {
+            const instance = createInstance('svc-1');
+            await backend.register(instance);
+            await backend.deregister('svc-1');
+            expect(consul.agent.service.deregister).toHaveBeenCalledWith('svc-1');
+        });
+        it('should stop TTL check interval', async () => {
+            const instance = createInstance('svc-1');
+            await backend.register(instance);
+            await backend.deregister('svc-1');
+            jest.clearAllMocks();
+            jest.advanceTimersByTime(30000);
+            // TTL check should NOT have been called after deregister
+            expect(consul.agent.check.pass).not.toHaveBeenCalled();
+        });
+    });
+    describe('heartbeat', () => {
+        it('should pass the TTL check', async () => {
+            await backend.heartbeat('svc-1');
+            expect(consul.agent.check.pass).toHaveBeenCalledWith('service:svc-1');
+        });
+        it('should not throw when consul fails', async () => {
+            consul.agent.check.pass.mockRejectedValueOnce(new Error('Consul error'));
+            await expect(backend.heartbeat('svc-1')).resolves.not.toThrow();
+        });
+    });
+    describe('getInstances', () => {
+        it('should return instances from consul health service', async () => {
+            consul.health.service.mockResolvedValueOnce([
+                {
+                    Service: {
+                        ID: 'svc-1',
+                        Service: 'my-service',
+                        Address: '10.0.0.1',
+                        Port: 8080,
+                        Meta: { zone: 'us-east-1', registeredAt: '2025-01-01T00:00:00Z' },
+                        Tags: ['web'],
+                    },
+                    Checks: [{ Status: 'passing' }],
+                },
+                {
+                    Service: {
+                        ID: 'svc-2',
+                        Service: 'my-service',
+                        Address: '10.0.0.2',
+                        Port: 8080,
+                        Meta: { zone: 'us-west-1' },
+                        Tags: ['api'],
+                    },
+                    Checks: [{ Status: 'passing' }],
+                },
+            ]);
+            const instances = await backend.getInstances('my-service');
+            expect(instances).toHaveLength(2);
+            expect(instances[0].id).toBe('svc-1');
+            expect(instances[0].host).toBe('10.0.0.1');
+        });
+        it('should set status based on check results', async () => {
+            consul.health.service.mockResolvedValueOnce([
+                {
+                    Service: {
+                        ID: 'svc-1',
+                        Service: 'my-service',
+                        Address: '10.0.0.1',
+                        Port: 8080,
+                    },
+                    Checks: [{ Status: 'critical' }],
+                },
+                {
+                    Service: {
+                        ID: 'svc-2',
+                        Service: 'my-service',
+                        Address: '10.0.0.2',
+                        Port: 8080,
+                    },
+                    Checks: [{ Status: 'warning' }],
+                },
+            ]);
+            const instances = await backend.getInstances('my-service');
+            expect(instances[0].status).toBe(types_1.ServiceStatus.DOWN);
+            expect(instances[1].status).toBe(types_1.ServiceStatus.STARTING);
+        });
+        it('should filter instances', async () => {
+            consul.health.service.mockResolvedValueOnce([
+                {
+                    Service: {
+                        ID: 'svc-1',
+                        Service: 'my-service',
+                        Address: '10.0.0.1',
+                        Port: 8080,
+                        Meta: { zone: 'us-east-1' },
+                    },
+                    Checks: [],
+                },
+                {
+                    Service: {
+                        ID: 'svc-2',
+                        Service: 'my-service',
+                        Address: '10.0.0.2',
+                        Port: 8080,
+                        Meta: { zone: 'us-west-1' },
+                    },
+                    Checks: [],
+                },
+            ]);
+            const instances = await backend.getInstances('my-service', { zone: 'us-east-1' });
+            expect(instances).toHaveLength(1);
+            expect(instances[0].id).toBe('svc-1');
+        });
+        it('should return empty array on error', async () => {
+            consul.health.service.mockRejectedValueOnce(new Error('Consul error'));
+            const instances = await backend.getInstances('my-service');
+            expect(instances).toEqual([]);
+        });
+    });
+    describe('getInstance', () => {
+        it('should return a specific instance', async () => {
+            consul.agent.service.list.mockResolvedValueOnce({
+                'svc-1': {
+                    ID: 'svc-1',
+                    Service: 'my-service',
+                    Address: '10.0.0.1',
+                    Port: 8080,
+                    Meta: { zone: 'us-east-1' },
+                    Tags: ['web'],
+                },
+            });
+            consul.agent.check.list.mockResolvedValueOnce({
+                'service:svc-1': { Status: 'passing' },
+            });
+            const instance = await backend.getInstance('svc-1');
+            expect(instance).toBeDefined();
+            expect(instance.id).toBe('svc-1');
+            expect(instance.status).toBe(types_1.ServiceStatus.UP);
+        });
+        it('should return null for non-existent instance', async () => {
+            consul.agent.service.list.mockResolvedValueOnce({});
+            const instance = await backend.getInstance('non-existent');
+            expect(instance).toBeNull();
+        });
+        it('should return null on error', async () => {
+            consul.agent.service.list.mockRejectedValueOnce(new Error('fail'));
+            const instance = await backend.getInstance('svc-1');
+            expect(instance).toBeNull();
+        });
+    });
+    describe('getAllServices', () => {
+        it('should return service names from catalog', async () => {
+            consul.catalog.service.list.mockResolvedValueOnce({
+                'service-a': [],
+                'service-b': [],
+                consul: [],
+            });
+            const services = await backend.getAllServices();
+            expect(services).toEqual(['service-a', 'service-b', 'consul']);
+        });
+        it('should return empty array on error', async () => {
+            consul.catalog.service.list.mockRejectedValueOnce(new Error('fail'));
+            const services = await backend.getAllServices();
+            expect(services).toEqual([]);
+        });
+    });
+    describe('updateStatus', () => {
+        it('should pass check for UP status', async () => {
+            await backend.updateStatus('svc-1', types_1.ServiceStatus.UP);
+            expect(consul.agent.check.pass).toHaveBeenCalledWith('service:svc-1');
+        });
+        it('should fail check for DOWN status', async () => {
+            await backend.updateStatus('svc-1', types_1.ServiceStatus.DOWN);
+            expect(consul.agent.check.fail).toHaveBeenCalledWith('service:svc-1');
+        });
+        it('should warn check for STARTING status', async () => {
+            await backend.updateStatus('svc-1', types_1.ServiceStatus.STARTING);
+            expect(consul.agent.check.warn).toHaveBeenCalledWith('service:svc-1');
+        });
+        it('should not throw on error', async () => {
+            consul.agent.check.pass.mockRejectedValueOnce(new Error('fail'));
+            await expect(backend.updateStatus('svc-1', types_1.ServiceStatus.UP)).resolves.not.toThrow();
+        });
+    });
+    describe('close', () => {
+        it('should stop all TTL check intervals', async () => {
+            const i1 = createInstance('svc-1');
+            const i2 = createInstance('svc-2');
+            await backend.register(i1);
+            await backend.register(i2);
+            await backend.close();
+            jest.clearAllMocks();
+            jest.advanceTimersByTime(60000);
+            expect(consul.agent.check.pass).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/__tests__/kubernetes-backend.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Kubernetes Backend Tests
+ * Uses mocked @kubernetes/client-node API
+ */
+export {};
+//# sourceMappingURL=kubernetes-backend.test.d.ts.map

package/dist/__tests__/kubernetes-backend.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kubernetes-backend.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/kubernetes-backend.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}