57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
# OpenSpec Change: network-plugin-failover
|
|
|
|
- **Change ID**: network-plugin-failover
|
|
- **Package**: `@suaveplan/network-plugin-failover` (new)
|
|
- **Status**: PROPOSED
|
|
- **Type**: new-package
|
|
- **Date**: 2026-04-29
|
|
|
|
## Why
|
|
|
|
The tiered network requires automatic recovery when a host (Tier 0) fails. The genesis `retry`, `fsm`, and `rate-limiter` packages provide primitives, but no plugin implements the host-failure detection, state transition, and emergency-election trigger. This plugin fills that gap by consuming peer health events from the bus and coordinating the `alive → suspect → dead → recovering` lifecycle.
|
|
|
|
## What changes
|
|
|
|
- **ADDED**: `FailoverPlugin` class implementing `NetworkPlugin`.
|
|
- **ADDED**: `FailoverCoordinator` — tracks peer health, manages state transitions, triggers elections.
|
|
- **ADDED**: `HeartbeatManager` — sends periodic heartbeats, collects responses, detects timeout.
|
|
- **ADDED**: `HealthMonitor` — maintains `alive | suspect | dead | recovering` states with configurable timeouts.
|
|
- **ADDED**: `PromoterManager` — when a host is declared dead, triggers an emergency election via `GovernancePlugin` events.
|
|
- **ADDED**: `NETWORK_FO_CODES` — frozen error registry.
|
|
|
|
## Out of scope
|
|
|
|
- Persistent state of failover log → future `network-plugin-failover-persistence`.
|
|
- Cross-group failover federation → future scope.
|
|
- Network partition detection (split-brain) → handled by `network-plugin-partition`. Failover manages single-host death (alive→suspect→dead). Partition manages group isolation (split-brain). The two plugins are complementary: failover emits heartbeat events that partition consumes for connectivity-map analysis.
|
|
|
|
## Source mapping
|
|
|
|
This change derives from `../suaveplan/enterprise/network-failover.md` and `../suaveplan/packages/universal/network-failover/`.
|
|
|
|
| Requirement | Source lines | Notes |
|
|
|---|---|---|
|
|
| Host failure detection (alive→suspect→dead) | `network-failover/README.md` §Failure Detection | verbatim |
|
|
| Heartbeat interval and timeout | `network-failover/README.md` §Configuration | verbatim |
|
|
| Automatic election trigger on dead host | `network-failover/README.md` §Automatic Recovery | verbatim |
|
|
|
|
### Requirements with no source line
|
|
|
|
| Requirement | Justification |
|
|
|---|---|
|
|
| Consumes `peer:connected`/`peer:disconnected` from bus | Decouples failover from transport implementation |
|
|
| Emits `failover:emergency-election` on bus | Loose coupling to governance plugin — no direct import |
|
|
| Uses `@suaveplan/rate-limiter` to throttle heartbeat bursts | Defensive — prevents self-DOS during mass disconnect |
|
|
|
|
## Verification approach
|
|
|
|
- `src/failover/failover.spec-conformance.test.ts` — pins state transitions, timeout, election trigger.
|
|
- `src/heartbeat/heartbeat.spec-conformance.test.ts` — pins interval, response, timeout.
|
|
- `src/health/health.spec-conformance.test.ts` — pins alive→suspect→dead→recovering.
|
|
- `src/promoter/promoter.spec-conformance.test.ts` — pins emergency election emission.
|
|
- `tests/dep-graph.test.ts` — pins no direct import of governance or transport packages.
|
|
|
|
## Migration impact
|
|
|
|
None — additive only.
|