1mod 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;
34pub(crate) const NOTIFICATION_HANDLER_CAPACITY: usize = 1_024;
38pub(crate) const NOTIFICATION_SESSION_SHARE: usize = 256;
42const 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
78type SessionPermits = Arc<Mutex<HashMap<String, usize>>>;
81
82struct 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 refused: Option<Notification>,
101}
102
103pub(super) struct NotificationDispatch {
104 queue: mpsc::Sender<NotificationDispatchItem>,
105 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 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#[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 #[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 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 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(¬ification).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 pub async fn close(&self) {
335 self.shutdown.send_replace(true);
336 }
337
338 #[must_use]
340 pub fn subscribe_notifications(&self) -> broadcast::Receiver<Notification> {
341 self.notifications.subscribe()
342 }
343
344 #[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 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 let _ = applied.wait_for(|applied| *applied >= accepted).await;
369 }
370}
371
372#[derive(Clone)]
375struct NotificationHandoff {
376 accepted: Arc<AtomicU64>,
377 applied: watch::Receiver<u64>,
378}