🛰️ peek-port (pport)

Orbital Surveillance for Localhost. A mission-critical port and process monitor, engineered in Rust for speed, safety, and fault tolerance.

---

📋 Mission Brief

Backend engineers often struggle with archaic commands (lsof -i :8080, netstat -ano) to manage locked ports. peek-port (pport) solves this by providing a modern, interactive, real-time Terminal User Interface (TUI).

Designed with a "Type-Driven" philosophy and "Zero-Cost Abstractions", pport ensures that process management is surgical: no freezes, no panics, and active safety interlocks.

🚀 Key Capabilities

• ⚡ Bare-Metal Performance: Built on the Tokio async runtime. Zero main-thread blocking.
• 🛡️ Safety First: Robust type system. "Two-Step Verification" modal before terminating any process.
• 🎨 Modern UI: Interface powered by ratatui with theme support and efficient rendering.
• 🔍 Precision Filtering: Launch in Sniper Mode (pport -p 3000) or Global Scan Mode.
• ⚙️ Persistent Configuration: TOML files (~/.config/pport/config.toml) to customize refresh rates and colors.
• 📦 Cross-Platform: Static binaries (musl) for Linux, macOS, and Windows.

🛠️ Installation

Option 1: Pre-compiled Binaries (Recommended)

Download the latest release from the Releases Page. Simply download, grant execution permissions, and move it to your $PATH.

Option 2: Build from Source

If you have the Rust toolchain installed:

cargo install --path .
# Or if published to crates.io:
# cargo install pport

🕹️ Usage

CLI Commands

Launch the application with optional arguments for speed and precision.

Bash

# Explorer Mode (View all listening ports)
pport

# Sniper Mode (Filter for a specific port immediately)
pport -p 8080

# Turbo Mode (High-frequency scanning for diagnostics)
pport --rate 100

Flight Deck Controls

Key

Action

Description

↑ / k

Navigate Up

Move cursor to the previous row

↓ / j

Navigate Down

Move cursor to the next row

K (Shift+k)

Kill Process

Initiate termination sequence (requires confirmation)

o

Open URL

Open http://localhost:<port> in the default browser

q / Esc

Quit

Exit application or cancel modals

Mission Note: On macOS and Linux, system processes often require elevated permissions to reveal their PIDs. Run with sudo pport if you need full root visibility.

⚙️ Configuration

Upon the first launch, pport automatically provisions a configuration file:

• Linux/Mac: ~/.config/pport/config.toml

• Windows: %APPDATA%\peek-port\pport\config.toml

Example config.toml

Ini, TOML

refresh_rate_ms = 1000  # Scan interval in milliseconds

[theme]
color_accent = "Cyan"   # Supported: Red, Green, Yellow, Blue, Magenta, Cyan, White, Gray
color_danger = "Red"    # Color for destructive actions (Kill)

🏗️ Architecture

This project adheres to strict software engineering principles to ensure maintainability and robustness:

1. Hexagonal Architecture: The business logic domain is strictly decoupled from the interface (TUI) and the OS layer (Sysinfo).

2. Concurrency Model: Utilizes the Actor/Producer-Consumer pattern. A background tokio::task gathers telemetry and ships it via mpsc channels to the UI, ensuring the interface remains fluid at all times.

3. Fail-Safe Design: Error handling leverages anyhow and result propagation. The application prefers graceful degradation (displaying "Unknown") over runtime panics.

🤝 Contributing

Contributions are welcome. Please ensure any PR passes clippy checks and maintains the "zero unwraps in production" philosophy.

1. Fork the project

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.