mirror of
https://github.com/samjage/metro-warden.git
synced 2026-06-06 01:10:42 +00:00
137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# Metro Warden
|
||
|
||
**Industrial dark metro map Network Operations Centre — Python Textual TUI**
|
||
|
||
Metro Warden is a keyboard-driven terminal UI for monitoring network
|
||
interfaces, routing tables, firewall rules, DNS health, and system resources.
|
||
It is built on [Textual](https://github.com/Textualize/textual) and follows a
|
||
pub/sub event-bus architecture with a single source of truth state store and
|
||
a plugin system.
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ MetroWarden (App) │
|
||
│ ┌──────────┐ ┌───────────┐ ┌──────────────────────────┐ │
|
||
│ │ EventBus │ │StateStore │ │ PluginRegistry │ │
|
||
│ │ pub/sub │◄─│ reactive │ │ network dns firewall sys │ │
|
||
│ └──────────┘ └───────────┘ └──────────────────────────┘ │
|
||
│ ▲ ▲ │ │
|
||
│ │ │ publishes │ │
|
||
│ ┌────┴───────────────────────────────┐ │ │
|
||
│ │ UI Tabs │◄─┘ │
|
||
│ │ Lines · Routes · Signals │ │
|
||
│ │ Chronicle · Registry · Garrison │ │
|
||
│ │ Settings │ │
|
||
│ └────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Core
|
||
|
||
| Module | Purpose |
|
||
|--------|---------|
|
||
| `core/bus.py` | Asyncio pub/sub event bus with wildcard topic support |
|
||
| `core/state.py` | Reactive state store; watchers + bus publication on change |
|
||
| `core/registry.py` | Plugin discovery, loading, lifecycle management |
|
||
| `core/app.py` | Main `MetroWarden(App)` class — wires everything together |
|
||
|
||
### Plugins
|
||
|
||
| Plugin | Topics published |
|
||
|--------|-----------------|
|
||
| `network` | `network.interfaces`, `network.stats` |
|
||
| `dns` | `dns.resolvers`, `dns.health`, `dns.query.result` |
|
||
| `firewall` | `firewall.rules`, `firewall.chains` |
|
||
| `system` | `system.cpu`, `system.memory`, `system.disk`, `system.load`, `system.snapshot` |
|
||
|
||
### Tabs
|
||
|
||
| Tab | Key | Content |
|
||
|-----|-----|---------|
|
||
| Lines | `1` | Network interfaces — name, status, IP, RX/TX |
|
||
| Routes | `2` | System routing table |
|
||
| Signals | `3` | Live scrolling event monitor |
|
||
| Chronicle | `4` | Persistent log viewer with filtering |
|
||
| Registry | `5` | Plugin status and toggle |
|
||
| Garrison | `6` | Firewall chains and rules |
|
||
| Settings | `7` | Configuration form |
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
# Create a virtual environment
|
||
python -m venv .venv
|
||
source .venv/bin/activate # or .venv\Scripts\activate on Windows
|
||
|
||
# Install dependencies
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
## Running
|
||
|
||
```bash
|
||
python main.py
|
||
|
||
# With debug logging
|
||
python main.py --debug
|
||
|
||
# Log to file
|
||
python main.py --log-file metro-warden.log
|
||
|
||
# Custom config
|
||
python main.py --config /path/to/config.toml
|
||
```
|
||
|
||
Or via the installed script:
|
||
|
||
```bash
|
||
metro-warden
|
||
```
|
||
|
||
## Keybindings
|
||
|
||
| Key | Action |
|
||
|-----|--------|
|
||
| `1–7` | Switch tab |
|
||
| `q` | Quit |
|
||
| `Ctrl+R` | Reload all plugins |
|
||
| `r` | Refresh current tab (where supported) |
|
||
| `c` | Clear log (Signals / Chronicle) |
|
||
| `p` | Pause Signals stream |
|
||
| `f` | Focus filter input (Chronicle) |
|
||
| `Enter` | Toggle plugin load (Registry) |
|
||
| `s` | Save settings (Settings) |
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
pytest
|
||
pytest --cov
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Edit `config/defaults.toml` to adjust poll intervals, enable/disable plugins,
|
||
and set display limits. The Settings tab writes back to this file on save.
|
||
|
||
## Theme
|
||
|
||
The industrial dark metro map aesthetic uses:
|
||
|
||
| Role | Colour |
|
||
|------|--------|
|
||
| Background | `#1a1a2e` deep charcoal |
|
||
| Surface / panels | `#16213e` |
|
||
| Primary / electric blue | `#00d4ff` |
|
||
| Active / green | `#00ff88` |
|
||
| Warning / amber | `#ff8c00` |
|
||
| Error / red | `#ff4444` |
|
||
|
||
CSS overrides live in `assets/styles/metro.tcss`.
|