netpulse-tui 0.1.0

Ultra-lightweight, zero-flicker, non-blocking terminal network dashboard in Rust
netpulse-tui-0.1.0 is not a library.

⚑ NetPulse

Ultra-lightweight, zero-flicker, non-blocking terminal network dashboard in Rust.

Crates.io License: MIT OR Apache-2.0 Build Status Platform Zero-Privilege


πŸš€ Why NetPulse?

Most terminal network tools force you into an unappealing trade-off: heavy background resource consumption, screen flicker during refresh, mandatory sudo/root privileges for basic ICMP pings, or complex configuration just to see why your connection feels sluggish.

NetPulse is built from the ground up for systems engineers, SREs, and terminal power users:

  • Zero Sudo Required: Transparent ICMP ping with automated non-blocking TCP fallback (ports 443 & 53) ensures reliable latency diagnostics in locked-down or containerized environments.
  • True Non-Blocking Async: Powered by Tokio and Hickory DNS; network I/O, DNS benchmarks, port polling, and UI rendering execute independently with zero frame drops.
  • Zero-Flicker Ratatui TUI: 15 FPS sub-millisecond redraws with zero heap allocations on the render path.
  • Minimal Footprint: Single static binary (< 4MB stripped), instant startup, and near-zero CPU/memory footprint.

πŸ“Ί Preview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ NETPULSE  ● 3 ifaces | gw: 192.168.1.1 | dns: 1.1.1.1 | status: active                                    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”Œ Network Interfaces β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”Œ Throughput History ───────────────────────────┐
β”‚Interface    RX Rate     TX Rate    Total RX    Total TX  β”‚β”‚ RX: en0 (14.2 MB/s)                           β”‚
β”‚en0          14.2 MB/s   1.8 MB/s   8.42 GB     2.15 GB   β”‚β”‚    β–ˆβ–…β–β–‚ β–‚ ▄▄▁▅                                β”‚
β”‚utun3        820 KB/s    110 KB/s   412.0 MB    98.4 MB   β”‚β”‚β–‚β–…β–„β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ƒβ–ˆβ–†β–ˆβ–ˆβ–ˆβ–ˆβ–ˆ                               β”‚
β”‚lo0          0 B/s       0 B/s      185.9 MB    185.9 MB  β”‚β”‚ TX: en0 (1.8 MB/s)                            β”‚
β”‚                                                          β”‚β”‚    ▁          β–ˆ                               β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”Œ Ping & Latency Probes β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”Œ DNS Latency Benchmark (avg: 12.4ms) ───────────────┐
│● 1.1.1.1 11ms [icmp]  ● 8.8.8.8 14ms [icmp]         ││● google.com       8.2ms (142.250.190.46)          β”‚
│● gw:192.168.1.1 1ms [icmp]                          ││● cloudflare.com  11.4ms (104.16.132.229)          β”‚
β”‚min: 1.0ms avg: 8.7ms max: 14.0ms loss: 0%           ││● github.com      17.6ms (140.82.121.4)            β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”Œ Open / Listening Ports (4) ───────────────────────────────────────────────────────────────────────────────┐
β”‚Proto       Port        PID         Process Name                                                           β”‚
β”‚TCP         22          1420        sshd                                                                   β”‚
β”‚TCP         5432        2811        postgres                                                               β”‚
β”‚TCP         8080        4190        node (backend-api)                                                     β”‚
β”‚UDP         5353        312         mDNSResponder                                                          β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
 q / esc quit  ctrl+c exit  ● pulse active

✨ Key Features

Feature Description
πŸ“Š Real-Time Bandwidth & Sparklines Per-interface RX/TX rates computed accurately over exact time deltas, accompanied by adaptive 30-sample history sparklines.
🌐 Zero-Privilege Latency Probing High-precision ICMP pings with seamless fallback to concurrent non-blocking TCP handshakes (raced across 443 & 53).
⚑ Parallel DNS Resolution Concurrently benchmarks your upstream resolvers against top global domains using futures::future::join_all.
πŸ” Open Port & Socket Auditor Scans listening TCP/UDP sockets and maps them to active process names without spiking CPU or memory.
🎨 Adaptive & Responsive UI Responsive Ratatui layout that scales cleanly from small terminal splits (40x10) to ultra-wide displays with NO_COLOR support.
πŸ›‘οΈ Endian-Safe Route Detection Cross-platform gateway discovery supporting macOS routing tables and Linux /proc/net/route on both Little-Endian and Big-Endian architectures.

