Skip to main content

graphrt_plugin_sdk/
lib.rs

1//! # graphrt-plugin-sdk
2//!
3//! Write graphrt plugins in Rust. A plugin is a small executable that serves
4//! node kinds (and optionally tools) over the graphrt plugin protocol
5//! (newline-delimited JSON-RPC 2.0 on stdin/stdout).
6//!
7//! ```no_run
8//! use graphrt_plugin_sdk::{Plugin, RunResult};
9//!
10//! #[tokio::main(flavor = "current_thread")]
11//! async fn main() -> std::io::Result<()> {
12//!     Plugin::new("acme")
13//!         .node("acme.len", |ctx, req| async move {
14//!             let text = req.config["text"].as_str().unwrap_or_default().to_owned();
15//!             ctx.chunk("log", "counting...");
16//!             Ok(RunResult::new().output("length", text.chars().count()))
17//!         })
18//!         .serve_stdio()
19//!         .await
20//! }
21//! ```
22//!
23//! Pair the executable with a `graphrt-plugin.json` manifest (see the graphrt
24//! plugin documentation). Never print to stdout yourself: it carries the protocol.
25//! Use [`RunCtx::log`] or stderr instead.
26
27use std::collections::HashMap;
28use std::fmt;
29use std::future::Future;
30use std::pin::Pin;
31use std::sync::atomic::{AtomicBool, Ordering};
32use std::sync::{Arc, Mutex};
33
34use serde::Serialize;
35use serde_json::{Map, Value, json};
36use tokio::io::{AsyncBufReadExt, AsyncRead, AsyncWrite, AsyncWriteExt, BufReader};
37use tokio::sync::{Notify, mpsc};
38
39/// Protocol version implemented by this SDK.
40pub const PROTOCOL_VERSION: u32 = 1;
41
42/// Largest accepted incoming message.
43pub const MAX_MESSAGE_BYTES: usize = 16 * 1024 * 1024;
44
45type BoxFuture<T> = Pin<Box<dyn Future<Output = T> + Send + 'static>>;
46type NodeHandler = Arc<dyn Fn(RunCtx, RunRequest) -> BoxFuture<Result<Outcome, PluginError>> + Send + Sync>;
47type ToolHandler = Arc<dyn Fn(ToolCall) -> BoxFuture<Result<ToolResult, PluginError>> + Send + Sync>;
48
49/// A `node.run` request.
50#[derive(Clone, Debug, PartialEq)]
51pub struct RunRequest {
52    pub request_id: String,
53    /// Node kind being run.
54    pub kind: String,
55    /// Id of the node in the workflow.
56    pub node_id: String,
57    /// 1-based attempt number (increments on retries).
58    pub attempt: u32,
59    /// Node configuration with variables already resolved by the host.
60    pub config: Value,
61    /// Present when the node resumes after pausing.
62    pub resume: Option<Resume>,
63}
64
65/// Resume data for a node that paused.
66#[derive(Clone, Debug, PartialEq)]
67pub struct Resume {
68    /// The state returned with [`Outcome::Pause`].
69    pub state: Value,
70    /// Host-supplied input (e.g. a submitted form), `null` if none.
71    pub input: Value,
72}
73
74/// Successful node result.
75#[derive(Clone, Debug, Default, PartialEq, Serialize)]
76pub struct RunResult {
77    pub outputs: Map<String, Value>,
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub branch: Option<String>,
80    #[serde(skip_serializing_if = "Vec::is_empty")]
81    pub writes: Vec<Value>,
82    #[serde(skip_serializing_if = "Option::is_none")]
83    pub usage: Option<Value>,
84    #[serde(skip_serializing_if = "Map::is_empty")]
85    pub metadata: Map<String, Value>,
86}
87
88impl RunResult {
89    pub fn new() -> Self {
90        Self::default()
91    }
92
93    /// Add an output. Values that fail to serialize become `null`.
94    pub fn output(mut self, name: impl Into<String>, value: impl Serialize) -> Self {
95        self.outputs.insert(name.into(), serde_json::to_value(value).unwrap_or(Value::Null));
96        self
97    }
98
99    /// Select an outgoing branch handle (for nodes declaring handles).
100    pub fn branch(mut self, handle: impl Into<String>) -> Self {
101        self.branch = Some(handle.into());
102        self
103    }
104
105    /// Write a variable outside the node's outputs, e.g. `["conversation", "topic"]`.
106    pub fn write(mut self, selector: &[&str], value: impl Serialize) -> Self {
107        let value = serde_json::to_value(value).unwrap_or(Value::Null);
108        self.writes.push(json!({"selector": selector, "value": value}));
109        self
110    }
111
112    /// Report token usage.
113    pub fn usage(mut self, prompt_tokens: u64, completion_tokens: u64) -> Self {
114        self.usage = Some(json!({
115            "prompt_tokens": prompt_tokens,
116            "completion_tokens": completion_tokens,
117            "total_tokens": prompt_tokens.saturating_add(completion_tokens),
118        }));
119        self
120    }
121
122    /// Attach observability metadata.
123    pub fn meta(mut self, key: impl Into<String>, value: impl Serialize) -> Self {
124        self.metadata.insert(key.into(), serde_json::to_value(value).unwrap_or(Value::Null));
125        self
126    }
127}
128
129/// What a node handler returns.
130#[derive(Clone, Debug, PartialEq)]
131pub enum Outcome {
132    Done(RunResult),
133    /// Pause the run; the node is called again with [`RunRequest::resume`].
134    Pause {
135        kind: String,
136        data: Value,
137        state: Value,
138    },
139}
140
141impl From<RunResult> for Outcome {
142    fn from(r: RunResult) -> Self {
143        Outcome::Done(r)
144    }
145}
146
147impl Outcome {
148    /// Pause with a kind (e.g. `approval`), data shown to the host, and private state.
149    pub fn pause(kind: impl Into<String>, data: impl Serialize, state: impl Serialize) -> Self {
150        Outcome::Pause {
151            kind: kind.into(),
152            data: serde_json::to_value(data).unwrap_or(Value::Null),
153            state: serde_json::to_value(state).unwrap_or(Value::Null),
154        }
155    }
156}
157
158/// An error reported to the host.
159#[derive(Clone, Debug, PartialEq)]
160pub struct PluginError {
161    /// Error category (becomes the node error type).
162    pub kind: String,
163    pub message: String,
164    /// Whether the host may retry.
165    pub retryable: bool,
166    pub retry_after_ms: Option<u64>,
167}
168
169impl PluginError {
170    /// A non-retryable error.
171    pub fn new(kind: impl Into<String>, message: impl Into<String>) -> Self {
172        Self { kind: kind.into(), message: message.into(), retryable: false, retry_after_ms: None }
173    }
174
175    /// A retryable error.
176    pub fn retryable(kind: impl Into<String>, message: impl Into<String>) -> Self {
177        Self { retryable: true, ..Self::new(kind, message) }
178    }
179
180    pub fn retry_after(mut self, ms: u64) -> Self {
181        self.retry_after_ms = Some(ms);
182        self
183    }
184
185    /// Invalid configuration or input.
186    pub fn invalid_input(message: impl Into<String>) -> Self {
187        Self::new("invalid_input", message)
188    }
189}
190
191impl fmt::Display for PluginError {
192    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
193        write!(f, "{}: {}", self.kind, self.message)
194    }
195}
196
197impl std::error::Error for PluginError {}
198
199/// A `tool.call` request.
200#[derive(Clone, Debug, PartialEq)]
201pub struct ToolCall {
202    pub name: String,
203    pub arguments: Value,
204}
205
206/// A tool result.
207#[derive(Clone, Debug, Default, PartialEq, Serialize)]
208pub struct ToolResult {
209    pub text: String,
210    #[serde(skip_serializing_if = "Value::is_null")]
211    pub data: Value,
212    pub is_error: bool,
213}
214
215impl ToolResult {
216    pub fn text(text: impl Into<String>) -> Self {
217        Self { text: text.into(), data: Value::Null, is_error: false }
218    }
219
220    pub fn error(text: impl Into<String>) -> Self {
221        Self { text: text.into(), data: Value::Null, is_error: true }
222    }
223
224    pub fn with_data(mut self, data: impl Serialize) -> Self {
225        self.data = serde_json::to_value(data).unwrap_or(Value::Null);
226        self
227    }
228}
229
230/// Per-request context: streaming, progress, logs and cancellation.
231#[derive(Clone)]
232pub struct RunCtx {
233    request_id: String,
234    out: mpsc::UnboundedSender<String>,
235    cancelled: Arc<AtomicBool>,
236    cancel_notify: Arc<Notify>,
237}
238
239impl fmt::Debug for RunCtx {
240    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
241        f.debug_struct("RunCtx").field("request_id", &self.request_id).finish_non_exhaustive()
242    }
243}
244
245impl RunCtx {
246    pub fn request_id(&self) -> &str {
247        &self.request_id
248    }
249
250    /// Stream text for output `field`.
251    pub fn chunk(&self, field: &str, chunk: &str) {
252        self.notify("node.chunk", json!({"request_id": self.request_id, "field": field, "chunk": chunk}));
253    }
254
255    /// Report structured progress.
256    pub fn progress(&self, name: &str, data: impl Serialize) {
257        let data = serde_json::to_value(data).unwrap_or(Value::Null);
258        self.notify("node.progress", json!({"request_id": self.request_id, "name": name, "data": data}));
259    }
260
261    /// Log a line on the host (`debug`, `info`, `warn` or `error`).
262    pub fn log(&self, level: &str, message: &str) {
263        self.notify("log", json!({"level": level, "message": message}));
264    }
265
266    /// Whether the host cancelled this request.
267    pub fn is_cancelled(&self) -> bool {
268        self.cancelled.load(Ordering::SeqCst)
269    }
270
271    /// Resolves when the host cancels this request.
272    pub async fn cancelled(&self) {
273        loop {
274            let notified = self.cancel_notify.notified();
275            if self.is_cancelled() {
276                return;
277            }
278            notified.await;
279        }
280    }
281
282    fn notify(&self, method: &str, params: Value) {
283        let _host_gone = self.out.send(json!({"jsonrpc": "2.0", "method": method, "params": params}).to_string());
284    }
285}
286
287/// A plugin: a set of node kinds and tools.
288#[derive(Clone, Default)]
289pub struct Plugin {
290    name: String,
291    nodes: HashMap<String, NodeHandler>,
292    descriptors: Vec<Value>,
293    tools: HashMap<String, ToolHandler>,
294    tool_specs: Vec<Value>,
295}
296
297impl fmt::Debug for Plugin {
298    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
299        let mut kinds: Vec<&String> = self.nodes.keys().collect();
300        kinds.sort();
301        f.debug_struct("Plugin").field("name", &self.name).field("nodes", &kinds).finish_non_exhaustive()
302    }
303}
304
305impl Plugin {
306    pub fn new(name: impl Into<String>) -> Self {
307        Self { name: name.into(), ..Self::default() }
308    }
309
310    /// Register a node kind handler.
311    pub fn node<F, Fut, O>(mut self, kind: impl Into<String>, handler: F) -> Self
312    where
313        F: Fn(RunCtx, RunRequest) -> Fut + Send + Sync + 'static,
314        Fut: Future<Output = Result<O, PluginError>> + Send + 'static,
315        O: Into<Outcome>,
316    {
317        let handler: NodeHandler = Arc::new(move |ctx, req| {
318            let fut = handler(ctx, req);
319            Box::pin(async move { fut.await.map(Into::into) })
320        });
321        self.nodes.insert(kind.into(), handler);
322        self
323    }
324
325    /// Publish a node descriptor from `initialize` (optional; the manifest is
326    /// usually enough). `descriptor` follows the graphrt node catalog format.
327    pub fn describe(mut self, descriptor: Value) -> Self {
328        self.descriptors.push(descriptor);
329        self
330    }
331
332    /// Register a tool. `spec` is `{name, description, parameters}`.
333    pub fn tool<F, Fut>(mut self, spec: Value, handler: F) -> Self
334    where
335        F: Fn(ToolCall) -> Fut + Send + Sync + 'static,
336        Fut: Future<Output = Result<ToolResult, PluginError>> + Send + 'static,
337    {
338        let name = spec.get("name").and_then(Value::as_str).unwrap_or_default().to_owned();
339        let handler: ToolHandler = Arc::new(move |call| Box::pin(handler(call)));
340        self.tools.insert(name, handler);
341        self.tool_specs.push(spec);
342        self
343    }
344
345    /// Serve the protocol on stdin/stdout until stdin closes or `shutdown` arrives.
346    pub async fn serve_stdio(self) -> std::io::Result<()> {
347        self.serve(tokio::io::stdin(), tokio::io::stdout()).await
348    }
349
350    /// Serve the protocol on any reader/writer pair (useful for tests and
351    /// in-process plugins).
352    pub async fn serve<R, W>(self, reader: R, writer: W) -> std::io::Result<()>
353    where
354        R: AsyncRead + Unpin + Send + 'static,
355        W: AsyncWrite + Unpin + Send + 'static,
356    {
357        let plugin = Arc::new(self);
358        let (out_tx, mut out_rx) = mpsc::unbounded_channel::<String>();
359        let writer_task = tokio::spawn(async move {
360            let mut writer = writer;
361            while let Some(mut line) = out_rx.recv().await {
362                line.push('\n');
363                if writer.write_all(line.as_bytes()).await.is_err() || writer.flush().await.is_err() {
364                    break;
365                }
366            }
367        });
368
369        let running: Arc<Mutex<HashMap<String, Running>>> = Arc::new(Mutex::new(HashMap::new()));
370        let mut lines = BufReader::new(reader);
371        let mut buf = Vec::new();
372        let mut shutdown = false;
373        // The host announces its line limit in `initialize`.
374        let mut limit = MAX_MESSAGE_BYTES;
375        loop {
376            buf.clear();
377            match read_line_capped(&mut lines, &mut buf, limit).await? {
378                Line::Eof => break,
379                Line::Oversized => {
380                    eprintln!("graphrt plugin {}: dropped a message above {limit} bytes", plugin.name);
381                    let id = recover_id(&buf);
382                    let msg = format!("message exceeds the {limit}-byte limit");
383                    send(&out_tx, error_response(&id, -32600, &msg, Some(json!({"kind": "message_too_large"}))));
384                    continue;
385                }
386                Line::Complete => {}
387            }
388            let Ok(text) = std::str::from_utf8(&buf) else {
389                eprintln!("graphrt plugin {}: message is not valid UTF-8", plugin.name);
390                let data = Some(json!({"kind": "plugin_protocol"}));
391                send(&out_tx, error_response(&recover_id(&buf), -32700, "message is not valid UTF-8", data));
392                continue;
393            };
394            let text = text.trim();
395            if text.is_empty() {
396                continue;
397            }
398            let Ok(msg) = serde_json::from_str::<Value>(text) else {
399                eprintln!("graphrt plugin {}: unreadable message", plugin.name);
400                let data = Some(json!({"kind": "plugin_protocol"}));
401                send(&out_tx, error_response(&recover_id(&buf), -32700, "parse error", data));
402                continue;
403            };
404            if let Some(announced) = msg
405                .get("params")
406                .and_then(|p| p.get("max_message_bytes"))
407                .and_then(Value::as_u64)
408                .filter(|_| msg.get("method").and_then(Value::as_str) == Some("initialize"))
409            {
410                limit = usize::try_from(announced).unwrap_or(usize::MAX).max(1024);
411            }
412            let id = msg.get("id").cloned();
413            let method = msg.get("method").and_then(Value::as_str).unwrap_or_default().to_owned();
414            let params = msg.get("params").cloned().unwrap_or(Value::Null);
415            match (method.as_str(), id) {
416                ("shutdown", _) => {
417                    shutdown = true;
418                    break;
419                }
420                ("node.cancel", None) => {
421                    let request_id = params.get("request_id").and_then(Value::as_str).unwrap_or_default();
422                    if let Some(r) = running.lock().ok().and_then(|mut m| m.remove(request_id)) {
423                        r.cancelled.store(true, Ordering::SeqCst);
424                        r.notify.notify_waiters();
425                        r.task.abort();
426                    }
427                }
428                (_, None) => {}
429                ("initialize", Some(id)) => {
430                    let mut result = Map::new();
431                    result.insert("protocol_version".into(), json!(PROTOCOL_VERSION));
432                    result.insert("name".into(), json!(plugin.name));
433                    if !plugin.descriptors.is_empty() {
434                        result.insert("nodes".into(), Value::Array(plugin.descriptors.clone()));
435                    }
436                    if !plugin.tool_specs.is_empty() {
437                        result.insert("tools".into(), Value::Array(plugin.tool_specs.clone()));
438                    }
439                    let result = Value::Object(result);
440                    send(&out_tx, ok_response(&id, result));
441                }
442                ("node.run", Some(id)) => plugin.start_run(id, params, &out_tx, &running),
443                ("tool.list", Some(id)) => {
444                    send(&out_tx, ok_response(&id, json!({"tools": plugin.tool_specs})));
445                }
446                ("tool.call", Some(id)) => plugin.start_tool(id, params, &out_tx),
447                (other, Some(id)) => {
448                    send(&out_tx, error_response(&id, -32601, &format!("method `{other}` not found"), None));
449                }
450            }
451        }
452        // `shutdown` stops in-flight work; end of input lets it finish and reply.
453        let in_flight: Vec<Running> =
454            running.lock().map(|mut m| m.drain().map(|(_, r)| r).collect()).unwrap_or_default();
455        for r in in_flight {
456            if shutdown {
457                r.task.abort();
458            } else {
459                let _finished_or_aborted = r.task.await;
460            }
461        }
462        // Tool tasks hold their own sender, so the writer drains until they finish.
463        drop(out_tx);
464        let _writer_done = writer_task.await;
465        Ok(())
466    }
467
468    fn start_run(
469        &self,
470        id: Value,
471        params: Value,
472        out: &mpsc::UnboundedSender<String>,
473        running: &Arc<Mutex<HashMap<String, Running>>>,
474    ) {
475        let request_id =
476            params.get("request_id").and_then(Value::as_str).map(str::to_owned).unwrap_or_else(|| id_text(&id));
477        let kind = params.get("kind").and_then(Value::as_str).unwrap_or_default().to_owned();
478        let Some(handler) = self.nodes.get(&kind).cloned() else {
479            let msg = format!("plugin `{}` has no node kind `{kind}`", self.name);
480            send(out, error_response(&id, -32602, &msg, Some(json!({"kind": "unknown_kind"}))));
481            return;
482        };
483        let resume = params.get("resume").filter(|r| !r.is_null()).map(|r| Resume {
484            state: r.get("state").cloned().unwrap_or(Value::Null),
485            input: r.get("input").cloned().unwrap_or(Value::Null),
486        });
487        let req = RunRequest {
488            request_id: request_id.clone(),
489            kind,
490            node_id: params.get("node_id").and_then(Value::as_str).unwrap_or_default().to_owned(),
491            attempt: params.get("attempt").and_then(Value::as_u64).and_then(|a| u32::try_from(a).ok()).unwrap_or(1),
492            config: params.get("config").cloned().unwrap_or(Value::Object(Map::new())),
493            resume,
494        };
495        let cancelled = Arc::new(AtomicBool::new(false));
496        let notify = Arc::new(Notify::new());
497        let ctx = RunCtx {
498            request_id: request_id.clone(),
499            out: out.clone(),
500            cancelled: cancelled.clone(),
501            cancel_notify: notify.clone(),
502        };
503        let out = out.clone();
504        let registry = running.clone();
505        let rid = request_id.clone();
506        // Hold the registry lock while spawning so a fast task cannot finish (and try
507        // to deregister) before it is registered.
508        let Ok(mut map) = running.lock() else { return };
509        let task = tokio::spawn(async move {
510            // The handler runs in its own task so a panic becomes an error reply
511            // instead of a silent timeout on the host. Aborting this task (cancel)
512            // aborts the handler too.
513            let inner = AbortOnDrop(tokio::spawn(handler(ctx, req)));
514            let line = match join_handler(inner).await {
515                Some(Ok(Outcome::Done(r))) => encode_result(&id, &r),
516                Some(Ok(Outcome::Pause { kind, data, state })) => {
517                    ok_response(&id, json!({"pause": {"kind": kind, "data": data, "state": state}}))
518                }
519                Some(Err(e)) => plugin_error_response(&id, &e),
520                None => {
521                    // Cancelled: the host abandoned the request.
522                    if let Ok(mut m) = registry.lock() {
523                        m.remove(&rid);
524                    }
525                    return;
526                }
527            };
528            send(&out, line);
529            if let Ok(mut m) = registry.lock() {
530                m.remove(&rid);
531            }
532        });
533        map.insert(request_id, Running { task, cancelled, notify });
534    }
535
536    fn start_tool(&self, id: Value, params: Value, out: &mpsc::UnboundedSender<String>) {
537        let name = params.get("name").and_then(Value::as_str).unwrap_or_default().to_owned();
538        let Some(handler) = self.tools.get(&name).cloned() else {
539            let msg = format!("plugin `{}` has no tool `{name}`", self.name);
540            send(out, error_response(&id, -32602, &msg, Some(json!({"kind": "unknown_tool"}))));
541            return;
542        };
543        let call = ToolCall { name, arguments: params.get("arguments").cloned().unwrap_or(Value::Null) };
544        let out = out.clone();
545        tokio::spawn(async move {
546            let inner = AbortOnDrop(tokio::spawn(handler(call)));
547            let line = match join_handler(inner).await {
548                Some(Ok(r)) => encode_result(&id, &r),
549                Some(Err(e)) => plugin_error_response(&id, &e),
550                None => return,
551            };
552            send(&out, line);
553        });
554    }
555}
556
557/// Aborts the wrapped task when dropped (so cancelling the outer task stops the handler).
558struct AbortOnDrop<T>(tokio::task::JoinHandle<T>);
559
560impl<T> Drop for AbortOnDrop<T> {
561    fn drop(&mut self) {
562        self.0.abort();
563    }
564}
565
566/// Wait for a handler task. A panic becomes a `plugin_panic` error; `None` means
567/// the task was cancelled.
568async fn join_handler<T>(mut task: AbortOnDrop<Result<T, PluginError>>) -> Option<Result<T, PluginError>> {
569    match (&mut task.0).await {
570        Ok(result) => Some(result),
571        Err(e) if e.is_panic() => {
572            let payload = e.into_panic();
573            let message = payload
574                .downcast_ref::<&str>()
575                .map(|s| (*s).to_owned())
576                .or_else(|| payload.downcast_ref::<String>().cloned())
577                .unwrap_or_else(|| "unknown panic".to_owned());
578            eprintln!("graphrt plugin handler panicked: {message}");
579            Some(Err(PluginError::new("plugin_panic", format!("handler panicked: {message}"))))
580        }
581        Err(_) => None,
582    }
583}
584
585/// Serialize a handler result, replying with an error when it cannot be encoded
586/// (never a `null` result the host would mistake for success).
587fn encode_result<T: Serialize>(id: &Value, result: &T) -> String {
588    match serde_json::to_value(result) {
589        Ok(value) => ok_response(id, value),
590        Err(e) => error_response(
591            id,
592            -32000,
593            &format!("result is not valid JSON: {e}"),
594            Some(json!({"kind": "invalid_output"})),
595        ),
596    }
597}
598
599/// Best-effort request id from the start of a line that could not be read.
600fn recover_id(line: &[u8]) -> Value {
601    let head = String::from_utf8_lossy(line.get(..line.len().min(4096)).unwrap_or_default()).into_owned();
602    let Some(pos) = head.find("\"id\"") else { return Value::Null };
603    let rest = head.get(pos + 4..).unwrap_or_default().trim_start();
604    let Some(rest) = rest.strip_prefix(':') else { return Value::Null };
605    let rest = rest.trim_start();
606    // A string id or an integer id.
607    if let Some(body) = rest.strip_prefix('"') {
608        let mut out = String::new();
609        let mut escaped = false;
610        for c in body.chars() {
611            match (escaped, c) {
612                (true, c) => {
613                    out.push(c);
614                    escaped = false;
615                }
616                (false, '\\') => escaped = true,
617                (false, '"') => return Value::String(out),
618                (false, c) => out.push(c),
619            }
620        }
621        return Value::Null;
622    }
623    let digits: String = rest.chars().take_while(|c| c.is_ascii_digit() || *c == '-').collect();
624    digits.parse::<i64>().map(Value::from).unwrap_or(Value::Null)
625}
626
627struct Running {
628    task: tokio::task::JoinHandle<()>,
629    cancelled: Arc<AtomicBool>,
630    notify: Arc<Notify>,
631}
632
633fn id_text(id: &Value) -> String {
634    match id {
635        Value::String(s) => s.clone(),
636        other => other.to_string(),
637    }
638}
639
640fn send(out: &mpsc::UnboundedSender<String>, line: String) {
641    let _host_gone = out.send(line);
642}
643
644fn ok_response(id: &Value, result: Value) -> String {
645    json!({"jsonrpc": "2.0", "id": id, "result": result}).to_string()
646}
647
648fn error_response(id: &Value, code: i64, message: &str, data: Option<Value>) -> String {
649    let mut error = Map::new();
650    error.insert("code".into(), json!(code));
651    error.insert("message".into(), json!(message));
652    if let Some(data) = data {
653        error.insert("data".into(), data);
654    }
655    json!({"jsonrpc": "2.0", "id": id, "error": Value::Object(error)}).to_string()
656}
657
658fn plugin_error_response(id: &Value, e: &PluginError) -> String {
659    let mut data = Map::new();
660    data.insert("kind".into(), json!(e.kind));
661    data.insert("retryable".into(), json!(e.retryable));
662    if let Some(ms) = e.retry_after_ms {
663        data.insert("retry_after_ms".into(), json!(ms));
664    }
665    error_response(id, -32000, &e.message, Some(Value::Object(data)))
666}
667
668/// Result of reading one line.
669enum Line {
670    Complete,
671    /// Longer than the limit: the rest of the line was discarded, `buf` holds its start.
672    Oversized,
673    Eof,
674}
675
676/// Read one `\n`-terminated line. Lines above `max` bytes are skipped up to their
677/// newline (keeping the stream in sync) and reported as [`Line::Oversized`].
678async fn read_line_capped<R: tokio::io::AsyncBufRead + Unpin>(
679    reader: &mut R,
680    buf: &mut Vec<u8>,
681    max: usize,
682) -> std::io::Result<Line> {
683    let mut oversized = false;
684    loop {
685        let available = reader.fill_buf().await?;
686        if available.is_empty() {
687            return Ok(match (buf.is_empty(), oversized) {
688                (_, true) => Line::Oversized,
689                (true, false) => Line::Eof,
690                (false, false) => Line::Complete,
691            });
692        }
693        let (chunk, done) = match available.iter().position(|b| *b == b'\n') {
694            Some(pos) => (available.get(..=pos).unwrap_or(available), true),
695            None => (available, false),
696        };
697        if !oversized && buf.len().saturating_add(chunk.len()) > max {
698            oversized = true;
699            // Keep the head (for recovering the request id), drop the rest.
700            let room = 4096usize.saturating_sub(buf.len());
701            buf.extend_from_slice(chunk.get(..room.min(chunk.len())).unwrap_or_default());
702        } else if !oversized {
703            buf.extend_from_slice(chunk);
704        }
705        let used = chunk.len();
706        reader.consume(used);
707        if done {
708            return Ok(if oversized { Line::Oversized } else { Line::Complete });
709        }
710    }
711}
712
713#[cfg(test)]
714mod tests {
715    use super::*;
716
717    async fn roundtrip(plugin: Plugin, input: &str) -> Vec<Value> {
718        let (client, server) = tokio::io::duplex(1 << 16);
719        let (server_r, server_w) = tokio::io::split(server);
720        let serve = tokio::spawn(plugin.serve(server_r, server_w));
721        let (client_r, mut client_w) = tokio::io::split(client);
722        client_w.write_all(input.as_bytes()).await.unwrap();
723        client_w.shutdown().await.unwrap();
724        let mut out = String::new();
725        let mut reader = BufReader::new(client_r);
726        let mut line = String::new();
727        while reader.read_line(&mut line).await.unwrap() > 0 {
728            out.push_str(&line);
729            line.clear();
730        }
731        serve.await.unwrap().unwrap();
732        out.lines().map(|l| serde_json::from_str(l).unwrap()).collect()
733    }
734
735    #[tokio::test]
736    async fn handles_initialize_run_and_errors() {
737        let plugin = Plugin::new("t")
738            .node("t.echo", |ctx, req| async move {
739                ctx.chunk("text", "hi");
740                Ok(RunResult::new().output("echo", req.config["x"].clone()))
741            })
742            .node("t.fail", |_ctx, _req| async move {
743                Err::<RunResult, _>(PluginError::retryable("busy", "try later").retry_after(5))
744            })
745            .node("t.pause", |_ctx, req| async move {
746                match req.resume {
747                    None => Ok(Outcome::pause("approval", json!({"q": "ok?"}), json!({"step": 1}))),
748                    Some(r) => Ok(RunResult::new().output("state", r.state).output("input", r.input).into()),
749                }
750            })
751            .tool(json!({"name": "add", "description": "", "parameters": {}}), |call| async move {
752                let a = call.arguments["a"].as_i64().unwrap_or(0);
753                Ok(ToolResult::text(format!("{}", a + 1)))
754            });
755        let input = [
756            r#"{"jsonrpc":"2.0","id":"i","method":"initialize","params":{}}"#,
757            r#"{"jsonrpc":"2.0","id":"r-1","method":"node.run","params":{"request_id":"r-1","kind":"t.echo","config":{"x":5}}}"#,
758            r#"{"jsonrpc":"2.0","id":"r-2","method":"node.run","params":{"request_id":"r-2","kind":"t.fail","config":{}}}"#,
759            r#"{"jsonrpc":"2.0","id":"r-3","method":"node.run","params":{"request_id":"r-3","kind":"t.nope","config":{}}}"#,
760            r#"{"jsonrpc":"2.0","id":"r-4","method":"node.run","params":{"request_id":"r-4","kind":"t.pause","config":{}}}"#,
761            r#"{"jsonrpc":"2.0","id":"r-5","method":"node.run","params":{"request_id":"r-5","kind":"t.pause","config":{},"resume":{"state":{"step":1},"input":"yes"}}}"#,
762            r#"{"jsonrpc":"2.0","id":"t-1","method":"tool.call","params":{"name":"add","arguments":{"a":41}}}"#,
763            r#"{"jsonrpc":"2.0","id":"x","method":"bogus"}"#,
764            "",
765        ]
766        .join("\n");
767        // Give spawned handlers time to answer before stdin closes the loop.
768        let msgs = tokio::time::timeout(std::time::Duration::from_secs(5), async {
769            let plugin = plugin;
770            roundtrip_wait(plugin, &input).await
771        })
772        .await
773        .unwrap();
774        let by_id = |id: &str| msgs.iter().find(|m| m["id"] == id).cloned().unwrap_or_default();
775        assert_eq!(by_id("i")["result"]["protocol_version"], 1);
776        assert_eq!(by_id("i")["result"]["tools"][0]["name"], "add");
777        assert_eq!(by_id("r-1")["result"]["outputs"]["echo"], 5);
778        assert!(msgs.iter().any(|m| m["method"] == "node.chunk" && m["params"]["request_id"] == "r-1"));
779        assert_eq!(by_id("r-2")["error"]["data"]["retryable"], true);
780        assert_eq!(by_id("r-2")["error"]["data"]["retry_after_ms"], 5);
781        assert_eq!(by_id("r-3")["error"]["code"], -32602);
782        assert_eq!(by_id("r-4")["result"]["pause"]["state"]["step"], 1);
783        assert_eq!(by_id("r-5")["result"]["outputs"]["input"], "yes");
784        assert_eq!(by_id("t-1")["result"]["text"], "42");
785        assert_eq!(by_id("x")["error"]["code"], -32601);
786    }
787
788    /// Like [`roundtrip`], but keeps stdin open until every request is answered.
789    async fn roundtrip_wait(plugin: Plugin, input: &str) -> Vec<Value> {
790        let expected = input.lines().filter(|l| l.contains("\"id\"")).count();
791        let (client, server) = tokio::io::duplex(1 << 16);
792        let (server_r, server_w) = tokio::io::split(server);
793        let serve = tokio::spawn(plugin.serve(server_r, server_w));
794        let (client_r, mut client_w) = tokio::io::split(client);
795        client_w.write_all(input.as_bytes()).await.unwrap();
796        let mut reader = BufReader::new(client_r);
797        let mut msgs = Vec::new();
798        let mut responses = 0;
799        let mut line = String::new();
800        while responses < expected {
801            line.clear();
802            if reader.read_line(&mut line).await.unwrap() == 0 {
803                break;
804            }
805            let v: Value = serde_json::from_str(line.trim()).unwrap();
806            if v.get("id").is_some() {
807                responses += 1;
808            }
809            msgs.push(v);
810        }
811        client_w.shutdown().await.unwrap();
812        serve.await.unwrap().unwrap();
813        msgs
814    }
815
816    #[tokio::test]
817    async fn shutdown_and_eof_end_the_loop() {
818        let msgs = roundtrip(Plugin::new("t"), "{\"jsonrpc\":\"2.0\",\"method\":\"shutdown\"}\n").await;
819        assert!(msgs.is_empty());
820        let msgs = roundtrip(Plugin::new("t"), "not json\n").await;
821        assert_eq!(msgs[0]["error"]["code"], -32700);
822    }
823
824    #[tokio::test]
825    async fn cancel_aborts_the_handler() {
826        let plugin = Plugin::new("t").node("t.slow", |ctx, _req| async move {
827            ctx.cancelled().await;
828            Ok(RunResult::new())
829        });
830        let (client, server) = tokio::io::duplex(1 << 16);
831        let (server_r, server_w) = tokio::io::split(server);
832        let serve = tokio::spawn(plugin.serve(server_r, server_w));
833        let (client_r, mut client_w) = tokio::io::split(client);
834        let run = r#"{"jsonrpc":"2.0","id":"r-1","method":"node.run","params":{"request_id":"r-1","kind":"t.slow","config":{}}}"#;
835        let cancel = r#"{"jsonrpc":"2.0","method":"node.cancel","params":{"request_id":"r-1"}}"#;
836        client_w.write_all(format!("{run}\n{cancel}\n").as_bytes()).await.unwrap();
837        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
838        client_w.shutdown().await.unwrap();
839        tokio::time::timeout(std::time::Duration::from_secs(2), serve).await.unwrap().unwrap().unwrap();
840        let mut rest = String::new();
841        let mut reader = BufReader::new(client_r);
842        let mut line = String::new();
843        while reader.read_line(&mut line).await.unwrap() > 0 {
844            rest.push_str(&line);
845            line.clear();
846        }
847        // A cancelled request gets no response.
848        assert!(!rest.contains("\"r-1\""), "{rest}");
849    }
850
851    #[tokio::test]
852    async fn panicking_handler_replies_with_an_error() {
853        let plugin = Plugin::new("t").node("t.panic", |_ctx, _req| async move {
854            if true {
855                panic!("kaboom");
856            }
857            Ok(RunResult::new())
858        });
859        let run = r#"{"jsonrpc":"2.0","id":"r-1","method":"node.run","params":{"request_id":"r-1","kind":"t.panic","config":{}}}"#;
860        let msgs = roundtrip(plugin, &format!("{run}\n")).await;
861        assert_eq!(msgs.len(), 1, "{msgs:?}");
862        assert_eq!(msgs[0]["id"], "r-1");
863        assert_eq!(msgs[0]["error"]["data"]["kind"], "plugin_panic");
864        assert!(msgs[0]["error"]["message"].as_str().unwrap().contains("kaboom"));
865    }
866
867    #[tokio::test]
868    async fn oversized_message_is_answered_and_stream_stays_in_sync() {
869        let plugin = Plugin::new("t").node("t.ok", |_ctx, _req| async move { Ok(RunResult::new().output("ok", true)) });
870        // The host announces a small limit, then sends a line above it, then a normal request.
871        let init = r#"{"jsonrpc":"2.0","id":"i","method":"initialize","params":{"max_message_bytes":2048}}"#;
872        let big = format!(
873            r#"{{"jsonrpc":"2.0","id":"r-big","method":"node.run","params":{{"kind":"t.ok","config":{{"x":"{}"}}}}}}"#,
874            "y".repeat(5000)
875        );
876        let ok = r#"{"jsonrpc":"2.0","id":"r-2","method":"node.run","params":{"request_id":"r-2","kind":"t.ok","config":{}}}"#;
877        let msgs = roundtrip(plugin, &format!("{init}\n{big}\n{ok}\n")).await;
878        let big_reply = msgs.iter().find(|m| m["id"] == "r-big").expect("reply to oversized request");
879        assert_eq!(big_reply["error"]["data"]["kind"], "message_too_large");
880        let ok_reply = msgs.iter().find(|m| m["id"] == "r-2").expect("later request still served");
881        assert_eq!(ok_reply["result"]["outputs"]["ok"], true);
882    }
883}