mod hub;
pub use hub::PushHub;
use std::fmt;
use std::future::Future;
use std::sync::Arc;
use futures::stream::{BoxStream, FuturesUnordered};
use futures::{Sink, SinkExt as _, Stream, StreamExt as _};
use jmap_server::Dispatcher;
use jmap_types::problem::ProblemDetails;
use jmap_types::{JmapError, JmapRequest, JmapResponse, State};
use serde_json::Value;
use tokio::sync::{OwnedSemaphorePermit, Semaphore};
use crate::{
ClientMessage, WebSocketPushDisable, WebSocketPushEnable, WsRequest, WsRequestError,
WsResponse, WsStateChange,
};
pub const CLOSE_UNSUPPORTED_DATA: u16 = 1003;
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Inbound {
Text(String),
Binary,
Close,
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Outbound {
Text(String),
Close {
code: u16,
reason: String,
},
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BinaryFrames {
#[default]
Close,
Ignore,
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConnectionConfig {
max_calls_in_request: usize,
max_size_request: Option<usize>,
max_concurrent_requests: usize,
binary_frames: BinaryFrames,
}
impl Default for ConnectionConfig {
fn default() -> Self {
Self {
max_calls_in_request: 16,
max_size_request: Some(10_000_000),
max_concurrent_requests: 4,
binary_frames: BinaryFrames::Close,
}
}
}
impl ConnectionConfig {
#[must_use]
pub fn max_calls_in_request(mut self, max: usize) -> Self {
self.max_calls_in_request = max;
self
}
#[must_use]
pub fn max_size_request(mut self, max: Option<usize>) -> Self {
self.max_size_request = max;
self
}
#[must_use]
pub fn max_concurrent_requests(mut self, max: usize) -> Self {
self.max_concurrent_requests = max.max(1);
self
}
#[must_use]
pub fn binary_frames(mut self, policy: BinaryFrames) -> Self {
self.binary_frames = policy;
self
}
pub fn max_calls_in_request_value(&self) -> usize {
self.max_calls_in_request
}
pub fn max_size_request_value(&self) -> Option<usize> {
self.max_size_request
}
pub fn max_concurrent_requests_value(&self) -> usize {
self.max_concurrent_requests
}
pub fn binary_frames_value(&self) -> BinaryFrames {
self.binary_frames
}
}
pub fn request_error(err: &JmapError, request_id: Option<String>) -> WsRequestError {
let status = jmap_server::error_status(err).as_u16();
WsRequestError::new(ProblemDetails::for_jmap_error(err, status), request_id)
}
#[allow(clippy::result_large_err)]
pub fn parse_client_message(
text: &str,
config: &ConnectionConfig,
) -> Result<ClientMessage, WsRequestError> {
if let Some(max) = config.max_size_request
&& text.len() > max
{
let mut err = JmapError::limit("maxSizeRequest");
err.description = Some(format!(
"The request is {} octets, more than maxSizeRequest {max}.",
text.len()
));
return Err(request_error(&err, None));
}
let value: Value = serde_json::from_str(text).map_err(|_| {
let mut err = JmapError::not_json();
err.description = Some("The request did not parse as I-JSON.".to_owned());
request_error(&err, None)
})?;
let Value::Object(mut obj) = value else {
return Err(not_request("The message is not a JSON object.", None));
};
let request_id = obj.get("id").and_then(Value::as_str).map(str::to_owned);
let Some(Value::String(ty)) = obj.remove("@type") else {
return Err(not_request("The message has no string @type.", request_id));
};
match ty.as_str() {
"Request" => {
let id = match obj.remove("id") {
None | Some(Value::Null) => None,
Some(Value::String(s)) => Some(s),
Some(_) => return Err(not_request("The request id is not a String.", None)),
};
match jmap_server::parse_request(Value::Object(obj), config.max_calls_in_request) {
Ok(request) => Ok(ClientMessage::Request(WsRequest::new(request, id))),
Err(err) => Err(request_error(&err, id)),
}
}
"WebSocketPushEnable" => serde_json::from_value::<WebSocketPushEnable>(Value::Object(obj))
.map(ClientMessage::PushEnable)
.map_err(|_| not_request("Malformed WebSocketPushEnable.", request_id)),
"WebSocketPushDisable" => {
serde_json::from_value::<WebSocketPushDisable>(Value::Object(obj))
.map(ClientMessage::PushDisable)
.map_err(|_| not_request("Malformed WebSocketPushDisable.", request_id))
}
_ => Err(not_request(
"The @type is not one a client may send.",
request_id,
)),
}
}
fn not_request(detail: &str, request_id: Option<String>) -> WsRequestError {
let mut err = JmapError::not_request();
err.description = Some(detail.to_owned());
request_error(&err, request_id)
}
pub trait RequestHandler: Send + Sync + 'static {
fn handle(
&self,
request: JmapRequest,
) -> impl Future<Output = Result<JmapResponse, JmapError>> + Send;
fn prepare_problem(&self, problem: &mut ProblemDetails) {
let _ = problem;
}
}
type SessionStateFn = dyn Fn() -> State + Send + Sync;
pub struct DispatcherHandler<C> {
dispatcher: Arc<Dispatcher<C>>,
caller: C,
session_state: Arc<SessionStateFn>,
known_capabilities: Option<Vec<String>>,
}
impl<C: Clone + Send + Sync + 'static> DispatcherHandler<C> {
pub fn new(
dispatcher: Arc<Dispatcher<C>>,
caller: C,
session_state: impl Fn() -> State + Send + Sync + 'static,
) -> Self {
Self {
dispatcher,
caller,
session_state: Arc::new(session_state),
known_capabilities: None,
}
}
#[must_use]
pub fn with_known_capabilities<I, S>(mut self, capabilities: I) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.known_capabilities = Some(capabilities.into_iter().map(Into::into).collect());
self
}
}
impl<C> fmt::Debug for DispatcherHandler<C> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("DispatcherHandler")
.field("known_capabilities", &self.known_capabilities)
.finish_non_exhaustive()
}
}
impl<C: Clone + Send + Sync + 'static> RequestHandler for DispatcherHandler<C> {
async fn handle(&self, request: JmapRequest) -> Result<JmapResponse, JmapError> {
if let Some(known) = &self.known_capabilities {
jmap_server::check_known_capabilities(&request, known)?;
}
let state = (self.session_state)();
Ok(self
.dispatcher
.dispatch(request, self.caller.clone(), state)
.await)
}
}
pub fn state_change_for_response(response: &JmapResponse) -> Option<jmap_types::StateChange> {
let mut changed: std::collections::BTreeMap<
jmap_types::Id,
std::collections::BTreeMap<String, State>,
> = std::collections::BTreeMap::new();
for call in &response.method_responses {
let Some(type_name) = call.name.strip_suffix("/set") else {
continue;
};
let args = &call.arguments;
let (Some(account), Some(new)) = (
args.get("accountId").and_then(serde_json::Value::as_str),
args.get("newState").and_then(serde_json::Value::as_str),
) else {
continue;
};
if args.get("oldState").and_then(serde_json::Value::as_str) == Some(new) {
continue;
}
changed
.entry(jmap_types::Id::from(account))
.or_default()
.insert(type_name.to_owned(), State::from(new));
}
(!changed.is_empty()).then(|| jmap_types::StateChange::new(changed))
}
#[derive(Debug)]
pub struct PublishingHandler<H> {
inner: H,
hub: PushHub,
}
impl<H: RequestHandler> PublishingHandler<H> {
pub fn new(inner: H, hub: PushHub) -> Self {
Self { inner, hub }
}
}
impl<H: RequestHandler> RequestHandler for PublishingHandler<H> {
async fn handle(&self, request: JmapRequest) -> Result<JmapResponse, JmapError> {
let response = self.inner.handle(request).await?;
if let Some(change) = state_change_for_response(&response) {
self.hub.publish(change);
}
Ok(response)
}
fn prepare_problem(&self, problem: &mut ProblemDetails) {
self.inner.prepare_problem(problem);
}
}
pub trait PushSource: Send + 'static {
fn subscribe(&mut self, enable: &WebSocketPushEnable) -> BoxStream<'static, WsStateChange>;
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default)]
pub struct NoPush;
impl PushSource for NoPush {
fn subscribe(&mut self, _enable: &WebSocketPushEnable) -> BoxStream<'static, WsStateChange> {
futures::stream::empty().boxed()
}
}
pub fn filter_state_change(
mut change: WsStateChange,
data_types: Option<&[String]>,
) -> Option<WsStateChange> {
if let Some(types) = data_types {
change.state_change.changed.retain(|_, by_type| {
by_type.retain(|name, _| types.iter().any(|t| t == name));
!by_type.is_empty()
});
}
if change.state_change.changed.is_empty() {
None
} else {
Some(change)
}
}
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum ConnectionError {
#[error("receiving a WebSocket message failed")]
Receive(#[source] Box<dyn std::error::Error + Send + Sync>),
#[error("sending a WebSocket message failed")]
Send(#[source] Box<dyn std::error::Error + Send + Sync>),
#[error("serializing a server message failed")]
Serialize(#[source] serde_json::Error),
}
pub struct Connection<H, P = NoPush> {
handler: Arc<H>,
push: P,
config: ConnectionConfig,
shared_limit: Option<Arc<Semaphore>>,
}
impl<H, P> fmt::Debug for Connection<H, P> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Connection")
.field("config", &self.config)
.field("shared_limit", &self.shared_limit.is_some())
.finish_non_exhaustive()
}
}
impl<H: RequestHandler> Connection<H, NoPush> {
pub fn new(handler: Arc<H>) -> Self {
Self {
handler,
push: NoPush,
config: ConnectionConfig::default(),
shared_limit: None,
}
}
}
type InFlight = std::pin::Pin<
Box<
dyn Future<
Output = (
Option<String>,
Result<JmapResponse, JmapError>,
Option<OwnedSemaphorePermit>,
),
> + Send,
>,
>;
impl<H: RequestHandler, P: PushSource> Connection<H, P> {
pub fn with_push<Q: PushSource>(self, push: Q) -> Connection<H, Q> {
Connection {
handler: self.handler,
push,
config: self.config,
shared_limit: self.shared_limit,
}
}
#[must_use]
pub fn with_config(mut self, config: ConnectionConfig) -> Self {
self.config = config;
self
}
#[must_use]
pub fn with_shared_limit(mut self, limit: Arc<Semaphore>) -> Self {
self.shared_limit = Some(limit);
self
}
pub async fn run<S, K, E>(self, mut incoming: S, mut outgoing: K) -> Result<(), ConnectionError>
where
S: Stream<Item = Result<Inbound, E>> + Unpin,
E: std::error::Error + Send + Sync + 'static,
K: Sink<Outbound> + Unpin,
K::Error: std::error::Error + Send + Sync + 'static,
{
let Self {
handler,
mut push,
config,
shared_limit,
} = self;
let mut in_flight: FuturesUnordered<InFlight> = FuturesUnordered::new();
let mut subscription: Option<(BoxStream<'static, WsStateChange>, Option<Vec<String>>)> =
None;
loop {
tokio::select! {
done = in_flight.next(), if !in_flight.is_empty() => {
let Some((request_id, result, permit)) = done else { continue };
drop(permit);
let text = match result {
Ok(response) => to_text(&WsResponse::new(response, request_id))?,
Err(err) => error_text(&*handler, request_error(&err, request_id))?,
};
send(&mut outgoing, Outbound::Text(text)).await?;
}
change = next_change(&mut subscription) => {
match change {
Some(change) => {
let types = subscription.as_ref().and_then(|(_, t)| t.as_deref());
if let Some(change) = filter_state_change(change, types) {
send(&mut outgoing, Outbound::Text(to_text(&change)?)).await?;
}
}
None => subscription = None,
}
}
message = incoming.next() => {
let message = match message {
None | Some(Ok(Inbound::Close)) => return Ok(()),
Some(Err(e)) => return Err(ConnectionError::Receive(Box::new(e))),
Some(Ok(m)) => m,
};
let text = match message {
Inbound::Text(text) => text,
Inbound::Binary => match config.binary_frames {
BinaryFrames::Ignore => continue,
BinaryFrames::Close => {
let close = Outbound::Close {
code: CLOSE_UNSUPPORTED_DATA,
reason: "binary messages are not supported".to_owned(),
};
send(&mut outgoing, close).await?;
return Ok(());
}
},
Inbound::Close => return Ok(()),
};
match parse_client_message(&text, &config) {
Err(e) => {
send(&mut outgoing, Outbound::Text(error_text(&*handler, e)?)).await?;
}
Ok(ClientMessage::Request(WsRequest { id, request })) => {
match admit(&in_flight, &config, shared_limit.as_ref()) {
Ok(permit) => {
let h = Arc::clone(&handler);
in_flight.push(Box::pin(async move {
let result = h.handle(request).await;
(id, result, permit)
}));
}
Err(()) => {
let err = JmapError::limit("maxConcurrentRequests");
let text = error_text(&*handler, request_error(&err, id))?;
send(&mut outgoing, Outbound::Text(text)).await?;
}
}
}
Ok(ClientMessage::PushEnable(enable)) => {
let stream = push.subscribe(&enable);
subscription = Some((stream, enable.data_types));
}
Ok(ClientMessage::PushDisable(_)) => subscription = None,
}
}
}
}
}
}
fn admit(
in_flight: &FuturesUnordered<InFlight>,
config: &ConnectionConfig,
shared: Option<&Arc<Semaphore>>,
) -> Result<Option<OwnedSemaphorePermit>, ()> {
if in_flight.len() >= config.max_concurrent_requests {
return Err(());
}
match shared {
None => Ok(None),
Some(s) => Arc::clone(s).try_acquire_owned().map(Some).map_err(|_| ()),
}
}
async fn next_change(
subscription: &mut Option<(BoxStream<'static, WsStateChange>, Option<Vec<String>>)>,
) -> Option<WsStateChange> {
match subscription {
Some((stream, _)) => stream.next().await,
None => std::future::pending().await,
}
}
fn to_text<T: serde::Serialize>(message: &T) -> Result<String, ConnectionError> {
serde_json::to_string(message).map_err(ConnectionError::Serialize)
}
fn error_text<H: RequestHandler>(
handler: &H,
mut error: WsRequestError,
) -> Result<String, ConnectionError> {
handler.prepare_problem(&mut error.problem);
to_text(&error)
}
async fn send<K>(outgoing: &mut K, message: Outbound) -> Result<(), ConnectionError>
where
K: Sink<Outbound> + Unpin,
K::Error: std::error::Error + Send + Sync + 'static,
{
outgoing
.send(message)
.await
.map_err(|e| ConnectionError::Send(Box::new(e)))
}
#[cfg(test)]
mod tests;