Skip to main content

astrs_node_api/
orphan.rs

1//! The orphan guard (blueprint §4.2).
2//!
3//! > **`astrs run`** — the single-process mode: the CLI embeds an in-process
4//! > daemon […] under one supervisor with the orphan guard (parent-pid +
5//! > process-group kill).
6//!
7//! A node spawned by a supervisor is told that supervisor's process id in
8//! `ASTRS_RUN_PARENT_PID`. If the supervisor dies without stopping its
9//! children — `kill -9` on the CLI, an OOM kill, a laptop lid — those children
10//! keep running, keep holding shared-memory segments, and keep their ports
11//! bound. The guard is what stops that: a low-frequency watch on the parent
12//! that turns its disappearance into an ordinary [`Event::Stop`], so the node
13//! winds down through exactly the same path a requested stop takes.
14//!
15//! # Why polling
16//!
17//! `pidfd_open` (Linux 5.3+) and `kqueue`'s `EVFILT_PROC` (BSD, macOS) both
18//! give an *event* rather than a poll, and `astrs-shm`'s
19//! [`ProcessWatch`](astrs_shm::ProcessWatch) already wraps them for the
20//! segment plane. The guard deliberately does not use them: it watches a
21//! process that is not a child of this one, where `pidfd` needs a capability
22//! this process may not have and `kqueue` needs a descriptor it cannot obtain.
23//! A `kill(pid, 0)` every two seconds costs one syscall per node per two
24//! seconds and works everywhere, which for a liveness check with a
25//! human-scale deadline is the right trade.
26//!
27//! # Pid reuse
28//!
29//! A pid can be reused, so "the pid still exists" is not quite "my parent is
30//! still alive". The window is small (the supervisor would have to die *and*
31//! the pid be recycled between two polls) and the consequence is benign (the
32//! node keeps running and is stopped by the ordinary path instead). The guard
33//! documents this rather than pretending otherwise.
34
35use std::sync::Arc;
36use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
37use std::time::Duration;
38
39use astrs_wire::StopCause;
40use tokio::task::JoinHandle;
41
42use crate::events::{Event, EventSource};
43use crate::runtime::NodeRuntime;
44
45/// How often the guard checks its parent, by default.
46///
47/// Two seconds: fast enough that an orphan does not outlive its supervisor by
48/// anything a human notices, slow enough to be invisible in a profile.
49pub const DEFAULT_POLL_INTERVAL: Duration = Duration::from_secs(2);
50
51/// Whether a process with this id currently exists.
52///
53/// Implemented with the null signal (`kill(pid, 0)`), which performs the
54/// permission and existence checks without delivering anything. A process that
55/// exists but belongs to another user answers `true`: the check is *liveness*,
56/// not ownership.
57///
58/// On a platform without the null-signal check this returns `true`, because
59/// "cannot tell" must not be reported as "gone" — a guard that stops a healthy
60/// node is worse than one that never fires.
61///
62/// # Examples
63///
64/// ```
65/// use astrs_node_api::orphan::process_exists;
66///
67/// assert!(process_exists(std::process::id()), "this process exists");
68/// ```
69#[must_use]
70pub fn process_exists(pid: u32) -> bool {
71    #[cfg(unix)]
72    {
73        let Ok(raw) = i32::try_from(pid) else {
74            return false;
75        };
76        let Some(pid) = rustix::process::Pid::from_raw(raw) else {
77            return false;
78        };
79        match rustix::process::test_kill_process(pid) {
80            Ok(()) => true,
81            // `EPERM` means "it exists, and you may not signal it" — which is
82            // still alive, and is what a node sees when its supervisor runs as
83            // another user.
84            Err(error) => error == rustix::io::Errno::PERM,
85        }
86    }
87    #[cfg(not(unix))]
88    {
89        let _ = pid;
90        true
91    }
92}
93
94/// A running watch on a supervising process.
95#[derive(Debug)]
96pub struct OrphanGuard {
97    /// The pid being watched.
98    parent: u32,
99    /// Set to stop the watch.
100    stop: Arc<AtomicBool>,
101    /// Set once the parent was observed to be gone.
102    fired: Arc<AtomicBool>,
103    /// How many polls the watch has performed.
104    polls: Arc<AtomicU64>,
105    /// The watch task.
106    task: JoinHandle<()>,
107}
108
109impl OrphanGuard {
110    /// Starts watching `parent`, stopping `source` when it disappears.
111    #[must_use]
112    pub fn watch(
113        parent: u32,
114        runtime: &NodeRuntime,
115        source: Arc<EventSource>,
116        interval: Duration,
117    ) -> Self {
118        let stop = Arc::new(AtomicBool::new(false));
119        let fired = Arc::new(AtomicBool::new(false));
120        let polls = Arc::new(AtomicU64::new(0));
121        let task = {
122            let stop = Arc::clone(&stop);
123            let fired = Arc::clone(&fired);
124            let polls = Arc::clone(&polls);
125            runtime.spawn(async move {
126                let interval = interval.max(Duration::from_millis(10));
127                loop {
128                    tokio::time::sleep(interval).await;
129                    if stop.load(Ordering::Acquire) || source.is_closed() {
130                        return;
131                    }
132                    polls.fetch_add(1, Ordering::Relaxed);
133                    if process_exists(parent) {
134                        continue;
135                    }
136                    fired.store(true, Ordering::Release);
137                    source.push_control(Event::Error(format!(
138                        "the supervising process {parent} exited; this node is orphaned"
139                    )));
140                    source.push_control(Event::Stop(StopCause::DaemonShutdown));
141                    return;
142                }
143            })
144        };
145        Self {
146            parent,
147            stop,
148            fired,
149            polls,
150            task,
151        }
152    }
153
154    /// Starts a guard only if `parent` is set (§4.2: the guard is optional).
155    #[must_use]
156    pub fn maybe_watch(
157        parent: Option<u32>,
158        runtime: &NodeRuntime,
159        source: Arc<EventSource>,
160        interval: Duration,
161    ) -> Option<Self> {
162        parent.map(|parent| Self::watch(parent, runtime, source, interval))
163    }
164
165    /// The pid being watched.
166    #[must_use]
167    pub const fn parent(&self) -> u32 {
168        self.parent
169    }
170
171    /// Whether the guard has observed the parent's disappearance.
172    #[must_use]
173    pub fn has_fired(&self) -> bool {
174        self.fired.load(Ordering::Acquire)
175    }
176
177    /// How many polls the watch has performed.
178    #[must_use]
179    pub fn poll_count(&self) -> u64 {
180        self.polls.load(Ordering::Relaxed)
181    }
182
183    /// Stops the watch.
184    ///
185    /// Idempotent, and implied by [`Drop`].
186    pub fn stop(&self) {
187        self.stop.store(true, Ordering::Release);
188    }
189}
190
191impl Drop for OrphanGuard {
192    fn drop(&mut self) {
193        self.stop();
194        self.task.abort();
195    }
196}
197
198#[cfg(test)]
199mod tests {
200    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
201
202    use super::*;
203
204    #[test]
205    fn this_process_exists_and_an_impossible_pid_does_not() {
206        assert!(process_exists(std::process::id()));
207        // Pid 0 addresses the caller's process *group* on Unix, and is never
208        // a process id; the guard must not read it as a live parent.
209        assert!(!process_exists(u32::MAX));
210    }
211
212    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
213    async fn a_live_parent_keeps_the_node_running() {
214        let source = Arc::new(EventSource::new());
215        let runtime = NodeRuntime::acquire().unwrap();
216        let guard = OrphanGuard::watch(
217            std::process::id(),
218            &runtime,
219            Arc::clone(&source),
220            Duration::from_millis(10),
221        );
222        tokio::time::sleep(Duration::from_millis(80)).await;
223        assert!(!guard.has_fired());
224        assert!(guard.poll_count() >= 1, "the watch is actually polling");
225        assert!(source.try_next().is_none());
226        assert_eq!(guard.parent(), std::process::id());
227    }
228
229    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
230    async fn a_dead_parent_stops_the_node() {
231        let source = Arc::new(EventSource::new());
232        let runtime = NodeRuntime::acquire().unwrap();
233        let _guard = OrphanGuard::watch(
234            u32::MAX,
235            &runtime,
236            Arc::clone(&source),
237            Duration::from_millis(10),
238        );
239        for _ in 0..200 {
240            if let Some(event) = source.try_next() {
241                let Event::Error(message) = event else {
242                    panic!("expected the orphan report first");
243                };
244                assert!(message.contains("orphaned"), "{message}");
245                let stop = source.try_next().unwrap();
246                assert!(stop.is_stop());
247                return;
248            }
249            tokio::time::sleep(Duration::from_millis(10)).await;
250        }
251        panic!("the guard never fired");
252    }
253
254    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
255    async fn stopping_the_guard_ends_the_watch() {
256        let source = Arc::new(EventSource::new());
257        let runtime = NodeRuntime::acquire().unwrap();
258        let guard = OrphanGuard::watch(
259            u32::MAX,
260            &runtime,
261            Arc::clone(&source),
262            Duration::from_millis(500),
263        );
264        guard.stop();
265        drop(guard);
266        tokio::time::sleep(Duration::from_millis(30)).await;
267        assert!(source.try_next().is_none(), "a stopped guard says nothing");
268    }
269
270    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
271    async fn no_parent_means_no_guard() {
272        let source = Arc::new(EventSource::new());
273        let runtime = NodeRuntime::acquire().unwrap();
274        assert!(OrphanGuard::maybe_watch(None, &runtime, source, DEFAULT_POLL_INTERVAL).is_none());
275    }
276
277    #[test]
278    fn the_default_interval_is_documented() {
279        assert_eq!(DEFAULT_POLL_INTERVAL, Duration::from_secs(2));
280    }
281}