zacheryasc
402a106beb
Major feature addition. For full details read `./docs/development_history/DISTRIBUTION.md` Signed-off-by: Zachery Aaron Shores-Chmielewski <zacheryasc@gmail.com>
126 lines
5.4 KiB
Markdown
126 lines
5.4 KiB
Markdown
# gossip-dashboard
|
|
|
|
Interactive web dashboard for visualizing gossip protocol simulations.
|
|
|
|
The workflow has two steps:
|
|
|
|
1. **Generate traces** -- run simulations against TOML config files, producing `.trace.json` files.
|
|
2. **Replay traces** -- start the dashboard server, point it at a directory of traces, and explore them in the browser.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# 1. Generate traces from the bundled configs (outputs to traces/)
|
|
cargo run -p gossip-dashboard --example generate_traces
|
|
|
|
# 2. Launch the dashboard
|
|
cargo run -p gossip-dashboard --example replay -- traces
|
|
# => open http://localhost:8080
|
|
```
|
|
|
|
## Commands
|
|
|
|
### `generate_traces`
|
|
|
|
Runs gossip simulations and writes `.trace.json` files.
|
|
|
|
```
|
|
generate_traces # all bundled configs -> traces/
|
|
generate_traces <out-dir> # all bundled configs -> <out-dir>/
|
|
generate_traces <out-dir> <config.toml> [more.toml …] # specific configs -> <out-dir>/
|
|
```
|
|
|
|
Bundled configs live in `examples/configs/`. When no config paths are given, every `.toml` in that directory is run.
|
|
|
|
Output filenames are derived from the simulation name (lowercased, spaces to underscores). Example output:
|
|
|
|
```
|
|
traces/
|
|
ring_10_nodes.trace.json
|
|
star_7_nodes.trace.json
|
|
chain_8_nodes.trace.json
|
|
full_mesh_6_nodes.trace.json
|
|
partition_&_heal_8_nodes.trace.json
|
|
```
|
|
|
|
### `replay`
|
|
|
|
Starts an HTTP server that serves the dashboard UI and the trace data.
|
|
|
|
```
|
|
replay <trace-dir> [port]
|
|
```
|
|
|
|
| Argument | Required | Default | Description |
|
|
|-------------|----------|---------|------------------------------------------|
|
|
| `trace-dir` | yes | -- | Directory containing `.trace.json` files |
|
|
| `port` | no | 8080 | Port to bind on |
|
|
|
|
The server exposes three endpoints:
|
|
|
|
| Route | Description |
|
|
|--------------------------|------------------------------------|
|
|
| `GET /` | Dashboard HTML |
|
|
| `GET /traces` | JSON list of available trace files |
|
|
| `GET /trace.json?file=…` | Fetch a specific trace |
|
|
|
|
## Configuration (TOML)
|
|
|
|
Each simulation is defined by a TOML file. Example (`ring_10.toml`):
|
|
|
|
```toml
|
|
name = "Ring (10 nodes)"
|
|
topology = "ring"
|
|
num_nodes = 10
|
|
num_rounds = 15
|
|
ticks_per_round = 5
|
|
num_threads = 1
|
|
|
|
[initial_data]
|
|
color = "blue"
|
|
version = "1"
|
|
status = "active"
|
|
```
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|--------------------|-------------------|----------|-------------------------------------------------------------------|
|
|
| `name` | string | yes | Display name for the simulation |
|
|
| `topology` | string | yes | Network topology (see below) |
|
|
| `num_nodes` | integer | yes | Number of gossip nodes |
|
|
| `num_rounds` | integer | yes | Number of gossip rounds to run |
|
|
| `ticks_per_round` | integer | yes | Simulation ticks per round |
|
|
| `num_threads` | integer | yes | Worker threads (`1` = deterministic single-threaded) |
|
|
| `heal_after_round` | integer | no | Round after which partitioned halves are bridged |
|
|
| `initial_data` | table of strings | no | Key-value pairs seeded on node 0 before gossip begins |
|
|
|
|
### Topologies
|
|
|
|
| Value | Shape |
|
|
|---------------|--------------------------------------------------------------------------|
|
|
| `ring` | Each node connects to the next, forming a circle |
|
|
| `star` | Node 0 is a hub with bidirectional links to every other node |
|
|
| `full_mesh` | Every node connects bidirectionally to every other node |
|
|
| `chain` | Unidirectional chain: node 0 -> 1 -> 2 -> ... -> N-1 |
|
|
| `partitioned` | Two isolated full-mesh halves; use `heal_after_round` to bridge them |
|
|
|
|
## Bundled configs
|
|
|
|
| File | Topology | Nodes | Rounds | Notes |
|
|
|---------------------------|-------------|-------|--------|----------------------------|
|
|
| `ring_10.toml` | ring | 10 | 15 | |
|
|
| `star_7.toml` | star | 7 | 10 | |
|
|
| `full_mesh_6.toml` | full_mesh | 6 | 8 | |
|
|
| `chain_8.toml` | chain | 8 | 20 | |
|
|
| `partitioned_8_heal.toml` | partitioned | 8 | 20 | Heals after round 10 |
|
|
|
|
## Dashboard UI
|
|
|
|
Once a trace is loaded in the browser:
|
|
|
|
- **Graph canvas** -- nodes arranged in a circle then refined with force-directed layout. Nodes and edges flash as events are replayed.
|
|
- **Stats panel** -- total nodes, edges, messages, current round.
|
|
- **Worker logs** -- per-thread activity feed.
|
|
- **Event table** -- full event log with columns: Seq, Round, Thread, Node, Event, Details.
|
|
- **Playback controls** -- First / Prev / Play / Pause / Next / Last, timeline slider, speed adjustment (10 ms -- 2000 ms per event).
|