Skip to main content

jmap_websocket/
lib.rs

1//! JMAP over WebSocket, [RFC 8887](https://www.rfc-editor.org/rfc/rfc8887)
2//! (`urn:ietf:params:jmap:websocket`).
3//!
4//! This is a support crate (workspace AGENTS.md §Support crates): no
5//! `*-types` or `*-server` crate depends on it, and a deployment opts in.
6//!
7//! Always available, with no async runtime:
8//!
9//! - [`CAPABILITY`], [`SUBPROTOCOL`] and [`offers_jmap`] for the
10//!   Session object (§3) and the opening handshake (§4.2).
11//! - [`WebSocketCapability`], the §3 capability object.
12//! - The §4.3 messages: [`WsRequest`], [`WebSocketPushEnable`] and
13//!   [`WebSocketPushDisable`] from the client ([`ClientMessage`]);
14//!   [`WsResponse`], [`WsRequestError`] and [`WsStateChange`] from the
15//!   server ([`ServerMessage`]).
16//!
17// The `server` items exist only with that feature: link them only then,
18// so `cargo doc` with default features has no broken links.
19#![cfg_attr(
20    feature = "server",
21    doc = "Feature `server`: [`server::Connection`], a session driver that turns
22incoming text frames into [`jmap_server::Dispatcher`] calls and writes
23the answers and push notifications back, over any `Stream` and `Sink`
24of messages, so it fits axum, tokio-tungstenite or another stack. Also
25[`server::PushHub`], an in-memory state-change source with `pushState`
26replay, and [`server::ExtensionHandler`], the hook for the extension
27message types of the JMAP Chat, VTC and Scene WebSocket drafts.
28"
29)]
30#![cfg_attr(
31    not(feature = "server"),
32    doc = "Feature `server`: `server::Connection`, a session driver that turns
33incoming text frames into `jmap_server::Dispatcher` calls and writes
34the answers and push notifications back, over any `Stream` and `Sink`
35of messages, so it fits axum, tokio-tungstenite or another stack. Also
36`server::PushHub`, an in-memory state-change source with `pushState`
37replay, and `server::ExtensionHandler`, the hook for the extension
38message types of the JMAP Chat, VTC and Scene WebSocket drafts.
39"
40)]
41//!
42//! Feature `tungstenite`: `tungstenite::serve` runs a connection over a
43//! tokio-tungstenite `WebSocketStream`; `tungstenite::accept_with_config`
44//! caps tungstenite's message size at `maxSizeRequest`.
45//!
46//! The authenticated HTTP request that opens the WebSocket, and the TLS
47//! under it (RFC 8887 §4.1, §5.1), are the deployment's.
48
49#![cfg_attr(docsrs, feature(doc_cfg))]
50#![forbid(unsafe_code)]
51
52mod capability;
53mod frame;
54
55#[cfg(feature = "server")]
56pub mod server;
57
58#[cfg(feature = "tungstenite")]
59pub mod tungstenite;
60
61pub use capability::WebSocketCapability;
62pub use frame::{
63    ClientMessage, ServerMessage, WebSocketPushDisable, WebSocketPushEnable, WsRequest,
64    WsRequestError, WsResponse, WsStateChange,
65};
66
67pub use jmap_types;
68
69#[cfg(feature = "server")]
70pub use futures;
71#[cfg(feature = "server")]
72pub use jmap_server;
73
74#[cfg(feature = "tungstenite")]
75pub use tokio_tungstenite;
76
77/// The JMAP capability URI of this extension (RFC 8887 §3, §6): the key
78/// of [`WebSocketCapability`] in the Session's `capabilities`.
79pub const CAPABILITY: &str = "urn:ietf:params:jmap:websocket";
80
81/// The WebSocket subprotocol name (RFC 8887 §4.2, §6.1). The client MUST
82/// list it in `Sec-WebSocket-Protocol`, and the server's reply MUST carry
83/// it for a JMAP connection to be established.
84pub const SUBPROTOCOL: &str = "jmap";
85
86/// Whether a `Sec-WebSocket-Protocol` request header value lists the
87/// [`SUBPROTOCOL`] (RFC 8887 §4.2).
88///
89/// The header is a comma-separated list of tokens (RFC 6455 §11.3.4);
90/// tokens are compared exactly, since subprotocol names are
91/// case-sensitive. A server that gets `false` must not complete the
92/// handshake as a JMAP connection.
93///
94/// ```
95/// assert!(jmap_websocket::offers_jmap("chat, jmap"));
96/// assert!(!jmap_websocket::offers_jmap("JMAP"));
97/// ```
98pub fn offers_jmap(header_value: &str) -> bool {
99    header_value.split(',').any(|t| t.trim() == SUBPROTOCOL)
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    /// RFC 8887 §6.1 registers the subprotocol identifier `jmap`; §3 names
107    /// the capability `urn:ietf:params:jmap:websocket`. 0.0.1 shipped
108    /// `CAPABILITY` with the same value.
109    #[test]
110    fn constants_match_rfc_8887() {
111        assert_eq!(CAPABILITY, "urn:ietf:params:jmap:websocket");
112        assert_eq!(SUBPROTOCOL, "jmap");
113    }
114
115    /// RFC 8887 §4.4 handshake: `Sec-WebSocket-Protocol: jmap`. RFC 6455
116    /// §11.3.4 makes the header a comma list of tokens.
117    #[test]
118    fn offers_jmap_reads_the_token_list() {
119        assert!(offers_jmap("jmap"));
120        assert!(offers_jmap("soap,jmap"));
121        assert!(offers_jmap(" soap , jmap "));
122        assert!(!offers_jmap("soap"));
123        assert!(!offers_jmap("jmapx"));
124        assert!(!offers_jmap(""));
125    }
126}