diff --git a/Cargo.lock b/Cargo.lock index 45a7cf0..c3a9bb1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2589,6 +2589,7 @@ dependencies = [ "lutra-control", "lutra-engine", "lutra-mcp", + "lutra-proc", "lutra-testkit", "proptest", "serde_json", diff --git a/apps/lutra-cli/Cargo.toml b/apps/lutra-cli/Cargo.toml index eb67709..245f79e 100644 --- a/apps/lutra-cli/Cargo.toml +++ b/apps/lutra-cli/Cargo.toml @@ -18,6 +18,7 @@ path = "src/main.rs" [dependencies] lutra-control.workspace = true lutra-mcp.workspace = true +lutra-proc.workspace = true serde_json = "1.0.154" [dev-dependencies] diff --git a/apps/lutra-cli/src/launch.rs b/apps/lutra-cli/src/launch.rs index 3d6be82..c4ad5f7 100644 --- a/apps/lutra-cli/src/launch.rs +++ b/apps/lutra-cli/src/launch.rs @@ -1,7 +1,6 @@ //! Finding and starting the desktop app when no Lutra is running. use std::path::{Path, PathBuf}; -use std::process::{Command, Stdio}; use std::thread; use std::time::{Duration, Instant}; @@ -70,11 +69,13 @@ fn resolve_link(path: PathBuf) -> PathBuf { std::fs::canonicalize(&path).unwrap_or(path) } -/// Starts `desktop` detached from this terminal (Windows: a detached process -/// in a new process group; Unix: a new process group, so a Ctrl-C or -/// hangup aimed at the terminal's foreground group does not reach it) and -/// waits until it answers -/// on the rendezvous file in `dir`. A desktop that exits successfully may +/// Starts `desktop` detached from this terminal through +/// [`lutra_proc::spawn_detached`] (Windows: a detached process in a new +/// process group that inherits none of this process's handles, so a script +/// reading `lutra`'s output through a pipe gets end of file as soon as +/// `lutra` exits; Unix: a new process group, so a Ctrl-C or hangup aimed at +/// the terminal's foreground group does not reach it) and waits until it +/// answers on the rendezvous file in `dir`. A desktop that exits successfully may /// have forwarded to an instance that started at the same time, so only a /// failed exit ends the wait early. /// @@ -82,25 +83,7 @@ fn resolve_link(path: PathBuf) -> PathBuf { /// A message if it cannot be started, exits early, or does not answer /// within [`START_TIMEOUT`]. pub fn start(desktop: &Path, dir: &Path) -> Result { - let mut command = Command::new(desktop); - command - .stdin(Stdio::null()) - .stdout(Stdio::null()) - .stderr(Stdio::null()); - #[cfg(windows)] - { - use std::os::windows::process::CommandExt; - const DETACHED_PROCESS: u32 = 0x0000_0008; - const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200; - command.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP); - } - #[cfg(unix)] - { - use std::os::unix::process::CommandExt; - command.process_group(0); - } - let mut child = command - .spawn() + let mut child = lutra_proc::spawn_detached(desktop, &[]) .map_err(|e| format!("cannot start {}: {e}", desktop.display()))?; let deadline = Instant::now() + START_TIMEOUT; loop { diff --git a/crates/proc/src/bin/lutra-proc-helper.rs b/crates/proc/src/bin/lutra-proc-helper.rs index 389b531..b910b2c 100644 --- a/crates/proc/src/bin/lutra-proc-helper.rs +++ b/crates/proc/src/bin/lutra-proc-helper.rs @@ -16,6 +16,12 @@ //! - `tree-on-input`: reads one line from standard input first, then acts //! as `tree-plain`. A test adopts the helper in between, so the //! grandchild starts only after the helper is in its job. +//! - `detached-plain`: starts the sleeping grandchild the way the `lutra` +//! CLI did before C9 F1 (a [`std::process::Command`] with null stdio, +//! detached in a new process group on Windows), `detached-proc`: through +//! [`lutra_proc::spawn_detached`]. Then it prints the grandchild's id and +//! exits. A test reading this output sees end of file at once unless the +//! grandchild inherited the pipe. //! //! Any other argument exits with code 2. @@ -32,6 +38,7 @@ 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"), + "detached-plain" | "detached-proc" => detached(role == "detached-proc"), "tree-on-input" => { let mut line = String::new(); if std::io::stdin().lock().read_line(&mut line).is_err() { @@ -72,6 +79,40 @@ fn tree(guarded: bool) -> ExitCode { ExitCode::SUCCESS } +/// Starts the grandchild detached (through `lutra_proc` when `proc`), +/// prints its id and returns. +fn detached(proc: bool) -> ExitCode { + let command = grandchild(); + let id = if proc { + let args: Vec<&std::ffi::OsStr> = command.get_args().collect(); + let program = std::path::Path::new(command.get_program()); + match lutra_proc::spawn_detached(program, &args) { + Ok(child) => child.id(), + Err(_) => return ExitCode::from(4), + } + } else { + let mut command = command; + command + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()); + #[cfg(windows)] + { + use std::os::windows::process::CommandExt; + command.creation_flags(0x0000_0008 | 0x0000_0200); + } + match command.spawn() { + Ok(child) => child.id(), + Err(_) => return ExitCode::from(4), + } + }; + let mut out = std::io::stdout(); + if writeln!(out, "{id}").and_then(|()| out.flush()).is_err() { + return ExitCode::from(5); + } + ExitCode::SUCCESS +} + /// A system program that sleeps for [`SLEEP`] without output. fn grandchild() -> Command { let seconds = SLEEP.as_secs(); diff --git a/crates/proc/src/lib.rs b/crates/proc/src/lib.rs index 8f441b5..7fbfeed 100644 --- a/crates/proc/src/lib.rs +++ b/crates/proc/src/lib.rs @@ -37,9 +37,18 @@ //! integrated terminal's ConPTY shell, into a kill-on-close job and returns //! a [`Guard`] that holds it. [`enable_ctrl_c`] (Windows) undoes an //! inherited "ignore Ctrl+C" flag before that shell starts. +//! +//! [`spawn_detached`] is the opposite of [`spawn`]: it starts a program that +//! outlives the caller and holds none of its handles, as the `lutra` CLI +//! starts the desktop app. On Windows the standard library makes every +//! inheritable handle of the caller (such as the pipe a script reads the +//! CLI's output from) inheritable by the child, so the script would wait +//! until the app exits; `spawn_detached` passes no handles at all. +use std::ffi::OsStr; use std::io; use std::ops::{Deref, DerefMut}; +use std::path::Path; use std::process::{Command, ExitStatus}; #[cfg(unix)] @@ -147,6 +156,78 @@ fn spawn_with( } } +/// A program started by [`spawn_detached`]. Dropping it leaves the program +/// running. +pub struct Detached { + /// The process (Windows: its handle). + #[cfg(windows)] + inner: windows::DetachedProcess, + /// The process. + #[cfg(not(windows))] + inner: std::process::Child, +} + +/// Starts `program` with `args` so that it outlives this process and holds +/// none of its handles: standard input, output and error are closed (null), +/// and it leaves this terminal's job control. +/// +/// - **Windows:** a detached process in a new process group +/// (`DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`, so it has no console +/// and a Ctrl+C in the caller's console does not reach it), created with +/// `bInheritHandles = FALSE`, so no handle of the caller is inherited. +/// - **Unix:** a new process group, so a Ctrl-C or hangup aimed at the +/// terminal's foreground group does not reach it; the standard library +/// opens its own descriptors close-on-exec. +/// +/// The environment and working directory are this process's. +/// +/// # Errors +/// The OS error of starting the program. +pub fn spawn_detached(program: &Path, args: &[&OsStr]) -> io::Result { + #[cfg(windows)] + { + windows::spawn_detached(program, args).map(|inner| Detached { inner }) + } + #[cfg(not(windows))] + { + let mut command = Command::new(program); + command + .args(args) + .stdin(std::process::Stdio::null()) + .stdout(std::process::Stdio::null()) + .stderr(std::process::Stdio::null()); + #[cfg(unix)] + { + use std::os::unix::process::CommandExt; + command.process_group(0); + } + command.spawn().map(|inner| Detached { inner }) + } +} + +impl Detached { + /// The process id. + pub fn id(&self) -> u32 { + self.inner.id() + } + + /// The exit status if the program has exited, without waiting. + /// + /// # Errors + /// The OS error of asking for it. + pub fn try_wait(&mut self) -> io::Result> { + self.inner.try_wait() + } +} + +impl std::fmt::Debug for Detached { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Detached") + .field("id", &self.id()) + .finish_non_exhaustive() + } +} + /// A kill-on-close job for a process Lutra did not start through [`spawn`] /// (Windows only, see [`adopt`]). Dropping it kills the process and /// everything it started. diff --git a/crates/proc/src/windows.rs b/crates/proc/src/windows.rs index c2aa990..8489d57 100644 --- a/crates/proc/src/windows.rs +++ b/crates/proc/src/windows.rs @@ -19,21 +19,29 @@ //! (`SetConsoleCtrlHandler(NULL, FALSE)`), so the terminal's shells pass //! Ctrl+C on to the programs they run. //! +//! [`spawn_detached`] starts a program through `CreateProcessW` directly, +//! with `bInheritHandles = FALSE`, which the standard library cannot do. +//! //! This is the one module in Lutra that allows `unsafe`: the job object, -//! Tool Help, thread and console APIs are only reachable through FFI. Every call gets +//! Tool Help, thread, process and console APIs are only reachable through FFI. Every call gets //! valid arguments by construction: handles come from `CreateJobObjectW`, -//! `CreateToolhelp32Snapshot` or `OpenThread` (owned by an [`OwnedHandle`] -//! right away) or from a live [`std::process::Child`], and the limit and -//! thread entry structures are plain C structs that are valid when zeroed. +//! `CreateToolhelp32Snapshot`, `OpenThread` or `CreateProcessW` (owned by an [`OwnedHandle`] +//! right away) or from a live [`std::process::Child`], strings passed in are +//! NUL-terminated UTF-16 buffers that outlive the call, and the limit, +//! thread entry, startup and process information structures are plain C +//! structs that are valid when zeroed. #![allow(unsafe_code)] +use std::ffi::OsStr; use std::io; +use std::os::windows::ffi::OsStrExt; use std::os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle, RawHandle}; -use std::os::windows::process::CommandExt; -use std::process::Command; +use std::os::windows::process::{CommandExt, ExitStatusExt}; +use std::path::Path; +use std::process::{Command, ExitStatus}; -use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE; +use windows_sys::Win32::Foundation::{INVALID_HANDLE_VALUE, WAIT_OBJECT_0, WAIT_TIMEOUT}; use windows_sys::Win32::System::Console::SetConsoleCtrlHandler; use windows_sys::Win32::System::Diagnostics::ToolHelp::{ CreateToolhelp32Snapshot, TH32CS_SNAPTHREAD, THREADENTRY32, Thread32First, Thread32Next, @@ -44,7 +52,9 @@ use windows_sys::Win32::System::JobObjects::{ SetInformationJobObject, TerminateJobObject, }; use windows_sys::Win32::System::Threading::{ - CREATE_NO_WINDOW, CREATE_SUSPENDED, OpenThread, ResumeThread, THREAD_SUSPEND_RESUME, + CREATE_NEW_PROCESS_GROUP, CREATE_NO_WINDOW, CREATE_SUSPENDED, CreateProcessW, DETACHED_PROCESS, + GetExitCodeProcess, OpenThread, PROCESS_INFORMATION, ResumeThread, STARTF_USESTDHANDLES, + STARTUPINFOW, THREAD_SUSPEND_RESUME, WaitForSingleObject, }; /// The exit code a process killed with its job reports. @@ -201,3 +211,148 @@ fn resume_thread(tid: u32) -> io::Result<()> { } Ok(()) } + +/// A program started by [`spawn_detached`]: its process handle and id. +pub(crate) struct DetachedProcess { + /// The process handle from `CreateProcessW`. + process: OwnedHandle, + /// The process id. + id: u32, +} + +/// Starts `program` with `args` as a detached process in a new process +/// group (`DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`) that inherits no +/// handle at all (`bInheritHandles = FALSE`) and has no standard handles +/// (`STARTF_USESTDHANDLES` with null handles). The standard library always +/// passes `TRUE`, so every inheritable handle of the caller, such as the +/// pipe a script reads its output from, would stay open in the program. +/// `program` is found the way `CreateProcessW` finds the first word of a +/// command line (`.exe` added, `PATH` searched), as the standard library +/// does for a bare name. +/// +/// # Errors +/// The OS error of `CreateProcessW`. +pub(crate) fn spawn_detached(program: &Path, args: &[&OsStr]) -> io::Result { + let mut line = quote(program.as_os_str()); + for arg in args { + line.push(SPACE); + line.extend(quote(arg)); + } + line.push(0); + let mut startup: STARTUPINFOW = unsafe { std::mem::zeroed() }; + startup.cb = u32::try_from(std::mem::size_of::()).unwrap_or(u32::MAX); + startup.dwFlags = STARTF_USESTDHANDLES; + let mut info: PROCESS_INFORMATION = unsafe { std::mem::zeroed() }; + let ok = unsafe { + CreateProcessW( + std::ptr::null(), + line.as_mut_ptr(), + std::ptr::null(), + std::ptr::null(), + 0, + DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP, + std::ptr::null(), + std::ptr::null(), + &raw const startup, + &raw mut info, + ) + }; + if ok == 0 { + return Err(io::Error::last_os_error()); + } + let process = unsafe { OwnedHandle::from_raw_handle(info.hProcess) }; + drop(unsafe { OwnedHandle::from_raw_handle(info.hThread) }); + Ok(DetachedProcess { + process, + id: info.dwProcessId, + }) +} + +impl DetachedProcess { + /// The process id. + pub(crate) fn id(&self) -> u32 { + self.id + } + + /// The exit status if the process has exited, without waiting. + /// + /// # Errors + /// The OS error of `WaitForSingleObject` or `GetExitCodeProcess`. + pub(crate) fn try_wait(&self) -> io::Result> { + let handle = self.process.as_raw_handle(); + match unsafe { WaitForSingleObject(handle, 0) } { + WAIT_TIMEOUT => Ok(None), + WAIT_OBJECT_0 => { + let mut code = 0u32; + if unsafe { GetExitCodeProcess(handle, &raw mut code) } == 0 { + return Err(io::Error::last_os_error()); + } + Ok(Some(ExitStatus::from_raw(code))) + } + _ => Err(io::Error::last_os_error()), + } + } +} + +/// A backslash in UTF-16. +const BACKSLASH: u16 = 0x5c; + +/// A double quote in UTF-16. +const QUOTE: u16 = 0x22; + +/// A space in UTF-16. +const SPACE: u16 = 0x20; + +/// A tab in UTF-16. +const TAB: u16 = 0x09; + +/// One argument quoted for a Windows command line as the C runtime and +/// `CommandLineToArgvW` split it: wrapped in quotes when empty or when it +/// has spaces, tabs or quotes; quotes and the backslashes before them (or +/// before the closing quote) are escaped. +fn quote(arg: &OsStr) -> Vec { + let units: Vec = arg.encode_wide().collect(); + let needs = units.is_empty() || units.iter().any(|&u| u == SPACE || u == TAB || u == QUOTE); + if !needs { + return units; + } + let mut out = vec![QUOTE]; + let mut backslashes = 0usize; + for &unit in &units { + if unit == BACKSLASH { + backslashes += 1; + continue; + } + let escaped = if unit == QUOTE { + backslashes * 2 + 1 + } else { + backslashes + }; + out.extend(std::iter::repeat_n(BACKSLASH, escaped)); + out.push(unit); + backslashes = 0; + } + out.extend(std::iter::repeat_n(BACKSLASH, backslashes * 2)); + out.push(QUOTE); + out +} + +#[cfg(test)] +mod tests { + use super::*; + + fn quoted(arg: &str) -> String { + String::from_utf16("e(OsStr::new(arg))).unwrap() + } + + #[test] + fn arguments_are_quoted_as_the_c_runtime_splits_them() { + assert_eq!(quoted("-n"), "-n"); + assert_eq!(quoted(r"C:\a\b"), r"C:\a\b"); + assert_eq!(quoted(""), r#""""#); + assert_eq!(quoted(r"C:\Program Files\x"), r#""C:\Program Files\x""#); + assert_eq!(quoted(r#"say "hi""#), r#""say \"hi\"""#); + assert_eq!(quoted(r"dir with space\"), r#""dir with space\\""#); + assert_eq!(quoted(r#"a\"b"#), r#""a\\\"b""#); + } +} diff --git a/crates/proc/tests/process_tree.rs b/crates/proc/tests/process_tree.rs index c9e5663..ed20814 100644 --- a/crates/proc/tests/process_tree.rs +++ b/crates/proc/tests/process_tree.rs @@ -135,3 +135,48 @@ fn dropping_an_adopt_guard_takes_the_tree_started_after_it() { assert_gone(reader); parent.wait().unwrap(); } + +/// Starts the helper in a `detached-*` role, reads the grandchild's id and +/// returns it with whether the output then reached end of file within +/// `within`. Kills the grandchild before returning. +fn detached_output_closes(role: &str, within: Duration) -> bool { + let mut parent = helper(role).spawn().unwrap(); + let mut reader = BufReader::new(parent.stdout.take().unwrap()); + let mut line = String::new(); + reader.read_line(&mut line).unwrap(); + let id: u32 = line.trim().parse().unwrap(); + assert!(parent.wait().unwrap().success()); + let (tx, rx) = mpsc::channel(); + thread::spawn(move || { + let mut rest = Vec::new(); + let _ = reader.read_to_end(&mut rest); + let _ = tx.send(()); + }); + let closed = rx.recv_timeout(within).is_ok(); + let kill = if cfg!(windows) { + Command::new("taskkill") + .args(["/F", "/PID", &id.to_string()]) + .output() + } else { + Command::new("kill").args(["-9", &id.to_string()]).output() + }; + kill.unwrap(); + closed +} + +#[test] +fn a_detached_start_holds_none_of_the_callers_handles() { + assert!( + detached_output_closes("detached-proc", GONE_WITHIN), + "the detached grandchild holds its parent's output pipe" + ); +} + +#[cfg(windows)] +#[test] +fn a_plain_detached_start_inherits_the_callers_pipe_on_windows() { + assert!( + !detached_output_closes("detached-plain", Duration::from_secs(3)), + "the standard library no longer passes inheritable handles on; spawn_detached may be simpler now" + ); +}