130 lines
6.9 KiB
Markdown
130 lines
6.9 KiB
Markdown
# Phase 3: Output & Distribution - Context
|
|
|
|
**Gathered:** 2026-03-22
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
CSV logging, documentation (`--help` + man page), Linux packaging (`cargo install`, `.deb`, `.rpm`), and test coverage for core logic. This makes tcptop a complete, installable Linux tool. macOS packaging (Homebrew) is deferred to Phase 4.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### CSV logging behavior
|
|
- **D-01:** `--log <path>` runs in headless mode — no TUI, just CSV output to file. TUI and CSV are mutually exclusive modes.
|
|
- **D-02:** All ConnectionRecord fields included in CSV rows: proto, local addr, local port, remote addr, remote port, PID, process name, state, bytes in, bytes out, packets in, packets out, rate in, rate out, RTT.
|
|
- **D-03:** Each snapshot writes one row per active connection at the `--interval` cadence (default 1s). Same tick rate as TUI display.
|
|
- **D-04:** Overwrite existing file if path already exists (no append mode).
|
|
- **D-05:** Each row includes a timestamp column (snapshot time) so rows can be correlated to their snapshot cycle.
|
|
- **D-06:** CSV includes a header row with column names (per OUTP-02).
|
|
|
|
### Help and man page
|
|
- **D-07:** `--help` uses clap's auto-generated output from existing `#[arg]` attributes. No additional customization needed — current level of detail is sufficient.
|
|
- **D-08:** Man page is hand-written (not auto-generated from clap) to allow richer prose, examples, and notes on eBPF requirements.
|
|
- **D-09:** Man page includes a detailed EXAMPLES section with common use cases (`tcptop --pid 1234`, `tcptop --port 443 --log capture.csv`, `tcptop --tcp --interval 2`, etc.).
|
|
- **D-10:** Man page is installed and accessible via `man tcptop` when the tool is installed through any supported method.
|
|
|
|
### Packaging and installability
|
|
- **D-11:** `cargo install tcptop` is the developer install path — expects nightly toolchain + bpf-linker already set up. No hand-holding for prerequisites.
|
|
- **D-12:** `.deb` and `.rpm` packages ship prebuilt binaries for easy install on Debian/Ubuntu and RHEL/Fedora. Generated via `cargo-deb` and `cargo-generate-rpm`.
|
|
- **D-13:** Packages distributed as bare files (GitHub releases). No APT/YUM repository.
|
|
- **D-14:** Packages include the man page so `man tcptop` works after install.
|
|
- **D-15:** No declared kernel version dependency in packages — fail at runtime with the existing privilege/capability check. Kernel version requirements are unreliable across distros due to feature backports.
|
|
- **D-16:** Homebrew/macOS packaging deferred to Phase 4.
|
|
|
|
### Test coverage
|
|
- **D-17:** Focus on CSV writer tests (correct header, correct fields, timestamp presence, overwrite behavior) and expanded data processing coverage (aggregator edge cases, filtering logic, rate calculation).
|
|
- **D-18:** Skip TUI rendering tests — verified manually.
|
|
- **D-19:** Skip eBPF/collector layer tests — verified manually on Linux VM.
|
|
- **D-20:** Cover critical paths, no specific coverage target. Done when CSV output and core data processing are well-tested.
|
|
|
|
### Claude's Discretion
|
|
- CSV timestamp format (ISO 8601 recommended)
|
|
- Man page structure and exact prose
|
|
- Which aggregator/filtering edge cases to test
|
|
- `cargo-deb` / `cargo-generate-rpm` configuration details
|
|
- How headless mode reuses the existing event loop vs having its own
|
|
- Build automation for `.deb`/`.rpm` (xtask, Makefile, or CI)
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Headless CSV mode should reuse the same collector/aggregator pipeline — just swap TUI rendering for CSV row writing.
|
|
- Phase 1 deferred `--batch`/`--once` mode (01-CONTEXT.md). Headless `--log` mode partially fulfills this — evaluate if a separate `--batch` flag is still needed or if `--log` covers the use case.
|
|
- Man page should mention that root/sudo is required and reference the exit code 77 convention from Phase 1 (D-11).
|
|
|
|
</specifics>
|
|
|
|
<canonical_refs>
|
|
## Canonical References
|
|
|
|
**Downstream agents MUST read these before planning or implementing.**
|
|
|
|
### CSV output
|
|
- `.planning/REQUIREMENTS.md` — OUTP-01, OUTP-02 (CSV logging requirements)
|
|
- `tcptop/src/model.rs` — ConnectionRecord struct with all fields to serialize
|
|
- `tcptop/src/output.rs` — Existing formatting helpers (format_bytes, format_rate, format_rtt) for reference
|
|
- `tcptop/src/main.rs` — Current event loop; headless mode needs an alternate code path
|
|
- `CLAUDE.md` §Technology Stack — csv 1.4.x crate with serde integration
|
|
|
|
### Documentation
|
|
- `.planning/REQUIREMENTS.md` — OUTP-03 (--help), OUTP-04 (man page)
|
|
- `tcptop/src/main.rs` lines 16-46 — Cli struct with clap derive attributes (auto-generates --help)
|
|
|
|
### Packaging
|
|
- `.planning/REQUIREMENTS.md` — OPS-03 (cargo install), OPS-04 (Homebrew → replaced with .deb/.rpm)
|
|
- `tcptop/Cargo.toml` — Package metadata (needs description, license, repository fields for cargo install/crates.io)
|
|
- `Cargo.toml` (workspace root) — Workspace structure
|
|
|
|
### Testing
|
|
- `.planning/REQUIREMENTS.md` — OPS-05 (test coverage)
|
|
- `tcptop/tests/pipeline_test.rs` — Existing test patterns (aggregator pipeline, output formatting)
|
|
- `tcptop/src/aggregator.rs` — Core data processing to expand test coverage on
|
|
|
|
</canonical_refs>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- `output.rs`: `format_bytes()`, `format_rate()`, `format_rtt()` — reuse for CSV cell formatting or use raw values
|
|
- `model.rs`: `ConnectionRecord` with all fields; can derive `Serialize` for csv crate integration
|
|
- `aggregator.rs`: `ConnectionTable` with `update()` and `tick()` — headless mode uses the same pipeline
|
|
- `pipeline_test.rs`: Established test pattern using synthetic `CollectorEvent`s fed into `ConnectionTable`
|
|
|
|
### Established Patterns
|
|
- Tokio async event loop with `select!` on collector channel + periodic tick — headless CSV mode can follow the same pattern minus the TUI branches
|
|
- Workspace dependency management in root `Cargo.toml`
|
|
- `cfg(target_os = "linux")` gating for platform-specific code
|
|
- xtask build pattern for eBPF compilation
|
|
|
|
### Integration Points
|
|
- `main.rs`: Branch on `--log` flag to choose TUI vs headless CSV mode before entering the event loop
|
|
- `Cli` struct: Add `--log <path>` flag
|
|
- `Cargo.toml`: Add `csv` and `serde` dependencies; add package metadata for crates.io
|
|
- Man page file: Add to repo (e.g., `doc/tcptop.1`) and configure `cargo-deb`/`cargo-generate-rpm` to install it
|
|
|
|
</code_context>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
- Homebrew formula for macOS — Phase 4 when macOS backend is implemented
|
|
- `--batch` or `--once` mode for stdout output without TUI — evaluate if `--log` covers this use case; if not, add to backlog
|
|
- JSON Lines output format (OUTP-V2-01) — v2 requirement
|
|
- Headless mode without file (stdout CSV) — potential v2 enhancement
|
|
- APT/YUM repository hosting — if tcptop gains enough users to warrant it
|
|
- UDP flow idle timeout configurable via CLI flag — carried from Phase 1/2 deferrals
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 03-output-distribution*
|
|
*Context gathered: 2026-03-22*
|