106 lines
5.5 KiB
Markdown
106 lines
5.5 KiB
Markdown
# OpenSpec Change: network-plugin-simulation
|
|
|
|
- **Change ID**: network-plugin-simulation
|
|
- **Package**: `@suaveplan/network-plugin-simulation` (new)
|
|
- **Status**: PROPOSED
|
|
- **Type**: new-package
|
|
- **Date**: 2026-04-29
|
|
|
|
## Why
|
|
|
|
Validating network resilience requires testing scenarios that are dangerous or impossible to reproduce in production: cascading host failures, network partitions, sudden client surges, and symmetric NAT blockages. A simulation framework enables deterministic, reproducible testing of the entire network stack under controlled conditions. This is essential for verifying the resilience claims of the tiered mesh architecture.
|
|
|
|
This plugin provides **virtual network environments** for testing: virtual nodes, predefined scenarios, network condition injection, and deterministic execution with seeded randomness.
|
|
|
|
## What changes
|
|
|
|
- **ADDED**: `SimulationPlugin` class implementing `NetworkPlugin` (dev-only, no-op in production).
|
|
- **ADDED**: `NetworkSimulator` — creates and manages virtual networks. Supports:
|
|
- Deterministic simulation with configurable seed
|
|
- Time acceleration/deceleration (simulated time vs wall-clock time)
|
|
- Virtual node factories with configurable capabilities
|
|
- Network topology creation (star, mesh, tiered, custom)
|
|
- **ADDED**: `ScenarioRunner` — executes predefined test scenarios with setup, event sequence, success criteria, and metric collection. Supports checkpointing for long scenarios.
|
|
- **ADDED**: `VirtualNode` — simulated peer that uses the same `NetworkNode` and plugin code as real nodes but operates in simulated time with injected `TimerController`.
|
|
- **ADDED**: `NetworkConditionInjector` — simulates realistic network conditions:
|
|
- Latency models: constant, random distribution, geographic-based
|
|
- Packet loss patterns: random, burst, connection-based
|
|
- Bandwidth limitations: fixed, variable, congestion-based
|
|
- Jitter: latency variation over time
|
|
- Connection disruptions: temporary and permanent
|
|
- **ADDED**: `ChaosEngine` — injects random failures for chaos testing:
|
|
- Probabilistic peer crashes
|
|
- Targeted transport failures
|
|
- Partition injection
|
|
- Random message drops
|
|
- **ADDED**: `PredefinedScenarios`:
|
|
- `ServerFailureScenario` — disconnect server, verify client-side takeover
|
|
- `NetworkPartitionScenario` — split mesh, verify independent operation, heal and reconcile
|
|
- `ClientSurgeScenario` — rapid peer growth, verify promotion and hierarchy adaptation
|
|
- `CascadingFailureScenario` — sequential host failures, verify circuit breaker and recovery
|
|
- **ADDED**: `NETWORK_SIM_CODES` — frozen error registry.
|
|
|
|
## Scenario definition format
|
|
|
|
```typescript
|
|
interface SimulationScenario {
|
|
name: string;
|
|
seed: number;
|
|
initialTopology: NetworkTopologyConfig;
|
|
nodeCount: number;
|
|
events: ScenarioEvent[];
|
|
networkConditions: NetworkConditionConfig;
|
|
successCriteria: SuccessCriterion[];
|
|
}
|
|
|
|
interface ScenarioEvent {
|
|
timeMs: number; // simulated time
|
|
type: 'join' | 'leave' | 'fail' | 'partition' | 'heal' | 'condition-change';
|
|
targetPeerIds?: string[];
|
|
condition?: NetworkConditionConfig;
|
|
}
|
|
```
|
|
|
|
## Out of scope
|
|
|
|
- Production deployment → this is a dev/test-only package.
|
|
- Performance benchmarking → `network-plugin-monitor` provides production metrics.
|
|
- Visual simulation UI → `network-plugin-devtools` provides visualization.
|
|
|
|
## Source mapping
|
|
|
|
This derives from `docs/old-network-planning/PHASE_8.md` §Simulation Framework and `PHASE_10.md` §End-to-End Tests.
|
|
|
|
| Requirement | Source lines | Notes |
|
|
|---|---|---|
|
|
| Virtual node factories | `PHASE_8.md` §Virtual Node Implementation | reworded; uses real `NetworkNode` code |
|
|
| Scenario runner | `PHASE_8.md` §Scenario Runner | reworded; declarative format |
|
|
| Network condition simulation | `PHASE_8.md` §Network Condition Simulation | verbatim: latency, loss, bandwidth, jitter |
|
|
| Predefined scenarios | `PHASE_8.md` §Predefined Simulation Scenarios | verbatim: 4 scenarios |
|
|
| Deterministic simulation | `PHASE_8.md` §Simulation Framework | verbatim: seed support |
|
|
|
|
### Requirements with no source line
|
|
|
|
| Requirement | Justification |
|
|
|---|---|
|
|
| `ChaosEngine` | Required for randomized failure injection beyond predefined scenarios |
|
|
| Time acceleration | Required to run long scenarios quickly in CI |
|
|
| Checkpointing | Required for debugging long-running scenario failures |
|
|
|
|
## Verification approach
|
|
|
|
- `src/simulator/simulator.spec-conformance.test.ts` — pins virtual network creation, seed determinism, time control.
|
|
- `src/scenario/scenario.spec-conformance.test.ts` — pins scenario execution, success criteria, event sequencing.
|
|
- `src/virtual-node/virtual-node.spec-conformance.test.ts` — pins behavior fidelity, resource simulation.
|
|
- `src/conditions/conditions.spec-conformance.test.ts` — pins latency, loss, bandwidth, jitter injection.
|
|
- `src/chaos/chaos.spec-conformance.test.ts` — pins random failures, partition injection, message drops.
|
|
- `src/scenarios/server-failure.spec-conformance.test.ts` — pins server disconnect, client takeover.
|
|
- `src/scenarios/partition.spec-conformance.test.ts` — pins split, independent operation, heal, reconcile.
|
|
- `src/scenarios/client-surge.spec-conformance.test.ts` — pins rapid growth, promotion, stabilization.
|
|
- `src/scenarios/cascading-failure.spec-conformance.test.ts` — pins sequential failures, circuit breaker, recovery.
|
|
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
|
|
|
## Migration impact
|
|
|
|
None — additive only. This package is dev-only and not imported in production builds.
|