mod dispatch;
mod driver;
mod error;
mod framing;
mod handshake;
mod matching;
mod stdio;
#[cfg(test)]
mod tests;
use std::collections::{HashMap, HashSet, VecDeque};
use std::sync::atomic::{AtomicI64, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, MutexGuard};
use tokio::sync::{OwnedSemaphorePermit, Semaphore, broadcast, mpsc, oneshot, watch};
use crate::DuplexTransport;
use crate::msp::{JsonRpcVersion, Notification, Request, RequestId};
pub use driver::ConnectionDriver;
pub use error::ConnectionError;
pub use crate::errors::{MspError, ProtocolError};
#[cfg(test)]
use stdio::PipeTransport;
pub use stdio::StdioTransport;
const OUTBOUND_CAPACITY: usize = 64;
const PROTOCOL_ERROR_CAPACITY: usize = 32;
const NOTIFICATION_CAPACITY: usize = 64;
pub(crate) const NOTIFICATION_HANDLER_CAPACITY: usize = 1_024;
pub(crate) const NOTIFICATION_SESSION_SHARE: usize = 256;
const NOTIFICATION_DISPATCH_CAPACITY: usize = NOTIFICATION_HANDLER_CAPACITY * 2 + 1;
type RequestResult = Result<serde_json::Map<String, serde_json::Value>, ConnectionError>;
struct OutboundRequest {
id: RequestId,
frame: String,
response: oneshot::Sender<RequestResult>,
}
enum OutboundMessage {
Request(OutboundRequest),
Notification {
frame: String,
submitted: oneshot::Sender<Result<(), ConnectionError>>,
},
}
type NotificationHandler = Arc<dyn Fn(Notification) + Send + Sync>;
enum NotificationDispatchItem {
Notification {
notification: Notification,
permit: SessionPermit,
},
Overflow {
notification: Notification,
marker: OverflowMarker,
},
}
type SessionPermits = Arc<Mutex<HashMap<String, usize>>>;
struct SessionPermit {
session: Option<(String, SessionPermits)>,
_permit: OwnedSemaphorePermit,
}
enum OverflowMarker {
Session(String),
Saturated,
}
#[derive(Default)]
struct SaturatedOverflow {
queued: bool,
sessions: HashSet<String>,
pending: VecDeque<Notification>,
refused: Option<Notification>,
}
pub(super) struct NotificationDispatch {
queue: mpsc::Sender<NotificationDispatchItem>,
accepted: Arc<AtomicU64>,
notification_capacity: Arc<Semaphore>,
session_permits: SessionPermits,
queued_overflows: Arc<Mutex<HashSet<String>>>,
saturated_overflow: Arc<Mutex<SaturatedOverflow>>,
}
pub(crate) struct NotificationDispatcher {
queue: mpsc::Receiver<NotificationDispatchItem>,
applied: watch::Sender<u64>,
handler: NotificationHandler,
overflow: NotificationHandler,
queued_overflows: Arc<Mutex<HashSet<String>>>,
saturated_overflow: Arc<Mutex<SaturatedOverflow>>,
closed: watch::Sender<bool>,
}
fn notification_session_id(notification: &Notification) -> Option<&str> {
notification
.params
.as_ref()
.and_then(|params| params.get("sessionId"))
.and_then(serde_json::Value::as_str)
}
fn lock_notification_overflows(queued: &Mutex<HashSet<String>>) -> MutexGuard<'_, HashSet<String>> {
match queued.lock() {
Ok(queued) => queued,
Err(poisoned) => poisoned.into_inner(),
}
}
fn lock_session_permits(
held: &Mutex<HashMap<String, usize>>,
) -> MutexGuard<'_, HashMap<String, usize>> {
match held.lock() {
Ok(held) => held,
Err(poisoned) => poisoned.into_inner(),
}
}
fn lock_saturated_overflow(
saturated: &Mutex<SaturatedOverflow>,
) -> MutexGuard<'_, SaturatedOverflow> {
match saturated.lock() {
Ok(saturated) => saturated,
Err(poisoned) => poisoned.into_inner(),
}
}
#[derive(Clone)]
pub struct Connection {
outbound: mpsc::Sender<OutboundMessage>,
handoff: Option<NotificationHandoff>,
notifications: broadcast::Sender<Notification>,
protocol_errors: broadcast::Sender<ProtocolError>,
shutdown: watch::Sender<bool>,
closed: watch::Receiver<bool>,
next_request_id: Arc<AtomicI64>,
}
impl Connection {
#[must_use]
pub fn new<T>(transport: T) -> (Self, ConnectionDriver<T>)
where
T: DuplexTransport,
{
Self::build(transport, None)
}
pub(crate) fn with_notification_handler<T, F, G>(
transport: T,
handler: F,
overflow: G,
) -> (Self, ConnectionDriver<T>, NotificationDispatcher)
where
T: DuplexTransport,
F: Fn(Notification) + Send + Sync + 'static,
G: Fn(Notification) + Send + Sync + 'static,
{
let handler: NotificationHandler = Arc::new(handler);
let overflow: NotificationHandler = Arc::new(overflow);
let queued_overflows = Arc::new(Mutex::new(HashSet::new()));
let saturated_overflow = Arc::new(Mutex::new(SaturatedOverflow::default()));
let (notification_queue, notifications) = mpsc::channel(NOTIFICATION_DISPATCH_CAPACITY);
let accepted = Arc::new(AtomicU64::new(0));
let (applied, applied_watch) = watch::channel(0);
let dispatch = NotificationDispatch {
queue: notification_queue,
accepted: Arc::clone(&accepted),
notification_capacity: Arc::new(Semaphore::new(NOTIFICATION_HANDLER_CAPACITY)),
session_permits: SessionPermits::default(),
queued_overflows: Arc::clone(&queued_overflows),
saturated_overflow: Arc::clone(&saturated_overflow),
};
let (mut connection, driver) = Self::build(transport, Some(dispatch));
connection.handoff = Some(NotificationHandoff {
accepted,
applied: applied_watch,
});
let closed = driver.closed_sender();
(
connection,
driver,
NotificationDispatcher {
queue: notifications,
applied,
handler,
overflow,
queued_overflows,
saturated_overflow,
closed,
},
)
}
fn build<T>(
transport: T,
notification_dispatch: Option<NotificationDispatch>,
) -> (Self, ConnectionDriver<T>)
where
T: DuplexTransport,
{
let (outbound, outbound_rx) = mpsc::channel(OUTBOUND_CAPACITY);
let (notifications, _) = broadcast::channel(NOTIFICATION_CAPACITY);
let (protocol_errors, _) = broadcast::channel(PROTOCOL_ERROR_CAPACITY);
let (shutdown, shutdown_rx) = watch::channel(false);
let (closed_tx, closed) = watch::channel(false);
(
Self {
outbound,
handoff: None,
notifications: notifications.clone(),
protocol_errors: protocol_errors.clone(),
shutdown,
closed,
next_request_id: Arc::new(AtomicI64::new(1)),
},
ConnectionDriver::new(
transport,
outbound_rx,
notifications,
notification_dispatch,
protocol_errors,
shutdown_rx,
closed_tx,
),
)
}
pub async fn request(
&self,
method: impl Into<String>,
params: Option<serde_json::Map<String, serde_json::Value>>,
) -> RequestResult {
if *self.shutdown.borrow() {
return Err(ConnectionError::Closed);
}
let id = RequestId::Integer(self.next_request_id.fetch_add(1, Ordering::Relaxed));
let request = Request {
jsonrpc: JsonRpcVersion::V2,
id: id.clone(),
method: method.into(),
params,
trace: None,
};
let mut frame = serde_json::to_string(&request).map_err(|error| {
ConnectionError::Protocol(ProtocolError::new(
format!("request could not be encoded: {error}"),
None,
))
})?;
frame.push('\n');
let (response, receiver) = oneshot::channel();
self.outbound
.send(OutboundMessage::Request(OutboundRequest {
id,
frame,
response,
}))
.await
.map_err(|_| ConnectionError::Closed)?;
receiver.await.unwrap_or(Err(ConnectionError::Closed))
}
pub async fn notify(
&self,
method: impl Into<String>,
params: Option<serde_json::Map<String, serde_json::Value>>,
) -> Result<(), ConnectionError> {
if *self.shutdown.borrow() {
return Err(ConnectionError::Closed);
}
let notification = Notification {
jsonrpc: JsonRpcVersion::V2,
method: method.into(),
params,
emitted_at_ms: None,
};
let mut frame = serde_json::to_string(¬ification).map_err(|error| {
ConnectionError::Protocol(ProtocolError::new(
format!("notification could not be encoded: {error}"),
None,
))
})?;
frame.push('\n');
let (submitted, submitted_rx) = oneshot::channel();
self.outbound
.send(OutboundMessage::Notification { frame, submitted })
.await
.map_err(|_| ConnectionError::Closed)?;
submitted_rx.await.unwrap_or(Err(ConnectionError::Closed))
}
pub async fn close(&self) {
self.shutdown.send_replace(true);
}
#[must_use]
pub fn subscribe_notifications(&self) -> broadcast::Receiver<Notification> {
self.notifications.subscribe()
}
#[must_use]
pub fn subscribe_protocol_errors(&self) -> broadcast::Receiver<ProtocolError> {
self.protocol_errors.subscribe()
}
pub(crate) fn subscribe_closed(&self) -> watch::Receiver<bool> {
self.closed.clone()
}
pub(crate) async fn notifications_received_applied(&self) {
let Some(handoff) = &self.handoff else {
return;
};
let accepted = handoff.accepted.load(Ordering::Acquire);
let mut applied = handoff.applied.clone();
let _ = applied.wait_for(|applied| *applied >= accepted).await;
}
}
#[derive(Clone)]
struct NotificationHandoff {
accepted: Arc<AtomicU64>,
applied: watch::Receiver<u64>,
}