first commit
This commit is contained in:
106
docs/networking/network/network-plugin-devtools/README.md
Normal file
106
docs/networking/network/network-plugin-devtools/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# @suaveplan/network-plugin-devtools - Developer-tools plugin for the Suaveplan mesh: NetworkVisualizer (hierarchy/flow/heat-map IR + injectable Renderer + bundled SVG renderer), StateInspector (tree view, ring-buffer history, RFC-6902-style diff via @suaveplan/diff, search/filter), SimulationConfigTool (programmatic topology + condition + event-timeline editor with JSON scenario export/import), PerformanceProfiler (latency p50/p95/p99 distribution, throughput, plugin overhead, memory tracking, two-window EMA regression detection, optimization suggestions), and DevToolsPlugin facade with tier gate and no-op-in-production guard.
|
||||
|
||||
## Summary
|
||||
|
||||
Developer-tools plugin for the Suaveplan mesh. Bundles four subsystems behind
|
||||
a single `NetworkPlugin` lifecycle so engineers can inspect, visualise, and
|
||||
profile the live network from the same node they run their tests against. The
|
||||
plugin is dev-only by contract: a `tierGate` callback decides activation at
|
||||
install time, and `requireActive()` raises `PLUGIN_DEV_DISABLED` so production
|
||||
call sites cannot silently exercise devtools work paths.
|
||||
|
||||
`DevToolsPlugin` ties the four subsystems together:
|
||||
|
||||
- **`NetworkVisualizer`** — renders the mesh as a `VisualizerScene` IR (hierarchy / flow / heat-map modes), supports filtering by tier / latency-group / session / transport, and exports to SVG (bundled `SvgRenderer`) or PNG / canvas / WebGL via injected `Renderer`.
|
||||
- **`StateInspector`** — per-path state browser with bounded ring-buffer history, RFC-6902-style diff via `@suaveplan/diff`, timeline scrubber (`scrub`), and composable `search` over `pathContains` / `peerId` / `sessionId` / version range.
|
||||
- **`SimulationConfigTool`** — programmatic scenario builder (peers, links, conditions, timeline events) with deterministic recording, playback grouping by `atMs`, and Zod-validated JSON export / import for sharing scenarios across teams.
|
||||
- **`PerformanceProfiler`** — latency p50 / p95 / p99 distribution, throughput per path, plugin overhead, memory tracking, two-window EMA + Z-score regression detection against named baselines, and category-tagged optimisation suggestions.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [inspector](./src/inspector/state-inspector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [state-inspector](./src/inspector/state-inspector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [devtools-plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [performance-profiler](./src/profiler/performance-profiler.md) — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
|
||||
- [performance-profiler.suggestions](./src/profiler/performance-profiler.suggestions.md) — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
|
||||
- [simulator](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [simulation-config-tool](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [network-visualizer](./src/visualizer/network-visualizer.md) — Renders the live mesh as a `VisualizerScene` intermediate representation (IR) and delegates byte production to an injec…
|
||||
- [svg-renderer](./src/visualizer/svg-renderer.md) — Pure-string SVG renderer that consumes a `VisualizerScene` and produces deterministic UTF-8 SVG bytes without touching…
|
||||
- [error-codes](./src/error-codes.md) — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
|
||||
<!-- end:auto-docs --> - [state-inspector](./src/inspector/state-inspector.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [devtools-plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [performance-profiler](./src/profiler/performance-profiler.md) — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
|
||||
- [performance-profiler.suggestions](./src/profiler/performance-profiler.suggestions.md) — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
|
||||
- [simulator](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [simulation-config-tool](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [network-visualizer](./src/visualizer/network-visualizer.md) — Renders the live mesh as a `VisualizerScene` intermediate representation (IR) and delegates byte production to an injec…
|
||||
- [svg-renderer](./src/visualizer/svg-renderer.md) — Pure-string SVG renderer that consumes a `VisualizerScene` and produces deterministic UTF-8 SVG bytes without touching…
|
||||
- [error-codes](./src/error-codes.md) — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
|
||||
- [state-inspector](./src/inspector/state-inspector.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [devtools-plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [performance-profiler](./src/profiler/performance-profiler.md) — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
|
||||
- [performance-profiler.suggestions](./src/profiler/performance-profiler.suggestions.md) — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
|
||||
- [simulator](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [simulation-config-tool](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [network-visualizer](./src/visualizer/network-visualizer.md) — Renders the live mesh as a `VisualizerScene` intermediate representation (IR) and delegates byte production to an injec…
|
||||
- [svg-renderer](./src/visualizer/svg-renderer.md) — Pure-string SVG renderer that consumes a `VisualizerScene` and produces deterministic UTF-8 SVG bytes without touching…
|
||||
- [error-codes](./src/error-codes.md) — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
|
||||
- [state-inspector](./src/inspector/state-inspector.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [devtools-plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [performance-profiler](./src/profiler/performance-profiler.md) — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
|
||||
- [performance-profiler.suggestions](./src/profiler/performance-profiler.suggestions.md) — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
|
||||
- [simulator](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [simulation-config-tool](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [network-visualizer](./src/visualizer/network-visualizer.md) — Renders the live mesh as a `VisualizerScene` intermediate representation (IR) and delegates byte production to an injec…
|
||||
- [svg-renderer](./src/visualizer/svg-renderer.md) — Pure-string SVG renderer that consumes a `VisualizerScene` and produces deterministic UTF-8 SVG bytes without touching…
|
||||
- [error-codes](./src/error-codes.md) — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
|
||||
- [state-inspector](./src/inspector/state-inspector.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ - [devtools-plugin](./src/plugin/devtools-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [performance-profiler](./src/profiler/performance-profiler.md) — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
|
||||
- [performance-profiler.suggestions](./src/profiler/performance-profiler.suggestions.md) — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
|
||||
- [simulator](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_ - [simulation-config-tool](./src/simulator/simulation-config-tool.md) — <!-- begin:auto-docs --> _(no submodules)_- [network-visualizer](./src/visualizer/network-visualizer.md) — Renders the live mesh as a `VisualizerScene` intermediate representation (IR) and delegates byte production to an injec…
|
||||
- [svg-renderer](./src/visualizer/svg-renderer.md) — Pure-string SVG renderer that consumes a `VisualizerScene` and produces deterministic UTF-8 SVG bytes without touching…
|
||||
- [error-codes](./src/error-codes.md) — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/network-plugin-devtools
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import { NetworkBus, NetworkNode } from "@suaveplan/network";
|
||||
import { DevToolsPlugin } from "@suaveplan/network-plugin-devtools";
|
||||
|
||||
const node = new NetworkNode({ id: "host-1", networkBus: new NetworkBus() });
|
||||
const devtools = new DevToolsPlugin({
|
||||
tierGate: () => process.env.NODE_ENV !== "production",
|
||||
topology: myTopologyAdapter,
|
||||
stream: myStreamAdapter,
|
||||
inspector: { historyLimit: 1024 },
|
||||
profiler: { regressionZScore: 2.5 },
|
||||
});
|
||||
|
||||
node.use(devtools);
|
||||
await node.start();
|
||||
|
||||
devtools.visualizer.start({ mode: "hierarchy", refreshRate: 30 });
|
||||
const svg = devtools.visualizer.export("svg");
|
||||
|
||||
devtools.inspector.record({
|
||||
path: "session/lobby",
|
||||
value: { players: 3 },
|
||||
version: 1,
|
||||
timestamp: Date.now(),
|
||||
peerId: "host-1",
|
||||
});
|
||||
|
||||
devtools.profiler.recordLatency("host-1->leaf-1", 42);
|
||||
const baseline = devtools.profiler.captureBaseline("v1.0.0");
|
||||
|
||||
devtools.simulator.addPeer({ id: "leaf-2", tier: "tier-2", capacity: 10 });
|
||||
const scenarioJson = devtools.simulator.exportJson();
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
- [`error-codes`](./src/error-codes.md) — `NETWORK_DEV_CODES` registry + `NetworkDevError`.
|
||||
- [`visualizer/network-visualizer`](./src/visualizer/network-visualizer.md) — IR-producing visualisation engine with three modes and pluggable renderer.
|
||||
- [`visualizer/svg-renderer`](./src/visualizer/svg-renderer.md) — bundled dep-free SVG renderer.
|
||||
- [`inspector/state-inspector`](./src/inspector/state-inspector.md) — per-path state browser, history, diff, search, scrubber.
|
||||
- [`simulator/simulation-config-tool`](./src/simulator/simulation-config-tool.md) — programmatic scenario builder with JSON round-trip.
|
||||
- [`profiler/performance-profiler`](./src/profiler/performance-profiler.md) — latency / throughput / overhead / memory tracking with regression detection.
|
||||
- [`profiler/performance-profiler.suggestions`](./src/profiler/performance-profiler.suggestions.md) — heuristic suggestion engine.
|
||||
- [`plugin/devtools-plugin`](./src/plugin/devtools-plugin.md) — facade satisfying `NetworkPlugin` with tier gate and production guard.
|
||||
|
||||
Reference in New Issue
Block a user