Skip to main content

graphrt_plugin/
conn.rs

1//! A multiplexed JSON-RPC connection over any byte stream (child process stdio,
2//! in-process duplex pipes...).
3//!
4//! One reader task routes responses to waiting callers by id and notifications
5//! to the in-flight request named by their `request_id`; one writer task
6//! serializes outgoing lines.
7
8use std::collections::HashMap;
9use std::fmt;
10use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
11use std::sync::{Arc, Mutex};
12
13use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncWrite, AsyncWriteExt, BufReader};
14use tokio::sync::{mpsc, oneshot};
15
16use crate::error::CallError;
17use crate::protocol::{self, Incoming, Notification};
18
19/// Receives notifications for one in-flight request.
20pub type NotifySink = Arc<dyn Fn(Notification) + Send + Sync>;
21
22/// Produces extra detail (e.g. the plugin's stderr tail) when the connection breaks.
23pub(crate) type CrashDetail = Arc<dyn Fn() -> String + Send + Sync>;
24
25struct Pending {
26    reply: oneshot::Sender<Result<serde_json::Value, CallError>>,
27    sink: Option<NotifySink>,
28}
29
30#[derive(Default)]
31struct Shared {
32    /// Pending requests. `None` once the connection is closed: the closed state and
33    /// the pending map change together under this one lock, so a request can never
34    /// be registered after the drain and then wait forever.
35    pending: Mutex<Option<HashMap<String, Pending>>>,
36    closed: AtomicBool,
37    close_reason: Mutex<Option<String>>,
38    logs: Mutex<LogBuffer>,
39    /// Plugin name used in forwarded log events.
40    label: Mutex<String>,
41}
42
43/// Most recent `log` notifications, bounded by line count and total bytes.
44#[derive(Default)]
45struct LogBuffer {
46    lines: std::collections::VecDeque<String>,
47    bytes: usize,
48}
49
50const MAX_LOG_LINES: usize = 200;
51/// Longest log line kept (longer lines are truncated).
52const MAX_LOG_LINE_BYTES: usize = 4 * 1024;
53/// Total bytes of retained log lines.
54const MAX_LOG_BYTES: usize = 256 * 1024;
55
56impl Shared {
57    fn new() -> Self {
58        Self { pending: Mutex::new(Some(HashMap::new())), ..Self::default() }
59    }
60
61    fn take_pending(&self, id: &str) -> Option<Pending> {
62        self.pending.lock().ok().and_then(|mut p| p.as_mut().and_then(|m| m.remove(id)))
63    }
64
65    fn sink_for(&self, request_id: &str) -> Option<NotifySink> {
66        self.pending.lock().ok().and_then(|p| p.as_ref().and_then(|m| m.get(request_id).and_then(|e| e.sink.clone())))
67    }
68
69    /// Register a pending request, or fail if the connection already closed.
70    fn register(&self, id: String, pending: Pending) -> Result<(), CallError> {
71        let mut guard = self.pending.lock().map_err(|_| CallError::Protocol("connection state poisoned".into()))?;
72        match guard.as_mut() {
73            Some(map) => {
74                map.insert(id, pending);
75                Ok(())
76            }
77            None => Err(CallError::Crashed(self.reason())),
78        }
79    }
80
81    fn close(&self, reason: String) {
82        if let Ok(mut r) = self.close_reason.lock() {
83            if r.is_none() {
84                *r = Some(reason.clone());
85            }
86        }
87        // Mark closed and take every pending request under the same lock.
88        let drained: Vec<Pending> = match self.pending.lock() {
89            Ok(mut p) => {
90                self.closed.store(true, Ordering::SeqCst);
91                p.take().map(|m| m.into_values().collect()).unwrap_or_default()
92            }
93            Err(_) => {
94                self.closed.store(true, Ordering::SeqCst);
95                Vec::new()
96            }
97        };
98        let reason = self.reason();
99        for pending in drained {
100            let _receiver_gone = pending.reply.send(Err(CallError::Crashed(reason.clone())));
101        }
102    }
103
104    fn reason(&self) -> String {
105        self.close_reason.lock().ok().and_then(|r| r.clone()).unwrap_or_else(|| "connection closed".into())
106    }
107
108    fn label(&self) -> String {
109        self.label.lock().map(|l| l.clone()).unwrap_or_default()
110    }
111
112    fn push_log(&self, mut line: String) {
113        truncate_utf8(&mut line, MAX_LOG_LINE_BYTES);
114        if let Ok(mut logs) = self.logs.lock() {
115            logs.bytes = logs.bytes.saturating_add(line.len());
116            logs.lines.push_back(line);
117            while logs.lines.len() > MAX_LOG_LINES || logs.bytes > MAX_LOG_BYTES {
118                match logs.lines.pop_front() {
119                    Some(old) => logs.bytes = logs.bytes.saturating_sub(old.len()),
120                    None => break,
121                }
122            }
123        }
124    }
125}
126
127/// Cut `s` to at most `max` bytes on a character boundary, marking the cut.
128pub(crate) fn truncate_utf8(s: &mut String, max: usize) {
129    if s.len() <= max {
130        return;
131    }
132    let mut end = max;
133    while end > 0 && !s.is_char_boundary(end) {
134        end -= 1;
135    }
136    s.truncate(end);
137    s.push_str("…[truncated]");
138}
139
140/// Forward a plugin log line to the operator (stderr), tagged with the plugin name.
141pub(crate) fn forward_log(plugin: &str, level: &str, message: &str) {
142    let mut message = message.to_owned();
143    truncate_utf8(&mut message, MAX_LOG_LINE_BYTES);
144    let level = match level {
145        "error" | "warn" | "warning" | "info" | "debug" | "trace" => level,
146        _ => "info",
147    };
148    // Plugin authors are told to log through the protocol instead of writing to
149    // stdout; surface those lines where operators look. Debug/trace stay quiet
150    // unless `GRAPHRT_PLUGIN_LOG=debug`.
151    let verbose = std::env::var("GRAPHRT_PLUGIN_LOG").is_ok_and(|v| v == "debug" || v == "trace");
152    if matches!(level, "debug" | "trace") && !verbose {
153        return;
154    }
155    let plugin = if plugin.is_empty() { "plugin" } else { plugin };
156    #[allow(clippy::print_stderr)]
157    {
158        eprintln!("[plugin {plugin}] {level}: {message}");
159    }
160}
161
162/// A live connection to a plugin.
163pub struct Connection {
164    shared: Arc<Shared>,
165    writer: mpsc::UnboundedSender<String>,
166    next_id: AtomicU64,
167    max_message_bytes: usize,
168    tasks: Vec<tokio::task::JoinHandle<()>>,
169    /// Resource kept alive with the connection (e.g. the child-process guard).
170    _guard: Option<Box<dyn std::any::Any + Send + Sync>>,
171}
172
173impl fmt::Debug for Connection {
174    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
175        f.debug_struct("Connection").field("closed", &self.is_closed()).finish_non_exhaustive()
176    }
177}
178
179impl Drop for Connection {
180    fn drop(&mut self) {
181        for task in &self.tasks {
182            task.abort();
183        }
184    }
185}
186
187impl Connection {
188    /// Connect over a reader/writer pair. Must be called inside a tokio runtime.
189    pub fn new<R, W>(reader: R, writer: W, max_message_bytes: usize) -> Self
190    where
191        R: AsyncRead + Send + Unpin + 'static,
192        W: AsyncWrite + Send + Unpin + 'static,
193    {
194        Self::with_guard(reader, writer, max_message_bytes, None, None)
195    }
196
197    pub(crate) fn with_guard<R, W>(
198        reader: R,
199        writer: W,
200        max_message_bytes: usize,
201        guard: Option<Box<dyn std::any::Any + Send + Sync>>,
202        crash_detail: Option<CrashDetail>,
203    ) -> Self
204    where
205        R: AsyncRead + Send + Unpin + 'static,
206        W: AsyncWrite + Send + Unpin + 'static,
207    {
208        let shared = Arc::new(Shared::new());
209        let (tx, rx) = mpsc::unbounded_channel::<String>();
210        let writer_task = tokio::spawn(write_loop(writer, rx, shared.clone()));
211        let reader_task = tokio::spawn(read_loop(
212            BufReader::new(reader),
213            shared.clone(),
214            tx.clone(),
215            max_message_bytes,
216            crash_detail,
217        ));
218        Self {
219            shared,
220            writer: tx,
221            next_id: AtomicU64::new(1),
222            max_message_bytes,
223            tasks: vec![reader_task, writer_task],
224            _guard: guard,
225        }
226    }
227
228    /// Whether the connection is closed (the plugin exited or broke the protocol).
229    pub fn is_closed(&self) -> bool {
230        self.shared.closed.load(Ordering::SeqCst)
231    }
232
233    /// A fresh request id, unique within this connection.
234    pub fn next_id(&self) -> String {
235        format!("r-{}", self.next_id.fetch_add(1, Ordering::Relaxed))
236    }
237
238    /// Recent `log` notifications from the plugin (`level: message`).
239    pub fn recent_logs(&self) -> Vec<String> {
240        self.shared.logs.lock().map(|l| l.lines.iter().cloned().collect()).unwrap_or_default()
241    }
242
243    /// Name used when forwarding the plugin's log lines to the operator.
244    pub fn set_label(&self, label: &str) {
245        if let Ok(mut l) = self.shared.label.lock() {
246            label.clone_into(&mut l);
247        }
248    }
249
250    /// Close the connection (pending requests fail with `reason`) and drop the
251    /// guarded resource on the next drop of this connection.
252    pub fn close(&self, reason: &str) {
253        self.shared.close(reason.to_owned());
254    }
255
256    /// Send a notification (fire and forget).
257    pub fn notify(&self, method: &str, params: &serde_json::Value) {
258        let _closed = self.writer.send(protocol::notification(method, params));
259    }
260
261    /// Send a request with id `id` and wait for its response. Notifications whose
262    /// `request_id` equals `id` go to `sink`. When the returned future is dropped
263    /// before completion and `cancel_on_drop` is set, a `node.cancel` notification
264    /// is sent.
265    pub async fn call(
266        &self,
267        id: String,
268        method: &str,
269        params: serde_json::Value,
270        sink: Option<NotifySink>,
271        cancel_on_drop: bool,
272    ) -> Result<serde_json::Value, CallError> {
273        if self.is_closed() {
274            return Err(CallError::Crashed(self.shared.reason()));
275        }
276        let line = protocol::request(&id, method, &params);
277        if line.len() > self.max_message_bytes {
278            return Err(CallError::Protocol(format!(
279                "request is {} bytes, above the {}-byte message limit",
280                line.len(),
281                self.max_message_bytes
282            )));
283        }
284        let (reply, rx) = oneshot::channel();
285        self.shared.register(id.clone(), Pending { reply, sink })?;
286        let mut guard = CancelGuard {
287            id: id.clone(),
288            shared: self.shared.clone(),
289            writer: self.writer.clone(),
290            armed: cancel_on_drop,
291        };
292        if self.writer.send(line).is_err() {
293            guard.armed = false;
294            self.shared.take_pending(&id);
295            return Err(CallError::Crashed(self.shared.reason()));
296        }
297        let result = rx.await.unwrap_or_else(|_| Err(CallError::Crashed(self.shared.reason())));
298        guard.armed = false;
299        result
300    }
301}
302
303/// Sends `node.cancel` if a call is abandoned before its response arrives.
304struct CancelGuard {
305    id: String,
306    shared: Arc<Shared>,
307    writer: mpsc::UnboundedSender<String>,
308    armed: bool,
309}
310
311impl Drop for CancelGuard {
312    fn drop(&mut self) {
313        if self.shared.take_pending(&self.id).is_some() && self.armed {
314            let params = serde_json::json!({"request_id": self.id});
315            let _closed = self.writer.send(protocol::notification("node.cancel", &params));
316        }
317    }
318}
319
320async fn write_loop<W: AsyncWrite + Unpin>(
321    mut writer: W,
322    mut rx: mpsc::UnboundedReceiver<String>,
323    shared: Arc<Shared>,
324) {
325    while let Some(mut line) = rx.recv().await {
326        line.push('\n');
327        let written = async {
328            writer.write_all(line.as_bytes()).await?;
329            writer.flush().await
330        };
331        if let Err(e) = written.await {
332            shared.close(format!("cannot write to plugin: {e}"));
333            return;
334        }
335    }
336}
337
338async fn read_loop<R: AsyncBufRead + Unpin>(
339    mut reader: R,
340    shared: Arc<Shared>,
341    writer: mpsc::UnboundedSender<String>,
342    max_message_bytes: usize,
343    crash_detail: Option<CrashDetail>,
344) {
345    let mut buf = Vec::new();
346    let reason = loop {
347        buf.clear();
348        match read_line_capped(&mut reader, &mut buf, max_message_bytes).await {
349            Ok(0) => break "plugin closed its output (process exited?)".to_owned(),
350            Ok(_) => {}
351            Err(e) => break e,
352        }
353        let Ok(line) = std::str::from_utf8(&buf) else {
354            break "plugin sent invalid UTF-8".to_owned();
355        };
356        let line = line.trim();
357        if line.is_empty() {
358            continue;
359        }
360        match protocol::parse(line) {
361            Ok(Incoming::Response { id, result }) => match shared.take_pending(&id) {
362                Some(pending) => {
363                    let _receiver_gone = pending.reply.send(result);
364                }
365                // Usually a late answer to a request that timed out or was cancelled.
366                None => forward_log(&shared.label(), "debug", &format!("ignored response to unknown request `{id}`")),
367            },
368            Ok(Incoming::Notification(n)) => route_notification(&shared, n),
369            Ok(Incoming::Request { id, method }) => {
370                let _closed = writer.send(protocol::method_not_found(&id, &method));
371            }
372            Err(e) => break e.to_string(),
373        }
374    };
375    let detail = match crash_detail {
376        Some(f) => {
377            // Let the stderr reader and the exit-status watcher catch up so the
378            // report says why the plugin died.
379            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
380            Some(f()).filter(|d| !d.trim().is_empty())
381        }
382        None => None,
383    };
384    let reason = match detail {
385        Some(d) => format!("{reason} ({d})"),
386        None => reason,
387    };
388    shared.close(reason);
389}
390
391fn route_notification(shared: &Shared, n: Notification) {
392    if n.method == "log" {
393        let level = n.params.get("level").and_then(|v| v.as_str()).unwrap_or("info");
394        let message = n.params.get("message").and_then(|v| v.as_str()).unwrap_or_default();
395        forward_log(&shared.label(), level, message);
396        shared.push_log(format!("{level}: {message}"));
397        // A log tied to a request also reaches that node's event stream.
398        if let Some(request_id) = n.request_id().map(str::to_owned) {
399            if let Some(sink) = shared.sink_for(&request_id) {
400                sink(n);
401            }
402        }
403        return;
404    }
405    let Some(request_id) = n.request_id().map(str::to_owned) else { return };
406    if let Some(sink) = shared.sink_for(&request_id) {
407        sink(n);
408    }
409}
410
411/// Read one `\n`-terminated line into `buf`, failing past `max` bytes.
412/// Returns the number of bytes read (0 at EOF).
413async fn read_line_capped<R: AsyncBufRead + Unpin>(
414    reader: &mut R,
415    buf: &mut Vec<u8>,
416    max: usize,
417) -> Result<usize, String> {
418    loop {
419        let available = reader.fill_buf().await.map_err(|e| format!("cannot read from plugin: {e}"))?;
420        if available.is_empty() {
421            return Ok(buf.len());
422        }
423        let (chunk, done) = match available.iter().position(|b| *b == b'\n') {
424            Some(pos) => (available.get(..=pos).unwrap_or(available), true),
425            None => (available, false),
426        };
427        if buf.len().saturating_add(chunk.len()) > max.saturating_add(1) {
428            return Err(format!("plugin message exceeds the {max}-byte limit"));
429        }
430        buf.extend_from_slice(chunk);
431        let used = chunk.len();
432        reader.consume(used);
433        if done {
434            return Ok(buf.len());
435        }
436    }
437}
438
439#[cfg(test)]
440mod tests {
441    use super::*;
442
443    #[tokio::test]
444    async fn call_after_close_fails_immediately() {
445        let (client, _server) = tokio::io::duplex(1024);
446        let (r, w) = tokio::io::split(client);
447        let conn = Connection::new(r, w, 1 << 20);
448        conn.close("gone");
449        // Even a caller that passed the `is_closed` check must not register a request
450        // after the drain; `register` refuses it under the same lock.
451        let err = conn.shared.register("x".into(), Pending { reply: oneshot::channel().0, sink: None });
452        assert!(matches!(err, Err(CallError::Crashed(m)) if m == "gone"));
453        let res = conn.call("r-1".into(), "node.run", serde_json::json!({}), None, false).await;
454        assert!(matches!(res, Err(CallError::Crashed(_))));
455    }
456
457    #[test]
458    fn retained_logs_are_bounded() {
459        let shared = Shared::new();
460        for _ in 0..500 {
461            shared.push_log("x".repeat(64 * 1024));
462        }
463        let logs = shared.logs.lock().unwrap();
464        assert!(logs.bytes <= MAX_LOG_BYTES);
465        assert!(logs.lines.iter().all(|l| l.len() <= MAX_LOG_LINE_BYTES + 16));
466    }
467}