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//! Feature `server`: [`server::Connection`], a session driver that turns
18//! incoming text frames into [`jmap_server::Dispatcher`] calls and writes
19//! the answers and push notifications back, over any `Stream` and `Sink`
20//! of messages, so it fits axum, tokio-tungstenite or another stack. Also
21//! [`server::PushHub`], an in-memory state-change source with `pushState`
22//! replay.
23//!
24//! Feature `tungstenite`: `tungstenite::serve` runs a connection over a
25//! tokio-tungstenite `WebSocketStream`.
26//!
27//! The authenticated HTTP request that opens the WebSocket, and the TLS
28//! under it (RFC 8887 §4.1, §5.1), are the deployment's.
29
30#![cfg_attr(docsrs, feature(doc_cfg))]
31#![forbid(unsafe_code)]
32
33mod capability;
34mod frame;
35
36#[cfg(feature = "server")]
37pub mod server;
38
39#[cfg(feature = "tungstenite")]
40pub mod tungstenite;
41
42pub use capability::WebSocketCapability;
43pub use frame::{
44    ClientMessage, ServerMessage, WebSocketPushDisable, WebSocketPushEnable, WsRequest,
45    WsRequestError, WsResponse, WsStateChange,
46};
47
48pub use jmap_types;
49
50#[cfg(feature = "server")]
51pub use futures;
52#[cfg(feature = "server")]
53pub use jmap_server;
54
55#[cfg(feature = "tungstenite")]
56pub use tokio_tungstenite;
57
58/// The JMAP capability URI of this extension (RFC 8887 §3, §6): the key
59/// of [`WebSocketCapability`] in the Session's `capabilities`.
60pub const CAPABILITY: &str = "urn:ietf:params:jmap:websocket";
61
62/// The WebSocket subprotocol name (RFC 8887 §4.2, §6.1). The client MUST
63/// list it in `Sec-WebSocket-Protocol`, and the server's reply MUST carry
64/// it for a JMAP connection to be established.
65pub const SUBPROTOCOL: &str = "jmap";
66
67/// Whether a `Sec-WebSocket-Protocol` request header value lists the
68/// [`SUBPROTOCOL`] (RFC 8887 §4.2).
69///
70/// The header is a comma-separated list of tokens (RFC 6455 §11.3.4);
71/// tokens are compared exactly, since subprotocol names are
72/// case-sensitive. A server that gets `false` must not complete the
73/// handshake as a JMAP connection.
74///
75/// ```
76/// assert!(jmap_websocket::offers_jmap("chat, jmap"));
77/// assert!(!jmap_websocket::offers_jmap("JMAP"));
78/// ```
79pub fn offers_jmap(header_value: &str) -> bool {
80    header_value.split(',').any(|t| t.trim() == SUBPROTOCOL)
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    /// RFC 8887 §6.1 registers the subprotocol identifier `jmap`; §3 names
88    /// the capability `urn:ietf:params:jmap:websocket`. 0.0.1 shipped
89    /// `CAPABILITY` with the same value.
90    #[test]
91    fn constants_match_rfc_8887() {
92        assert_eq!(CAPABILITY, "urn:ietf:params:jmap:websocket");
93        assert_eq!(SUBPROTOCOL, "jmap");
94    }
95
96    /// RFC 8887 §4.4 handshake: `Sec-WebSocket-Protocol: jmap`. RFC 6455
97    /// §11.3.4 makes the header a comma list of tokens.
98    #[test]
99    fn offers_jmap_reads_the_token_list() {
100        assert!(offers_jmap("jmap"));
101        assert!(offers_jmap("soap,jmap"));
102        assert!(offers_jmap(" soap , jmap "));
103        assert!(!offers_jmap("soap"));
104        assert!(!offers_jmap("jmapx"));
105        assert!(!offers_jmap(""));
106    }
107}