tcptop/.planning/milestones/v1.0-phases/03-output-distribution/03-CONTEXT.md

Phase 3: Output & Distribution - Context

Gathered: 2026-03-22 Status: Ready for planning

## 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.

## 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)

## 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).

<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 CollectorEvents 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 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

---

Phase: 03-output-distribution Context gathered: 2026-03-22