use std::fmt;
use std::io::Write;
use std::path::PathBuf;
#[cfg(target_os = "linux")]
use astrs_manifest::RT_PRIORITY_MAX;
use serde::Serialize;
use crate::error::CliError;
pub const DEFAULT_COORDINATOR_PORT: u16 = 7407;
pub const DEFAULT_DAEMON_PORT: u16 = 7408;
#[derive(Debug, Clone)]
pub struct DoctorArgs {
pub json: bool,
pub coordinator_port: u16,
pub daemon_port: u16,
}
impl Default for DoctorArgs {
fn default() -> Self {
Self {
json: false,
coordinator_port: DEFAULT_COORDINATOR_PORT,
daemon_port: DEFAULT_DAEMON_PORT,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CheckStatus {
Ok,
Info,
Warning,
Error,
}
impl fmt::Display for CheckStatus {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(match self {
Self::Ok => "ok",
Self::Info => "info",
Self::Warning => "warning",
Self::Error => "error",
})
}
}
#[derive(Debug, Clone, Serialize)]
pub struct DoctorCheck {
pub name: String,
pub status: CheckStatus,
pub detail: String,
}
#[derive(Debug, Clone, Serialize)]
pub struct DoctorReport {
pub checks: Vec<DoctorCheck>,
}
impl DoctorReport {
#[must_use]
pub fn exit_code(&self) -> i32 {
i32::from(self.checks.iter().any(|c| c.status == CheckStatus::Error))
}
}
pub fn run(out: &mut dyn Write, args: &DoctorArgs) -> Result<DoctorReport, CliError> {
let checks = vec![
check_port("port:coordinator", args.coordinator_port),
check_port("port:daemon", args.daemon_port),
check_shm(),
check_multicast(),
check_rt_capability(),
check_toolchain("rustc"),
check_toolchain("cargo"),
check_runtime_dir(),
];
let report = DoctorReport { checks };
if args.json {
let json = serde_json::to_string_pretty(&report).unwrap_or_else(|err| {
format!("{{\"error\": \"failed to serialize doctor report: {err}\"}}")
});
writeln!(out, "{json}").map_err(|e| CliError::io("<output>", e))?;
} else {
writeln!(out, "{}", render_table(&report)).map_err(|e| CliError::io("<output>", e))?;
}
Ok(report)
}
fn check_port(name: &str, port: u16) -> DoctorCheck {
match std::net::TcpListener::bind(("127.0.0.1", port)) {
Ok(_listener) => DoctorCheck {
name: name.to_string(),
status: CheckStatus::Ok,
detail: format!("127.0.0.1:{port} is available"),
},
Err(err) if err.kind() == std::io::ErrorKind::AddrInUse => DoctorCheck {
name: name.to_string(),
status: CheckStatus::Warning,
detail: format!(
"127.0.0.1:{port} is already in use (a daemon/coordinator may already be running): {err}"
),
},
Err(err) => DoctorCheck {
name: name.to_string(),
status: CheckStatus::Error,
detail: format!("could not probe 127.0.0.1:{port}: {err}"),
},
}
}
const RTPS_SPDP_GROUP: std::net::Ipv4Addr = std::net::Ipv4Addr::new(239, 255, 0, 1);
fn check_multicast() -> DoctorCheck {
let name = "multicast".to_string();
let socket = match std::net::UdpSocket::bind("0.0.0.0:0") {
Ok(socket) => socket,
Err(err) => {
return DoctorCheck {
name,
status: CheckStatus::Warning,
detail: format!("could not open a UDP socket to probe multicast: {err}"),
};
}
};
match socket.join_multicast_v4(&RTPS_SPDP_GROUP, &std::net::Ipv4Addr::UNSPECIFIED) {
Ok(()) => DoctorCheck {
name,
status: CheckStatus::Ok,
detail: format!("joined the RTPS SPDP probe group {RTPS_SPDP_GROUP} successfully"),
},
Err(err) => DoctorCheck {
name,
status: CheckStatus::Warning,
detail: format!(
"could not join multicast group {RTPS_SPDP_GROUP}: {err} (ROS 2 discovery, \
blueprint §10, will not work on this network; AstRS's own control plane does \
not use multicast and is unaffected)"
),
},
}
}
#[cfg(target_os = "linux")]
fn check_rt_capability() -> DoctorCheck {
let name = "rt".to_string();
let capabilities = match rustix::thread::capabilities(None) {
Ok(capabilities) => capabilities,
Err(err) => {
return DoctorCheck {
name,
status: CheckStatus::Warning,
detail: format!("could not read this process's capabilities: {err}"),
};
}
};
let has_cap_sys_nice = capabilities
.effective
.contains(rustix::thread::CapabilitySet::SYS_NICE);
let rtprio_soft = rustix::process::getrlimit(rustix::process::Resource::Rtprio)
.current
.unwrap_or(u64::MAX);
let max_priority = if has_cap_sys_nice {
u64::from(RT_PRIORITY_MAX)
} else {
rtprio_soft.min(u64::from(RT_PRIORITY_MAX))
};
if max_priority == 0 {
DoctorCheck {
name,
status: CheckStatus::Warning,
detail: "no real-time scheduling available: this process has neither \
CAP_SYS_NICE nor an RLIMIT_RTPRIO soft limit above 0 — a manifest \
`rt: { policy: fifo|rr, ... }` node will fail to spawn with EPERM. \
Grant CAP_SYS_NICE to the daemon binary (e.g. \
`setcap cap_sys_nice+ep <path-to-astrs-daemon>`) or raise \
RLIMIT_RTPRIO for the user running it (e.g. an `rtprio` line in \
/etc/security/limits.conf) to use it."
.to_string(),
}
} else {
DoctorCheck {
name,
status: CheckStatus::Ok,
detail: format!(
"real-time scheduling available up to priority {max_priority} (via {})",
if has_cap_sys_nice {
"CAP_SYS_NICE"
} else {
"RLIMIT_RTPRIO"
}
),
}
}
}
#[cfg(not(target_os = "linux"))]
fn check_rt_capability() -> DoctorCheck {
DoctorCheck {
name: "rt".to_string(),
status: CheckStatus::Info,
detail: "real-time scheduling reservations (rt:) are Linux-only; this platform \
always runs nodes under the ordinary time-sharing class regardless of any \
rt: block in the manifest"
.to_string(),
}
}
fn human_bytes(bytes: u64) -> String {
const UNITS: [&str; 5] = ["B", "KiB", "MiB", "GiB", "TiB"];
let mut value = bytes as f64;
let mut unit = 0;
while value >= 1024.0 && unit < UNITS.len() - 1 {
value /= 1024.0;
unit += 1;
}
if unit == 0 {
format!("{bytes} {}", UNITS[0])
} else {
format!("{value:.1} {}", UNITS[unit])
}
}
#[cfg(unix)]
fn check_shm() -> DoctorCheck {
match rustix::fs::statvfs("/dev/shm") {
Ok(stat) => {
let total = stat.f_frsize.saturating_mul(stat.f_blocks);
let available = stat.f_frsize.saturating_mul(stat.f_bavail);
DoctorCheck {
name: "shm".to_string(),
status: CheckStatus::Ok,
detail: format!(
"/dev/shm: {} total, {} available",
human_bytes(total),
human_bytes(available)
),
}
}
Err(_) => DoctorCheck {
name: "shm".to_string(),
status: CheckStatus::Info,
detail: "/dev/shm is not present on this platform (expected on macOS); AstRS's \
POSIX shared memory (shm_open) does not require it, and this check \
deliberately does not shell out to `sysctl` to approximate a kernel limit \
— see the runtime-dir check for a real writability probe instead"
.to_string(),
},
}
}
#[cfg(not(unix))]
fn check_shm() -> DoctorCheck {
DoctorCheck {
name: "shm".to_string(),
status: CheckStatus::Info,
detail: "SHM introspection is implemented for Unix platforms only".to_string(),
}
}
fn check_toolchain(binary: &str) -> DoctorCheck {
let name = format!("toolchain:{binary}");
match std::process::Command::new(binary).arg("--version").output() {
Ok(output) if output.status.success() => DoctorCheck {
name,
status: CheckStatus::Ok,
detail: String::from_utf8_lossy(&output.stdout).trim().to_string(),
},
Ok(output) => DoctorCheck {
name,
status: CheckStatus::Error,
detail: format!("`{binary} --version` exited with {}", output.status),
},
Err(err) => DoctorCheck {
name,
status: CheckStatus::Error,
detail: format!("could not run `{binary} --version`: {err}"),
},
}
}
fn check_runtime_dir() -> DoctorCheck {
let (dir, source) = runtime_dir();
if let Err(err) = std::fs::create_dir_all(&dir) {
return DoctorCheck {
name: "runtime_dir".to_string(),
status: CheckStatus::Error,
detail: format!("could not create `{}` ({source}): {err}", dir.display()),
};
}
let probe = dir.join(format!(".astrs-doctor-probe-{}", std::process::id()));
match std::fs::write(&probe, b"astrs doctor probe") {
Ok(()) => {
let _ = std::fs::remove_file(&probe);
DoctorCheck {
name: "runtime_dir".to_string(),
status: CheckStatus::Ok,
detail: format!("`{}` is writable ({source})", dir.display()),
}
}
Err(err) => DoctorCheck {
name: "runtime_dir".to_string(),
status: CheckStatus::Error,
detail: format!("`{}` exists but is not writable: {err}", dir.display()),
},
}
}
fn runtime_dir() -> (PathBuf, &'static str) {
match std::env::var_os("XDG_RUNTIME_DIR") {
Some(value) if !value.is_empty() => (PathBuf::from(value).join("astrs"), "XDG_RUNTIME_DIR"),
_ => (
std::env::temp_dir().join("astrs"),
"std::env::temp_dir() fallback (XDG_RUNTIME_DIR unset)",
),
}
}
fn render_table(report: &DoctorReport) -> String {
let name_width = report
.checks
.iter()
.map(|c| c.name.len())
.max()
.unwrap_or(4)
.max(4);
let mut out = String::new();
for check in &report.checks {
out.push_str(&format!(
"{:<name_width$} {:<7} {}\n",
check.name,
check.status.to_string(),
check.detail,
));
}
out.push_str(&format!(
"\n{} check(s), exit code {}",
report.checks.len(),
report.exit_code()
));
out
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
#[test]
fn a_bound_port_is_reported_in_use() {
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
let check = check_port("port:test", port);
assert_eq!(check.status, CheckStatus::Warning);
drop(listener);
}
#[test]
fn a_freed_port_is_reported_available() {
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
drop(listener);
let check = check_port("port:test", port);
assert_eq!(check.status, CheckStatus::Ok);
}
#[test]
fn human_bytes_formats_common_magnitudes() {
assert_eq!(human_bytes(512), "512 B");
assert_eq!(human_bytes(1536), "1.5 KiB");
assert_eq!(human_bytes(1024 * 1024 * 2), "2.0 MiB");
}
#[test]
fn shm_check_never_errors_only_ok_or_info() {
let check = check_shm();
assert!(matches!(check.status, CheckStatus::Ok | CheckStatus::Info));
}
#[test]
fn toolchain_checks_find_rustc_and_cargo_in_this_dev_environment() {
let rustc = check_toolchain("rustc");
assert_eq!(rustc.status, CheckStatus::Ok, "{rustc:?}");
let cargo = check_toolchain("cargo");
assert_eq!(cargo.status, CheckStatus::Ok, "{cargo:?}");
}
#[test]
fn toolchain_check_reports_error_for_a_nonexistent_binary() {
let check = check_toolchain("astrs-doctor-definitely-does-not-exist-as-a-binary");
assert_eq!(check.status, CheckStatus::Error);
}
#[test]
fn runtime_dir_check_creates_and_probes_writability() {
let check = check_runtime_dir();
assert_eq!(check.status, CheckStatus::Ok, "{check:?}");
}
#[test]
fn multicast_check_never_errors_only_ok_or_warning() {
let check = check_multicast();
assert!(
matches!(check.status, CheckStatus::Ok | CheckStatus::Warning),
"{check:?}"
);
assert!(check.detail.contains("239.255.0.1"));
}
#[test]
fn full_report_has_eight_checks_and_exit_code_is_zero_or_one() {
let mut out = Vec::new();
let report = run(&mut out, &DoctorArgs::default()).unwrap();
assert_eq!(report.checks.len(), 8);
assert!(report.exit_code() == 0 || report.exit_code() == 1);
}
#[test]
fn rt_capability_check_never_errors_only_ok_warning_or_info() {
let check = check_rt_capability();
assert!(
matches!(
check.status,
CheckStatus::Ok | CheckStatus::Warning | CheckStatus::Info
),
"{check:?}"
);
assert_eq!(check.name, "rt");
}
#[cfg(target_os = "linux")]
#[test]
fn rt_capability_check_names_the_grant_when_unavailable() {
let check = check_rt_capability();
if check.status == CheckStatus::Warning {
assert!(check.detail.contains("CAP_SYS_NICE"), "{}", check.detail);
assert!(check.detail.contains("RLIMIT_RTPRIO"), "{}", check.detail);
}
}
#[cfg(not(target_os = "linux"))]
#[test]
fn rt_capability_check_is_informational_off_linux() {
let check = check_rt_capability();
assert_eq!(check.status, CheckStatus::Info);
assert!(check.detail.contains("Linux-only"), "{}", check.detail);
}
#[test]
fn json_output_round_trips_every_check() {
let mut out = Vec::new();
let args = DoctorArgs {
json: true,
..DoctorArgs::default()
};
let report = run(&mut out, &args).unwrap();
let text = String::from_utf8(out).unwrap();
let value: serde_json::Value = serde_json::from_str(&text).unwrap();
assert_eq!(
value["checks"].as_array().map(Vec::len),
Some(report.checks.len())
);
}
#[test]
fn table_output_lists_every_check_name() {
let mut out = Vec::new();
let report = run(&mut out, &DoctorArgs::default()).unwrap();
let text = String::from_utf8(out).unwrap();
for check in &report.checks {
assert!(
text.contains(&check.name),
"missing {} in:\n{text}",
check.name
);
}
}
#[test]
fn default_ports_match_the_blueprint() {
assert_eq!(DEFAULT_COORDINATOR_PORT, 7407);
assert_eq!(DEFAULT_DAEMON_PORT, 7408);
}
}