Tasks: enterprise-service-discovery

Change ID: enterprise-service-discovery Package: @suaveplan/service-discovery Target path: universal/network/service-discovery Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/network, @suaveplan/retry

0. Pre-flight (non-negotiable)

0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

Create directory universal/network/service-discovery/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/events workspace:^, @suaveplan/network workspace:^, @suaveplan/retry workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability.
Write tsconfig.json extending @suaveplan/typescript-config/library.json.
Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
Add lint, typecheck, test, test:coverage, build, docs:check scripts.

2. Types + errors

Write src/types/common.ts — all interfaces and type aliases from proposal.
Write src/types/common.md.
Write src/error-codes.ts — ServiceDiscoveryErrorCode, SERVICE_DISCOVERY_ERROR_METADATA, registerServiceDiscoveryErrorCodes().
Write Zod schemas: ServiceEndpointSchema, HealthCheckSchema, ServiceRegistrationSchema, ServiceInstanceSchema, ServiceRegistryOptionsSchema, ServiceResolverOptionsSchema.

3. MemoryRegistryBackend

Implement MemoryRegistryBackend implements RegistryBackend — Map<string, ServiceInstance> store, register/deregister/get/list/refresh/updateStatus. list supports optional name and tags filters (tag filter = intersection).
Write memory-backend.test.ts (≤500 lines): register, deregister, list with filters, refresh resets TTL, updateStatus.
Write memory-backend.md.

4. Health checks

HTTP probe

Implement runHttpProbe(endpoint, check, httpClient): Promise<boolean> — GET <protocol>://<host>:<port><path>, return true if status 2xx, false otherwise; timeout from check.timeoutMs.
Write http-probe.test.ts (uses stub HttpClient) and http-probe.md.

TCP probe

Implement runTcpProbe(endpoint, check, connectFn): Promise<boolean> — injectable connectFn(host, port): Promise<void> (abstracts net.connect); returns true on success within timeout.
Write tcp-probe.test.ts and tcp-probe.md.

Health scheduler

Implement HealthScheduler — for each registered instance with a healthCheck, runs probes on intervalMs using injectable Clock; updates ServiceInstance.status via backend; tracks consecutive failure/success counts; emits events on status change.
Write health-scheduler.test.ts (≤500 lines): probe triggers, failure threshold, success threshold, stop clears timers.
Write health-scheduler.md.

5. Load balancing strategies

Implement roundRobin(instances): ServiceInstance — stateful cursor (closure-based, not class-level to keep it pure).
Implement weighted(instances): ServiceInstance — weighted random selection (cumulative weight table + RNG via injectable function).
Write round-robin.test.ts, round-robin.md, weighted.test.ts, weighted.md.

6. ServiceRegistry

Implement ServiceRegistry — delegates to backend; TTL sweeper (setInterval on Clock); emits service:registered, service:deregistered, service:status-changed on events bus; startHealthChecks/stopHealthChecks.
Wire OTel: counter service_discovery.register_total, counter service_discovery.health_check_total.
Write service-registry.test.ts (≤500 lines): register, deregister, listHealthy, TTL expiry, event emission.
Write service-registry.md.

7. ServiceResolver

Implement ServiceResolver — resolve calls registry.listHealthy, applies load balancing strategy, throws SERVICE_DISCOVERY_NO_HEALTHY_INSTANCES if empty; resolveAll returns full healthy list.
Wire OTel: counter service_discovery.resolve_total, histogram service_discovery.resolve_duration_ms.
Write service-resolver.test.ts (≤500 lines): resolve with round-robin, weighted, random, first-healthy; empty list throws; abort signal.
Write service-resolver.md.

8. Benchmarks

Write src/__benchmarks__/service-discovery.bench.ts — register 100 services, resolve hot path round-robin 1000 instances, health check scheduler overhead.

9. Tests

Write tests/integration.test.ts — full lifecycle: register → health check → resolve → deregister.
Write tests/property.test.ts (fast-check) — round-robin covers all instances in N calls, weighted distribution converges, register+list invariants.

10. Docs + verify + publish

All co-located .md files (≥200 words each).
Write README.md at package root.
bunx turbo lint typecheck test --filter=@suaveplan/service-discovery — green.
bunx turbo test:coverage --filter=@suaveplan/service-discovery — 100%.
bun scripts/publish.ts --package @suaveplan/service-discovery.
Archive to openspec/archive/2026-04-24-enterprise-service-discovery/.

6.0 KiB Raw Permalink Blame History