byteor_runtime/

doctor.rs

use std::path::{Path, PathBuf};

use serde::Serialize;

use crate::{
    effective_tuning_report, profile_defaults, EffectiveTuningReport, MlockallPreset,
    ResolvedTuning, TuningProfile,
};
use crate::host::{probe_shm_dir_writable, shm_runtime_context};
use crate::tuning::refresh_effective_tuning_rollup;

/// One doctor/preflight check.
#[derive(Debug, Serialize)]
pub struct Check {
    /// Stable check name.
    pub name: &'static str,
    /// Whether the check passed.
    pub ok: bool,
    /// Machine-readable details.
    pub details: serde_json::Value,
}

/// Doctor/preflight report.
#[derive(Debug, Serialize)]
pub struct Report {
    /// Whether all checks passed.
    pub ok: bool,
    /// Selected tuning profile.
    pub profile: String,
    /// Effective tuning derived from the profile and CLI overrides.
    pub tuning: EffectiveTuningReport,
    /// Per-check results.
    pub checks: Vec<Check>,
}

/// Print a human-friendly summary of checks to stderr.
pub fn eprint_human(checks: &[Check]) {
    for c in checks {
        if c.ok {
            eprintln!("ok   {}", c.name);
        } else {
            eprintln!("FAIL {}", c.name);
        }
    }
}

fn read_proc_status_field(name: &str) -> Option<String> {
    let s = std::fs::read_to_string("/proc/self/status").ok()?;
    for line in s.lines() {
        if let Some(rest) = line.strip_prefix(&format!("{name}:")) {
            return Some(rest.trim().to_string());
        }
    }
    None
}

fn cpu_pinning_check() -> Check {
    let allowed = read_proc_status_field("Cpus_allowed_list");
    let ok = allowed.as_deref().map(|s| !s.is_empty()).unwrap_or(false);
    Check {
        name: "cpu_pinning",
        ok,
        details: serde_json::json!({
            "cpus_allowed_list": allowed,
        }),
    }
}

fn parse_cap_eff_hex(s: &str) -> Option<u64> {
    u64::from_str_radix(s.trim(), 16).ok()
}

fn has_cap_ipc_lock() -> Option<bool> {
    let cap_eff = read_proc_status_field("CapEff")?;
    let n = parse_cap_eff_hex(&cap_eff)?;
    Some((n & (1u64 << 14)) != 0)
}

fn has_cap_sys_nice() -> Option<bool> {
    let cap_eff = read_proc_status_field("CapEff")?;
    let n = parse_cap_eff_hex(&cap_eff)?;
    Some((n & (1u64 << 23)) != 0)
}

fn proc_limits_soft_value_bytes(name_prefix: &str) -> Option<u64> {
    let limits = std::fs::read_to_string("/proc/self/limits").ok()?;
    for line in limits.lines() {
        if !line.starts_with(name_prefix) {
            continue;
        }
        let parts: Vec<&str> = line.split_whitespace().collect();
        if parts.len() < 4 {
            return None;
        }
        let soft = parts[parts.len().saturating_sub(3)];
        if soft == "unlimited" {
            return None;
        }
        let n = soft.parse::<u64>().ok()?;
        let units = parts[parts.len().saturating_sub(1)];
        match units {
            "bytes" => return Some(n),
            "kbytes" => return Some(n.saturating_mul(1024)),
            _ => return None,
        }
    }
    None
}

fn proc_limits_soft_value_u64(name_prefix: &str) -> Option<u64> {
    let limits = std::fs::read_to_string("/proc/self/limits").ok()?;
    for line in limits.lines() {
        if !line.starts_with(name_prefix) {
            continue;
        }
        let parts: Vec<&str> = line.split_whitespace().collect();
        if parts.len() < 4 {
            return None;
        }
        let soft = parts[parts.len().saturating_sub(3)];
        if soft == "unlimited" {
            return None;
        }
        return soft.parse::<u64>().ok();
    }
    None
}

fn mlockall_availability_check(mlockall_required: bool) -> Check {
    mlockall_availability_check_from_state(
        mlockall_required,
        has_cap_ipc_lock(),
        proc_limits_soft_value_bytes("Max locked memory"),
    )
}

pub(crate) fn mlockall_availability_check_from_state(
    mlockall_required: bool,
    cap_ipc_lock: Option<bool>,
    max_locked_bytes: Option<u64>,
) -> Check {
    let ok = if !mlockall_required {
        true
    } else {
        let cap_ok = cap_ipc_lock.unwrap_or(false);
        let rlimit_ok = max_locked_bytes.unwrap_or(0) > 0;
        cap_ok || rlimit_ok
    };

    Check {
        name: "mlockall",
        ok,
        details: serde_json::json!({
            "required": mlockall_required,
            "cap_ipc_lock": cap_ipc_lock,
            "max_locked_bytes": max_locked_bytes,
        }),
    }
}

fn rt_scheduling_capability_check() -> Check {
    rt_scheduling_capability_check_from_state(
        has_cap_sys_nice(),
        proc_limits_soft_value_u64("Max realtime priority"),
    )
}

pub(crate) fn rt_scheduling_capability_check_from_state(
    cap_sys_nice: Option<bool>,
    max_rt_prio: Option<u64>,
) -> Check {
    let ok = cap_sys_nice.unwrap_or(false) || max_rt_prio.unwrap_or(0) > 0;

    Check {
        name: "rt_scheduling",
        ok,
        details: serde_json::json!({
            "cap_sys_nice": cap_sys_nice,
            "max_realtime_priority": max_rt_prio,
        }),
    }
}

