Skip to main content

jmap_websocket/
capability.rs

1//! The RFC 8887 §3 capability object.
2
3use serde::{Deserialize, Serialize};
4
5/// The value of the [`CAPABILITY`](crate::CAPABILITY) key in a Session's
6/// `capabilities` (RFC 8887 §3).
7///
8/// ```
9/// use jmap_websocket::WebSocketCapability;
10///
11/// let cap = WebSocketCapability::new("wss://server.example.com/jmap/ws/", true);
12/// assert_eq!(
13///     serde_json::to_value(&cap).unwrap(),
14///     serde_json::json!({"url": "wss://server.example.com/jmap/ws/", "supportsPush": true}),
15/// );
16/// ```
17///
18/// Unknown members are kept in [`extra`](Self::extra) (workspace
19/// extras-preservation policy, AGENTS.md).
20#[non_exhaustive]
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(rename_all = "camelCase")]
23pub struct WebSocketCapability {
24    /// `url`: the wss-URI of the WebSocket URL endpoint (RFC 6455 §3).
25    /// This type does not check the scheme.
26    pub url: String,
27    /// `supportsPush`: whether the server sends push notifications over
28    /// the WebSocket (RFC 8887 §4.3.5). Required on the wire; a missing
29    /// value reads as `false`.
30    #[serde(default)]
31    pub supports_push: bool,
32    /// Vendor, site and future-spec members not covered above.
33    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
34    pub extra: serde_json::Map<String, serde_json::Value>,
35}
36
37impl WebSocketCapability {
38    /// A capability for endpoint `url` with `supportsPush` set to
39    /// `supports_push` and no extension members.
40    pub fn new(url: impl Into<String>, supports_push: bool) -> Self {
41        Self {
42            url: url.into(),
43            supports_push,
44            extra: serde_json::Map::new(),
45        }
46    }
47}
48
49#[cfg(test)]
50mod tests {
51    use super::*;
52    use serde_json::json;
53
54    /// RFC 8887 §3 example, verbatim.
55    const RFC_EXAMPLE: &str = r#"{
56     "url": "wss://server.example.com/jmap/ws/",
57     "supportsPush": true
58   }"#;
59
60    #[test]
61    fn rfc_8887_section_3_example_round_trips() {
62        let cap: WebSocketCapability = serde_json::from_str(RFC_EXAMPLE).unwrap();
63        assert_eq!(cap.url, "wss://server.example.com/jmap/ws/");
64        assert!(cap.supports_push);
65        assert!(cap.extra.is_empty());
66        let expected: serde_json::Value = serde_json::from_str(RFC_EXAMPLE).unwrap();
67        assert_eq!(serde_json::to_value(&cap).unwrap(), expected);
68    }
69
70    /// Workspace extras-preservation policy: an unknown member survives a
71    /// round trip.
72    #[test]
73    fn unknown_member_is_preserved() {
74        let wire = json!({"url": "wss://h/ws", "supportsPush": false, "x-vendor": {"a": 1}});
75        let cap: WebSocketCapability = serde_json::from_value(wire.clone()).unwrap();
76        assert_eq!(cap.extra["x-vendor"], json!({"a": 1}));
77        assert_eq!(serde_json::to_value(&cap).unwrap(), wire);
78    }
79}