100 lines
4.3 KiB
Markdown
100 lines
4.3 KiB
Markdown
# OpenSpec Change: network-plugin-devtools
|
|
|
|
- **Change ID**: network-plugin-devtools
|
|
- **Package**: `@suaveplan/network-plugin-devtools` (new)
|
|
- **Status**: PROPOSED
|
|
- **Type**: new-package
|
|
- **Date**: 2026-04-29
|
|
|
|
## Why
|
|
|
|
Debugging a distributed mesh network is notoriously difficult. Peers join and leave, messages are dropped, topology reorganizes, and state diverges. Without specialized developer tools, engineers must rely on console logs and guesswork. The old planning documents envisioned a comprehensive developer experience layer: real-time network visualization, interactive state inspection, simulation configuration, and performance profiling.
|
|
|
|
This plugin provides **developer tools** for the network layer: visualization, state inspection, simulation configuration, and performance analysis. It is dev-only and does not run in production.
|
|
|
|
## What changes
|
|
|
|
- **ADDED**: `DevToolsPlugin` class implementing `NetworkPlugin` (dev-only, no-op in production).
|
|
- **ADDED**: `NetworkVisualizer` — real-time visualization of the mesh:
|
|
- Hierarchy view: tier structure, host/sub-host/leaf nodes, parent-child edges
|
|
- Message flow view: animated message paths, throughput per link, dropped messages
|
|
- Performance heat map: latency color-coding, bandwidth saturation, error rates
|
|
- Filtering by tier, latency group, session, transport type
|
|
- Export to PNG/SVG for documentation
|
|
- **ADDED**: `StateInspector` — interactive state browser:
|
|
- Tree view of all synchronized state paths
|
|
- Historical state viewing with timeline scrubber
|
|
- Diff visualization between two state versions
|
|
- Search and filter by path, peer, or session
|
|
- **ADDED**: `SimulationConfigTool` — scenario builder UI:
|
|
- Drag-and-drop network topology editor
|
|
- Network condition editor (latency, loss, bandwidth curves)
|
|
- Event timeline editor
|
|
- Simulation recording and playback
|
|
- Scenario sharing (export/import JSON)
|
|
- **ADDED**: `PerformanceProfiler` — performance analysis:
|
|
- Message latency distribution (p50, p95, p99)
|
|
- Transport throughput per path
|
|
- Plugin overhead measurement
|
|
- Memory usage tracking
|
|
- Regression detection: compares current run against baseline
|
|
- Optimization suggestions based on bottlenecks
|
|
- **ADDED**: `NETWORK_DEV_CODES` — frozen error registry.
|
|
|
|
## DevTools API
|
|
|
|
```typescript
|
|
// Start visualization
|
|
visualizer.start({ mode: 'hierarchy', refreshRate: 30 });
|
|
|
|
// Focus on a specific peer
|
|
visualizer.focus(peerId);
|
|
|
|
// Inspect state at a path
|
|
inspector.inspect('game/positions/player1');
|
|
|
|
// Run a predefined scenario
|
|
simulator.runScenario('client-surge', { nodeCount: 100 });
|
|
|
|
// Compare performance against baseline
|
|
profiler.compare(baselineRunId);
|
|
```
|
|
|
|
## Out of scope
|
|
|
|
- Production monitoring → `network-plugin-monitor`.
|
|
- Production alerting → `network-plugin-monitor`.
|
|
- Simulation engine → `network-plugin-simulation`.
|
|
- Framework-specific UI components → future React/Vue/Angular wrappers.
|
|
|
|
## Source mapping
|
|
|
|
This derives from `docs/old-network-planning/ADAPT_5.md` §Developer Tooling and `PHASE_8.md` §Visualization.
|
|
|
|
| Requirement | Source lines | Notes |
|
|
|---|---|---|
|
|
| Network visualizer | `ADAPT_5.md` §Network Visualizer Tool | reworded; modes: hierarchy, messages, performance |
|
|
| State inspector | `ADAPT_5.md` §State Inspector Tool | reworded; diff visualization |
|
|
| Simulation config | `ADAPT_5.md` §Simulation Configuration Tool | reworded; scenario builder |
|
|
| Performance profiling | `ADAPT_5.md` §Performance Profiling Tools | reworded; regression detection |
|
|
|
|
### Requirements with no source line
|
|
|
|
| Requirement | Justification |
|
|
|---|---|
|
|
| Export to PNG/SVG | Required for documentation and bug reports |
|
|
| Regression detection | Required to catch performance degradation in CI |
|
|
| Scenario sharing | Required for team collaboration on test cases |
|
|
|
|
## Verification approach
|
|
|
|
- `src/visualizer/visualizer.spec-conformance.test.ts` — pins hierarchy rendering, message flow, heat map.
|
|
- `src/inspector/inspector.spec-conformance.test.ts` — pins state tree, history, diff.
|
|
- `src/simulator/simulator.spec-conformance.test.ts` — pins scenario builder, playback, export/import.
|
|
- `src/profiler/profiler.spec-conformance.test.ts` — pins latency distribution, overhead, regression.
|
|
- `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.
|