pub(crate) fn annotate_tuning_report_from_checks(
    mut tuning: EffectiveTuningReport,
    checks: &[Check],
) -> EffectiveTuningReport {
    for check in checks {
        if let Some(observations) = tuning.host_observations.as_mut() {
            match check.name {
                "cpu_pinning" => {
                    observations.cpu_pinning_supported = Some(check.ok);
                    observations.observed_cpu_set = check
                        .details
                        .get("cpus_allowed_list")
                        .and_then(serde_json::Value::as_str)
                        .map(ToOwned::to_owned);
                }
                "mlockall" => {
                    observations.mlockall_supported = Some(check.ok);
                }
                "rt_scheduling" => {
                    observations.realtime_scheduler_supported = Some(check.ok);
                }
                _ => {}
            }
        }

        if check.ok {
            continue;
        }

        match check.name {
            "cpu_pinning" if tuning.requested.pinning_mode.is_some() => {
                tuning.applied.pinning_mode = None;
                tuning.degraded.pinning_mode = tuning.requested.pinning_mode.clone();
                push_failure_reason(
                    &mut tuning.failure_reasons,
                    "pinning requested but host readiness checks did not confirm a usable CPU affinity mask"
                        .to_string(),
                );
            }
            "mlockall" if tuning.requested.mlockall == Some(true) => {
                tuning.applied.mlockall = None;
                tuning.degraded.mlockall = Some(true);
                push_failure_reason(
                    &mut tuning.failure_reasons,
                    "mlockall requested but host readiness checks did not confirm CAP_IPC_LOCK or a sufficient memlock rlimit"
                        .to_string(),
                );
            }
            "shm_dir" => {
                tuning.applied.shm_parent = None;
                tuning.degraded.shm_parent = tuning.requested.shm_parent.clone();
                let detail = check
                    .details
                    .get("write_err")
                    .and_then(serde_json::Value::as_str)
                    .or_else(|| check.details.get("path").and_then(serde_json::Value::as_str))
                    .unwrap_or("shm_dir check failed");
                push_failure_reason(
                    &mut tuning.failure_reasons,
                    format!("shm_parent requested but host readiness checks failed: {detail}"),
                );
            }
            "rt_scheduling" if tuning.requested.sched_preset.is_some() => {
                tuning.applied.sched_preset = None;
                tuning.applied.rt_prio = None;
                tuning.degraded.sched_preset = tuning.requested.sched_preset.clone();
                tuning.degraded.rt_prio = tuning.requested.rt_prio;
                push_failure_reason(
                    &mut tuning.failure_reasons,
                    "realtime scheduling requested but host readiness checks did not confirm CAP_SYS_NICE or a sufficient realtime priority rlimit"
                        .to_string(),
                );
            }
            _ => {}
        }
    }

    refresh_effective_tuning_rollup(&mut tuning);

    tuning
}

fn push_failure_reason(reasons: &mut Vec<String>, reason: String) {
    if !reasons.iter().any(|existing| existing == &reason) {
        reasons.push(reason);
    }
}

fn shm_dir_check(shm_parent: &Path) -> Check {
    let mut ok = true;
    let context = shm_runtime_context(shm_parent);
    let mut detail = serde_json::json!({
        "path": context.path,
        "fstype": context.mount_fstype,
        "hugetlbfs": context.hugetlbfs,
    });

    if !shm_parent.exists() {
        ok = false;
        detail["exists"] = serde_json::json!(false);
    } else {
        detail["exists"] = serde_json::json!(true);
        detail["is_dir"] = serde_json::json!(shm_parent.is_dir());
        if !shm_parent.is_dir() {
            ok = false;
        }

        match probe_shm_dir_writable(shm_parent) {
            Ok(()) => {
                detail["writable"] = serde_json::json!(true);
            }
            Err(e) => {
                ok = false;
                detail["writable"] = serde_json::json!(false);
                detail["write_err"] = serde_json::json!(e.to_string());
            }
        }
    }

    Check {
        name: "shm_dir",
        ok,
        details: detail,
    }
}

/// Run `doctor` / preflight checks.
pub fn doctor(mlockall_required: bool, shm_parent: PathBuf) -> Report {
    let mut tuning = profile_defaults(TuningProfile::Default, shm_parent);
    tuning.mlockall = if mlockall_required {
        MlockallPreset::On
    } else {
        MlockallPreset::None
    };
    doctor_with_tuning(&tuning)
}

pub fn doctor_with_tuning(tuning: &ResolvedTuning) -> Report {
    let mut checks = Vec::new();
    checks.push(cpu_pinning_check());
    checks.push(mlockall_availability_check(
        tuning.mlockall == MlockallPreset::On,
    ));
    checks.push(shm_dir_check(&tuning.shm_parent));

    #[cfg(target_os = "linux")]
    {
        let preflight =
            byteor_ops::preflight_linux_minimal(&tuning.shm_parent, tuning.mlockall == MlockallPreset::On);
        match preflight {
            Ok(r) => {
                checks.push(Check {
                    name: "linux_preflight",
                    ok: r.is_ok(),
                    details: serde_json::json!({
                        "observations": r.observations,
                        "warnings": r.warnings,
                        "errors": r.errors,
                        "strict": tuning.mlockall == MlockallPreset::On,
                    }),
                });
            }
            Err(e) => {
                checks.push(Check {
                    name: "linux_preflight",
                    ok: false,
                    details: serde_json::json!({
                        "error": e.to_string(),
                        "strict": tuning.mlockall == MlockallPreset::On,
                    }),
                });
            }
        }

        checks.push(rt_scheduling_capability_check());
    }

    let ok = checks.iter().all(|c| c.ok);
    let tuning = annotate_tuning_report_from_checks(effective_tuning_report(tuning.profile, tuning), &checks);
    Report {
        ok,
        profile: tuning.profile.as_str().to_string(),
        tuning,
        checks,
    }
}