feat(tools): add openmonitor — TUI and web dashboard for openads_serverd

[Admnwk]

Summary

Adds tools/openmonitor/, a Rust lab/monitoring tool for a running openads_serverd instance.

Features

• Wire telemetry — reads MgRequest / MgSnapshot (uptime, connections, open tables, packet counters)
• Studio HTTP — lists active sessions via /api/server/sessions, kill session from TUI
• TUI — ratatui terminal UI with sparkline history
• Web dashboard — optional browser UI (--web, default :9850)
• CI-friendly — --once prints a text snapshot and exits

Build

cd tools/openmonitor
cargo build --release

Windows: build.bat (requires cargo on PATH).

Usage

openmonitor --wire-port 16262 --http http://127.0.0.1:16263
openmonitor --wire-port 16262 --http http://127.0.0.1:16263 --once
openmonitor --wire-port 16262 --http http://127.0.0.1:16263 --web

See tools/openmonitor/README.md for full CLI reference.

Notes

• Standalone Rust crate (not wired into CMake yet) — same pattern as optional tooling alongside tools/bench.
• Companion lab scripts live in a separate repo (openads-wire-lab); this PR only adds the monitor tool itself.
• Default wire port is 16262 (lab-friendly; avoids clashing with legacy default 6262).

Co-Authored-By: Grok Build (colab) noreply@x.ai

[gemini-code-assist]

Code Review

This pull request introduces openmonitor, a Rust-based terminal (TUI) and web dashboard monitor for the openads_serverd service, reading live telemetry from wire and HTTP APIs. The feedback highlights several critical issues: a compilation error in http_api.rs due to an invalid unwrap_or_default() call, a terminal state restoration bug in main.rs on early exit, blocking synchronous calls inside async Axum handlers in web.rs, a potential out-of-memory vulnerability in wire.rs from unconstrained network frame allocations, silently ignored JSON deserialization errors, and a potential out-of-bounds panic when the session list shrinks.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

unwrap_or_default() is called on the result of reqwest::blocking::Client::builder().build(). However, reqwest::blocking::Client does not implement Default. This will cause a compilation error. Using .expect("failed to build reqwest client") or handling the error is a safer and correct approach.

Suggested change

	client: reqwest::blocking::Client::builder()
	.timeout(std::time::Duration::from_secs(5))
	.build()
	.unwrap_or_default(),
	client: reqwest::blocking::Client::builder()
	.timeout(std::time::Duration::from_secs(5))
	.build()
	.expect("failed to build reqwest client"),

[gemini-code-assist]

If any of the ? operators inside run_tui (such as event::poll or event::read) return an error, the function will exit early before restoring the terminal state. This leaves the user's terminal in raw mode and alternate screen, which is a poor user experience. Wrapping the main loop in a closure or block and ensuring the cleanup code always runs before returning the result prevents this issue.

fn run_tui(app: &mut TuiState, cfg: &MonitorConfig, args: &Args) -> Result<()> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;
    let mut term = ratatui::init();

    let tick = Duration::from_secs(cfg.interval_secs);
    let mut needs_redraw = true;

    let res = (|| -> Result<()> {
        loop {
            if needs_redraw || app.last_refresh.elapsed() >= tick {
                app.refresh(cfg);
                needs_redraw = true;
            }

            if needs_redraw {
                term.draw(|f| ui(f, app, cfg, args))?;
                needs_redraw = false;
            }

            if event::poll(Duration::from_millis(200))? {
                if let Event::Key(key) = event::read()? {
                    if key.kind != KeyEventKind::Press {
                        continue;
                    }
                    match key.code {
                        KeyCode::Char('q') | KeyCode::Esc => break,
                        KeyCode::Char('r') => {
                            app.refresh(cfg);
                            app.status_msg = "refreshed".into();
                            needs_redraw = true;
                        }
                        KeyCode::Up => {
                            app.selected_session = app.selected_session.saturating_sub(1);
                            needs_redraw = true;
                        }
                        KeyCode::Down => {
                            if !app.inner.http.sessions.is_empty() {
                                app.selected_session = 
                                    (app.selected_session + 1).min(app.inner.http.sessions.len() - 1);
                            }
                            needs_redraw = true;
                        }
                        KeyCode::Char('g') => {
                            app.show_graphs = !app.show_graphs;
                            app.status_msg = if app.show_graphs {
                                "graphs on".into()
                            } else {
                                "graphs off".into()
                            };
                            needs_redraw = true;
                        }
                        KeyCode::Char('k') => {
                            if let (Some(base), Some(sess)) = 
                                (&cfg.http, app.inner.http.sessions.get(app.selected_session))
                            {
                                let client = HttpClient::new(base);
                                match client.kill_session(sess.id) {
                                    Ok(()) => {
                                        app.status_msg = format!("killed session {}", sess.id);
                                        app.refresh(cfg);
                                    }
                                    Err(e) => app.status_msg = format!("kill failed: {e}"),
                                }
                                needs_redraw = true;
                            } else {
                                app.status_msg = "kill needs --http and a selected session".into();
                                needs_redraw = true;
                            }
                        }
                        _ => {}
                    }
                }
            }
        }
        Ok(())
    })();

    disable_raw_mode()?;
    stdout().execute(LeaveAlternateScreen)?;
    ratatui::restore();
    res
}

