130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
---
|
|
phase: 02-interactive-tui
|
|
plan: 01
|
|
subsystem: tui
|
|
tags: [ratatui, crossterm, tui, clap, keyboard, terminal]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 01-data-pipeline
|
|
provides: ConnectionRecord, ConnectionTable, format_rate/format_rtt/format_bytes
|
|
provides:
|
|
- TUI module with App state, draw, and event handling
|
|
- Terminal lifecycle (init/restore) in main.rs
|
|
- Clap CLI struct with filtering and interval flags
|
|
- Sortable, filterable, color-coded connection table
|
|
affects: [02-interactive-tui, 03-output-packaging]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: [ratatui 0.30.0, crossterm 0.29.0, futures 0.3]
|
|
patterns: [immediate-mode TUI rendering, App state struct, tokio::select! with EventStream]
|
|
|
|
key-files:
|
|
created:
|
|
- tcptop/src/tui/mod.rs
|
|
- tcptop/src/tui/app.rs
|
|
- tcptop/src/tui/draw.rs
|
|
- tcptop/src/tui/event.rs
|
|
modified:
|
|
- Cargo.toml
|
|
- tcptop/Cargo.toml
|
|
- tcptop/src/lib.rs
|
|
- tcptop/src/main.rs
|
|
|
|
key-decisions:
|
|
- "Used Color::Rgb for new/closing connection highlights instead of named colors (DarkGreen/DarkRed not in ratatui)"
|
|
- "Moved Cli::parse() inside cfg blocks to avoid unused variable warnings on macOS"
|
|
|
|
patterns-established:
|
|
- "TUI App struct pattern: centralized state with sort/filter/highlight, rendered each tick"
|
|
- "EventStream in tokio::select! for non-blocking keyboard input alongside collector events"
|
|
- "Terminal lifecycle: ratatui::init() before async, ratatui::restore() after"
|
|
|
|
requirements-completed: [DISP-01, DISP-02, DISP-04, DISP-05, DISP-06, DISP-08]
|
|
|
|
# Metrics
|
|
duration: 4min
|
|
completed: 2026-03-22
|
|
---
|
|
|
|
# Phase 02 Plan 01: Core TUI Summary
|
|
|
|
**Ratatui-based interactive TUI with sortable connection table, summary header, bandwidth coloring, and keyboard-driven navigation replacing Phase 1 stdout output**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 4 min
|
|
- **Started:** 2026-03-22T02:18:45Z
|
|
- **Completed:** 2026-03-22T02:22:16Z
|
|
- **Tasks:** 3
|
|
- **Files modified:** 8
|
|
|
|
## Accomplishments
|
|
- Built full TUI module (app.rs, draw.rs, event.rs) with sortable, filterable connection table
|
|
- Added bandwidth-intensity row coloring (dim to bright) and new/closing connection highlights
|
|
- Wired terminal lifecycle and clap CLI with 7 flags (--port, --pid, --process, --interface, --tcp, --udp, --interval)
|
|
- Replaced Phase 1 stdout streaming with ratatui rendering in tokio::select! loop
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Add dependencies and create TUI module with App state** - `f0f50d7` (feat)
|
|
2. **Task 2: Create draw.rs and event.rs for rendering and keyboard handling** - `17b84fe` (feat)
|
|
3. **Task 3: Wire TUI into main.rs with terminal lifecycle and clap CLI** - `e05dbb4` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `tcptop/src/tui/mod.rs` - TUI module root declaring app, draw, event submodules
|
|
- `tcptop/src/tui/app.rs` - App state struct with InputMode, SortColumn, CliFilters, sort/filter/highlight methods
|
|
- `tcptop/src/tui/draw.rs` - Rendering: 3-region layout (header, table, status bar), help overlay, bandwidth coloring
|
|
- `tcptop/src/tui/event.rs` - Keyboard handler: mnemonic sort keys, filter-as-you-type, quit, column toggle, scrolling
|
|
- `tcptop/src/main.rs` - Terminal init/restore, clap Cli struct, EventStream in select loop
|
|
- `Cargo.toml` - Added ratatui, crossterm, futures workspace dependencies
|
|
- `tcptop/Cargo.toml` - Added ratatui, crossterm, futures crate dependencies
|
|
- `tcptop/src/lib.rs` - Added `pub mod tui;`
|
|
|
|
## Decisions Made
|
|
- Used `Color::Rgb(0, 60, 0)` and `Color::Rgb(80, 0, 0)` for subtle new/closing connection highlights since ratatui does not have DarkGreen/DarkRed named color variants
|
|
- Moved `Cli::parse()` inside `#[cfg]` blocks to eliminate unused variable warnings when compiling on macOS (Linux-only collector path)
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Fixed DarkGreen/DarkRed color constants**
|
|
- **Found during:** Task 2 (draw.rs rendering)
|
|
- **Issue:** Plan specified `Color::DarkGreen` and `Color::DarkRed` but ratatui 0.30 only has standard ANSI Color variants (no dark green/red)
|
|
- **Fix:** Used `Color::Rgb(0, 60, 0)` for new connections and `Color::Rgb(80, 0, 0)` for closing connections
|
|
- **Files modified:** tcptop/src/tui/draw.rs
|
|
- **Verification:** `cargo check` compiles clean
|
|
- **Committed in:** 17b84fe (Task 2 commit)
|
|
|
|
**2. [Rule 1 - Bug] Fixed unused variable warnings on macOS**
|
|
- **Found during:** Task 3 (main.rs wiring)
|
|
- **Issue:** `cli` variable and `ConnectionTable` import unused when compiling on macOS (no Linux cfg)
|
|
- **Fix:** Moved `Cli::parse()` inside cfg blocks, added `#[cfg(target_os = "linux")]` to ConnectionTable import
|
|
- **Files modified:** tcptop/src/main.rs
|
|
- **Verification:** `cargo check` produces zero warnings on macOS
|
|
- **Committed in:** e05dbb4 (Task 3 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 2 auto-fixed (2 bugs)
|
|
**Impact on plan:** Minor API differences from plan spec. No scope creep.
|
|
|
|
## Issues Encountered
|
|
None
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- TUI rendering pipeline complete, ready for Plan 02 (sort/filter/CSV wiring)
|
|
- All keyboard shortcuts implemented and ready for interactive use
|
|
- --interface flag parsed but not yet wired to collector (documented as TODO for Plan 02)
|
|
|
|
---
|
|
*Phase: 02-interactive-tui*
|
|
*Completed: 2026-03-22*
|