Port Detective
Relevant source files
The following files were used as context for generating this wiki page:
Port Detective is a specialized networking utility within the DevUtils suite designed to inspect local network port activity. It allows developers to identify which ports are currently in use, discover the specific Process Identifiers (PIDs) associated with those ports, and terminate processes that are blocking required network addresses.
The tool bridges the frontend React interface with the local system's networking stack using the Tauri framework. This architecture enables secure execution of system-level commands like port scanning and process termination, which are typically restricted in standard web environments.
Sources: components/tools/port-detective.tsx:1-24, README.md:1-15
Architecture and Core Logic
Port Detective operates as a client-side React component that communicates with a Rust-based backend via Tauri's IPC (Inter-Process Communication) bridge. The frontend manages user input and state, while the backend performs heavy-lifting tasks such as scanning the ephemeral port range and interacting with the OS process manager.
Data Structures
The system relies on a consistent data interface for representing network state:
| Field | Type | Description |
|---|---|---|
port | number | The specific TCP/UDP port number being inspected. |
inUse | boolean | Indicates if the port is currently bound by a process. |
pid | number (optional) | The unique Process ID owning the port. |
processName | string (optional) | The human-readable name of the executable. |
needsAdmin | boolean (optional) | Flag indicating if higher privileges are needed to view details. |
Sources: components/tools/port-detective.tsx:26-32
System Interaction Flow
The following diagram illustrates how the frontend requests port data and how the system responds through the Tauri bridge.
The UI utilizes specific backend commands named check_port, scan_listening_ports, and kill_process to perform these operations.
Sources: components/tools/port-detective.tsx:50-130, messages/en.json:630-660
Key Features
Port Detective is divided into two primary functional modules managed by a tabbed interface.
Single Port Inspection
This module allows users to query a specific port number (1-65535). It provides detailed information including the PID and process name if the port is occupied. Users can directly terminate the offending process from this view.
Port Range Scanning
The scanner identifies all listening ports within a user-defined range. It uses the scan_listening_ports command, which is optimized for performance compared to individual port checks.
| Feature | Component/Function | UI Reference |
|---|---|---|
| Port Validation | parseInt + Range Check | tools.portDetective.errors.invalidPort |
| Process Termination | handleKillProcess | tools.portDetective.kill |
| Range Scanning | handleScanPorts | tools.portDetective.scan |
| Admin Awareness | showAdminWarning state | tools.portDetective.adminWarning |
Sources: components/tools/port-detective.tsx:66-150, messages/en.json:645-662
Security and Privileges
A critical aspect of the Port Detective architecture is its handling of system privileges. While basic port availability can often be checked by standard users, retrieving the processName or pid on many operating systems (macOS, Linux, and Windows) requires elevated permissions.
The component monitors the needsAdmin flag returned by the backend. If true, the UI renders an Alert component informing the user that process details are hidden due to insufficient permissions.
Sources: components/tools/port-detective.tsx:55-63, components/tools/port-detective.tsx:185-210
Implementation Details
The frontend is built using React and the @tauri-apps/api/core library. It leverages various UI components from the project's internal library, including Tabs, Card, and Progress.
// Example of the backend invocation for scanning
const handleScanPorts = async () => {
// ... validation logic ...
const results = await invoke<PortInfo[]>("scan_listening_ports", {
startPort,
endPort,
});
setScanResults(results);
// ... state updates ...
};
Sources: components/tools/port-detective.tsx:96-115, package.json:52-54
Summary
Port Detective provides a vital bridge between the DevUtils application and the host operating system's network layer. By utilizing Tauri's native capabilities, it offers a high-performance alternative to command-line tools like lsof or netstat, providing a GUI for port management and process cleanup directly within the developer's workspace.
Sources: README.md:23, components/tool-content.tsx:37