Skip to main content

rigspark_runtime/
process_control.rs

1use crate::identity::{Listener, NativeProcessProbe, ProcessIdentity, ProcessProbe};
2use std::{
3    collections::BTreeMap,
4    future::Future,
5    path::{Path, PathBuf},
6    process::Stdio,
7    time::Duration,
8};
9use tokio_util::sync::CancellationToken;
10
11pub struct SpawnSpec {
12    pub binary: PathBuf,
13    pub args: Vec<String>,
14    pub env: BTreeMap<String, String>,
15}
16#[async_trait::async_trait]
17pub trait ChildProcess: Send {
18    fn pid(&self) -> u32;
19    fn exited(&mut self) -> Result<bool, String>;
20    async fn terminate(&mut self) -> Result<(), String>;
21    fn detach(&mut self);
22}
23#[async_trait::async_trait]
24pub trait ProcessControl: Send + Sync {
25    async fn occupied(&self, endpoint: &str) -> Result<bool, String>;
26    async fn spawn(&self, spec: &SpawnSpec) -> Result<Box<dyn ChildProcess>, String>;
27    async fn signal(&self, process: &ProcessIdentity, force: bool) -> Result<(), String>;
28    async fn alive(&self, pid: u32) -> Result<bool, String>;
29}
30struct NativeChild {
31    child: tokio::process::Child,
32    detached: bool,
33    pid: u32,
34}
35#[async_trait::async_trait]
36impl ChildProcess for NativeChild {
37    fn pid(&self) -> u32 {
38        self.pid
39    }
40    fn exited(&mut self) -> Result<bool, String> {
41        self.child
42            .try_wait()
43            .map(|value| value.is_some())
44            .map_err(|_| "cannot observe child exit".into())
45    }
46    async fn terminate(&mut self) -> Result<(), String> {
47        if self.exited()? {
48            return Ok(());
49        }
50        self.child
51            .start_kill()
52            .map_err(|_| "child termination failed")?;
53        tokio::time::timeout(Duration::from_secs(5), self.child.wait())
54            .await
55            .map_err(|_| "child termination timed out")?
56            .map_err(|_| "child wait failed")?;
57        Ok(())
58    }
59    fn detach(&mut self) {
60        self.detached = true;
61    }
62}
63impl Drop for NativeChild {
64    fn drop(&mut self) {
65        if !self.detached {
66            let _ = self.child.start_kill();
67        }
68    }
69}
70pub struct NativeProcessControl;
71#[async_trait::async_trait]
72impl ProcessControl for NativeProcessControl {
73    async fn occupied(&self, endpoint: &str) -> Result<bool, String> {
74        let url = crate::state::loopback(endpoint).map_err(|error| error.to_string())?;
75        let host = url
76            .host_str()
77            .ok_or("missing host")?
78            .trim_matches(['[', ']']);
79        let port = url.port_or_known_default().ok_or("missing port")?;
80        let addresses = if host == "localhost" {
81            vec![format!("127.0.0.1:{port}"), format!("[::1]:{port}")]
82        } else {
83            vec![format!(
84                "{}:{port}",
85                if host.contains(':') {
86                    format!("[{host}]")
87                } else {
88                    host.into()
89                }
90            )]
91        };
92        for address in addresses {
93            match tokio::time::timeout(
94                Duration::from_secs(2),
95                tokio::net::TcpStream::connect(address),
96            )
97            .await
98            {
99                Ok(Ok(_)) => return Ok(true),
100                Ok(Err(error)) if error.kind() == std::io::ErrorKind::ConnectionRefused => (),
101                _ => return Err("cannot establish port availability".into()),
102            }
103        }
104        Ok(false)
105    }
106    async fn spawn(&self, spec: &SpawnSpec) -> Result<Box<dyn ChildProcess>, String> {
107        if !spec.binary.is_absolute() || spec.args.iter().any(|arg| arg.contains('\0')) {
108            return Err("invalid spawn specification".into());
109        }
110        let mut command = tokio::process::Command::new(&spec.binary);
111        command
112            .args(&spec.args)
113            .env_clear()
114            .envs(&spec.env)
115            .stdin(Stdio::null())
116            .stdout(Stdio::null())
117            .stderr(Stdio::null());
118        let mut child = command.spawn().map_err(|_| "runtime spawn failed")?;
119        let Some(pid) = child.id().filter(|pid| *pid > 0) else {
120            let _ = child.kill().await;
121            return Err("runtime reported invalid PID".into());
122        };
123        Ok(Box::new(NativeChild {
124            child,
125            detached: false,
126            pid,
127        }))
128    }
129    async fn signal(&self, expected: &ProcessIdentity, force: bool) -> Result<(), String> {
130        let observed = NativeProcessProbe
131            .process(expected.pid)
132            .await
133            .map_err(|_| "cannot verify process before signal")?;
134        if !same_process(&observed, expected) {
135            return Err("process changed before signal".into());
136        }
137        #[cfg(unix)]
138        {
139            let pid = i32::try_from(expected.pid)
140                .ok()
141                .and_then(rustix::process::Pid::from_raw)
142                .ok_or("invalid process PID")?;
143            rustix::process::kill_process(
144                pid,
145                if force {
146                    rustix::process::Signal::KILL
147                } else {
148                    rustix::process::Signal::TERM
149                },
150            )
151            .map_err(|_| "signal failed".to_owned())
152        }
153        #[cfg(windows)]
154        {
155            let _ = force;
156            let system = sysinfo::System::new_all();
157            let process = system
158                .process(sysinfo::Pid::from_u32(expected.pid))
159                .ok_or("process unavailable")?;
160            if process.kill() {
161                Ok(())
162            } else {
163                Err("process termination failed".into())
164            }
165        }
166        #[cfg(not(any(unix, windows)))]
167        {
168            let _ = force;
169            Err("unsupported platform".into())
170        }
171    }
172    async fn alive(&self, pid: u32) -> Result<bool, String> {
173        #[cfg(unix)]
174        {
175            let pid = i32::try_from(pid)
176                .ok()
177                .and_then(rustix::process::Pid::from_raw)
178                .ok_or("invalid process PID")?;
179            match rustix::process::test_kill_process(pid) {
180                Ok(()) => Ok(true),
181                Err(rustix::io::Errno::SRCH) => Ok(false),
182                Err(rustix::io::Errno::PERM) => Ok(true),
183                Err(_) => Err("process existence unavailable".into()),
184            }
185        }
186        #[cfg(not(unix))]
187        {
188            let system = sysinfo::System::new_all();
189            Ok(system.process(sysinfo::Pid::from_u32(pid)).is_some())
190        }
191    }
192}
193pub fn same_process(actual: &ProcessIdentity, expected: &ProcessIdentity) -> bool {
194    actual.pid == expected.pid
195        && actual.executable == expected.executable
196        && actual.started == expected.started
197}
198pub fn resolve_binary(binary: &str) -> Result<PathBuf, String> {
199    let path = Path::new(binary);
200    if path.is_absolute() {
201        return path
202            .canonicalize()
203            .map_err(|_| "runtime executable unavailable".into());
204    }
205
206    for directory in std::env::split_paths(&std::env::var_os("PATH").unwrap_or_default()) {
207        if directory.as_os_str().is_empty() {
208            continue;
209        }
210        for name in [binary.to_owned(), format!("{binary}.exe")] {
211            let candidate = directory.join(name);
212            if candidate.is_file() {
213                return candidate
214                    .canonicalize()
215                    .map_err(|_| "runtime executable cannot be resolved".into());
216            }
217        }
218    }
219    Err("runtime executable not found on PATH".into())
220}
221pub fn bitnet_server_path(value: Option<&std::ffi::OsStr>) -> Result<PathBuf, String> {
222    let invalid = || {
223        "Set RIGSPARK_BITNET_SERVER to the absolute path of a compiled BitNet llama-server executable (not stock llama.cpp)".to_owned()
224    };
225    let path = Path::new(value.ok_or_else(invalid)?);
226    if !path.is_absolute()
227        || path
228            .to_str()
229            .is_none_or(|text| text.chars().any(char::is_control))
230        || !path.is_file()
231    {
232        return Err(invalid());
233    }
234    let path = path.canonicalize().map_err(|_| invalid())?;
235    #[cfg(unix)]
236    {
237        use std::os::unix::fs::PermissionsExt;
238        if path.metadata().map_err(|_| invalid())?.permissions().mode() & 0o111 == 0 {
239            return Err(invalid());
240        }
241    }
242    Ok(path)
243}
244
245pub fn resolve_bitnet_server() -> Result<PathBuf, String> {
246    bitnet_server_path(std::env::var_os("RIGSPARK_BITNET_SERVER").as_deref())
247}
248
249pub fn minimal_env() -> BTreeMap<String, String> {
250    [
251        "PATH",
252        "HOME",
253        "USER",
254        "LOGNAME",
255        "LANG",
256        "LC_ALL",
257        "LC_CTYPE",
258        "TMPDIR",
259        "TMP",
260        "TEMP",
261        "SYSTEMROOT",
262        "WINDIR",
263        "COMSPEC",
264        "PATHEXT",
265    ]
266    .into_iter()
267    .filter_map(|key| std::env::var(key).ok().map(|value| (key.into(), value)))
268    .collect()
269}
270pub async fn listener(
271    probe: &dyn ProcessProbe,
272    endpoint: &str,
273    cancel: &CancellationToken,
274) -> Result<Listener, String> {
275    let url = crate::state::loopback(endpoint).map_err(|error| error.to_string())?;
276    let host = url.host_str().ok_or("missing host")?;
277    let port = url.port_or_known_default().ok_or("missing port")?;
278    tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(Duration::from_secs(5),probe.listener(port,host))=>{
279        let observed=result.map_err(|_|"listener probe timed out")?.map_err(|_|"listener identity unavailable")?;
280        crate::identity::choose_listener(std::slice::from_ref(&observed),port,host).map_err(|_|"listener address mismatch".into())
281    }}
282}
283pub async fn wait_owned<F, Fut>(
284    child: Box<dyn ChildProcess>,
285    endpoint: &str,
286    executable: &str,
287    probe: &dyn ProcessProbe,
288    cancel: &CancellationToken,
289    ready: F,
290) -> Result<Listener, String>
291where
292    F: FnOnce() -> Fut,
293    Fut: Future<Output = Result<(), String>>,
294{
295    wait_owned_with_timeout(
296        child,
297        endpoint,
298        executable,
299        probe,
300        cancel,
301        Duration::from_secs(30),
302        ready,
303    )
304    .await
305}
306pub async fn wait_owned_with_timeout<F, Fut>(
307    mut child: Box<dyn ChildProcess>,
308    endpoint: &str,
309    executable: &str,
310    probe: &dyn ProcessProbe,
311    cancel: &CancellationToken,
312    timeout: Duration,
313    ready: F,
314) -> Result<Listener, String>
315where
316    F: FnOnce() -> Fut,
317    Fut: Future<Output = Result<(), String>>,
318{
319    if timeout.is_zero() || timeout > Duration::from_secs(300) {
320        child.terminate().await?;
321        return Err("invalid readiness deadline".into());
322    }
323    let operation = async {
324        if child.pid() == 0 {
325            return Err("invalid child PID".into());
326        }
327        let readiness = ready();
328        tokio::pin!(readiness);
329        loop {
330            if child.exited()? {
331                return Err("runtime exited before readiness".into());
332            }
333            tokio::select! {result=&mut readiness=>{result?;break;},_=tokio::time::sleep(Duration::from_millis(50))=>()}
334        }
335        let observed = listener(probe, endpoint, cancel).await?;
336        if observed.identity.pid != child.pid() || observed.identity.executable != executable {
337            return Err("readiness belongs to another process".into());
338        }
339        Ok(observed)
340    };
341    let result = tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(timeout,operation)=>result.map_err(|_|"runtime readiness timed out".to_owned()).and_then(|result|result)};
342    match result {
343        Ok(observed) => {
344            child.detach();
345            Ok(observed)
346        }
347        Err(error) => {
348            child
349                .terminate()
350                .await
351                .map_err(|cleanup| format!("{error}; {cleanup}"))?;
352            Err(error)
353        }
354    }
355}
356pub async fn stop_owned(
357    endpoint: &str,
358    expected: &ProcessIdentity,
359    probe: &dyn ProcessProbe,
360    control: &dyn ProcessControl,
361    cancel: &CancellationToken,
362) -> Result<(), String> {
363    let observed = listener(probe, endpoint, cancel).await?;
364    if !same_process(&observed.identity, expected) {
365        return Err("listener changed; refusing to stop".into());
366    }
367    for force in [false, true] {
368        let current = tokio::select! {biased;_=cancel.cancelled()=>return Err("cancelled".into()),result=tokio::time::timeout(Duration::from_secs(5),probe.process(expected.pid))=>result.map_err(|_|"process probe timed out")?.map_err(|_|"process identity unavailable")?};
369        if !same_process(&current, expected) {
370            if force {
371                return Ok(());
372            }
373            return Err("process changed; refusing to stop".into());
374        }
375        control.signal(expected, force).await?;
376        for _ in 0..10 {
377            if !control.alive(expected.pid).await? {
378                return Ok(());
379            }
380            let current = match probe.process(expected.pid).await {
381                Ok(current) => current,
382                Err(_) => {
383                    if !control.alive(expected.pid).await? {
384                        return Ok(());
385                    }
386                    return Err("process identity unavailable after signal".into());
387                }
388            };
389            if !same_process(&current, expected) {
390                return Ok(());
391            }
392            tokio::select! {biased;_=cancel.cancelled()=>return Err("cancelled".into()),_=tokio::time::sleep(Duration::from_millis(50))=>()}
393        }
394    }
395    Err("runtime remains alive after termination".into())
396}