Skip to main content

agent_client_protocol/jsonrpc/
run.rs

1//! Run trait for background tasks that run alongside a connection.
2//!
3//! Run implementations are composable background tasks that run while a connection is active.
4//! They're used for things like MCP tool handlers that need to receive calls through
5//! channels and invoke user-provided closures.
6
7use std::future::Future;
8use std::marker::PhantomData;
9use std::sync::{Arc, Mutex};
10
11use futures::FutureExt;
12use futures::future::{Either, select};
13
14use crate::{
15    ConnectionTo,
16    jsonrpc::{Protocol, protocol},
17    role::Role,
18};
19
20/// Cleanup policy installed by the boundary that owns a runner composition.
21/// The first error is visible even while a chain retains its sibling for cleanup.
22#[derive(Clone)]
23pub(crate) struct RunnerErrorScope {
24    error: Arc<Mutex<Option<crate::Error>>>,
25    close: Arc<dyn Fn() + Send + Sync>,
26    cleanup: futures::future::Shared<futures::future::BoxFuture<'static, ()>>,
27}
28
29impl std::fmt::Debug for RunnerErrorScope {
30    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
31        formatter
32            .debug_struct("RunnerErrorScope")
33            .finish_non_exhaustive()
34    }
35}
36
37impl RunnerErrorScope {
38    pub(crate) fn new(
39        close: impl Fn() + Send + Sync + 'static,
40        cleanup: impl Future<Output = ()> + Send + 'static,
41    ) -> Self {
42        Self {
43            error: Arc::default(),
44            close: Arc::new(close),
45            cleanup: cleanup.boxed().shared(),
46        }
47    }
48
49    pub(crate) fn error(&self) -> Option<crate::Error> {
50        self.error
51            .lock()
52            .expect("runner error mutex poisoned")
53            .clone()
54    }
55
56    pub(crate) fn finish(
57        &self,
58        error: crate::Error,
59    ) -> futures::future::Shared<futures::future::BoxFuture<'static, ()>> {
60        let first_error = {
61            let mut stored = self.error.lock().expect("runner error mutex poisoned");
62            if stored.is_none() {
63                *stored = Some(error);
64                true
65            } else {
66                false
67            }
68        };
69        if first_error {
70            (self.close)();
71        }
72        self.cleanup.clone()
73    }
74}
75
76/// A background task that runs alongside a connection.
77///
78/// The task receives a `ConnectionTo<Counterpart>` for communicating with the other side.
79///
80/// Implementations are composed using [`ChainRun`] and run in parallel
81/// when the connection is active.
82pub trait RunWithConnectionTo<Counterpart: Role>: Send {
83    /// Run this task to completion.
84    fn run_with_connection_to(
85        self,
86        cx: ConnectionTo<Counterpart>,
87    ) -> impl Future<Output = Result<(), crate::Error>> + Send;
88}
89
90/// A no-op runner that completes immediately.
91#[derive(Debug, Default)]
92pub struct NullRun;
93
94impl<Counterpart: Role> RunWithConnectionTo<Counterpart> for NullRun {
95    fn run_with_connection_to(
96        self,
97        _cx: ConnectionTo<Counterpart>,
98    ) -> impl Future<Output = Result<(), crate::Error>> + Send {
99        std::future::ready(Ok(()))
100    }
101}
102
103/// Runs two [`RunWithConnectionTo`] implementations in parallel.
104#[derive(Debug)]
105pub struct ChainRun<A, B> {
106    a: A,
107    b: B,
108}
109
110impl<A, B> ChainRun<A, B> {
111    /// Create a chain from two runners.
112    pub fn new(a: A, b: B) -> Self {
113        Self { a, b }
114    }
115}
116
117impl<Counterpart: Role, A, B> RunWithConnectionTo<Counterpart> for ChainRun<A, B>
118where
119    A: RunWithConnectionTo<Counterpart>,
120    B: RunWithConnectionTo<Counterpart>,
121{
122    async fn run_with_connection_to(
123        self,
124        cx: ConnectionTo<Counterpart>,
125    ) -> Result<(), crate::Error> {
126        // Box the futures to avoid stack overflow with deeply nested RunIn chains
127        let a_fut = Box::pin(self.a.run_with_connection_to(cx.clone()));
128        let b_fut = Box::pin(self.b.run_with_connection_to(cx.clone()));
129        match select(a_fut, b_fut).await {
130            Either::Left((Ok(()), b)) => b.await,
131            Either::Right((Ok(()), a)) => a.await,
132            Either::Left((Err(error), b)) => {
133                finish_runner_after_error(b, &cx, error.clone()).await;
134                Err(error)
135            }
136            Either::Right((Err(error), a)) => {
137                finish_runner_after_error(a, &cx, error.clone()).await;
138                Err(error)
139            }
140        }
141    }
142}
143
144async fn finish_runner_after_error<R: Role>(
145    runner: impl Future<Output = Result<(), crate::Error>>,
146    cx: &ConnectionTo<R>,
147    error: crate::Error,
148) {
149    // A sibling runner can own the actual scoped operation. Keep it polled
150    // through the owning boundary's cleanup, never arbitrary infinite user work.
151    match select(Box::pin(runner), Box::pin(cx.finish_runner_error(error))).await {
152        Either::Left((_, cleanup)) => cleanup.await,
153        Either::Right(((), _)) => {}
154    }
155}
156
157/// A runner created from a closure via [`with_spawned`](crate::Builder::with_spawned).
158pub struct SpawnedRun<F, P> {
159    task_fn: F,
160    location: &'static std::panic::Location<'static>,
161    protocol: PhantomData<fn() -> P>,
162}
163
164impl<F, P> SpawnedRun<F, P> {
165    /// Create a new spawned runner from a closure.
166    pub fn new(location: &'static std::panic::Location<'static>, task_fn: F) -> Self {
167        Self {
168            task_fn,
169            location,
170            protocol: PhantomData,
171        }
172    }
173}
174
175impl<Counterpart, F, Fut, P> RunWithConnectionTo<Counterpart> for SpawnedRun<F, P>
176where
177    Counterpart: Role,
178    P: Protocol,
179    F: FnOnce(P::Connection<Counterpart>) -> Fut + Send,
180    Fut: Future<Output = Result<(), crate::Error>> + Send,
181{
182    async fn run_with_connection_to(
183        self,
184        connection: ConnectionTo<Counterpart>,
185    ) -> Result<(), crate::Error> {
186        let location = self.location;
187        (self.task_fn)(protocol::connection_from_raw::<P, _>(connection))
188            .await
189            .map_err(|err| {
190                let data = err.data.clone();
191                err.data(serde_json::json!({
192                    "spawned_at": format!("{}:{}:{}", location.file(), location.line(), location.column()),
193                    "data": data,
194                }))
195            })
196    }
197}
198
199#[cfg(test)]
200mod tests {
201    use super::RunnerErrorScope;
202    use std::sync::{
203        Arc,
204        atomic::{AtomicUsize, Ordering},
205    };
206
207    #[test]
208    fn repeated_runner_errors_close_and_join_scope_once() {
209        let closes = Arc::new(AtomicUsize::new(0));
210        let joins = Arc::new(AtomicUsize::new(0));
211        let close_count = closes.clone();
212        let join_count = joins.clone();
213        let scope = RunnerErrorScope::new(
214            move || {
215                close_count.fetch_add(1, Ordering::SeqCst);
216            },
217            async move {
218                join_count.fetch_add(1, Ordering::SeqCst);
219            },
220        );
221        let first_error = crate::Error::invalid_params().data("first");
222        let first = scope.finish(first_error.clone());
223        let second = scope.clone().finish(crate::Error::internal_error());
224
225        assert_eq!(scope.error(), Some(first_error));
226        assert_eq!(closes.load(Ordering::SeqCst), 1);
227        futures::executor::block_on(futures::future::join(first, second));
228        assert_eq!(joins.load(Ordering::SeqCst), 1);
229    }
230}