Martino Ferrari
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# RMon Developer Guide
|
|
|
|
This guide covers the internal architecture, protocol, and extension points of the RMon system.
|
|
|
|
## Architecture Overview
|
|
|
|
RMon is built with a focus on performance, safety, and portability.
|
|
|
|
### `rmon-common`
|
|
Contains shared types used by both the agent and UI.
|
|
- **Protocol**: Defined in `src/protocol.rs`. Uses `bincode` for serialization over a length-prefixed TCP stream.
|
|
- **Data Model**: `src/signal.rs` defines `Sample`, `SignalInfo`, and `SignalId`.
|
|
|
|
### `rmon-agent`
|
|
A multi-threaded server using `tokio`.
|
|
- **Dispatcher**: Samples from all sources flow through a central `mpsc` channel to a dispatcher task.
|
|
- **Fan-out**: The dispatcher sends samples to:
|
|
1. The **Storage Engine** (binary append logs).
|
|
2. All connected **Session Handlers** via a `broadcast` channel.
|
|
- **DataSource Trait**: Abstract interface for data ingestion. New source types only need to implement the `run` and `signals` methods.
|
|
|
|
### `rmon-ui`
|
|
An immediate-mode GUI application.
|
|
- **Backend Thread**: A separate thread runs the `tokio` runtime for non-blocking network I/O.
|
|
- **Event Loop**: Communicates with the UI thread via `mpsc` channels (`UiMessage`).
|
|
- **Repaint Policy**: The UI only repaints when new data arrives or on a fixed interval (50ms) to ensure smooth real-time performance.
|
|
|
|
## Adding a New Data Source
|
|
|
|
To add a new source type (e.g., `MQTT` or `Serial`):
|
|
|
|
1. **Update Config**: Add relevant fields to `SourceConfig` and `SignalSourceConfig` in `rmon-agent/src/config.rs`.
|
|
2. **Implement `DataSource`**: Create a new file in `rmon-agent/src/sources/` and implement the trait:
|
|
```rust
|
|
#[async_trait]
|
|
pub trait DataSource: Send + 'static {
|
|
fn name(&self) -> &str;
|
|
fn signals(&self) -> Vec<SignalInfo>;
|
|
async fn run(self: Box<Self>, tx: mpsc::Sender<(SignalId, Sample)>) -> Result<()>;
|
|
}
|
|
```
|
|
3. **Register**: Add the source to `rmon-agent/src/sources/mod.rs` and update the `run_agent` loop in `rmon-agent/src/lib.rs`.
|
|
|
|
## Development Workflows
|
|
|
|
### Static Agent Build (Linux)
|
|
```bash
|
|
cargo build --release --target x86_64-unknown-linux-musl -p rmon-agent
|
|
```
|
|
|
|
### Integration Testing
|
|
The project uses automated integration tests that spin up real agent instances and verify the protocol flow.
|
|
```bash
|
|
cargo test -p rmon-agent --test agent_test
|
|
```
|
|
|
|
### Protocol Changes
|
|
If you modify `rmon-common/src/protocol.rs`:
|
|
1. Increment `PROTOCOL_VERSION` in `protocol.rs`.
|
|
2. Rebuild both the UI and the Agent.
|
|
3. The UI will automatically detect the version mismatch on handshake and refuse to connect to old agents.
|