πŸ“¦ Installation

Option 1: Via Cargo (from Crates.io)

Installs the netpulse executable binary onto your PATH:

cargo install netpulse-tui

Option 2: Via cargo-binstall (Fast Pre-built Binary)

cargo binstall netpulse-tui

Option 3: Download Pre-built Binaries

Download the pre-compiled binary for your platform from the GitHub Releases:

# macOS (Apple Silicon / ARM64)
curl -LO https://github.com/unknownman/netpulse/releases/latest/download/netpulse-aarch64-apple-darwin.tar.gz
tar -xzf netpulse-aarch64-apple-darwin.tar.gz
sudo mv netpulse /usr/local/bin/

# Linux (x86_64)
curl -LO https://github.com/unknownman/netpulse/releases/latest/download/netpulse-x86_64-unknown-linux-musl.tar.gz
tar -xzf netpulse-x86_64-unknown-linux-musl.tar.gz
sudo mv netpulse /usr/local/bin/

Option 4: Build from Source

git clone https://github.com/unknownman/netpulse.git
cd netpulse
cargo build --release
sudo cp target/release/netpulse /usr/local/bin/

🐚 Shell Completions

Generate native auto-completion scripts for your shell using --generate-completions:

# Zsh
netpulse --generate-completions zsh > ~/.zfunc/_netpulse
# Add 'fpath+=~/.zfunc' to your ~/.zshrc if not already present

# Bash
netpulse --generate-completions bash > ~/.local/share/bash-completion/completions/netpulse

# Fish
netpulse --generate-completions fish > ~/.config/fish/completions/netpulse.fish

πŸ’» Usage & CLI Flags

# Launch with default settings (1s refresh, auto-detect active interfaces)
netpulse

# High-frequency refresh (250ms interval)
netpulse -i 250

# Monitor a specific interface only (e.g. en0 or eth0)
netpulse --interface en0

# Show all interfaces including inactive / virtual loopbacks
netpulse --all

# Plain monochrome output (or export NO_COLOR=1)
netpulse --no-color

CLI Reference

Flag Short Default Description
--interval <MS> -i 1000 Collector refresh interval in milliseconds
--interface <NAME> Auto Network interface to monitor
--all -a false Show all interfaces, including inactive ones
--no-color false Disable ANSI colored output
--generate-completions <SHELL> Output shell completion script (bash, zsh, fish, powershell, elvish)
--help -h Print help and options
--version -V Print version

⌨️ Keyboard Shortcuts

Key Action
q Quit application and restore terminal
Esc Quit application and restore terminal
Ctrl + C Force exit safely

πŸ—οΈ Architecture & Zero-Privilege Security

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                      main.rs                           β”‚
β”‚  (15 FPS Ratatui Loop Β· Zero Heap Allocation / Render) β”‚
β””β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚                 β”‚                 β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Bandwidth Task  β”‚β”‚  Latency Task  β”‚β”‚    DNS Task       β”‚
β”‚  (sysinfo-rs)   β”‚β”‚ (ICMP + TCP)   β”‚β”‚(Hickory Resolver) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1. Lock-Free Communication: Each background collector asynchronously publishes immutable snapshots over tokio::sync::watch channels without shared Mutex locks or global statics.
  2. True Async Network I/O: Network probes utilize non-blocking async sockets bounded by deterministic timeouts, preventing unresponsive threads even on broken routing paths.
  3. Safe Sub-millisecond Rendering: Snapshot states are borrowed directly by reference during UI passes (watch::Receiver::borrow()), completely avoiding clone churn and garbage collection pauses.
  4. Zero-Privilege Guarantee: Uses OS routing sysctls and non-privileged raw ICMP/TCP handshake capabilities provided by modern Linux kernels (net.ipv4.ping_group_range) and macOS sockets.

🀝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# Run test suite
cargo test -- --nocapture

# Run linter
cargo clippy --all-targets --all-features -- -D warnings

πŸ“œ License

This project is dual-licensed under either:

at your option.