Skip to main content

rightkit_sync/helper/
process.rs

1//! Child-process line-JSON client. One long-lived helper, respawned after any
2//! failure (timeout, crash, protocol error); the helper keeps no state that
3//! matters across restarts because the cursor lives in the ledger.
4
5use std::collections::VecDeque;
6use std::io::{BufRead, BufReader, Read, Write};
7use std::path::PathBuf;
8use std::process::{Child, ChildStdin, Command, Stdio};
9use std::sync::atomic::{AtomicU64, Ordering};
10use std::sync::mpsc::{self, Receiver, RecvTimeoutError};
11use std::sync::{Arc, Mutex};
12use std::time::Duration;
13
14use serde_json::{Map, Value};
15
16use super::wire::{Response, PROTOCOL_VERSION};
17use crate::error::{SyncError, SyncResult};
18
19/// Largest accepted response line. A line over the cap kills the helper.
20const MAX_LINE_BYTES: usize = 128 * 1024 * 1024;
21
22#[derive(Debug, Clone)]
23pub struct HelperConfig {
24    pub program: PathBuf,
25    pub args: Vec<String>,
26    pub envs: Vec<(String, String)>,
27    /// Per-request deadline (donor: 45 s; CloudKit batches can be slow).
28    pub request_timeout: Duration,
29}
30
31impl HelperConfig {
32    pub fn new(program: impl Into<PathBuf>) -> Self {
33        Self {
34            program: program.into(),
35            args: Vec::new(),
36            envs: Vec::new(),
37            request_timeout: Duration::from_secs(120),
38        }
39    }
40    pub fn arg(mut self, a: impl Into<String>) -> Self {
41        self.args.push(a.into());
42        self
43    }
44    pub fn env(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
45        self.envs.push((k.into(), v.into()));
46        self
47    }
48    pub fn timeout(mut self, d: Duration) -> Self {
49        self.request_timeout = d;
50        self
51    }
52    /// Arguments the real `rightkit-cloudkit-helper` needs.
53    pub fn cloudkit(self, container: &str, zone: &str, subscription: &str) -> Self {
54        self.arg("--container")
55            .arg(container)
56            .arg("--zone")
57            .arg(zone)
58            .arg("--subscription")
59            .arg(subscription)
60    }
61}
62
63struct Live {
64    child: Child,
65    stdin: ChildStdin,
66    lines: Receiver<Result<String, String>>,
67}
68
69pub struct HelperProcess {
70    cfg: HelperConfig,
71    live: Mutex<Option<Live>>,
72    next_id: AtomicU64,
73    stderr_tail: Arc<Mutex<VecDeque<String>>>,
74    spawns: AtomicU64,
75}
76
77impl HelperProcess {
78    pub fn new(cfg: HelperConfig) -> Self {
79        Self {
80            cfg,
81            live: Mutex::new(None),
82            next_id: AtomicU64::new(1),
83            stderr_tail: Arc::new(Mutex::new(VecDeque::new())),
84            spawns: AtomicU64::new(0),
85        }
86    }
87
88    /// How many helper processes were started (observability and tests).
89    pub fn spawn_count(&self) -> u64 {
90        self.spawns.load(Ordering::Relaxed)
91    }
92
93    fn spawn(&self) -> SyncResult<Live> {
94        let mut cmd = Command::new(&self.cfg.program);
95        cmd.args(&self.cfg.args)
96            .stdin(Stdio::piped())
97            .stdout(Stdio::piped())
98            .stderr(Stdio::piped());
99        #[cfg(windows)]
100        {
101            use std::os::windows::process::CommandExt;
102            cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW: never flash a console from a GUI host
103        }
104        for (k, v) in &self.cfg.envs {
105            cmd.env(k, v);
106        }
107        let mut child = cmd.spawn().map_err(|e| {
108            SyncError::Unavailable(format!(
109                "sync helper {} could not start: {e}",
110                self.cfg.program.display()
111            ))
112        })?;
113        self.spawns.fetch_add(1, Ordering::Relaxed);
114        let stdin = child.stdin.take().expect("piped stdin");
115        let stdout = child.stdout.take().expect("piped stdout");
116        let stderr = child.stderr.take().expect("piped stderr");
117        let (tx, rx) = mpsc::channel();
118        std::thread::spawn(move || {
119            let mut reader = BufReader::new(stdout);
120            loop {
121                let mut line = String::new();
122                match reader
123                    .by_ref()
124                    .take(MAX_LINE_BYTES as u64 + 1)
125                    .read_line(&mut line)
126                {
127                    Ok(0) => {
128                        let _ = tx.send(Err("helper closed stdout".to_string()));
129                        return;
130                    }
131                    Ok(_) if line.len() > MAX_LINE_BYTES => {
132                        let _ = tx.send(Err("helper response line too large".to_string()));
133                        return;
134                    }
135                    Ok(_) => {
136                        if tx.send(Ok(line)).is_err() {
137                            return;
138                        }
139                    }
140                    Err(e) => {
141                        let _ = tx.send(Err(e.to_string()));
142                        return;
143                    }
144                }
145            }
146        });
147        let tail = Arc::clone(&self.stderr_tail);
148        std::thread::spawn(move || {
149            for line in BufReader::new(stderr).lines().map_while(Result::ok) {
150                let mut t = tail.lock().unwrap();
151                if t.len() >= 20 {
152                    t.pop_front();
153                }
154                t.push_back(line);
155            }
156        });
157        Ok(Live {
158            child,
159            stdin,
160            lines: rx,
161        })
162    }
163
164    fn stderr_summary(&self) -> String {
165        let t = self.stderr_tail.lock().unwrap();
166        t.back().cloned().unwrap_or_default()
167    }
168
169    fn kill(live: Option<Live>) {
170        if let Some(mut l) = live {
171            let _ = l.child.kill();
172            let _ = l.child.wait();
173        }
174    }
175
176    /// Stop the helper (also happens on drop).
177    pub fn shutdown(&self) {
178        let live = self.live.lock().unwrap().take();
179        Self::kill(live);
180    }
181
182    /// One request, one response. Transport-level failures (spawn, write,
183    /// timeout, EOF, malformed line) kill the helper and surface as retryable
184    /// errors; helper-reported errors come back as `Ok(Response{ok:false})`
185    /// mapped by the caller.
186    pub fn call(&self, cmd: &str, params: Map<String, Value>) -> SyncResult<Response> {
187        let id = self.next_id.fetch_add(1, Ordering::Relaxed);
188        let mut req = params;
189        req.insert("v".into(), PROTOCOL_VERSION.into());
190        req.insert("id".into(), id.into());
191        req.insert("cmd".into(), cmd.into());
192        let line = Value::Object(req).to_string();
193
194        let mut guard = self.live.lock().unwrap();
195        if guard.is_none() {
196            *guard = Some(self.spawn()?);
197        }
198        let outcome = (|| -> Result<Response, String> {
199            let live = guard.as_mut().expect("spawned");
200            live.stdin
201                .write_all(line.as_bytes())
202                .and_then(|()| live.stdin.write_all(b"\n"))
203                .and_then(|()| live.stdin.flush())
204                .map_err(|e| format!("write to helper failed: {e}"))?;
205            let deadline = std::time::Instant::now() + self.cfg.request_timeout;
206            loop {
207                let left = deadline.saturating_duration_since(std::time::Instant::now());
208                match live.lines.recv_timeout(left) {
209                    Ok(Ok(text)) => {
210                        let resp: Response = serde_json::from_str(text.trim())
211                            .map_err(|e| format!("malformed helper response: {e}"))?;
212                        if resp.id == id {
213                            return Ok(resp);
214                        }
215                        // Stale id from a request we already abandoned.
216                    }
217                    Ok(Err(e)) => return Err(e),
218                    Err(RecvTimeoutError::Timeout) => {
219                        return Err(format!(
220                            "helper timed out after {:?}",
221                            self.cfg.request_timeout
222                        ))
223                    }
224                    Err(RecvTimeoutError::Disconnected) => {
225                        return Err("helper reader stopped".to_string())
226                    }
227                }
228            }
229        })();
230        match outcome {
231            Ok(resp) => Ok(resp),
232            Err(why) => {
233                Self::kill(guard.take());
234                let tail = self.stderr_summary();
235                let detail = if tail.is_empty() {
236                    why
237                } else {
238                    format!("{why} ({tail})")
239                };
240                Err(SyncError::RetryAfter { secs: 15.0, detail })
241            }
242        }
243    }
244}
245
246impl Drop for HelperProcess {
247    fn drop(&mut self) {
248        let live = self.live.get_mut().ok().and_then(Option::take);
249        Self::kill(live);
250    }
251}