nex_squid/crates/squid-platform/src/process.rs

341 lines
13 KiB
Rust

//! Stopping one process, because the interface is allowed to ask for it.
//!
//! A file cleaner that can list what is running can also be asked to stop what
//! is running, and the ask is honest: a hung app is the reason people open a
//! dashboard at all. The two halves of the job are not equally interesting.
//!
//! The *how* is boring and short. Unix sends `SIGKILL`; Windows opens the
//! process for `PROCESS_TERMINATE` and calls `TerminateProcess`. Both are the
//! same promise — this process stops now and saves nothing — which is why the
//! interface calls it a forced stop on every platform instead of a polite quit
//! it did not perform.
//!
//! The *whether* is where the damage is, so it is answered twice. First here,
//! by rule: squid never stops itself, never stops the first process of the
//! machine, and on Windows never stops the handful of processes a boot rests
//! on. Those rules exist because the OS does not enforce all of them. An
//! unelevated process on macOS cannot reach `WindowServer` anyway, but an
//! elevated `squid` on Windows *can* open `csrss.exe` for termination, and the
//! reward for one misplaced Enter is a machine that reboots without asking. A
//! guard that costs six names is cheaper than that conversation.
//!
//! Then by the operating system, whose answer is the only one that carries any
//! authority about this user, this token, this moment. The reason it says no is
//! kept: `EPERM` and `ERROR_ACCESS_DENIED` mean "you are not that user", which
//! tells the reader to reach for an elevated terminal, while `ESRCH` means the
//! process already left on its own, which asks for nothing at all. Guessing one
//! message for both is how a tool teaches people to distrust its errors.
//!
//! Note that this module answers for a pid and nothing else. Whether the pid in
//! front of the user is still the process they read the name of is a question
//! about the sample that produced it, and it is asked where the samples live
//! (`squid_stats::Sampler::stop`).
use std::fmt;
/// The rule that stands between squid and a process.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OffLimits {
/// The process is this squid. Stopping it would end the answer along with
/// the question.
Itself,
/// The first process of the machine: the kernel and `init`/`launchd` on
/// unix, the System Idle Process and `System` on Windows.
First,
/// A Windows process the session or the boot depends on, named here so the
/// message can say which.
Boot(&'static str),
}
impl OffLimits {
/// The rule in English, for logs and for the command line. The interface
/// translates the *rule*, not this sentence, so that one rule cannot drift
/// into two wordings.
pub fn reason(self) -> &'static str {
match self {
OffLimits::Itself => "this is squid itself",
OffLimits::First => "the first process of the machine",
OffLimits::Boot(name) => name,
}
}
}
/// Why a process was not stopped.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StopError {
/// It was already gone: either it exited between the list being drawn and
/// the key being pressed, or the pid now belongs to something else.
Gone { pid: u32 },
/// A rule in this module declined, before anything was attempted.
Refused(OffLimits),
/// The operating system refused, in its own words.
Denied { reason: String },
}
impl fmt::Display for StopError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
StopError::Gone { pid } => write!(f, "process {pid} is no longer running"),
StopError::Refused(rule) => write!(f, "refused: {}", rule.reason()),
StopError::Denied { reason } => f.write_str(reason),
}
}
}
impl std::error::Error for StopError {}
/// The processes a Windows session cannot afford to lose, without their
/// extension. `svchost` is deliberately absent: it hosts services a user may
/// genuinely need to restart, and the machine survives it.
#[cfg(windows)]
const CRITICAL: [&str; 6] = ["csrss", "smss", "wininit", "services", "lsass", "winlogon"];
/// The half of the rule a pid answers on its own, before anything is read
/// about it.
///
/// Split from [`refusal`] because the two halves get asked at different moments:
/// this one is asked of the number the interface is holding, where the name
/// rule needs the process that is really behind the number. A process that is
/// off limits should be refused as that, rather than reported as missing merely
/// because no listing happened to describe it.
pub fn pid_refusal(pid: u32) -> Option<OffLimits> {
if pid == std::process::id() {
return Some(OffLimits::Itself);
}
// Unix: 0 is the kernel, 1 is init. Windows: 0 is the System Idle Process
// and 4 is the System process, and both show up in a memory-sorted list.
if pid <= 1 || (cfg!(windows) && pid == 4) {
return Some(OffLimits::First);
}
None
}
/// Which rule declines this process, if one does.
///
/// `name` is what the process calls itself, which is the only thing the user
/// read. The comparison is on the extensionless stem because a listing may or
/// may not carry `.exe` depending on where it was taken from.
pub fn refusal(pid: u32, name: &str) -> Option<OffLimits> {
if let Some(rule) = pid_refusal(pid) {
return Some(rule);
}
// The name decides anything only on Windows, where a process is named as
// firmly as it is numbered. Taking it anyway keeps one question — "may this
// pid be stopped" — answerable from one place on every platform.
let _ = &name;
#[cfg(windows)]
{
let stem = name
.rsplit(['\\', '/'])
.next()
.unwrap_or(name)
.to_lowercase();
let stem = stem.strip_suffix(".exe").unwrap_or(&stem);
if let Some(found) = CRITICAL.iter().copied().find(|critical| *critical == stem) {
return Some(OffLimits::Boot(found));
}
}
None
}
/// Force a process to stop, now.
///
/// Only the pid is passed, so a caller that knows the name it displayed has to
/// check the name itself — which is the point: `refusal` and a fresh read of the
/// pid are the caller's job, and this function makes no promises about *which*
/// process the pid belongs to today.
pub fn force_stop(pid: u32) -> Result<(), StopError> {
// `cfg` rather than `cfg!`, because the halves of this function are not two
// branches of one program: on Windows there is no `unix` module to name, and
// on macOS there is no `windows` one. An `if` would ask both to exist.
#[cfg(unix)]
{
unix::force_stop(pid)
}
#[cfg(windows)]
{
windows::force_stop(pid)
}
#[cfg(not(any(unix, windows)))]
{
Err(StopError::Denied {
reason: "stopping processes is not implemented for this platform".into(),
})
}
}
#[cfg(unix)]
mod unix {
use super::StopError;
pub fn force_stop(pid: u32) -> Result<(), StopError> {
let rc = unsafe { libc::kill(pid as libc::pid_t, libc::SIGKILL) };
if rc == 0 {
return Ok(());
}
let error = std::io::Error::last_os_error();
// ESRCH: nothing answers to this pid any more. The user asked to stop a
// process and there is no process; that is a report, not a failure to
// explain away.
if error.raw_os_error() == Some(libc::ESRCH) {
return Err(StopError::Gone { pid });
}
Err(StopError::Denied {
reason: error.to_string(),
})
}
}
#[cfg(windows)]
mod windows {
use super::StopError;
use windows_sys::Win32::Foundation::CloseHandle;
use windows_sys::Win32::System::Threading::{OpenProcess, TerminateProcess, PROCESS_TERMINATE};
/// The exit status a forced stop reports. `1` is what Task Manager's
/// "End task" leaves behind, and nothing reads it: the process is simply
/// not running afterwards.
const FORCED: u32 = 1;
pub fn force_stop(pid: u32) -> Result<(), StopError> {
let handle = unsafe { OpenProcess(PROCESS_TERMINATE, 0, pid) };
if handle.is_null() {
return Err(denied(pid));
}
let ok = unsafe { TerminateProcess(handle, FORCED) };
unsafe { CloseHandle(handle) };
if ok == 0 {
return Err(denied(pid));
}
Ok(())
}
/// The message the system gave, in the words it gives the user: "Access is
/// denied." for a process owned by another account, "The parameter is
/// incorrect." once the pid has stopped existing.
fn denied(pid: u32) -> StopError {
let error = std::io::Error::last_os_error();
if error.raw_os_error().is_some_and(|code| code == 87) {
// ERROR_INVALID_PARAMETER: no such process.
return StopError::Gone { pid };
}
StopError::Denied {
reason: error.to_string(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::process::{Child, Command, Stdio};
#[test]
fn squid_never_stops_itself() {
let here = std::process::id();
assert_eq!(refusal(here, "squid"), Some(OffLimits::Itself));
}
#[test]
fn the_first_processes_are_off_limits_everywhere() {
assert_eq!(pid_refusal(0), Some(OffLimits::First));
assert_eq!(pid_refusal(1), Some(OffLimits::First));
assert_eq!(refusal(0, "kernel_task"), Some(OffLimits::First));
assert_eq!(refusal(1, "launchd"), Some(OffLimits::First));
// A normal process, on any platform, is fair game.
assert_eq!(refusal(4_242, "TextEdit"), None);
}
#[cfg(windows)]
#[test]
fn the_processes_a_boot_rests_on_are_named_not_guessed() {
assert_eq!(refusal(4, "System"), Some(OffLimits::First));
assert_eq!(
refusal(520, "C:\\Windows\\System32\\csrss.exe"),
Some(OffLimits::Boot("csrss"))
);
// Extensionless, upper case, and the folder it was read from must not
// change the answer.
assert_eq!(refusal(640, "LSASS"), Some(OffLimits::Boot("lsass")));
// `svchost` hosts services a user may need to restart, and the machine
// survives losing one, so the guard stays out of the way.
assert_eq!(refusal(1234, "svchost.exe"), None);
}
/// The whole point of the feature: a process that is running stops.
///
/// `ping` against the loopback is used because it exists on every platform
/// this runs on, takes a minute, and losing it hurts nothing. The test
/// waits for the exit rather than trusting the return code of the kill: on
/// Windows the kill is synchronous but the handle we spawned through is
/// not, and a zombie that has stopped running is still a stopped process.
#[test]
fn a_running_process_stops_when_it_is_asked() {
let mut child = sleeper();
let pid = child.id();
assert!(
child.try_wait().expect("child is running").is_none(),
"the child died before being asked"
);
let outcome = force_stop(pid);
if outcome.is_err() {
let _ = child.kill();
}
outcome.expect("stopping a child of this test must be allowed");
let status = child.wait().expect("the child is reaped");
assert!(
!status.success(),
"a killed process reported success: {status:?}"
);
}
fn sleeper() -> Child {
let mut command = if cfg!(windows) {
let mut command = Command::new("ping");
command.args(["-n", "60", "127.0.0.1"]);
command
} else {
let mut command = Command::new("sleep");
command.arg("60");
command
};
command
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn()
.expect("a loopback ping / sleep should start")
}
/// `ESRCH` and `EPERM` ask for opposite things from the reader — one says
/// "nothing to do", the other says "become a more privileged user" — so the
/// two must not arrive as the same message. A pid nobody owns is the
/// reproducible half of that pair.
#[cfg(unix)]
#[test]
fn a_pid_that_is_not_there_reports_itself_as_gone() {
let vacant = first_vacant_pid();
assert!(refusal(vacant, "Nothing").is_none());
let error = force_stop(vacant).expect_err("nothing owns this pid");
assert!(
matches!(error, StopError::Gone { pid } if pid == vacant),
"expected Gone({vacant}), got {error:?}"
);
}
/// PIDs are handed out upwards and then wrap, so just below the ceiling the
/// range is empty. The ceiling itself is not usable: `pid_t` is an `i32` on
/// macOS, and `kill` answers `EINVAL` rather than `ESRCH` outside its range.
#[cfg(unix)]
fn first_vacant_pid() -> u32 {
let top = if cfg!(target_os = "macos") {
999_999
} else {
4_194_304
};
(top - 64..top)
.filter(|pid| *pid != std::process::id())
.find(|pid| unsafe { libc::getpgid(*pid as libc::pid_t) } != 0)
.expect("a vacant pid near the top of the range")
}
}