Skip to main content

muse_code_sdk/
connection.rs

1//! MSP NDJSON framing and request matching.
2
3mod dispatch;
4mod driver;
5mod error;
6mod framing;
7mod handshake;
8mod matching;
9mod stdio;
10#[cfg(test)]
11mod tests;
12
13use std::collections::{HashMap, HashSet, VecDeque};
14use std::sync::atomic::{AtomicI64, AtomicU64, Ordering};
15use std::sync::{Arc, Mutex, MutexGuard};
16
17use tokio::sync::{OwnedSemaphorePermit, Semaphore, broadcast, mpsc, oneshot, watch};
18
19use crate::DuplexTransport;
20use crate::msp::{JsonRpcVersion, Notification, Request, RequestId};
21
22pub use driver::ConnectionDriver;
23pub use error::ConnectionError;
24
25pub use crate::errors::{MspError, ProtocolError};
26
27#[cfg(test)]
28use stdio::PipeTransport;
29pub use stdio::StdioTransport;
30
31const OUTBOUND_CAPACITY: usize = 64;
32const PROTOCOL_ERROR_CAPACITY: usize = 32;
33const NOTIFICATION_CAPACITY: usize = 64;
34// Bounds live notifications waiting to be routed. The client router's pending
35// total (`MAX_PENDING_NOTIFICATIONS_TOTAL`) covers only sessions that have not
36// registered yet and is this same constant.
37pub(crate) const NOTIFICATION_HANDLER_CAPACITY: usize = 1_024;
38// Under contention, a session holding this many handoff permits gets no new
39// one. The client router's per-session pending bound
40// (`MAX_PENDING_NOTIFICATIONS_PER_SESSION`) is this same constant.
41pub(crate) const NOTIFICATION_SESSION_SHARE: usize = 256;
42// Every queued item keeps its normal permit or per-session overflow marker
43// while it is in the channel, so the channel holds at most the handler
44// capacity in normal notifications, the same number of overflow markers, and
45// one FIFO slot for the global (saturated) marker. A send that holds its permit
46// or marker therefore never finds it full (`debug_assert_dispatch_capacity`).
47const NOTIFICATION_DISPATCH_CAPACITY: usize = NOTIFICATION_HANDLER_CAPACITY * 2 + 1;
48
49type RequestResult = Result<serde_json::Map<String, serde_json::Value>, ConnectionError>;
50
51struct OutboundRequest {
52    id: RequestId,
53    frame: String,
54    response: oneshot::Sender<RequestResult>,
55}
56
57enum OutboundMessage {
58    Request(OutboundRequest),
59    Notification {
60        frame: String,
61        submitted: oneshot::Sender<Result<(), ConnectionError>>,
62    },
63}
64
65type NotificationHandler = Arc<dyn Fn(Notification) + Send + Sync>;
66
67enum NotificationDispatchItem {
68    Notification {
69        notification: Notification,
70        permit: SessionPermit,
71    },
72    Overflow {
73        notification: Notification,
74        marker: OverflowMarker,
75    },
76}
77
78// Handoff permits held per session. A session has an entry
79// only while it holds at least one permit.
80type SessionPermits = Arc<Mutex<HashMap<String, usize>>>;
81
82// One handoff permit, counted against its frame's session if it has one.
83// Dropping it releases both.
84struct SessionPermit {
85    session: Option<(String, SessionPermits)>,
86    _permit: OwnedSemaphorePermit,
87}
88
89enum OverflowMarker {
90    Session(String),
91    Saturated,
92}
93
94#[derive(Default)]
95struct SaturatedOverflow {
96    queued: bool,
97    sessions: HashSet<String>,
98    pending: VecDeque<Notification>,
99    // The frame refused at the cap; reported after the accepted drain.
100    refused: Option<Notification>,
101}
102
103pub(super) struct NotificationDispatch {
104    queue: mpsc::Sender<NotificationDispatchItem>,
105    // Notifications queued for the handler, counted after each send; overflow
106    // markers are not counted.
107    accepted: Arc<AtomicU64>,
108    notification_capacity: Arc<Semaphore>,
109    session_permits: SessionPermits,
110    queued_overflows: Arc<Mutex<HashSet<String>>>,
111    saturated_overflow: Arc<Mutex<SaturatedOverflow>>,
112}
113
114pub(crate) struct NotificationDispatcher {
115    queue: mpsc::Receiver<NotificationDispatchItem>,
116    // Counted notifications the handler has finished, in queue order.
117    applied: watch::Sender<u64>,
118    handler: NotificationHandler,
119    overflow: NotificationHandler,
120    queued_overflows: Arc<Mutex<HashSet<String>>>,
121    saturated_overflow: Arc<Mutex<SaturatedOverflow>>,
122    closed: watch::Sender<bool>,
123}
124
125fn notification_session_id(notification: &Notification) -> Option<&str> {
126    notification
127        .params
128        .as_ref()
129        .and_then(|params| params.get("sessionId"))
130        .and_then(serde_json::Value::as_str)
131}
132
133fn lock_notification_overflows(queued: &Mutex<HashSet<String>>) -> MutexGuard<'_, HashSet<String>> {
134    match queued.lock() {
135        Ok(queued) => queued,
136        Err(poisoned) => poisoned.into_inner(),
137    }
138}
139
140fn lock_session_permits(
141    held: &Mutex<HashMap<String, usize>>,
142) -> MutexGuard<'_, HashMap<String, usize>> {
143    match held.lock() {
144        Ok(held) => held,
145        Err(poisoned) => poisoned.into_inner(),
146    }
147}
148
149fn lock_saturated_overflow(
150    saturated: &Mutex<SaturatedOverflow>,
151) -> MutexGuard<'_, SaturatedOverflow> {
152    match saturated.lock() {
153        Ok(saturated) => saturated,
154        Err(poisoned) => poisoned.into_inner(),
155    }
156}
157
158/// Cloneable request handle for one MSP transport.
159///
160/// [`Connection::new`] also returns a [`ConnectionDriver`]. The caller drives
161/// that future on its own executor; this crate never creates or blocks an async
162/// runtime.
163#[derive(Clone)]
164pub struct Connection {
165    outbound: mpsc::Sender<OutboundMessage>,
166    handoff: Option<NotificationHandoff>,
167    notifications: broadcast::Sender<Notification>,
168    protocol_errors: broadcast::Sender<ProtocolError>,
169    shutdown: watch::Sender<bool>,
170    closed: watch::Receiver<bool>,
171    next_request_id: Arc<AtomicI64>,
172}
173
174impl Connection {
175    /// Builds a request handle and its caller-driven transport loop.
176    #[must_use]
177    pub fn new<T>(transport: T) -> (Self, ConnectionDriver<T>)
178    where
179        T: DuplexTransport,
180    {
181        Self::build(transport, None)
182    }
183
184    pub(crate) fn with_notification_handler<T, F, G>(
185        transport: T,
186        handler: F,
187        overflow: G,
188    ) -> (Self, ConnectionDriver<T>, NotificationDispatcher)
189    where
190        T: DuplexTransport,
191        F: Fn(Notification) + Send + Sync + 'static,
192        G: Fn(Notification) + Send + Sync + 'static,
193    {
194        let handler: NotificationHandler = Arc::new(handler);
195        let overflow: NotificationHandler = Arc::new(overflow);
196        let queued_overflows = Arc::new(Mutex::new(HashSet::new()));
197        let saturated_overflow = Arc::new(Mutex::new(SaturatedOverflow::default()));
198        let (notification_queue, notifications) = mpsc::channel(NOTIFICATION_DISPATCH_CAPACITY);
199        let accepted = Arc::new(AtomicU64::new(0));
200        let (applied, applied_watch) = watch::channel(0);
201        let dispatch = NotificationDispatch {
202            queue: notification_queue,
203            accepted: Arc::clone(&accepted),
204            notification_capacity: Arc::new(Semaphore::new(NOTIFICATION_HANDLER_CAPACITY)),
205            session_permits: SessionPermits::default(),
206            queued_overflows: Arc::clone(&queued_overflows),
207            saturated_overflow: Arc::clone(&saturated_overflow),
208        };
209        let (mut connection, driver) = Self::build(transport, Some(dispatch));
210        connection.handoff = Some(NotificationHandoff {
211            accepted,
212            applied: applied_watch,
213        });
214        let closed = driver.closed_sender();
215        (
216            connection,
217            driver,
218            NotificationDispatcher {
219                queue: notifications,
220                applied,
221                handler,
222                overflow,
223                queued_overflows,
224                saturated_overflow,
225                closed,
226            },
227        )
228    }
229
230    fn build<T>(
231        transport: T,
232        notification_dispatch: Option<NotificationDispatch>,
233    ) -> (Self, ConnectionDriver<T>)
234    where
235        T: DuplexTransport,
236    {
237        let (outbound, outbound_rx) = mpsc::channel(OUTBOUND_CAPACITY);
238        let (notifications, _) = broadcast::channel(NOTIFICATION_CAPACITY);
239        let (protocol_errors, _) = broadcast::channel(PROTOCOL_ERROR_CAPACITY);
240        let (shutdown, shutdown_rx) = watch::channel(false);
241        let (closed_tx, closed) = watch::channel(false);
242        (
243            Self {
244                outbound,
245                handoff: None,
246                notifications: notifications.clone(),
247                protocol_errors: protocol_errors.clone(),
248                shutdown,
249                closed,
250                next_request_id: Arc::new(AtomicI64::new(1)),
251            },
252            ConnectionDriver::new(
253                transport,
254                outbound_rx,
255                notifications,
256                notification_dispatch,
257                protocol_errors,
258                shutdown_rx,
259                closed_tx,
260            ),
261        )
262    }
263
264    /// Sends one request and waits for the response carrying the same id.
265    ///
266    /// A successful transport write means only that the frame was submitted.
267    /// This future remains pending until the matching result or error arrives.
268    pub async fn request(
269        &self,
270        method: impl Into<String>,
271        params: Option<serde_json::Map<String, serde_json::Value>>,
272    ) -> RequestResult {
273        if *self.shutdown.borrow() {
274            return Err(ConnectionError::Closed);
275        }
276        let id = RequestId::Integer(self.next_request_id.fetch_add(1, Ordering::Relaxed));
277        let request = Request {
278            jsonrpc: JsonRpcVersion::V2,
279            id: id.clone(),
280            method: method.into(),
281            params,
282            trace: None,
283        };
284        let mut frame = serde_json::to_string(&request).map_err(|error| {
285            ConnectionError::Protocol(ProtocolError::new(
286                format!("request could not be encoded: {error}"),
287                None,
288            ))
289        })?;
290        frame.push('\n');
291        let (response, receiver) = oneshot::channel();
292        self.outbound
293            .send(OutboundMessage::Request(OutboundRequest {
294                id,
295                frame,
296                response,
297            }))
298            .await
299            .map_err(|_| ConnectionError::Closed)?;
300        receiver.await.unwrap_or(Err(ConnectionError::Closed))
301    }
302
303    /// Submits one fire-and-forget notification to the transport.
304    pub async fn notify(
305        &self,
306        method: impl Into<String>,
307        params: Option<serde_json::Map<String, serde_json::Value>>,
308    ) -> Result<(), ConnectionError> {
309        if *self.shutdown.borrow() {
310            return Err(ConnectionError::Closed);
311        }
312        let notification = Notification {
313            jsonrpc: JsonRpcVersion::V2,
314            method: method.into(),
315            params,
316            emitted_at_ms: None,
317        };
318        let mut frame = serde_json::to_string(&notification).map_err(|error| {
319            ConnectionError::Protocol(ProtocolError::new(
320                format!("notification could not be encoded: {error}"),
321                None,
322            ))
323        })?;
324        frame.push('\n');
325        let (submitted, submitted_rx) = oneshot::channel();
326        self.outbound
327            .send(OutboundMessage::Notification { frame, submitted })
328            .await
329            .map_err(|_| ConnectionError::Closed)?;
330        submitted_rx.await.unwrap_or(Err(ConnectionError::Closed))
331    }
332
333    /// Stops the transport loop without waiting for peer-side completion.
334    pub async fn close(&self) {
335        self.shutdown.send_replace(true);
336    }
337
338    /// Subscribes to server notifications received after subscription.
339    #[must_use]
340    pub fn subscribe_notifications(&self) -> broadcast::Receiver<Notification> {
341        self.notifications.subscribe()
342    }
343
344    /// Subscribes to non-fatal framing and correlation errors.
345    #[must_use]
346    pub fn subscribe_protocol_errors(&self) -> broadcast::Receiver<ProtocolError> {
347        self.protocol_errors.subscribe()
348    }
349
350    pub(crate) fn subscribe_closed(&self) -> watch::Receiver<bool> {
351        self.closed.clone()
352    }
353
354    /// Returns once the notification handler has finished every notification
355    /// queued for it before the call, or once its dispatcher is gone. A caller
356    /// that saw a response first therefore finds every notification that
357    /// preceded it on the wire handed to the handler; overflow markers are
358    /// not counted. A connection with no notification handler returns at
359    /// once.
360    pub(crate) async fn notifications_received_applied(&self) {
361        let Some(handoff) = &self.handoff else {
362            return;
363        };
364        let accepted = handoff.accepted.load(Ordering::Acquire);
365        let mut applied = handoff.applied.clone();
366        // An error means the dispatcher dropped its sender: nothing more is
367        // applied, so there is nothing left to wait for.
368        let _ = applied.wait_for(|applied| *applied >= accepted).await;
369    }
370}
371
372/// The notification handoff's progress, read by callers that must order
373/// themselves after the notifications already received.
374#[derive(Clone)]
375struct NotificationHandoff {
376    accepted: Arc<AtomicU64>,
377    applied: watch::Receiver<u64>,
378}