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