@hazeljs/discovery 0.2.0-beta.1

package/README.md

@@ -0,0 +1,281 @@
+# @hazeljs/discovery
+
+Service Discovery and Registry for HazelJS microservices - inspired by Netflix Eureka and Consul.
+
+[![npm version](https://img.shields.io/npm/v/@hazeljs/discovery.svg)](https://www.npmjs.com/package/@hazeljs/discovery)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+## Installation
+
+```bash
+npm install @hazeljs/discovery
+```
+
+## Quick Start
+
+### 1. Register a Service
+
+```typescript
+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();
+```
+
+### 2. Discover Services
+
+```typescript
+import { DiscoveryClient } from '@hazeljs/discovery';
+
+const client = new DiscoveryClient({
+  cacheEnabled: true,
+  cacheTTL: 30000,
+});
+
+// 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');
+```
+
+### 3. Call Services
+
+```typescript
+import { ServiceClient } from '@hazeljs/discovery';
+
+const serviceClient = new ServiceClient(discoveryClient, {
+  serviceName: 'user-service',
+  loadBalancingStrategy: 'round-robin',
+  timeout: 5000,
+  retries: 3,
+});
+
+// Automatic service discovery + load balancing
+const user = await serviceClient.get('/users/123');
+```
+
+### 4. With HazelJS Decorators
+
+```typescript
+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
+```typescript
+const instance = await client.getInstance('service-name', 'round-robin');
+```
+
+### Random
+```typescript
+const instance = await client.getInstance('service-name', 'random');
+```
+
+### Least Connections
+```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',
+  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' });
+```
+
+## Service Filtering
+
+```typescript
+const instances = await client.getInstances('user-service', {
+  zone: 'us-east-1',
+  status: ServiceStatus.UP,
+  tags: ['api', 'production'],
+  metadata: { version: '2.0.0' },
+});
+```
+
+## Registry Backends
+
+### Memory (Development)
+```typescript
+import { MemoryRegistryBackend } from '@hazeljs/discovery';
+
+const backend = new MemoryRegistryBackend();
+const registry = new ServiceRegistry(config, backend);
+```
+
+### Redis (Production)
+```typescript
+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:',
+  ttl: 90, // seconds
+});
+
+const registry = new ServiceRegistry(config, backend);
+```
+
+### Consul
+```typescript
+import Consul from 'consul';
+import { ConsulRegistryBackend } from '@hazeljs/discovery';
+
+const consul = new Consul({
+  host: 'localhost',
+  port: 8500,
+});
+
+const backend = new ConsulRegistryBackend(consul, {
+  ttl: '30s',
+  datacenter: 'dc1',
+});
+
+const registry = new ServiceRegistry(config, backend);
+```
+
+### Kubernetes
+```typescript
+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',
+});
+
+// In Kubernetes, service registration is handled by the platform
+// Use the backend for service discovery only
+const client = new DiscoveryClient({}, backend);
+```
+
+## API Reference
+
+### ServiceRegistry
+
+```typescript
+class ServiceRegistry {
+  constructor(config: ServiceRegistryConfig, backend?: RegistryBackend);
+  register(): Promise<void>;
+  deregister(): Promise<void>;
+  getInstance(): ServiceInstance | null;
+  getBackend(): RegistryBackend;
+}
+```
+
+### DiscoveryClient
+
+```typescript
+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;
+}
+```
+
+### ServiceClient
+
+```typescript
+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>>;
+  delete<T>(path: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+  patch<T>(path: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+}
+```
+
+## Examples
+
+See the [examples](./examples) directory for complete working examples.
+
+## Testing
+
+```bash
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [HazelJS](https://hazeljs.com)
+
+## Links
+
+- [Documentation](https://hazeljs.com/docs)
+- [GitHub](https://github.com/hazel-js/hazeljs)
+- [Issues](https://github.com/hazel-js/hazeljs/issues)
+- [Roadmap](../../ROADMAP_2.0.md)

package/dist/__tests__/decorators.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Decorators Tests
+ */
+import 'reflect-metadata';
+//# sourceMappingURL=decorators.test.d.ts.map

package/dist/__tests__/decorators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/decorators.test.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,kBAAkB,CAAC"}

package/dist/__tests__/decorators.test.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Decorators Tests
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const service_registry_decorator_1 = require("../decorators/service-registry.decorator");
+const inject_service_client_decorator_1 = require("../decorators/inject-service-client.decorator");
+describe('Decorators', () => {
+    describe('ServiceRegistry', () => {
+        it('should attach metadata to class', () => {
+            const config = {
+                name: 'test-service',
+                port: 3000,
+                zone: 'us-east-1',
+            };
+            let TestService = class TestService {
+            };
+            TestService = __decorate([
+                (0, service_registry_decorator_1.ServiceRegistry)(config)
+            ], TestService);
+            const metadata = (0, service_registry_decorator_1.getServiceRegistryMetadata)(TestService);
+            expect(metadata).toEqual(config);
+        });
+        it('should return undefined for class without decorator', () => {
+            class TestService {
+            }
+            const metadata = (0, service_registry_decorator_1.getServiceRegistryMetadata)(TestService);
+            expect(metadata).toBeUndefined();
+        });
+    });
+    describe('InjectServiceClient', () => {
+        it('should attach metadata to parameter', () => {
+            let TestService = class TestService {
+                constructor(_userClient, _orderClient) { }
+            };
+            TestService = __decorate([
+                __param(0, (0, inject_service_client_decorator_1.InjectServiceClient)('user-service')),
+                __param(1, (0, inject_service_client_decorator_1.InjectServiceClient)('order-service', { timeout: 5000 })),
+                __metadata("design:paramtypes", [Object, Object])
+            ], TestService);
+            const metadata = (0, inject_service_client_decorator_1.getInjectServiceClientMetadata)(TestService);
+            expect(metadata).toBeDefined();
+            expect(metadata?.[0]).toEqual({
+                serviceName: 'user-service',
+            });
+            expect(metadata?.[1]).toEqual({
+                serviceName: 'order-service',
+                timeout: 5000,
+            });
+        });
+        it('should return undefined for class without decorator', () => {
+            class TestService {
+                constructor(_client) { }
+            }
+            const metadata = (0, inject_service_client_decorator_1.getInjectServiceClientMetadata)(TestService);
+            expect(metadata).toBeUndefined();
+        });
+    });
+});

package/dist/__tests__/discovery-client.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Discovery Client Tests
+ */
+export {};
+//# sourceMappingURL=discovery-client.test.d.ts.map

package/dist/__tests__/discovery-client.test.d.ts.map

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

package/dist/__tests__/discovery-client.test.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Discovery Client Tests
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const discovery_client_1 = require("../client/discovery-client");
+const memory_backend_1 = require("../backends/memory-backend");
+const types_1 = require("../types");
+describe('DiscoveryClient', () => {
+    let client;
+    let backend;
+    beforeEach(() => {
+        backend = new memory_backend_1.MemoryRegistryBackend();
+        client = new discovery_client_1.DiscoveryClient({}, backend);
+    });
+    const createInstance = (id, name = 'test-service') => ({
+        id,
+        name,
+        host: 'localhost',
+        port: 3000,
+        status: types_1.ServiceStatus.UP,
+        lastHeartbeat: new Date(),
+        registeredAt: new Date(),
+    });
+    describe('getInstances', () => {
+        it('should return instances from backend', async () => {
+            const instance1 = createInstance('1', 'service-a');
+            const instance2 = createInstance('2', 'service-a');
+            await backend.register(instance1);
+            await backend.register(instance2);
+            const instances = await client.getInstances('service-a');
+            expect(instances).toHaveLength(2);
+        });
+        it('should apply filters', async () => {
+            const instance1 = { ...createInstance('1'), zone: 'us-east-1' };
+            const instance2 = { ...createInstance('2'), zone: 'us-west-1' };
+            await backend.register(instance1);
+            await backend.register(instance2);
+            const instances = await client.getInstances('test-service', {
+                zone: 'us-east-1',
+            });
+            expect(instances).toHaveLength(1);
+            expect(instances[0].id).toBe('1');
+        });
+        it('should use cache when enabled', async () => {
+            const clientWithCache = new discovery_client_1.DiscoveryClient({ cacheEnabled: true, cacheTTL: 1000 }, backend);
+            const instance = createInstance('1');
+            await backend.register(instance);
+            const first = await clientWithCache.getInstances('test-service');
+            expect(first).toHaveLength(1);
+            // Remove from backend
+            await backend.deregister('1');
+            // Should still return cached result
+            const second = await clientWithCache.getInstances('test-service');
+            expect(second).toHaveLength(1);
+        });
+        it('should refresh cache after TTL expires', async () => {
+            const clientWithCache = new discovery_client_1.DiscoveryClient({ cacheEnabled: true, cacheTTL: 50 }, backend);
+            const instance = createInstance('1');
+            await backend.register(instance);
+            await clientWithCache.getInstances('test-service');
+            await backend.deregister('1');
+            // Wait for cache to expire
+            await new Promise((resolve) => setTimeout(resolve, 60));
+            const instances = await clientWithCache.getInstances('test-service');
+            expect(instances).toHaveLength(0);
+        });
+    });
+    describe('getInstance', () => {
+        it('should return a single instance using load balancing', async () => {
+            const instance1 = createInstance('1');
+            const instance2 = createInstance('2');
+            await backend.register(instance1);
+            await backend.register(instance2);
+            const instance = await client.getInstance('test-service');
+            expect(instance).toBeDefined();
+            expect(['1', '2']).toContain(instance?.id);
+        });
+        it('should return null when no instances available', async () => {
+            const instance = await client.getInstance('non-existent');
+            expect(instance).toBeNull();
+        });
+        it('should use specified load balancing strategy', async () => {
+            const instance1 = createInstance('1');
+            const instance2 = createInstance('2');
+            await backend.register(instance1);
+            await backend.register(instance2);
+            // Round robin should cycle
+            const first = await client.getInstance('test-service', 'round-robin');
+            const second = await client.getInstance('test-service', 'round-robin');
+            const third = await client.getInstance('test-service', 'round-robin');
+            expect(first?.id).toBe('1');
+            expect(second?.id).toBe('2');
+            expect(third?.id).toBe('1');
+        });
+        it('should apply filters', async () => {
+            const instance1 = { ...createInstance('1'), zone: 'us-east-1' };
+            const instance2 = { ...createInstance('2'), zone: 'us-west-1' };
+            await backend.register(instance1);
+            await backend.register(instance2);
+            const instance = await client.getInstance('test-service', 'round-robin', {
+                zone: 'us-east-1',
+            });
+            expect(instance?.id).toBe('1');
+        });
+    });
+    describe('getAllServices', () => {
+        it('should return all service names', async () => {
+            await backend.register(createInstance('1', 'service-a'));
+            await backend.register(createInstance('2', 'service-b'));
+            const services = await client.getAllServices();
+            expect(services.sort()).toEqual(['service-a', 'service-b']);
+        });
+    });
+    describe('clearCache', () => {
+        it('should clear cache for specific service', () => {
+            const clientWithCache = new discovery_client_1.DiscoveryClient({ cacheEnabled: true }, backend);
+            clientWithCache.clearCache('service-a');
+            // Should not throw
+            expect(true).toBe(true);
+        });
+        it('should clear all cache when no service specified', () => {
+            const clientWithCache = new discovery_client_1.DiscoveryClient({ cacheEnabled: true }, backend);
+            clientWithCache.clearCache();
+            // Should not throw
+            expect(true).toBe(true);
+        });
+    });
+    describe('getBackend', () => {
+        it('should return the backend instance', () => {
+            const backend = client.getBackend();
+            expect(backend).toBeInstanceOf(memory_backend_1.MemoryRegistryBackend);
+        });
+    });
+    describe('getLoadBalancerFactory', () => {
+        it('should return the load balancer factory', () => {
+            const factory = client.getLoadBalancerFactory();
+            expect(factory).toBeDefined();
+            expect(factory.get('round-robin')).toBeDefined();
+        });
+    });
+});

package/dist/__tests__/load-balancer-strategies.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Load Balancer Strategies Tests
+ */
+export {};
+//# sourceMappingURL=load-balancer-strategies.test.d.ts.map

package/dist/__tests__/load-balancer-strategies.test.d.ts.map

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