Skip to main content

muse_code_sdk/connection/
driver.rs

1use std::collections::{HashMap, VecDeque};
2use std::future::poll_fn;
3use std::io;
4use std::task::Poll;
5
6use tokio::sync::{broadcast, mpsc, oneshot, watch};
7
8use crate::DuplexTransport;
9use crate::errors::ErrorCode;
10use crate::msp::{
11    ErrorData, ErrorObject, ErrorResponse, JsonRpcVersion, Notification, Request, RequestId,
12    SuccessResponse,
13};
14
15use super::framing::NdjsonDecoder;
16use super::matching::{DisplayRequestId, RequestKey};
17use super::{
18    ConnectionError, MspError, NotificationDispatch, OutboundMessage, ProtocolError, RequestResult,
19};
20
21pub(super) async fn write_or_shutdown<T>(
22    transport: &mut T,
23    frame: &str,
24    shutdown: &mut watch::Receiver<bool>,
25) -> Option<io::Result<()>>
26where
27    T: DuplexTransport,
28{
29    if *shutdown.borrow() {
30        return None;
31    }
32    tokio::select! {
33        biased;
34        _ = shutdown.changed() => None,
35        result = transport.write(frame) => Some(result),
36    }
37}
38
39/// The transport loop paired with a [`super::Connection`].
40pub struct ConnectionDriver<T> {
41    transport: T,
42    outbound: mpsc::Receiver<OutboundMessage>,
43    notifications: broadcast::Sender<Notification>,
44    notification_dispatch: Option<NotificationDispatch>,
45    protocol_errors: broadcast::Sender<ProtocolError>,
46    shutdown: watch::Receiver<bool>,
47    closed: watch::Sender<bool>,
48    pending: HashMap<RequestKey, oneshot::Sender<RequestResult>>,
49    decoder: NdjsonDecoder,
50    /// Answers to server-initiated requests from the chunk being handled,
51    /// written in arrival order before the next transport read.
52    server_request_replies: VecDeque<String>,
53}
54
55impl<T> ConnectionDriver<T>
56where
57    T: DuplexTransport,
58{
59    pub(super) fn new(
60        transport: T,
61        outbound: mpsc::Receiver<OutboundMessage>,
62        notifications: broadcast::Sender<Notification>,
63        notification_dispatch: Option<NotificationDispatch>,
64        protocol_errors: broadcast::Sender<ProtocolError>,
65        shutdown: watch::Receiver<bool>,
66        closed: watch::Sender<bool>,
67    ) -> Self {
68        Self {
69            transport,
70            outbound,
71            notifications,
72            notification_dispatch,
73            protocol_errors,
74            shutdown,
75            closed,
76            pending: HashMap::new(),
77            decoder: NdjsonDecoder::default(),
78            server_request_replies: VecDeque::new(),
79        }
80    }
81
82    pub(super) fn closed_sender(&self) -> watch::Sender<bool> {
83        self.closed.clone()
84    }
85
86    /// Runs until every request handle is dropped or the transport closes.
87    pub async fn run(mut self) {
88        let mut prefer_inbound = false;
89        let mut drain_notifications = false;
90        'driver: loop {
91            let event = next_driver_event(
92                &mut self.transport,
93                &mut self.outbound,
94                &mut self.shutdown,
95                prefer_inbound,
96            )
97            .await;
98            prefer_inbound = !prefer_inbound;
99            match event {
100                DriverEvent::Outbound(Some(OutboundMessage::Request(request))) => {
101                    let key = RequestKey::from(&request.id);
102                    self.pending.insert(key.clone(), request.response);
103                    match write_or_shutdown(&mut self.transport, &request.frame, &mut self.shutdown)
104                        .await
105                    {
106                        Some(Ok(())) => {}
107                        Some(Err(error)) => {
108                            self.fail_transport(error);
109                            break;
110                        }
111                        None => break,
112                    }
113                }
114                DriverEvent::Outbound(Some(OutboundMessage::Notification { frame, submitted })) => {
115                    match write_or_shutdown(&mut self.transport, &frame, &mut self.shutdown).await {
116                        Some(Ok(())) => {
117                            let _ = submitted.send(Ok(()));
118                        }
119                        Some(Err(error)) => {
120                            let kind = error.kind();
121                            let message = error.to_string();
122                            let _ = submitted.send(Err(ConnectionError::Transport(error)));
123                            self.fail_transport(io::Error::new(kind, message));
124                            break;
125                        }
126                        None => {
127                            let _ = submitted.send(Err(ConnectionError::Closed));
128                            break;
129                        }
130                    }
131                }
132                DriverEvent::Shutdown | DriverEvent::Outbound(None) => break,
133                DriverEvent::Inbound(Err(error)) => {
134                    self.fail_transport(error);
135                    break;
136                }
137                DriverEvent::Inbound(Ok(None)) => {
138                    if let Some(trailing_bytes) = self.decoder.truncated_frame_byte_len() {
139                        let error = ProtocolError::new(
140                            format!(
141                                "inbound stream ended with a truncated frame of {trailing_bytes} bytes"
142                            ),
143                            None,
144                        );
145                        self.fail_protocol(error.clone());
146                        self.report(error);
147                    }
148                    drain_notifications = true;
149                    break;
150                }
151                DriverEvent::Inbound(Ok(Some(chunk))) => {
152                    for line in self.decoder.push(&chunk) {
153                        if !self.handle_line(line) {
154                            drain_notifications = true;
155                            break 'driver;
156                        }
157                    }
158                    while let Some(reply) = self.server_request_replies.pop_front() {
159                        match write_or_shutdown(&mut self.transport, &reply, &mut self.shutdown)
160                            .await
161                        {
162                            Some(Ok(())) => {}
163                            Some(Err(error)) => {
164                                self.fail_transport(error);
165                                break 'driver;
166                            }
167                            None => break 'driver,
168                        }
169                    }
170                }
171            }
172        }
173        // EOF and dispatch-cap refusal settle pending requests only after
174        // already-accepted notifications apply. Explicit close must remain
175        // independent of a wedged handler, so other exits do not await it.
176        if drain_notifications && self.notification_dispatch.take().is_some() {
177            let mut dispatch_closed = self.closed.subscribe();
178            if !*dispatch_closed.borrow() && !*self.shutdown.borrow() {
179                tokio::select! {
180                    biased;
181                    _ = self.shutdown.changed() => {}
182                    _ = dispatch_closed.changed() => {}
183                }
184            }
185        } else if self.notification_dispatch.is_none() {
186            let _ = self.closed.send(true);
187        }
188    }
189
190    fn handle_line(&mut self, raw_line: String) -> bool {
191        let line = raw_line.strip_suffix('\r').unwrap_or(&raw_line);
192        if line.trim().is_empty() {
193            return true;
194        }
195        let value = match serde_json::from_str::<serde_json::Value>(line) {
196            Ok(value) => value,
197            Err(_) => {
198                self.report(ProtocolError::new(
199                    "inbound frame is not valid JSON",
200                    Some(line),
201                ));
202                return true;
203            }
204        };
205        let Some(object) = value.as_object() else {
206            self.report(ProtocolError::new(
207                "inbound frame is not a JSON-RPC 2.0 object",
208                Some(line),
209            ));
210            return true;
211        };
212        if object.get("jsonrpc") != Some(&serde_json::Value::String("2.0".to_owned())) {
213            self.report(ProtocolError::new(
214                "inbound frame is not a JSON-RPC 2.0 object",
215                Some(line),
216            ));
217            return true;
218        }
219        if object.get("method").is_some() && object.get("id").is_none() {
220            match serde_json::from_value::<Notification>(value) {
221                Ok(notification) => {
222                    if let Some(dispatch) = &self.notification_dispatch
223                        && !dispatch.try_send(notification.clone())
224                    {
225                        return false;
226                    }
227                    let _ = self.notifications.send(notification);
228                }
229                Err(_) => self.report(ProtocolError::new(
230                    "inbound frame is not a valid notification",
231                    Some(line),
232                )),
233            }
234            return true;
235        }
236        // Server-initiated requests use the server's own id space, so they
237        // must never be matched against our pending ids.
238        if object.contains_key("method") {
239            match serde_json::from_value::<Request>(value) {
240                Ok(request) if !matches!(request.id, RequestId::Integer(id) if id > 0) => {
241                    self.report(ProtocolError::new(
242                        "server request id must be a positive integer",
243                        Some(line),
244                    ));
245                }
246                // A client-owned connection routes approvals and user-input
247                // questions to their session in order with its view events; the
248                // reply is only the presentation receipt.
249                Ok(request)
250                    if matches!(
251                        request.method.as_str(),
252                        APPROVAL_REQUEST_METHOD | USER_INPUT_REQUEST_METHOD
253                    ) && self.notification_dispatch.is_some() =>
254                {
255                    let receipt = presentation_receipt(&request.id);
256                    let routed = Notification {
257                        jsonrpc: JsonRpcVersion::V2,
258                        method: request.method,
259                        params: request.params,
260                        emitted_at_ms: None,
261                    };
262                    if let Some(dispatch) = &self.notification_dispatch
263                        && !dispatch.try_send(routed)
264                    {
265                        return false;
266                    }
267                    self.queue_reply(receipt);
268                }
269                Ok(request) => self.queue_reply(method_not_found(request)),
270                Err(_) => self.report(ProtocolError::new(
271                    "inbound frame is not a valid server request",
272                    Some(line),
273                )),
274            }
275            return true;
276        }
277        let Some(id_value) = object.get("id") else {
278            self.report(ProtocolError::new("response has no usable id", Some(line)));
279            return true;
280        };
281        let id = match serde_json::from_value::<RequestId>(id_value.clone()) {
282            Ok(id) => id,
283            Err(_) => {
284                self.report(ProtocolError::new("response has no usable id", Some(line)));
285                return true;
286            }
287        };
288        let key = RequestKey::from(&id);
289        let Some(response) = self.pending.remove(&key) else {
290            self.report(ProtocolError::new(
291                format!("response for unknown request id {}", DisplayRequestId(&id)),
292                Some(line),
293            ));
294            return true;
295        };
296
297        let has_result = object.contains_key("result");
298        let has_error = object.contains_key("error");
299        if has_result == has_error {
300            let error = ProtocolError::new(
301                "response must carry exactly one of result or error",
302                Some(line),
303            );
304            let _ = response.send(Err(error.clone().into()));
305            self.report(error);
306            return true;
307        }
308
309        if has_result {
310            match serde_json::from_value::<SuccessResponse>(value) {
311                Ok(success) => {
312                    let _ = response.send(Ok(success.result));
313                }
314                Err(_) => {
315                    let error = ProtocolError::new("response result must be an object", Some(line));
316                    let _ = response.send(Err(error.clone().into()));
317                    self.report(error);
318                }
319            }
320            return true;
321        }
322
323        match serde_json::from_value::<ErrorResponse>(value) {
324            Ok(failure) => match MspError::try_from(failure.error) {
325                Ok(error) => {
326                    let _ = response.send(Err(error.into()));
327                }
328                Err(error) => {
329                    let _ = response.send(Err(error.clone().into()));
330                    self.report(error);
331                }
332            },
333            Err(_) => {
334                let error =
335                    ProtocolError::new("error response has an invalid error object", Some(line));
336                let _ = response.send(Err(error.clone().into()));
337                self.report(error);
338            }
339        }
340        true
341    }
342
343    fn queue_reply(&mut self, reply: Result<String, serde_json::Error>) {
344        match reply {
345            Ok(reply) => self.server_request_replies.push_back(reply),
346            Err(error) => self.report(ProtocolError::new(
347                format!("server request reply could not be encoded: {error}"),
348                None,
349            )),
350        }
351    }
352
353    fn report(&self, error: ProtocolError) {
354        let _ = self.protocol_errors.send(error);
355    }
356
357    fn fail_protocol(&mut self, error: ProtocolError) {
358        for (_, response) in self.pending.drain() {
359            let _ = response.send(Err(ConnectionError::Protocol(error.clone())));
360        }
361    }
362
363    fn fail_transport(&mut self, error: io::Error) {
364        // `io::Error` is not cloneable; every waiter receives the same stable
365        // ErrorKind while the text remains diagnostic-only context.
366        let kind = error.kind();
367        let message = error.to_string();
368        for (_, response) in self.pending.drain() {
369            let _ = response.send(Err(ConnectionError::Transport(io::Error::new(
370                kind,
371                message.clone(),
372            ))));
373        }
374    }
375}
376
377enum DriverEvent {
378    Shutdown,
379    Outbound(Option<OutboundMessage>),
380    Inbound(io::Result<Option<String>>),
381}
382
383async fn next_driver_event<T>(
384    transport: &mut T,
385    outbound: &mut mpsc::Receiver<OutboundMessage>,
386    shutdown: &mut watch::Receiver<bool>,
387    prefer_inbound: bool,
388) -> DriverEvent
389where
390    T: DuplexTransport,
391{
392    if *shutdown.borrow() {
393        return DriverEvent::Shutdown;
394    }
395    let mut shutdown_changed = Box::pin(shutdown.changed());
396    let mut receive = Box::pin(outbound.recv());
397    let mut read = transport.read_chunk();
398    poll_fn(move |context| {
399        if shutdown_changed.as_mut().poll(context).is_ready() {
400            return Poll::Ready(DriverEvent::Shutdown);
401        }
402        if prefer_inbound {
403            if let Poll::Ready(chunk) = read.as_mut().poll(context) {
404                return Poll::Ready(DriverEvent::Inbound(chunk));
405            }
406            receive.as_mut().poll(context).map(DriverEvent::Outbound)
407        } else {
408            if let Poll::Ready(request) = receive.as_mut().poll(context) {
409                return Poll::Ready(DriverEvent::Outbound(request));
410            }
411            read.as_mut().poll(context).map(DriverEvent::Inbound)
412        }
413    })
414    .await
415}
416
417const APPROVAL_REQUEST_METHOD: &str = "approval/request";
418const USER_INPUT_REQUEST_METHOD: &str = "userInput/request";
419
420/// The presentation receipt: "a surface showed or will show this".
421fn presentation_receipt(id: &RequestId) -> Result<String, serde_json::Error> {
422    let reply = SuccessResponse {
423        jsonrpc: JsonRpcVersion::V2,
424        id: id.clone(),
425        result: serde_json::Map::new(),
426    };
427    let mut frame = serde_json::to_string(&reply)?;
428    frame.push('\n');
429    Ok(frame)
430}
431
432/// The TypeScript/Python connections' answer to a server request no handler
433/// claims; the host treats any reply as presentation-only.
434fn method_not_found(request: Request) -> Result<String, serde_json::Error> {
435    let code = ErrorCode::MethodNotFound;
436    let reply = ErrorResponse {
437        jsonrpc: JsonRpcVersion::V2,
438        id: Some(request.id),
439        error: ErrorObject {
440            code: code.code(),
441            message: format!("method not found: {}", request.method),
442            data: Some(Box::new(ErrorData {
443                retryable: code.retryable(),
444                ..ErrorData::new(code.kind())
445            })),
446        },
447    };
448    let mut frame = serde_json::to_string(&reply)?;
449    frame.push('\n');
450    Ok(frame)
451}