hyperi-rustlib 2.8.5

There's plenty of sage advice out there about how to run Rust services in production at scale — config cascades, structured logging, masking secrets, multi-backend secrets management, Prometheus, OpenTelemetry, Kafka transports, tiered disk-spillover sinks, adaptive worker pools, graceful shutdown — but almost none of it as code you can just install and use. This is that code. Opinionated, drop-in, working out of the box. The patterns from blog posts, watercooler chats and beers with your Google mates as actual library — not a framework you assemble from twenty crates and 8 weeks of munging.
Documentation 
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

// Project:   hyperi-rustlib
// File:      src/top/mod.rs
// Purpose:   TUI metrics dashboard module
// Language:  Rust
//
// License:   BUSL-1.1
// 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, thiserror::Error)]
pub enum TopError {
    /// Terminal initialisation or rendering error.
    #[error("terminal error: {0}")]
    Terminal(String),

    /// Metrics fetch error.
    #[error("fetch error: {0}")]
    Fetch(String),

    /// Runtime/threading error.
    #[error("runtime error: {0}")]
    Runtime(String),
}

/// 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),
    }
}