buswatch_tui/
lib.rs

1// Library crate: public API items may not be used by the binary
2#![allow(unused)]
3
4//! # buswatch
5//!
6//! A diagnostic TUI and library for monitoring Caryatid message bus activity.
7//!
8//! This crate provides tools for visualizing and diagnosing the health of
9//! modules communicating via the Caryatid message bus. It can receive monitor
10//! snapshots from various sources (files, channels, network streams) and
11//! display them in an interactive terminal UI.
12//!
13//! ## Architecture
14//!
15//! The crate is organized into four main modules:
16//!
17//! ```text
18//! ┌─────────────────────────────────────────────────────────────┐
19//! │                        Application                          │
20//! │  ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐ │
21//! │  │  app    │───▶│   data   │───▶│   ui    │───▶│ Terminal│ │
22//! │  │ (state) │    │(processing)   │(rendering)   │         │ │
23//! │  └────┬────┘    └──────────┘    └─────────┘    └─────────┘ │
24//! │       │                                                     │
25//! │       ▼                                                     │
26//! │  ┌─────────┐                                                │
27//! │  │ source  │◀── FileSource | StreamSource | ChannelSource  │
28//! │  │ (input) │                                                │
29//! │  └─────────┘                                                │
30//! └─────────────────────────────────────────────────────────────┘
31//! ```
32//!
33//! - **[`app`]**: Application state, view navigation, and user interaction logic
34//! - **[`source`]**: Data source abstraction ([`DataSource`] trait) with implementations
35//!   for file polling, TCP streams, and channel-based input
36//! - **[`data`]**: Data models and processing - converts raw snapshots into health-annotated
37//!   [`MonitorData`], tracks history for sparklines, and builds data flow graphs
38//! - **[`ui`]**: Terminal rendering using ratatui - summary tables, bottleneck views,
39//!   flow matrices, and theme support
40//!
41//! ## Features
42//!
43//! - **Summary view**: Overview of all modules with health status
44//! - **Bottleneck detection**: Highlights topics with pending reads/writes
45//! - **Data flow visualization**: Shows producer/consumer relationships
46//! - **Historical tracking**: Sparklines and rate calculations
47//!
48//! ## Usage
49//!
50//! ### As a CLI tool
51//!
52//! ```bash
53//! # Monitor a JSON file (produced by caryatid's Monitor)
54//! buswatch --file monitor.json
55//!
56//! # Monitor via TCP connection
57//! buswatch --connect localhost:9090
58//! ```
59//!
60//! ### As a library with file source
61//!
62//! ```
63//! use buswatch_tui::{App, FileSource, Thresholds};
64//!
65//! let source = Box::new(FileSource::new("monitor.json"));
66//! let app = App::new(source, Thresholds::default());
67//! ```
68//!
69//! ### As a library with stream source (TCP, etc.)
70//!
71//! ```no_run
72//! use std::io::Cursor;
73//! use buswatch_tui::{App, StreamSource, Thresholds};
74//!
75//! # tokio_test::block_on(async {
76//! // Example with a cursor (in practice, use TcpStream)
77//! let data = b"{}\n";
78//! let stream = Cursor::new(data.to_vec());
79//! let source = StreamSource::spawn(stream, "example");
80//! let app = App::new(Box::new(source), Thresholds::default());
81//! # });
82//! ```
83//!
84//! ### As a library with channel source (for message bus integration)
85//!
86//! ```
87//! use buswatch_tui::{App, ChannelSource, Thresholds};
88//!
89//! // Create a channel for receiving snapshots
90//! let (tx, source) = ChannelSource::create("rabbitmq://localhost");
91//!
92//! // Create the app
93//! let app = App::new(Box::new(source), Thresholds::default());
94//! ```
95//!
96//! ### Bridging from a message bus
97//!
98//! ```no_run
99//! use buswatch_tui::StreamSource;
100//! use tokio::sync::mpsc;
101//!
102//! # tokio_test::block_on(async {
103//! // Create a bytes channel
104//! let (tx, rx) = mpsc::channel::<Vec<u8>>(16);
105//! let source = StreamSource::from_bytes_channel(rx, "rabbitmq");
106//! # });
107//! ```
108
109pub mod app;
110pub mod data;
111pub mod events;
112pub mod source;
113pub mod ui;
114
115// Caryatid integration module (requires "subscribe" feature)
116#[cfg(feature = "subscribe")]
117pub mod subscribe;
118
119// Re-export main types for convenience
120pub use app::App;
121pub use data::{HealthStatus, ModuleData, MonitorData, Thresholds, TopicRead, TopicWrite};
122pub use source::{
123    ChannelSource, DataSource, FileSource, Microseconds, ModuleMetrics, ReadMetrics, SchemaVersion,
124    Snapshot, StreamSource, WriteMetrics,
125};
126
127// Re-export buswatch-types for direct access
128pub use buswatch_types;
buswatch_tui/lib.rs

buswatch_tui/
lib.rs
