use std::collections::HashMap;
use std::net::TcpListener;
use std::process::Command;
use std::sync::{Mutex, OnceLock};
use std::time::{Duration, Instant};
use crate::models::{CheckStatus, DiagnosticResult};
pub const DEFAULT_DEV_PORTS: &[u16] = &[3000, 5000, 8000, 8080, 9000];
pub const CRITICAL_PORTS: &[u16] = &[80, 443, 5432, 3306, 27017];
pub const CACHE_TTL: Duration = Duration::from_secs(30);
pub fn status_for_port(port: u16) -> CheckStatus {
if CRITICAL_PORTS.contains(&port) || port < 1024 {
CheckStatus::Fail
} else {
CheckStatus::Warn
}
}
pub fn parse_netstat(output: &str) -> Vec<(u16, u32)> {
let mut out = Vec::new();
for line in output.lines() {
let upper = line.to_ascii_uppercase();
if !(upper.contains("LISTENING") || upper.contains("LISTEN")) {
continue;
}
let fields: Vec<&str> = line.split_whitespace().collect();
let Some(local) = fields.iter().find(|f| f.contains(':')) else {
continue;
};
let Some(port) = local.rsplit(':').next().and_then(|s| s.parse::<u16>().ok()) else {
continue;
};
let Some(pid) = fields.last().and_then(|s| s.parse::<u32>().ok()) else {
continue;
};
out.push((port, pid));
}
out.sort_unstable();
out.dedup();
out
}
fn parse_csv_row(line: &str) -> Vec<String> {
let mut fields = Vec::new();
let mut current = String::new();
let mut in_quotes = false;
for ch in line.chars() {
match ch {
'"' => in_quotes = !in_quotes,
',' if !in_quotes => {
fields.push(current.trim().to_string());
current.clear();
}
other => current.push(other),
}
}
fields.push(current.trim().to_string());
fields
}
pub fn parse_tasklist(output: &str) -> HashMap<u32, String> {
let mut names = HashMap::new();
for line in output.lines() {
let fields = parse_csv_row(line);
if !line.starts_with('"') || fields.len() < 2 {
continue;
}
let (name, pid) = (
fields[0].trim_matches('"').to_string(),
fields[1].trim_matches('"'),
);
if let Ok(pid) = pid.parse::<u32>() {
names.insert(pid, name);
}
}
names
}
pub fn parse_lsof(output: &str) -> Vec<(u16, u32, String)> {
let mut out = Vec::new();
for line in output.lines() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() < 2 {
continue;
}
let Ok(pid) = fields[1].parse::<u32>() else {
continue; };
let command = fields[0].to_string();
let Some(port) = fields.iter().rev().find_map(|field| {
field
.rsplit(':')
.next()
.and_then(|s| s.trim_end_matches("(LISTEN)").parse::<u16>().ok())
}) else {
continue;
};
out.push((port, pid, command));
}
out.sort_unstable_by_key(|(port, _, _)| *port);
out.dedup();
out
}
pub fn parse_proc_net_tcp(output: &str) -> Vec<u16> {
let mut out = Vec::new();
for line in output.lines() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() < 4 {
continue;
}
if fields[3] != "0A" {
continue; }
let Some((_, hex_port)) = fields[1].rsplit_once(':') else {
continue;
};
if let Ok(port) = u16::from_str_radix(hex_port, 16) {
out.push(port);
}
}
out.sort_unstable();
out.dedup();
out
}
#[cfg(target_os = "windows")]
fn platform_command_scan() -> Vec<(u16, u32, String)> {
let output = match Command::new("netstat").arg("-ano").output() {
Ok(output) => output,
Err(_) => return Vec::new(),
};
if !output.status.success() {
return Vec::new();
}
let text = String::from_utf8_lossy(&output.stdout);
let listening = parse_netstat(&text);
if listening.is_empty() {
return Vec::new();
}
let names = match Command::new("tasklist")
.args(["/FO", "CSV", "/NH"])
.output()
{
Ok(output) => parse_tasklist(&String::from_utf8_lossy(&output.stdout)),
Err(_) => HashMap::new(),
};
listening
.into_iter()
.map(|(port, pid)| {
let raw_name = names
.get(&pid)
.cloned()
.unwrap_or_else(|| "unknown".to_string());
let name = raw_name
.strip_suffix(".exe")
.unwrap_or(&raw_name)
.to_string();
(port, pid, name)
})
.collect()
}
#[cfg(any(target_os = "macos", target_os = "freebsd"))]
fn platform_command_scan() -> Vec<(u16, u32, String)> {
let output = match Command::new("lsof")
.args(["-iTCP", "-sTCP:LISTEN", "-P", "-n"])
.output()
{
Ok(output) => output,
Err(_) => return Vec::new(),
};
if !output.status.success() {
return Vec::new();
}
parse_lsof(&String::from_utf8_lossy(&output.stdout))
}
#[cfg(target_os = "linux")]
fn platform_command_scan() -> Vec<(u16, u32, String)> {
use std::fs;
let lsof = Command::new("lsof")
.args(["-iTCP", "-sTCP:LISTEN", "-P", "-n"])
.output();
if let Ok(output) = lsof {
if output.status.success() {
let found = parse_lsof(&String::from_utf8_lossy(&output.stdout));
if !found.is_empty() {
return found;
}
}
}
let mut ports = Vec::new();
for proc in ["/proc/net/tcp", "/proc/net/tcp6"] {
if let Ok(text) = fs::read_to_string(proc) {
ports.extend(parse_proc_net_tcp(&text));
}
}
ports
.into_iter()
.map(|port| (port, 0, "unknown".to_string()))
.collect()
}
pub fn is_port_in_use(port: u16) -> bool {
TcpListener::bind(("127.0.0.1", port)).is_err()
}
fn parallel_in_use(ports: &[u16]) -> Vec<u16> {
let shared: Mutex<Vec<u16>> = Mutex::new(Vec::new());
std::thread::scope(|scope| {
for chunk in ports.chunks(4) {
let chunk = chunk.to_vec();
let shared = &shared;
scope.spawn(move || {
let found: Vec<u16> = chunk
.into_iter()
.filter(|port| is_port_in_use(*port))
.collect();
shared.lock().unwrap().extend(found);
});
}
});
shared.into_inner().unwrap()
}
fn platform_scan() -> Vec<(u16, u32, String)> {
let scanned = platform_command_scan();
if scanned.is_empty() {
parallel_in_use(DEFAULT_DEV_PORTS)
.into_iter()
.map(|port| (port, 0, "unknown".to_string()))
.collect()
} else {
scanned
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PortStatus {
pub port: u16,
pub pid: u32,
pub process_name: String,
pub status: CheckStatus,
}
struct CachedEntry {
pid: u32,
process_name: String,
}
pub struct PortWatcher {
cache: Mutex<HashMap<u16, CachedEntry>>,
observed: Mutex<HashMap<u16, Instant>>,
ttl: Duration,
scanner: Box<dyn Fn() -> Vec<(u16, u32, String)> + Send + Sync>,
}
fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
mutex
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
impl PortWatcher {
pub fn new() -> Self {
Self {
cache: Mutex::new(HashMap::new()),
observed: Mutex::new(HashMap::new()),
ttl: CACHE_TTL,
scanner: Box::new(platform_scan),
}
}
pub fn with_scanner(
ttl: Duration,
scanner: Box<dyn Fn() -> Vec<(u16, u32, String)> + Send + Sync>,
) -> Self {
Self {
cache: Mutex::new(HashMap::new()),
observed: Mutex::new(HashMap::new()),
ttl,
scanner,
}
}
pub fn clear(&self) {
lock(&self.cache).clear();
lock(&self.observed).clear();
}
pub fn check(&self, ports_to_check: &[u16]) -> Vec<PortStatus> {
let now = Instant::now();
let stale = {
let observed = lock(&self.observed);
ports_to_check.iter().any(|port| {
observed
.get(port)
.is_none_or(|checked_at| now.duration_since(*checked_at) >= self.ttl)
})
};
if stale {
let scan = (self.scanner)();
let mut cache = lock(&self.cache);
let mut observed = lock(&self.observed);
for port in ports_to_check {
cache.remove(port);
observed.insert(*port, now);
}
for (port, pid, process_name) in scan {
observed.insert(port, now);
cache.insert(port, CachedEntry { pid, process_name });
}
}
let cache = lock(&self.cache);
ports_to_check
.iter()
.filter_map(|port| {
cache.get(port).map(|entry| PortStatus {
port: *port,
pid: entry.pid,
process_name: entry.process_name.clone(),
status: status_for_port(*port),
})
})
.collect()
}
pub fn find_blocked(&self, ports_to_check: &[u16]) -> Vec<(u16, u32, String)> {
self.check(ports_to_check)
.into_iter()
.map(|status| (status.port, status.pid, status.process_name))
.collect()
}
}
impl Default for PortWatcher {
fn default() -> Self {
Self::new()
}
}
fn default_watcher() -> &'static PortWatcher {
static WATCHER: OnceLock<PortWatcher> = OnceLock::new();
WATCHER.get_or_init(PortWatcher::new)
}
pub fn check_blocked_ports(ports_to_check: &[u16]) -> Vec<(u16, u32, String)> {
default_watcher().find_blocked(ports_to_check)
}
pub fn find_blocked_ports(ports_to_check: &[u16]) -> Vec<(u16, u32)> {
check_blocked_ports(ports_to_check)
.into_iter()
.map(|(port, pid, _)| (port, pid))
.collect()
}
pub fn port_remediation(port: u16, pid: u32) -> String {
let kill = if cfg!(windows) {
format!("taskkill /PID {pid} /F")
} else {
format!("kill {pid}")
};
format!(
"Stop the process (e.g. `{kill}`), or configure your app to use another port (e.g. PORT={port})"
)
}
pub fn diagnostic_for(port: u16, pid: u32, process_name: &str) -> DiagnosticResult {
let display = if process_name.trim().is_empty() {
"unknown process"
} else {
process_name
};
DiagnosticResult::new(
format!("Port {port}"),
status_for_port(port),
format!("Port {port} is occupied by PID {pid} ({display})"),
)
.with_remediation(port_remediation(port, pid))
}
pub fn blocked_port_results(ports_to_check: &[u16]) -> Vec<DiagnosticResult> {
check_blocked_ports(ports_to_check)
.into_iter()
.map(|(port, pid, process_name)| diagnostic_for(port, pid, &process_name))
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
#[test]
fn parse_netstat_extracts_port_and_pid() {
let netstat = "\
TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 9921
TCP 127.0.0.1:8080 0.0.0.0:0 LISTENING 12345
TCP [::]:135 0.0.0.0:0 LISTENING 1234
UDP 0.0.0.0:137 *:* 65500
";
let found = parse_netstat(netstat);
assert_eq!(found, vec![(135, 1234), (3000, 9921), (8080, 12345)]);
}
#[test]
fn parse_netstat_ignores_non_listening() {
let netstat = "\
TCP 127.0.0.1:50001 0.0.0.0:0 ESTABLISHED 55
TCP 127.0.0.1:50002 0.0.0.0:0 TIME_WAIT 0
";
assert!(parse_netstat(netstat).is_empty());
}
#[test]
fn parse_tasklist_maps_pids_to_names() {
let tasks = "\
\"node.exe\",\"9921\",\"Console\",\"1\",\"30,292 K\"
\"python.exe\",\"12345\",\"Console\",\"1\",\"11,240 K\"
INFO: No tasks are running
";
let names = parse_tasklist(tasks);
assert_eq!(names.get(&9921).map(String::as_str), Some("node.exe"));
assert_eq!(names.get(&12345).map(String::as_str), Some("python.exe"));
assert_eq!(names.len(), 2);
}
#[test]
fn parse_lsof_extracts_command_pid_and_port() {
let lsof = "\
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 9921 aseem 21u IPv4 12345 0t0 TCP *:3000 (LISTEN)
python 12345 aseem 22u IPv6 67890 0t0 TCP [::]:8080 (LISTEN)
bash 7777 aseem 4u IPv4 11111 0t0 TCP 127.0.0.1:5432 (LISTEN)
";
let found = parse_lsof(lsof);
assert!(found.contains(&(3000, 9921, "node".to_string())));
assert!(found.contains(&(8080, 12345, "python".to_string())));
assert!(found.contains(&(5432, 7777, "bash".to_string())));
assert_eq!(found.len(), 3);
}
#[test]
fn parse_proc_net_tcp_keeps_only_listening_hex_ports() {
let tcp = "\
sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode
0: 0100007F:0BB8 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 12345 1 0000000000000000 100 0 0 10 0
1: 0100007F:D940 0100007F:0BB8 01 00000000:00000000 00:00000000 00000000 0 0 54321 1 0000000000000000 20 4 30 10 -1
2: 0100007F:1388 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 99999 1 0000000000000000 100 0 0 10 0
";
assert_eq!(parse_proc_net_tcp(tcp), vec![3000, 5000]);
}
#[test]
fn status_classifies_critical_and_privileged_fail() {
assert_eq!(status_for_port(3000), CheckStatus::Warn);
assert_eq!(status_for_port(5432), CheckStatus::Fail);
assert_eq!(status_for_port(443), CheckStatus::Fail);
assert_eq!(status_for_port(80), CheckStatus::Fail);
}
#[test]
fn diagnostic_for_builds_message_and_remediation() {
let d = diagnostic_for(3000, 9921, "node");
assert_eq!(d.check_name, "Port 3000");
assert_eq!(d.status, CheckStatus::Warn);
assert_eq!(d.message, "Port 3000 is occupied by PID 9921 (node)");
let remediation = d.remediation.unwrap();
assert!(remediation.contains("9921"));
assert!(remediation.contains("3000"));
if cfg!(windows) {
assert!(remediation.contains("taskkill"));
} else {
assert!(remediation.contains("kill 9921"));
}
}
#[test]
fn diagnostic_for_unknown_process_is_readable() {
let d = diagnostic_for(8080, 0, "");
assert!(d.message.contains("unknown process"));
}
#[test]
fn diagnostic_for_critical_port_fails() {
let d = diagnostic_for(5432, 6880, "postgres");
assert_eq!(d.status, CheckStatus::Fail);
}
#[test]
fn watcher_caches_scan_results() {
let calls = Arc::new(AtomicUsize::new(0));
let calls_for_scan = Arc::clone(&calls);
let scanner: Box<dyn Fn() -> Vec<(u16, u32, String)> + Send + Sync> = Box::new(move || {
calls_for_scan.fetch_add(1, Ordering::SeqCst);
vec![(3000, 111, "web-server".to_string())]
});
let watcher = PortWatcher::with_scanner(Duration::from_secs(60), scanner);
let first = watcher.find_blocked(&[3000, 8080]);
let second = watcher.find_blocked(&[3000, 8080]);
assert_eq!(first, vec![(3000, 111, "web-server".to_string())]);
assert_eq!(second, first);
assert_eq!(calls.load(Ordering::SeqCst), 1);
}
#[test]
fn watcher_rescans_after_clear() {
let calls = Arc::new(AtomicUsize::new(0));
let calls_for_scan = Arc::clone(&calls);
let scanner: Box<dyn Fn() -> Vec<(u16, u32, String)> + Send + Sync> = Box::new(move || {
calls_for_scan.fetch_add(1, Ordering::SeqCst);
vec![(5000, 222, "api".to_string())]
});
let watcher = PortWatcher::with_scanner(Duration::from_secs(60), scanner);
let _ = watcher.find_blocked(&[5000]);
watcher.clear();
let _ = watcher.find_blocked(&[5000]);
assert_eq!(calls.load(Ordering::SeqCst), 2);
}
#[test]
fn watcher_stale_entry_triggers_rescan() {
let calls = Arc::new(AtomicUsize::new(0));
let calls_for_scan = Arc::clone(&calls);
let scanner: Box<dyn Fn() -> Vec<(u16, u32, String)> + Send + Sync> = Box::new(move || {
calls_for_scan.fetch_add(1, Ordering::SeqCst);
vec![(9000, 333, "old".to_string())]
});
let watcher = PortWatcher::with_scanner(Duration::ZERO, scanner);
let _ = watcher.find_blocked(&[9000]);
let _ = watcher.find_blocked(&[9000]);
assert_eq!(calls.load(Ordering::SeqCst), 2);
}
#[test]
fn is_port_in_use_detects_bound_port() {
let listener = TcpListener::bind(("127.0.0.1", 0)).expect("bind ephemeral port");
let port = listener.local_addr().expect("local addr").port();
let occupied = is_port_in_use(port);
drop(listener);
assert!(occupied);
}
#[test]
fn is_port_in_use_free_after_drop() {
let listener = TcpListener::bind(("127.0.0.1", 0)).expect("bind ephemeral port");
let port = listener.local_addr().expect("local addr").port();
drop(listener);
assert!(!is_port_in_use(port));
}
#[test]
fn check_blocked_ports_runs_without_panicking() {
let results = check_blocked_ports(DEFAULT_DEV_PORTS);
for (port, pid, _) in &results {
assert!(DEFAULT_DEV_PORTS.contains(port));
assert_ne!(*pid, 0, "port {port} should resolve to a PID");
}
}
#[test]
fn default_ports_are_well_known_dev_ports() {
assert_eq!(DEFAULT_DEV_PORTS, &[3000, 5000, 8000, 8080, 9000]);
}
}