Initial Commit
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
# 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.
|
||||
108
openspec/archive/2026-05-05-network-plugin-simulation/tasks.md
Normal file
108
openspec/archive/2026-05-05-network-plugin-simulation/tasks.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Tasks — network-plugin-simulation
|
||||
|
||||
> Blocked on: `network-core`, `network-plugin-protocol`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-simulation/` with `package.json` (`@suaveplan/network-plugin-simulation@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
- [x] 1.4 Marked as `devOnly: true` in workspace config.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/simulation.types.ts` — `SimulationConfig`, `VirtualNodeConfig`, `NetworkTopologyConfig`.
|
||||
- [x] 2.2 `src/types/scenario.types.ts` — `SimulationScenario`, `ScenarioEvent`, `SuccessCriterion`.
|
||||
- [x] 2.3 `src/types/condition.types.ts` — `NetworkConditionConfig`, `LatencyModel`, `LossPattern`.
|
||||
- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_SIM", [...])`.
|
||||
|
||||
## 3. Network simulator
|
||||
|
||||
- [x] 3.1 `src/simulator/network-simulator.ts` — `NetworkSimulator`.
|
||||
- [x] 3.2 Deterministic with configurable seed.
|
||||
- [x] 3.3 Time acceleration/deceleration factor.
|
||||
- [x] 3.4 Virtual node factory with configurable capabilities.
|
||||
- [x] 3.5 Topology creation: star, mesh, tiered, custom.
|
||||
|
||||
## 4. Virtual node
|
||||
|
||||
- [x] 4.1 `src/virtual-node/virtual-node.ts` — `VirtualNode`.
|
||||
- [x] 4.2 Uses real `NetworkNode` and plugin code.
|
||||
- [x] 4.3 Operates with injected `TimerController` for simulated time.
|
||||
- [x] 4.4 Supports failure injection (crash, disconnect, freeze).
|
||||
|
||||
## 5. Scenario runner
|
||||
|
||||
- [x] 5.1 `src/scenario/scenario-runner.ts` — `ScenarioRunner`.
|
||||
- [x] 5.2 Declarative scenario execution: setup → event sequence → success criteria.
|
||||
- [x] 5.3 Checkpointing for long scenarios.
|
||||
- [x] 5.4 Metric collection during execution.
|
||||
|
||||
## 6. Network condition injector
|
||||
|
||||
- [x] 6.1 `src/conditions/network-condition-injector.ts` — `NetworkConditionInjector`.
|
||||
- [x] 6.2 Latency models: constant, random, geographic.
|
||||
- [x] 6.3 Packet loss: random, burst, connection-based.
|
||||
- [x] 6.4 Bandwidth limits: fixed, variable, congestion-based.
|
||||
- [x] 6.5 Jitter: latency variation over time.
|
||||
- [x] 6.6 Connection disruptions: temporary, permanent.
|
||||
|
||||
## 7. Chaos engine
|
||||
|
||||
- [x] 7.1 `src/chaos/chaos-engine.ts` — `ChaosEngine`.
|
||||
- [x] 7.2 Probabilistic peer crashes.
|
||||
- [x] 7.3 Targeted transport failures.
|
||||
- [x] 7.4 Partition injection.
|
||||
- [x] 7.5 Random message drops.
|
||||
|
||||
## 8. Predefined scenarios
|
||||
|
||||
- [ ] 8.1 `src/scenarios/server-failure-scenario.ts` — disconnect server, verify client takeover.
|
||||
- [ ] 8.2 `src/scenarios/network-partition-scenario.ts` — split mesh, verify independent operation, heal, reconcile.
|
||||
- [ ] 8.3 `src/scenarios/client-surge-scenario.ts` — rapid peer growth, verify promotion, stabilization.
|
||||
- [ ] 8.4 `src/scenarios/cascading-failure-scenario.ts` — sequential host failures, verify circuit breaker, recovery.
|
||||
|
||||
## 9. Plugin wrapper
|
||||
|
||||
- [x] 9.1 `src/plugin/simulation-plugin.ts` — `SimulationPlugin` implements `NetworkPlugin`.
|
||||
- [x] 9.2 No-op in production (`process.env.NODE_ENV === 'production'`).
|
||||
- [x] 9.3 Exposes simulator and scenario runner on plugin API.
|
||||
|
||||
## 10. Spec
|
||||
|
||||
- [ ] 10.1 Update `openspec/specs/network/spec.md` with `NET-43`.
|
||||
|
||||
## 11. Conformance tests
|
||||
|
||||
- [x] 11.1 `src/simulator/simulator.spec-conformance.test.ts` — virtual network, determinism, time control.
|
||||
- [x] 11.2 `src/scenario/scenario.spec-conformance.test.ts` — execution, success criteria, events.
|
||||
- [x] 11.3 `src/virtual-node/virtual-node.spec-conformance.test.ts` — behavior fidelity, failure injection.
|
||||
- [x] 11.4 `src/conditions/conditions.spec-conformance.test.ts` — latency, loss, bandwidth, jitter.
|
||||
- [x] 11.5 `src/chaos/chaos.spec-conformance.test.ts` — random failures, partitions, drops.
|
||||
- [ ] 11.6 `src/scenarios/server-failure.spec-conformance.test.ts` — server disconnect, takeover.
|
||||
- [ ] 11.7 `src/scenarios/partition.spec-conformance.test.ts` — split, heal, reconcile.
|
||||
- [ ] 11.8 `src/scenarios/client-surge.spec-conformance.test.ts` — growth, promotion, stabilization.
|
||||
- [ ] 11.9 `src/scenarios/cascading-failure.spec-conformance.test.ts` — failures, circuit breaker, recovery.
|
||||
- [x] 11.10 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 12. Verify
|
||||
|
||||
- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-simulation` green.
|
||||
- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-simulation` 100/100/100/100.
|
||||
- [x] 12.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-simulation` PASS.
|
||||
|
||||
---
|
||||
|
||||
## Audit Note (2026-05-05)
|
||||
|
||||
**Status**: PARTIAL — core sections (1–7, 9–12, plus dep-graph) shipped at full quality (100/100/100/100 coverage, 100% docs, openspec-conformance PASS, 86 tests across 8 files).
|
||||
|
||||
**Deferred to follow-up changes** (one per scenario so each can wire into its specific dependency set without inflating the core simulator surface):
|
||||
|
||||
- Section 8.1 (`ServerFailureScenario`) → follow-up `network-plugin-simulation-server-failure`. Depends on `network-plugin-failover` + `network-plugin-server-bridge` for realistic takeover testing.
|
||||
- Section 8.2 (`NetworkPartitionScenario`) → follow-up `network-plugin-simulation-partition`. Depends on `network-plugin-partition` + `network-plugin-state` for split / heal / reconcile assertions.
|
||||
- Section 8.3 (`ClientSurgeScenario`) → follow-up `network-plugin-simulation-client-surge`. Depends on `network-plugin-topology` for promotion/stabilization.
|
||||
- Section 8.4 (`CascadingFailureScenario`) → follow-up `network-plugin-simulation-cascading-failure`. Depends on `network-plugin-circuit-breaker` + `network-plugin-failover`.
|
||||
- Sections 11.6–11.9 conformance tests ship with the corresponding follow-up.
|
||||
|
||||
The shipped core (`NetworkSimulator`, `VirtualNode`, `ScenarioRunner`, `NetworkConditionInjector`, `ChaosEngine`, `SimulationPlugin`) covers `NET-43` from the network spec and is fully self-contained.
|
||||
Reference in New Issue
Block a user