1use 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
39pub const PROTOCOL_VERSION: u32 = 1;
41
42pub 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#[derive(Clone, Debug, PartialEq)]
51pub struct RunRequest {
52 pub request_id: String,
53 pub kind: String,
55 pub node_id: String,
57 pub attempt: u32,
59 pub config: Value,
61 pub resume: Option<Resume>,
63}
64
65#[derive(Clone, Debug, PartialEq)]
67pub struct Resume {
68 pub state: Value,
70 pub input: Value,
72}
73
74#[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 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 pub fn branch(mut self, handle: impl Into<String>) -> Self {
101 self.branch = Some(handle.into());
102 self
103 }
104
105 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 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 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#[derive(Clone, Debug, PartialEq)]
131pub enum Outcome {
132 Done(RunResult),
133 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 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#[derive(Clone, Debug, PartialEq)]
160pub struct PluginError {
161 pub kind: String,
163 pub message: String,
164 pub retryable: bool,
166 pub retry_after_ms: Option<u64>,
167}
168
169impl PluginError {
170 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 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 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#[derive(Clone, Debug, PartialEq)]
201pub struct ToolCall {
202 pub name: String,
203 pub arguments: Value,
204}
205
206#[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#[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 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 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 pub fn log(&self, level: &str, message: &str) {
263 self.notify("log", json!({"level": level, "message": message}));
264 }
265
266 pub fn is_cancelled(&self) -> bool {
268 self.cancelled.load(Ordering::SeqCst)
269 }
270
271 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#[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 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 pub fn describe(mut self, descriptor: Value) -> Self {
328 self.descriptors.push(descriptor);
329 self
330 }
331
332 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 pub async fn serve_stdio(self) -> std::io::Result<()> {
347 self.serve(tokio::io::stdin(), tokio::io::stdout()).await
348 }
349
350 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 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 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 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 let Ok(mut map) = running.lock() else { return };
509 let task = tokio::spawn(async move {
510 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 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
557struct 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
566async 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
585fn 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
599fn 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 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
668enum Line {
670 Complete,
671 Oversized,
673 Eof,
674}
675
676async 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 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 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 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 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 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}