tcptop/.planning/milestones/v1.0-REQUIREMENTS.md

# 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

- [x] **DATA-01**: Tool collects per-connection byte counts (sent and received) in real time
- [x] **DATA-02**: Tool collects per-connection packet counts (sent and received) in real time
- [x] **DATA-03**: Tool shows TCP connection state (ESTABLISHED, LISTEN, TIME_WAIT, etc.)
- [x] **DATA-04**: Tool correlates each connection to its owning process (PID and process name)
- [x] **DATA-05**: Tool estimates per-connection TCP round-trip time (RTT) in real time
- [x] **DATA-06**: Tool calculates bandwidth rates (KB/s or MB/s) per connection, not just cumulative bytes
- [x] **DATA-07**: Tool tracks both TCP and UDP connections (UDP flows synthesized from src/dst tuples with idle timeout)

### Display

- [x] **DISP-01**: User sees a real-time sortable table with one row per connection showing all stats
- [x] **DISP-02**: User sees a summary header with total connection count and aggregate bandwidth in/out
- [x] **DISP-03**: User can sort the table by any column via keyboard
- [x] **DISP-04**: User sees local address, local port, remote address, remote port per connection
- [x] **DISP-05**: User can configure refresh interval via CLI flag (default 1 second)
- [x] **DISP-06**: Connections are color-coded by bandwidth usage (heat map style)
- [x] **DISP-07**: User can search/filter the live view with '/' key (filter by IP, port, or process name)
- [x] **DISP-08**: User can quit with 'q' or Ctrl-C

### Filtering

- [x] **FILT-01**: User can filter by port via CLI flag (`--port`), supporting source port, destination port, or either
- [x] **FILT-02**: User can filter by process via CLI flag (`--pid` or `--process`)
- [x] **FILT-03**: User can select network interface via CLI flag (`--interface`)
- [x] **FILT-04**: User can filter by protocol via CLI flag (`--tcp` / `--udp`)

### Output

- [x] **OUTP-01**: User can log connection data to CSV file via `--log <path>` flag
- [x] **OUTP-02**: CSV output includes header row and periodic snapshots of all connections
- [x] **OUTP-03**: Tool provides `--help` with clear usage documentation
- [x] **OUTP-04**: Tool ships with a man page

### Operations

- [x] **OPS-01**: Tool detects missing root/elevated privileges at startup and shows clear error with instructions
- [x] **OPS-02**: Tool runs with low overhead on the host being monitored (no heavy polling)
- [x] **OPS-03**: Tool is installable via `cargo install`
- [x] **OPS-05**: Tool has test coverage for core data processing and display logic

### Platform

- [x] **PLAT-01**: Tool works on Linux (kernel 5.8+) using eBPF for data collection
- [x] **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*