fb8463507c
All 3 phases shipped (8 plans, 29 requirements). macOS backend dropped from v1 scope. Archives created in .planning/milestones/. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
# Roadmap: tcptop
|
|
|
|
## Overview
|
|
|
|
tcptop is built in three phases that follow the data flow: first, get real connection data flowing from the kernel to userspace (the hardest engineering); second, build the interactive TUI that makes that data useful; third, add output modes, packaging, and test coverage to make it distributable on Linux. Each phase delivers a verifiable capability -- Phase 1 proves the data pipeline works, Phase 2 delivers a usable Linux tool, Phase 3 makes it installable and complete.
|
|
|
|
## Phases
|
|
|
|
**Phase Numbering:**
|
|
- Integer phases (1, 2, 3, 4): Planned milestone work
|
|
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
|
|
|
Decimal phases appear between their surrounding integers in numeric order.
|
|
|
|
- [ ] **Phase 1: Data Pipeline** - eBPF-based kernel data collection with platform abstraction, delivering real per-connection stats on Linux
|
|
- [ ] **Phase 2: Interactive TUI** - Real-time sortable connection table with filtering, keyboard controls, and summary header
|
|
- [x] **Phase 3: Output & Distribution** - CSV logging, documentation, packaging, and test coverage (completed 2026-03-22)
|
|
|
|
## Phase Details
|
|
|
|
### Phase 1: Data Pipeline
|
|
**Goal**: Real connection data flows from the Linux kernel to userspace with per-connection stats available for consumption
|
|
**Depends on**: Nothing (first phase)
|
|
**Requirements**: DATA-01, DATA-02, DATA-03, DATA-04, DATA-05, DATA-06, DATA-07, PLAT-01, PLAT-03, OPS-01, OPS-02
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Running `tcptop` on Linux with root prints per-connection byte and packet counts to stdout (proof of life)
|
|
2. Each connection row shows local/remote addresses, PID, process name, TCP state, and RTT estimate
|
|
3. UDP flows appear as synthesized connections (grouped by src/dst tuple) alongside TCP connections
|
|
4. Running without root produces a clear error message with instructions, not a Rust backtrace
|
|
5. The data collection imposes negligible overhead on the host (no heavy polling, eBPF ring buffer based)
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 01-01-PLAN.md -- Workspace scaffold, shared types, platform trait, privilege check
|
|
- [x] 01-02-PLAN.md -- eBPF kernel programs and Linux collector
|
|
- [x] 01-03-PLAN.md -- Aggregator, output formatter, and main event loop
|
|
|
|
### Phase 2: Interactive TUI
|
|
**Goal**: Users can monitor and investigate network connections in real time through a polished terminal interface
|
|
**Depends on**: Phase 1
|
|
**Requirements**: DISP-01, DISP-02, DISP-03, DISP-04, DISP-05, DISP-06, DISP-07, DISP-08, FILT-01, FILT-02, FILT-03, FILT-04
|
|
**Success Criteria** (what must be TRUE):
|
|
1. User sees a live-updating table of connections with a summary header showing total connections and aggregate bandwidth
|
|
2. User can sort the table by any column using keyboard shortcuts and filter the live view with '/' search
|
|
3. User can launch with --port, --pid/--process, --interface, or --tcp/--udp flags to see only matching connections
|
|
4. Connections are color-coded by bandwidth usage and the display refreshes at a configurable interval (--interval)
|
|
5. User can quit cleanly with 'q' or Ctrl-C and the terminal restores to its previous state
|
|
**Plans**: 2 plans
|
|
|
|
Plans:
|
|
- [x] 02-01-PLAN.md -- TUI module scaffold, App state, rendering (header/table/status bar), terminal lifecycle, clap CLI
|
|
- [x] 02-02-PLAN.md -- Sort/filter/keyboard polish, CLI filter flags, human verification on Linux VM
|
|
|
|
### Phase 3: Output & Distribution
|
|
**Goal**: tcptop is a complete, installable Linux tool with CSV logging, documentation, and test coverage
|
|
**Depends on**: Phase 2
|
|
**Requirements**: OUTP-01, OUTP-02, OUTP-03, OUTP-04, OPS-03, OPS-05
|
|
**Success Criteria** (what must be TRUE):
|
|
1. User can run `tcptop --log output.csv` and get a CSV file with header row and periodic snapshots of all connections
|
|
2. User can run `tcptop --help` and see clear usage documentation; a man page is available
|
|
3. User can install via `cargo install tcptop` and via Homebrew
|
|
4. Core data processing and display logic have automated test coverage
|
|
**Plans**: 3 plans
|
|
|
|
Plans:
|
|
- [x] 03-01-PLAN.md -- CSV writer module, headless event loop, --log flag, CSV tests
|
|
- [x] 03-02-PLAN.md -- Man page, package metadata, .deb/.rpm configuration
|
|
- [x] 03-03-PLAN.md -- Expanded test coverage (aggregator + filtering), Linux VM verification
|
|
|
|
## Progress
|
|
|
|
**Execution Order:**
|
|
Phases execute in numeric order: 1 -> 2 -> 3
|
|
|
|
| Phase | Plans Complete | Status | Completed |
|
|
|-------|----------------|--------|-----------|
|
|
| 1. Data Pipeline | 3/3 | Complete | - |
|
|
| 2. Interactive TUI | 2/2 | Complete | - |
|
|
| 3. Output & Distribution | 3/3 | Complete | 2026-03-22 |
|