rmon/DEVELOPER_GUIDE.md

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:

   #[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)

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.

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.