hyperi-rustlib 2.5.4

Opinionated Rust framework for high-throughput data pipelines at PB scale. Auto-wiring config, logging, metrics, tracing, health, and graceful shutdown — built from many years of production infrastructure experience.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

// Project:   hyperi-rustlib
// File:      src/top/mod.rs
// Purpose:   TUI metrics dashboard module
// Language:  Rust
//
// License:   FSL-1.1-ALv2
// Copyright: (c) 2026 HYPERI PTY LIMITED

//! Live TUI metrics dashboard — like `vector top` for DFE services.
//!
//! Polls a running service's Prometheus `/metrics` endpoint and displays
//! a sortable, auto-refreshing table of metrics in the terminal.
//!
//! ## Usage
//!
//! ```bash
//! dfe-loader top                                  # Interactive TUI (default)
//! dfe-loader top --metrics-url http://remote:9090 # Remote endpoint
//! dfe-loader top --interval 5                     # 5-second refresh
//! dfe-loader top --once                           # Single scrape, table to stdout
//! dfe-loader top --json                           # Single scrape, JSON to stdout
//! dfe-loader top --once --filter kafka            # Filter by name substring
//! dfe-loader top --json --filter "buffer.*rows"   # Filter with wildcard pattern
//! ```
//!
//! ## Keybindings (TUI mode)
//!
//! | Key | Action |
//! |-----|--------|
//! | `q` / `Esc` | Quit |
//! | `j` / `↓` | Move down |
//! | `k` / `↑` | Move up |
//! | `g` / `Home` | Go to top |
//! | `G` / `End` | Go to bottom |
//! | `s` | Cycle sort column |
//! | `S` | Reverse sort direction |
//! | `r` | Force refresh |

mod config;
mod dashboard;
pub mod metrics;
mod oneshot;

pub use config::{TopConfig, TopOutputMode};
pub use dashboard::run_dashboard;
pub use metrics::{MetricSample, MetricType, ScrapeResult, fetch_metrics_http, parse_prometheus};
pub use oneshot::run_oneshot;

/// Errors from the TUI dashboard.
#[derive(Debug)]
pub enum TopError {
    /// Terminal initialisation or rendering error.
    Terminal(String),

    /// Metrics fetch error.
    Fetch(String),

    /// Runtime/threading error.
    Runtime(String),
}

impl std::fmt::Display for TopError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Terminal(e) => write!(f, "terminal error: {e}"),
            Self::Fetch(e) => write!(f, "fetch error: {e}"),
            Self::Runtime(e) => write!(f, "runtime error: {e}"),
        }
    }
}

impl std::error::Error for TopError {}

/// Run the metrics dashboard or one-shot output.
///
/// In TUI mode, blocks until the user presses `q` or `Esc`.
/// In `--once` or `--json` mode, scrapes once and prints to stdout.
///
/// # Errors
///
/// Returns `TopError` on terminal or network failures.
pub fn run_top(config: &TopConfig) -> Result<(), TopError> {
    match config.output_mode {
        TopOutputMode::Tui => run_dashboard(config),
        TopOutputMode::Once | TopOutputMode::Json => run_oneshot(config),
    }
}