Initial Commit
This commit is contained in:
253
openspec/changes/enterprise-service-discovery/proposal.md
Normal file
253
openspec/changes/enterprise-service-discovery/proposal.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# OpenSpec Change: enterprise-service-discovery
|
||||
|
||||
- **Change ID**: enterprise-service-discovery
|
||||
- **Package**: `@suaveplan/service-discovery`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/network/service-discovery`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/service-discovery.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/service-discovery` on the genesis branch from scratch at enterprise quality. The package provides a service registry and discovery system: `ServiceRegistry` (register/deregister/lookup services by name and tags), health-check scheduler (HTTP and TCP probes, injectable), TTL-based expiry, `ServiceResolver` with round-robin and weighted load balancing, in-memory and pluggable backends, and event-bus change notifications. Pure TypeScript, no platform hard deps.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data. The main-branch package had 97.76% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `ServiceDiscoveryError`; `SERVICE_DISCOVERY.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `StorageLike` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Event bus for registry-change notifications |
|
||||
| `@suaveplan/network` (`workspace:^`) | `HttpClient` for HTTP health probes |
|
||||
| `@suaveplan/retry` (`workspace:^`) | Retry on health-check probes |
|
||||
| `zod` (`catalog:forms`) | Zod schemas for all public option types |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
class ServiceDiscoveryError extends SuaveplanError
|
||||
|
||||
type ServiceStatus = 'healthy' | 'unhealthy' | 'unknown'
|
||||
type HealthCheckType = 'http' | 'tcp' | 'custom'
|
||||
type LoadBalancingStrategy = 'round-robin' | 'weighted' | 'random' | 'first-healthy'
|
||||
|
||||
interface ServiceEndpoint {
|
||||
host: string
|
||||
port: number
|
||||
protocol?: string // default: 'http'
|
||||
path?: string // default: '/'
|
||||
}
|
||||
|
||||
interface HealthCheck {
|
||||
type: HealthCheckType
|
||||
intervalMs?: number // default: 30000
|
||||
timeoutMs?: number // default: 5000
|
||||
failureThreshold?: number // default: 3; mark unhealthy after N consecutive failures
|
||||
successThreshold?: number // default: 1; mark healthy after N consecutive successes
|
||||
customCheck?: (endpoint: ServiceEndpoint) => Promise<boolean>
|
||||
}
|
||||
|
||||
interface ServiceRegistration {
|
||||
id: string // unique per instance
|
||||
name: string // service name (logical)
|
||||
version?: string
|
||||
endpoint: ServiceEndpoint
|
||||
tags?: string[]
|
||||
metadata?: Record<string, string>
|
||||
ttlMs?: number // auto-expire if not refreshed; 0 = no expiry
|
||||
healthCheck?: HealthCheck
|
||||
weight?: number // for weighted load balancing; default: 1
|
||||
}
|
||||
|
||||
interface ServiceInstance extends ServiceRegistration {
|
||||
status: ServiceStatus
|
||||
registeredAt: number // unix epoch ms
|
||||
lastSeenAt: number
|
||||
lastCheckedAt?: number
|
||||
failureCount: number
|
||||
successCount: number
|
||||
}
|
||||
|
||||
interface RegistryBackend {
|
||||
register(instance: ServiceRegistration): Promise<void>
|
||||
deregister(id: string): Promise<void>
|
||||
get(id: string): Promise<ServiceInstance | undefined>
|
||||
list(name?: string, tags?: string[]): Promise<ServiceInstance[]>
|
||||
refresh(id: string): Promise<void> // reset TTL
|
||||
updateStatus(id: string, status: ServiceStatus): Promise<void>
|
||||
}
|
||||
|
||||
interface ServiceRegistryOptions {
|
||||
backend?: RegistryBackend // default: MemoryRegistryBackend
|
||||
events?: EventBusLike // for change notifications
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
}
|
||||
|
||||
class ServiceRegistry {
|
||||
constructor(options?: ServiceRegistryOptions)
|
||||
register(registration: ServiceRegistration): Promise<void>
|
||||
deregister(id: string): Promise<void>
|
||||
refresh(id: string): Promise<void>
|
||||
get(id: string): Promise<ServiceInstance | undefined>
|
||||
list(name?: string, tags?: string[]): Promise<ServiceInstance[]>
|
||||
listHealthy(name: string, tags?: string[]): Promise<ServiceInstance[]>
|
||||
startHealthChecks(client?: HttpClient): void
|
||||
stopHealthChecks(): void
|
||||
}
|
||||
|
||||
interface ServiceResolverOptions {
|
||||
registry: ServiceRegistry
|
||||
strategy?: LoadBalancingStrategy // default: 'round-robin'
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
}
|
||||
|
||||
class ServiceResolver {
|
||||
constructor(options: ServiceResolverOptions)
|
||||
resolve(name: string, tags?: string[]): Promise<ServiceInstance>
|
||||
resolveAll(name: string, tags?: string[]): Promise<ServiceInstance[]>
|
||||
}
|
||||
|
||||
function createServiceRegistry(options?: ServiceRegistryOptions): ServiceRegistry
|
||||
function createServiceResolver(options: ServiceResolverOptions): ServiceResolver
|
||||
|
||||
// In-memory backend (default)
|
||||
class MemoryRegistryBackend implements RegistryBackend { ... }
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type ServiceDiscoveryErrorCode =
|
||||
| 'SERVICE_DISCOVERY_NOT_FOUND'
|
||||
| 'SERVICE_DISCOVERY_ALREADY_REGISTERED'
|
||||
| 'SERVICE_DISCOVERY_HEALTH_CHECK_FAILED'
|
||||
| 'SERVICE_DISCOVERY_NO_HEALTHY_INSTANCES'
|
||||
| 'SERVICE_DISCOVERY_TTL_EXPIRED'
|
||||
| 'SERVICE_DISCOVERY_INVALID_REGISTRATION'
|
||||
|
||||
const SERVICE_DISCOVERY_ERROR_METADATA: Readonly<Record<ServiceDiscoveryErrorCode, CodeMetadata>>
|
||||
function registerServiceDiscoveryErrorCodes(): void
|
||||
```
|
||||
|
||||
### Zod schemas
|
||||
|
||||
```ts
|
||||
ServiceEndpointSchema
|
||||
HealthCheckSchema
|
||||
ServiceRegistrationSchema
|
||||
ServiceInstanceSchema
|
||||
ServiceRegistryOptionsSchema
|
||||
ServiceResolverOptionsSchema
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Pluggable `RegistryBackend`** — `MemoryRegistryBackend` ships by default; callers can swap to Redis, SurrealDB, or any other store implementing the interface.
|
||||
2. **Health-check scheduler** — HTTP probes use `@suaveplan/network` `HttpClient`; TCP probes use injected `net.connect`-compatible function. All timers use injectable `Clock`.
|
||||
3. **TTL expiry** — background sweeper removes expired registrations; sweep interval = min(TTL) / 2.
|
||||
4. **Event notifications** — `'service:registered'`, `'service:deregistered'`, `'service:status-changed'` events emitted on `EventBusLike`.
|
||||
5. **Load balancing** — four strategies: round-robin (stateful cursor), weighted (WRR), random (injected RNG), first-healthy (deterministic).
|
||||
6. **`AbortSignal` propagation** — `resolve` accepts optional signal; throws `ServiceDiscoveryError(SERVICE_DISCOVERY_NO_HEALTHY_INSTANCES)` on abort.
|
||||
7. **OTel instrumentation** — counter `service_discovery.register_total`, counter `service_discovery.resolve_total`, histogram `service_discovery.resolve_duration_ms`, counter `service_discovery.health_check_total` (attr `service_discovery.result`).
|
||||
8. **Property-based tests** — round-robin resolves to all registered healthy instances in N calls (no skips), weighted strategy probability distribution converges, register+deregister+list invariants.
|
||||
9. **Benchmark suite** — `register` 100 services, `resolve` hot path (round-robin, 1000 instances), health check scheduler overhead.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/network/service-discovery/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
service-registry/
|
||||
service-registry.ts
|
||||
service-registry.md
|
||||
service-registry.types.ts
|
||||
service-registry.test.ts
|
||||
index.ts
|
||||
service-resolver/
|
||||
service-resolver.ts
|
||||
service-resolver.md
|
||||
service-resolver.types.ts
|
||||
service-resolver.test.ts
|
||||
index.ts
|
||||
backends/
|
||||
memory-backend/
|
||||
memory-backend.ts
|
||||
memory-backend.md
|
||||
memory-backend.test.ts
|
||||
index.ts
|
||||
health/
|
||||
http-probe/
|
||||
http-probe.ts
|
||||
http-probe.md
|
||||
http-probe.test.ts
|
||||
index.ts
|
||||
tcp-probe/
|
||||
tcp-probe.ts
|
||||
tcp-probe.md
|
||||
tcp-probe.test.ts
|
||||
index.ts
|
||||
health-scheduler/
|
||||
health-scheduler.ts
|
||||
health-scheduler.md
|
||||
health-scheduler.test.ts
|
||||
index.ts
|
||||
balancing/
|
||||
round-robin/
|
||||
round-robin.ts
|
||||
round-robin.md
|
||||
round-robin.test.ts
|
||||
index.ts
|
||||
weighted/
|
||||
weighted.ts
|
||||
weighted.md
|
||||
weighted.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
service-discovery.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: any microservice or multi-peer architecture on genesis; `@suaveplan/api-gateway` consumers.
|
||||
**Breaking changes**: none — fresh build.
|
||||
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/retry` published to Verdaccio.
|
||||
Reference in New Issue
Block a user