// IFTOPRS — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

iftoprs is a single-binary real-time bandwidth monitor written in Rust. Live libpcap capture feeds an async tokio pipeline; a per-flow tracker computes 2 s / 10 s / 40 s sliding-window averages, cumulative byte counters, and 40-sample sparkline history; a ratatui TUI renders the result with mouse + keyboard navigation, hover tooltips, 31 cyberpunk color themes, configurable bandwidth alerts, and live filter / pin / drill-down. Background lsof polling joins each flow to its owning (PID, process_name). A headless --json mode streams NDJSON snapshots for pipelines. Auto-restart with exponential backoff keeps the capture loop alive across transient kernel / driver hiccups. 21,812 production Rust lines + 6,112 integration-test lines + 2,256 test functions + 31 themes + 17 CLI flags + 14 direct (249 transitive) crates — macOS & Linux on x86_64 + aarch64.

~SCALE & POSITION

Where iftoprs sits in the bandwidth-monitor landscape. iftoprs is single-author, single-binary, single-language Rust; the prior-art set spans different languages, different scopes, and different UX trade-offs.

Comparison rows reflect each tool's public feature set as observed from project READMEs and man pages. iftoprs targets the iftop UX with strict feature-superset goals: every iftop feature has an equivalent or stronger replacement (live filter, mouse, themes, sparkline, process column, JSON), and every iftoprs setting auto-persists to ~/.iftoprs.conf in TOML.

#SUBSYSTEM BREAKDOWN

Source partitioned by role. UI rendering and capture parsing dominate — ratatui draw paths and the per-protocol packet decoder are the two heaviest subsystems. The CLI is wide because every flag, completion shell, and color swatch list is generated from one clap derive surface.

$FILES BY SIZE

Every .rs file in the crate. ui/app.rs + capture/parser.rs + ui/render.rs together account for ~35% of total source. The integration test file alone is 1.2× larger than the largest production file — behavior is pinned heavily for a CLI tool.

@CAPTURE PIPELINE

Packets flow through five stages between the wire and the screen. The async hand-off between capture and parser keeps the libpcap thread tight; the parser runs on a dedicated tokio task; the UI thread reads only the resulting flow table. Auto-restart re-arms the capture handle on transient errors so a driver hiccup never tears down the visible UI.

   Wire (NIC / VLAN / WiFi / loopback)
        │
        ▼
  ┌────────────────┐     ┌────────────────┐     ┌────────────────┐
  │ sniffer.rs     │────▶│ parser.rs      │────▶│ tracker.rs     │
  │ (184)          │     │ (2,950)        │     │ (1,018)        │
  │ pcap_loop      │     │ Eth / VLAN     │     │ 5-tuple store  │
  │ BPF compile    │     │ IPv4 / IPv6    │     │ TX / RX split  │
  │ exp-backoff    │     │ TCP / UDP /    │     │ window math    │
  │ restart        │     │ ICMP / Other   │     │ alert eval     │
  └────────────────┘     └────────────────┘     └───────┬────────┘
                                                        │
                              ┌─────────────────────────┤
                              │                         │
                              ▼                         ▼
                    ┌────────────────┐         ┌────────────────┐
                    │ resolver.rs    │         │ history.rs     │
                    │ (1,732)        │         │ (854)          │
                    │ async DNS      │         │ 40-sample ring │
                    │ port names     │         │ sparkline      │
                    │ TTL cache      │         │ peak tracking  │
                    └────────┬───────┘         └────────┬───────┘
                             │                          │
                             └────────────┬─────────────┘
                                          │
                                          ▼
                                ┌────────────────┐
                                │ procinfo.rs    │
                                │ (408)          │
                                │ lsof poll      │
                                │ PID + name     │
                                │ cache (Arc/Mut)│
                                └────────┬───────┘
                                         │
                                         ▼
                               ┌──────────────────┐
                               │ ui/app.rs        │
                               │ (3,654)          │
                               │ state + input    │
                               └────────┬─────────┘
                                        │
                                        ▼
                               ┌──────────────────┐
                               │ ui/render.rs     │
                               │ (2,610)          │
                               │ ratatui paint    │
                               └──────────────────┘

A second egress path skips the renderer entirely: when --json is set, main.rs writes one {"flows":[...]} object per refresh interval to stdout and never starts a terminal.

&FEATURE INVENTORY

Every user-visible capability, partitioned by axis. Anything keyed off ~/.iftoprs.conf auto-persists when toggled in the TUI — users never edit the file by hand unless they want to.

%THEME CATALOG

31 cyberpunk color themes defined in src/config/theme.rs. The ThemeName enum and ThemeName::ALL table are the single source of truth for the chooser, the --list-colors swatch dump, and the TOML config validator. Default is NeonSprawl.

*TEST SURFACE

2,256 test functions across the production crate and integration suite. CI runs format + clippy + test on Ubuntu + macOS on every push and pull request. Integration tests drive the built binary via CARGO_BIN_EXE_iftoprs — not cargo run — so the assertions hit the real binary.

// TEST DISTRIBUTION (UNIT)

// CI MATRIX

Workflow uses least-privilege contents: read permissions, cancels in-progress runs on the same branch when a newer commit arrives, sets fail-fast: false so both OSes finish even when one fails, and pins per-job timeouts so a hung runner can't burn the queue.

+DEPENDENCIES

14 direct crates declared in Cargo.toml; 249 total in Cargo.lock once tokio / ratatui / regex pull in their full transitive graph. Single binary out of cargo install iftoprs — LTO + strip + opt-level 3 in the release profile.

System-level dependency: libpcap for raw packet capture. macOS ships libpcap system-wide. Linux requires libpcap-dev (Debian / Ubuntu) or libpcap-devel (Fedora / RHEL).

?KEY DESIGN DECISIONS

Decisions that shape the codebase but aren't obvious from the source.