[gemini-code-assist]

Calling synchronous blocking operations like HttpClient::kill_session and state.refresh inside an async Axum handler blocks the Tokio executor thread, which can starve other tasks and degrade performance. It is highly recommended to run these blocking operations inside tokio::task::spawn_blocking.

async fn api_kill_session(
    State(st): State<WebState>,
    Path(id): Path<u64>,
) -> impl IntoResponse {
    let Some(base) = st.cfg.http.clone() else {
        return (StatusCode::BAD_REQUEST, "monitor started without --http").into_response();
    };
    let res = tokio::task::spawn_blocking(move || {
        let client = HttpClient::new(&base);
        client.kill_session(id).map(|_| {
            if let Ok(mut state) = st.poll.write() {
                state.refresh(&st.cfg);
                if let Ok(mut out) = st.snap.write() {
                    *out = state.to_snapshot(&st.cfg);
                }
            }
        })
    })
    .await;

    match res {
        Ok(Ok(())) => StatusCode::OK.into_response(),
        Ok(Err(e)) => (StatusCode::BAD_GATEWAY, e.to_string()).into_response(),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()).into_response(),
    }
}

[gemini-code-assist]

The frame length len is read directly from the network as a u32 and used to allocate a Vec of that size. If a corrupted or malicious server sends a very large length, this can cause an out-of-memory crash (OOM panic) on the client. Adding a reasonable upper limit (e.g., 16MB) before allocating the payload buffer prevents this vulnerability.

    let len = u32::from_be_bytes([header[0], header[1], header[2], header[3]]) as usize;
    if len > 16 * 1024 * 1024 {
        return Err(anyhow::anyhow!("frame length {} exceeds maximum limit of 16MB", len));
    }
    let opcode = header[4];
    let mut payload = vec![0u8; len];

[gemini-code-assist]

If r.json().ok() returns None due to a JSON deserialization failure, the error is silently ignored, and snap.health remains None without any error message. It is better to capture the deserialization error and store it in snap.error to assist with debugging.

        match self.client.get(format!("{}/api/health", self.base)).send() {
            Ok(r) if r.status().is_success() => {
                match r.json::<Health>() {
                    Ok(h) => snap.health = Some(h),
                    Err(e) => snap.error = Some(format!("health JSON decode: {e}")),
                }
            }
            Ok(r) => snap.error = Some(format!("health HTTP {}", r.status())),
            Err(e) => snap.error = Some(format!("health: {e}")),
        }

[gemini-code-assist]

If the number of active HTTP sessions shrinks after a refresh, app.selected_session can become out of bounds. Clamping selected_session to the new session list length inside TuiState::refresh ensures the selection highlight remains valid and visible.

impl TuiState {
    fn refresh(&mut self, cfg: &MonitorConfig) {
        self.inner.refresh(cfg);
        self.last_refresh = Instant::now();
        let len = self.inner.http.sessions.len();
        if self.selected_session >= len {
            self.selected_session = len.saturating_sub(1);
        }
    }
}