H1: child processes die with Lutra (crates/proc)

New layer-0 crate lutra-proc: spawn(Command) puts the child into a
kill-on-close group. Windows: one job object per child with
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE (windows-sys), nested jobs work.
Unix: a new process group plus a /bin/sh watchdog that kills the group
when Lutra's pipe closes (drop, kill, quit or SIGKILL of Lutra).
Child::kill and Drop take the whole group.

Phpactor (supervision spawn) and the php -v probe in lutra-lsp start
through it. Tests kill a parent hard and check that its child is gone
(with and without the parent in a group), plus kill and drop of a tree.
Docs: architecture "Child processes", G6 note.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 12:59:57 +01:00
parent e5891ddeb4
commit 90d03284f2
13 changed files with 555 additions and 14 deletions

View file

@ -18,6 +18,7 @@ test = false
doc = false
[dependencies]
lutra-proc.workspace = true
lutra-text.workspace = true
lutra-vfs.workspace = true
ring = "0.17.14"

View file

@ -20,13 +20,14 @@ use std::ffi::{OsStr, OsString};
use std::io::{BufReader, Write};
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::path::{Path, PathBuf};
use std::process::{Child, ChildStdin, Command, Stdio};
use std::process::{ChildStdin, Command, Stdio};
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::mpsc::{self, Receiver, Sender, SyncSender, TrySendError};
use std::sync::{Arc, Mutex, MutexGuard, Weak};
use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant};
use lutra_proc::Child;
use lutra_text::{Buffer, Edit, Position};
use serde_json::{Value, json};
@ -470,7 +471,9 @@ impl Shared {
self.set_status(&mut state, Status::Ready);
}
/// Starts the server process with piped stdio and no console window.
/// Starts the server process with piped stdio and no console window,
/// in a [`lutra_proc`] group, so it and everything it starts die with
/// Lutra even when Lutra is killed.
///
/// # Errors
/// [`LspError::Spawn`] when the executable cannot be started.
@ -490,7 +493,7 @@ impl Shared {
use std::os::windows::process::CommandExt;
command.creation_flags(CREATE_NO_WINDOW);
}
command.spawn().map_err(|error| LspError::Spawn {
lutra_proc::spawn(command).map_err(|error| LspError::Spawn {
command: self.launch.command.to_string_lossy().into_owned(),
detail: error.to_string(),
})
@ -711,11 +714,11 @@ enum Exit {
Crashed(String),
}
/// Kills and reaps a process. Errors are ignored on purpose: the process
/// may have exited already, and there is nothing else to do about it.
/// Kills and reaps a process and everything in its group. Errors are
/// ignored on purpose: the process may have exited already, and there is
/// nothing else to do about it.
fn kill(child: &mut Child) {
let _ = child.kill();
let _ = child.wait();
let _ = child.kill_and_wait();
}
/// Calls a reply outside any lock. A panicking callback is caught so it

View file

@ -188,7 +188,7 @@ pub fn run_version(path: &Path, timeout: Duration) -> Result<Vec<u8>, PhpError>
.stdout(Stdio::piped())
.stderr(Stdio::null());
hide_window(&mut command);
let mut child = command.spawn().map_err(|e| failed(e.to_string()))?;
let mut child = lutra_proc::spawn(command).map_err(|e| failed(e.to_string()))?;
let stdout = child
.stdout
.take()
@ -208,8 +208,7 @@ pub fn run_version(path: &Path, timeout: Duration) -> Result<Vec<u8>, PhpError>
match child.try_wait() {
Ok(Some(status)) => break status,
Ok(None) if Instant::now() >= deadline => {
let _ = child.kill();
let _ = child.wait();
let _ = child.kill_and_wait();
return Err(failed(format!(
"php -v did not finish within {} s",
timeout.as_secs()

29
crates/proc/Cargo.toml Normal file
View file

@ -0,0 +1,29 @@
[package]
name = "lutra-proc"
description = "Child processes that die with Lutra: job objects on Windows, process groups on Unix"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 0
[[bin]]
name = "lutra-proc-helper"
path = "src/bin/lutra-proc-helper.rs"
test = false
doc = false
[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61.2", features = [
"Win32_Foundation",
"Win32_Security",
"Win32_System_JobObjects",
"Win32_System_Threading",
] }
[lints]
workspace = true

View file

@ -0,0 +1,77 @@
//! A process tree builder for the `lutra-proc` tests.
//!
//! Not shipped: the integration tests start it through
//! `CARGO_BIN_EXE_lutra-proc-helper`. Roles, by the first argument:
//!
//! - `tree-plain`: starts a sleeping grandchild with a plain
//! [`std::process::Command`], `tree-proc`: starts it through
//! [`lutra_proc::spawn`]. The grandchild is a system program (`ping` on
//! Windows, `sleep` elsewhere) rather than this helper, because virus
//! scanners delay an unsigned program that starts copies of itself by
//! tens of seconds. It gets this process's standard output as its
//! standard error, so it holds the pipe without writing to it. Then this
//! process prints `ready` and sleeps. A test reading that output sees
//! end of file only once the grandchild is gone too, which is how it
//! checks that no process was left behind.
//!
//! Any other argument exits with code 2.
use std::io::Write;
use std::process::{Command, ExitCode, Stdio};
use std::thread;
use std::time::Duration;
/// How long the helper and its grandchild sleep.
const SLEEP: Duration = Duration::from_secs(120);
/// Runs the role named by the first argument.
fn main() -> ExitCode {
let role = std::env::args().nth(1).unwrap_or_default();
match role.as_str() {
"tree-plain" | "tree-proc" => tree(role == "tree-proc"),
_ => ExitCode::from(2),
}
}
/// Starts the grandchild (through `lutra_proc` when `guarded`), prints
/// `ready` and sleeps.
fn tree(guarded: bool) -> ExitCode {
let mut command = grandchild();
command
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::from(std::io::stdout()));
let _guarded;
let _plain;
if guarded {
let Ok(child) = lutra_proc::spawn(command) else {
return ExitCode::from(4);
};
_guarded = child;
} else {
let Ok(child) = command.spawn() else {
return ExitCode::from(4);
};
_plain = child;
}
let mut out = std::io::stdout();
if writeln!(out, "ready").and_then(|()| out.flush()).is_err() {
return ExitCode::from(5);
}
thread::sleep(SLEEP);
ExitCode::SUCCESS
}
/// A system program that sleeps for [`SLEEP`] without output.
fn grandchild() -> Command {
let seconds = SLEEP.as_secs();
if cfg!(windows) {
let mut command = Command::new("ping");
command.args(["-n", &(seconds + 1).to_string(), "127.0.0.1"]);
command
} else {
let mut command = Command::new("sleep");
command.arg(seconds.to_string());
command
}
}

161
crates/proc/src/lib.rs Normal file
View file

@ -0,0 +1,161 @@
//! Child processes that die with Lutra (layer L0).
//!
//! [`spawn`] starts a [`std::process::Command`] inside a group that the
//! operating system tears down when Lutra's process ends, even when Lutra
//! is killed hard, and returns a [`Child`] whose [`Child::kill`] and
//! [`Drop`] take the whole group (the child and everything it started).
//! Phpactor uses it now; git, `php -l` and other tools use it next.
//!
//! - **Windows:** every child gets its own job object with
//! `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. Lutra holds the only handle, so
//! the job closes, and kills its processes, when the [`Child`] is dropped
//! or when Lutra's process ends in any way (the kernel closes its
//! handles). Jobs nest (Windows 8 and later), so this works when Lutra
//! itself runs inside a job (a terminal, `cargo`, a CI runner).
//! Processes the child starts are in the job too.
//! - **Unix:** the child leads a new process group. A watchdog
//! (`/bin/sh`, in its own process group) blocks on a pipe whose write end
//! only Lutra holds; when the pipe closes, because the [`Child`] is
//! dropped or killed, because Lutra quits, or because Lutra is killed
//! with `SIGKILL`, it sends `SIGKILL` to the child's group. What a
//! `SIGKILL` of Lutra can still leave behind: processes that left the
//! group themselves (`setsid`, `setpgid`, i.e. daemons), and the child if
//! Lutra dies in the microseconds between starting it and starting its
//! watchdog. If the watchdog itself is killed, the group is only killed
//! by an explicit [`Child::kill`] or drop, which then signal the direct
//! child only.
//!
//! A child starts running before it is put into its job (Windows) or before
//! its watchdog exists (Unix), so a grandchild it starts in that window
//! (microseconds) can escape; language servers and git start their own
//! children much later.
use std::io;
use std::ops::{Deref, DerefMut};
use std::process::{Command, ExitStatus};
#[cfg(unix)]
mod unix;
#[cfg(windows)]
mod windows;
#[cfg(unix)]
use unix::Group;
#[cfg(windows)]
use windows::Group;
/// The group a child runs in on platforms without job objects or process
/// groups: nothing beyond the child itself.
#[cfg(not(any(unix, windows)))]
struct Group;
#[cfg(not(any(unix, windows)))]
impl Group {
/// Nothing to set up.
fn prepare(_command: &mut Command) {}
/// Nothing to attach.
///
/// # Errors
/// Never.
fn attach(_child: &std::process::Child) -> io::Result<Self> {
Ok(Self)
}
/// Nothing to kill beyond the child, which [`Child::kill`] handles.
fn kill(&mut self) {}
}
/// A child process in its own kill-on-close group.
///
/// It dereferences to [`std::process::Child`] for the pipes, `id`,
/// `try_wait` and `wait`. [`Child::kill`] replaces the standard `kill` and
/// takes the whole group. Dropping it kills the group and reaps the child,
/// so a [`Child`] must be kept for as long as the process should run.
pub struct Child {
/// The process itself.
inner: std::process::Child,
/// Its job object (Windows) or watchdog (Unix).
group: Group,
}
/// Starts `command` in a new kill-on-close group (see the crate docs).
///
/// Everything else about `command` (arguments, environment, working
/// directory, stdio, Windows creation flags) is used as given.
///
/// # Errors
/// The error of [`Command::spawn`], or the error of setting up the group
/// (Windows: creating the job or assigning the process to it; Unix:
/// starting the watchdog). When the group cannot be set up, the child that
/// was already started is killed and reaped before the error is returned,
/// so it never runs unguarded.
pub fn spawn(mut command: Command) -> io::Result<Child> {
Group::prepare(&mut command);
let mut inner = command.spawn()?;
match Group::attach(&inner) {
Ok(group) => Ok(Child { inner, group }),
Err(error) => {
let _ = inner.kill();
let _ = inner.wait();
Err(error)
}
}
}
impl Child {
/// Kills the child and every process in its group, without waiting for
/// the child; call [`std::process::Child::wait`] to reap it.
///
/// Killing a child that has exited already is not an error.
///
/// # Errors
/// The error of killing the direct child, as
/// [`std::process::Child::kill`] reports it. Failing to reach the rest
/// of the group is not reported: the job (Windows) or watchdog (Unix)
/// is the only handle on it, and it is consumed either way.
pub fn kill(&mut self) -> io::Result<()> {
self.group.kill();
self.inner.kill()
}
/// Kills the group (see [`Child::kill`]) and waits for the child.
///
/// # Errors
/// The error of [`std::process::Child::wait`].
pub fn kill_and_wait(&mut self) -> io::Result<ExitStatus> {
let _ = self.kill();
self.inner.wait()
}
}
impl Deref for Child {
type Target = std::process::Child;
fn deref(&self) -> &Self::Target {
&self.inner
}
}
impl DerefMut for Child {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.inner
}
}
impl std::fmt::Debug for Child {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Child")
.field("id", &self.inner.id())
.finish_non_exhaustive()
}
}
impl Drop for Child {
/// Kills the group and reaps the child. Errors are ignored on purpose:
/// the process may have exited already, and a destructor has no one to
/// report to.
fn drop(&mut self) {
let _ = self.kill_and_wait();
}
}

68
crates/proc/src/unix.rs Normal file
View file

@ -0,0 +1,68 @@
//! Unix: the child leads a new process group, and a watchdog kills that
//! group when Lutra's end of a pipe closes.
//!
//! The watchdog is `/bin/sh` reading its standard input, a pipe whose
//! write end only the [`Group`] holds (standard library pipes are
//! close-on-exec, so no other child inherits it). `read` returns at end of
//! file, which happens when the [`Group`] drops the pipe or when Lutra's
//! process ends for any reason, including `SIGKILL`; the watchdog then
//! sends `SIGKILL` to the group. It runs in a process group of its own, so
//! a Ctrl-C or hangup aimed at Lutra's group does not take it down first.
use std::io;
use std::os::unix::process::CommandExt;
use std::process::{ChildStdin, Command, Stdio};
/// The watchdog script: wait for end of file on stdin, then kill the
/// process group given as `$1`.
const WATCHDOG: &str = "read -r _; kill -KILL -\"$1\" 2>/dev/null";
/// The child's process group and its watchdog.
pub(crate) struct Group {
/// The watchdog process, reaped after it has killed the group.
watchdog: std::process::Child,
/// Lutra's end of the watchdog's pipe; dropping it fires the watchdog.
trigger: Option<ChildStdin>,
}
impl Group {
/// Makes the child the leader of a new process group.
pub(crate) fn prepare(command: &mut Command) {
command.process_group(0);
}
/// Starts the watchdog for the group led by `child`.
///
/// # Errors
/// The error of starting `/bin/sh`, or a missing stdin pipe.
pub(crate) fn attach(child: &std::process::Child) -> io::Result<Self> {
let mut watchdog = Command::new("/bin/sh")
.arg("-c")
.arg(WATCHDOG)
.arg("lutra-proc-watchdog")
.arg(child.id().to_string())
.stdin(Stdio::piped())
.stdout(Stdio::null())
.stderr(Stdio::null())
.process_group(0)
.spawn()?;
let Some(trigger) = watchdog.stdin.take() else {
let _ = watchdog.kill();
let _ = watchdog.wait();
return Err(io::Error::other("the watchdog has no stdin pipe"));
};
Ok(Self {
watchdog,
trigger: Some(trigger),
})
}
/// Fires the watchdog and waits until it has killed the group. The
/// results are ignored on purpose: a watchdog that is gone already has
/// nothing left to do, and the caller kills the direct child itself.
pub(crate) fn kill(&mut self) {
if self.trigger.take().is_some() {
let _ = self.watchdog.wait();
}
}
}

View file

@ -0,0 +1,77 @@
//! Windows: one job object per child with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`
//! (<https://learn.microsoft.com/windows/win32/procthread/job-objects>).
//!
//! This is the one module in Lutra that allows `unsafe`: the job object API
//! is only reachable through FFI. Every call gets valid arguments by
//! construction: handles come from `CreateJobObjectW` (owned by an
//! [`OwnedHandle`] right away) or from a live [`std::process::Child`], and
//! the limit structure is a plain C struct that is valid when zeroed.
#![allow(unsafe_code)]
use std::io;
use std::os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle};
use std::process::Command;
use windows_sys::Win32::System::JobObjects::{
AssignProcessToJobObject, CreateJobObjectW, JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
JOBOBJECT_EXTENDED_LIMIT_INFORMATION, JobObjectExtendedLimitInformation,
SetInformationJobObject, TerminateJobObject,
};
/// The exit code a process killed with its job reports.
const KILLED_EXIT_CODE: u32 = 1;
/// The job a child runs in. Lutra holds the only handle; closing it (on
/// drop, or when Lutra's process ends) kills every process in the job.
pub(crate) struct Group {
/// The job object.
job: OwnedHandle,
}
impl Group {
/// Nothing to set on the command: the process joins its job right
/// after it starts.
pub(crate) fn prepare(_command: &mut Command) {}
/// Creates a kill-on-close job and puts `child` into it.
///
/// # Errors
/// The OS error of `CreateJobObjectW`, `SetInformationJobObject` or
/// `AssignProcessToJobObject`.
pub(crate) fn attach(child: &std::process::Child) -> io::Result<Self> {
let raw = unsafe { CreateJobObjectW(std::ptr::null(), std::ptr::null()) };
if raw.is_null() {
return Err(io::Error::last_os_error());
}
let job = unsafe { OwnedHandle::from_raw_handle(raw) };
let mut limits: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { std::mem::zeroed() };
limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
let size = u32::try_from(std::mem::size_of::<JOBOBJECT_EXTENDED_LIMIT_INFORMATION>())
.map_err(io::Error::other)?;
let set = unsafe {
SetInformationJobObject(
job.as_raw_handle(),
JobObjectExtendedLimitInformation,
std::ptr::from_ref(&limits).cast(),
size,
)
};
if set == 0 {
return Err(io::Error::last_os_error());
}
let assigned =
unsafe { AssignProcessToJobObject(job.as_raw_handle(), child.as_raw_handle()) };
if assigned == 0 {
return Err(io::Error::last_os_error());
}
Ok(Self { job })
}
/// Terminates every process in the job. The result is ignored on
/// purpose: the job may be empty already, and closing the handle on
/// drop kills whatever is left anyway.
pub(crate) fn kill(&mut self) {
let _ = unsafe { TerminateJobObject(self.job.as_raw_handle(), KILLED_EXIT_CODE) };
}
}

View file

@ -0,0 +1,103 @@
//! Process trees started through `lutra_proc` die with their owner.
//!
//! Each test starts `lutra-proc-helper` in a tree role: the helper starts a
//! sleeping grandchild that holds its standard output, prints `ready`
//! and sleeps. Reading that output to end of file proves that every
//! process holding it, the grandchild included, has exited. Without the
//! groups the grandchild sleeps for two minutes and the read times out.
#![allow(clippy::unwrap_used)]
use std::io::{BufRead, BufReader, Read};
use std::process::{ChildStdout, Command, Stdio};
use std::sync::mpsc;
use std::thread;
use std::time::Duration;
/// How long a test waits for a tree to go away.
const GONE_WITHIN: Duration = Duration::from_secs(15);
/// The helper in `role`, with its output piped.
fn helper(role: &str) -> Command {
let mut command = Command::new(env!("CARGO_BIN_EXE_lutra-proc-helper"));
command
.arg(role)
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::null());
command
}
/// Waits for the helper's `ready` line and returns the rest of its output.
fn ready(stdout: ChildStdout) -> BufReader<ChildStdout> {
let mut reader = BufReader::new(stdout);
let mut line = String::new();
reader.read_line(&mut line).unwrap();
assert_eq!(line.trim(), "ready");
reader
}
/// Asserts that the output reaches end of file within [`GONE_WITHIN`],
/// i.e. that no process holding it is left.
fn assert_gone(mut reader: BufReader<ChildStdout>) {
let (tx, rx) = mpsc::channel();
thread::spawn(move || {
let mut rest = Vec::new();
let _ = reader.read_to_end(&mut rest);
let _ = tx.send(());
});
assert!(
rx.recv_timeout(GONE_WITHIN).is_ok(),
"a grandchild still holds the pipe after {GONE_WITHIN:?}"
);
}
#[test]
fn hard_kill_of_the_parent_takes_its_guarded_child() {
let mut parent = helper("tree-proc").spawn().unwrap();
let reader = ready(parent.stdout.take().unwrap());
parent.kill().unwrap();
parent.wait().unwrap();
assert_gone(reader);
}
#[test]
fn hard_kill_works_when_the_parent_is_in_a_group_itself() {
let mut parent = lutra_proc::spawn(helper("tree-proc")).unwrap();
let reader = ready(parent.stdout.take().unwrap());
std::process::Child::kill(&mut parent).unwrap();
parent.wait().unwrap();
assert_gone(reader);
drop(parent);
}
#[test]
fn kill_takes_the_whole_tree() {
let mut parent = lutra_proc::spawn(helper("tree-plain")).unwrap();
let reader = ready(parent.stdout.take().unwrap());
parent.kill().unwrap();
parent.wait().unwrap();
assert_gone(reader);
}
#[test]
fn drop_takes_the_whole_tree() {
let mut parent = lutra_proc::spawn(helper("tree-plain")).unwrap();
let reader = ready(parent.stdout.take().unwrap());
drop(parent);
assert_gone(reader);
}
#[test]
fn a_child_that_exits_reports_its_status() {
let mut child = lutra_proc::spawn(helper("unknown-role")).unwrap();
let status = child.wait().unwrap();
assert_eq!(status.code(), Some(2));
child.kill().unwrap();
}
#[test]
fn a_missing_program_is_an_error() {
let error = lutra_proc::spawn(Command::new("lutra-proc-no-such-program")).unwrap_err();
assert_eq!(error.kind(), std::io::ErrorKind::NotFound);
}