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>
5.7 KiB
5.7 KiB
Requirements Archive: v1.0 MVP
Archived: 2026-03-22 Status: SHIPPED
For current requirements, see .planning/REQUIREMENTS.md.
Requirements: tcptop
Defined: 2026-03-21 Core Value: Live, accurate, per-connection network visibility with process correlation from the terminal
v1 Requirements
Data Collection
- DATA-01: Tool collects per-connection byte counts (sent and received) in real time
- DATA-02: Tool collects per-connection packet counts (sent and received) in real time
- DATA-03: Tool shows TCP connection state (ESTABLISHED, LISTEN, TIME_WAIT, etc.)
- DATA-04: Tool correlates each connection to its owning process (PID and process name)
- DATA-05: Tool estimates per-connection TCP round-trip time (RTT) in real time
- DATA-06: Tool calculates bandwidth rates (KB/s or MB/s) per connection, not just cumulative bytes
- DATA-07: Tool tracks both TCP and UDP connections (UDP flows synthesized from src/dst tuples with idle timeout)
Display
- DISP-01: User sees a real-time sortable table with one row per connection showing all stats
- DISP-02: User sees a summary header with total connection count and aggregate bandwidth in/out
- DISP-03: User can sort the table by any column via keyboard
- DISP-04: User sees local address, local port, remote address, remote port per connection
- DISP-05: User can configure refresh interval via CLI flag (default 1 second)
- DISP-06: Connections are color-coded by bandwidth usage (heat map style)
- DISP-07: User can search/filter the live view with '/' key (filter by IP, port, or process name)
- DISP-08: User can quit with 'q' or Ctrl-C
Filtering
- FILT-01: User can filter by port via CLI flag (
--port), supporting source port, destination port, or either - FILT-02: User can filter by process via CLI flag (
--pidor--process) - FILT-03: User can select network interface via CLI flag (
--interface) - FILT-04: User can filter by protocol via CLI flag (
--tcp/--udp)
Output
- OUTP-01: User can log connection data to CSV file via
--log <path>flag - OUTP-02: CSV output includes header row and periodic snapshots of all connections
- OUTP-03: Tool provides
--helpwith clear usage documentation - OUTP-04: Tool ships with a man page
Operations
- OPS-01: Tool detects missing root/elevated privileges at startup and shows clear error with instructions
- OPS-02: Tool runs with low overhead on the host being monitored (no heavy polling)
- OPS-03: Tool is installable via
cargo install - OPS-05: Tool has test coverage for core data processing and display logic
Platform
- PLAT-01: Tool works on Linux (kernel 5.8+) using eBPF for data collection
- PLAT-03: Platform abstraction allows different backends without changing display/filtering/output logic
v2 Requirements
Display Enhancements
- DISP-V2-01: Reverse DNS resolution for remote IPs (toggleable with -n/--no-resolve)
- DISP-V2-02: Connection duration/age display (time since first seen)
- DISP-V2-03: Freeze/pause display with 'p' key
Output Enhancements
- OUTP-V2-01: JSON Lines output format as alternative to CSV
- OUTP-V2-02: Headless mode (CSV/JSONL output without TUI)
Out of Scope
| Feature | Reason |
|---|---|
| Layer 7 / application protocol inspection | Massive scope expansion, different tool category (wireshark territory) |
| Built-in graphing / sparklines | Terminal real estate better used for connection table; CSV export covers offline analysis |
| Windows support | No eBPF/DTrace; users can use WSL2 |
| Historical data storage / database | Turns monitoring tool into time-series DB; CSV covers offline analysis |
| Promiscuous mode / sniffing other hosts | Core value is per-process local correlation, not network-wide capture |
| Real-time alerting / thresholds | Monitoring tools observe; alerting tools alert. Script on CSV output |
| UDP RTT estimation | No built-in ACK mechanism; show N/A for UDP. TCP RTT is the valuable metric |
| macOS support (PLAT-02) | PKTAP packet capture provides degraded data fidelity vs Linux eBPF — not worth the complexity for v1. Platform abstraction trait remains for future use |
| Homebrew distribution (OPS-04) | Tied to macOS support; Linux distribution via cargo install and .deb/.rpm is sufficient for v1 |
Traceability
| Requirement | Phase | Status |
|---|---|---|
| DATA-01 | Phase 1 | Complete |
| DATA-02 | Phase 1 | Complete |
| DATA-03 | Phase 1 | Complete |
| DATA-04 | Phase 1 | Complete |
| DATA-05 | Phase 1 | Complete |
| DATA-06 | Phase 1 | Complete |
| DATA-07 | Phase 1 | Complete |
| DISP-01 | Phase 2 | Complete |
| DISP-02 | Phase 2 | Complete |
| DISP-03 | Phase 2 | Complete |
| DISP-04 | Phase 2 | Complete |
| DISP-05 | Phase 2 | Complete |
| DISP-06 | Phase 2 | Complete |
| DISP-07 | Phase 2 | Complete |
| DISP-08 | Phase 2 | Complete |
| FILT-01 | Phase 2 | Complete |
| FILT-02 | Phase 2 | Complete |
| FILT-03 | Phase 2 | Complete |
| FILT-04 | Phase 2 | Complete |
| OUTP-01 | Phase 3 | Complete |
| OUTP-02 | Phase 3 | Complete |
| OUTP-03 | Phase 3 | Complete |
| OUTP-04 | Phase 3 | Complete |
| OPS-01 | Phase 1 | Complete |
| OPS-02 | Phase 1 | Complete |
| OPS-03 | Phase 3 | Complete |
| OPS-05 | Phase 3 | Complete |
| PLAT-01 | Phase 1 | Complete |
| PLAT-03 | Phase 1 | Complete |
Coverage:
- v1 requirements: 29 total (2 moved to Out of Scope: OPS-04, PLAT-02)
- Mapped to phases: 29
- Unmapped: 0
Requirements defined: 2026-03-21 Last updated: 2026-03-22 — macOS (PLAT-02) and Homebrew (OPS-04) moved to Out of Scope