ruma_events/space/
child.rs

1//! Types for the [`m.space.child`] event.
2//!
3//! [`m.space.child`]: https://spec.matrix.org/latest/client-server-api/#mspacechild
4
5use ruma_common::{MilliSecondsSinceUnixEpoch, OwnedRoomId, OwnedServerName, OwnedUserId};
6use ruma_macros::{Event, EventContent};
7use serde::{Deserialize, Serialize};
8
9/// The content of an `m.space.child` event.
10///
11/// The admins of a space can advertise rooms and subspaces for their space by setting
12/// `m.space.child` state events.
13///
14/// The `state_key` is the ID of a child room or space, and the content must contain a `via` key
15/// which gives a list of candidate servers that can be used to join the room.
16#[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
17#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
18#[ruma_event(type = "m.space.child", kind = State, state_key_type = OwnedRoomId)]
19pub struct SpaceChildEventContent {
20    /// List of candidate servers that can be used to join the room.
21    pub via: Vec<OwnedServerName>,
22
23    /// Provide a default ordering of siblings in the room list.
24    ///
25    /// Rooms are sorted based on a lexicographic ordering of the Unicode codepoints of the
26    /// characters in `order` values. Rooms with no `order` come last, in ascending numeric order
27    /// of the origin_server_ts of their m.room.create events, or ascending lexicographic order of
28    /// their room_ids in case of equal `origin_server_ts`. `order`s which are not strings, or do
29    /// not consist solely of ascii characters in the range `\x20` (space) to `\x7E` (`~`), or
30    /// consist of more than 50 characters, are forbidden and the field should be ignored if
31    /// received.
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub order: Option<String>,
34
35    /// Space admins can mark particular children of a space as "suggested".
36    ///
37    /// This mainly serves as a hint to clients that that they can be displayed differently, for
38    /// example by showing them eagerly in the room list. A child which is missing the `suggested`
39    /// property is treated identically to a child with `"suggested": false`. A suggested child may
40    /// be a room or a subspace.
41    ///
42    /// Defaults to `false`.
43    #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
44    pub suggested: bool,
45}
46
47impl SpaceChildEventContent {
48    /// Creates a new `SpaceChildEventContent` with the given routing servers.
49    pub fn new(via: Vec<OwnedServerName>) -> Self {
50        Self { via, order: None, suggested: false }
51    }
52}
53
54/// An `m.space.child` event represented as a Stripped State Event with an added `origin_server_ts`
55/// key.
56#[derive(Clone, Debug, Event)]
57#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
58pub struct HierarchySpaceChildEvent {
59    /// The content of the space child event.
60    pub content: SpaceChildEventContent,
61
62    /// The fully-qualified ID of the user who sent this event.
63    pub sender: OwnedUserId,
64
65    /// The room ID of the child.
66    pub state_key: OwnedRoomId,
67
68    /// Timestamp in milliseconds on originating homeserver when this event was sent.
69    pub origin_server_ts: MilliSecondsSinceUnixEpoch,
70}
71
72#[cfg(test)]
73mod tests {
74    use js_int::uint;
75    use ruma_common::{server_name, MilliSecondsSinceUnixEpoch};
76    use serde_json::{from_value as from_json_value, json, to_value as to_json_value};
77
78    use super::{HierarchySpaceChildEvent, SpaceChildEventContent};
79
80    #[test]
81    fn space_child_serialization() {
82        let content = SpaceChildEventContent {
83            via: vec![server_name!("example.com").to_owned()],
84            order: Some("uwu".to_owned()),
85            suggested: false,
86        };
87
88        let json = json!({
89            "via": ["example.com"],
90            "order": "uwu",
91        });
92
93        assert_eq!(to_json_value(&content).unwrap(), json);
94    }
95
96    #[test]
97    fn space_child_empty_serialization() {
98        let content = SpaceChildEventContent { via: vec![], order: None, suggested: false };
99
100        let json = json!({ "via": [] });
101
102        assert_eq!(to_json_value(&content).unwrap(), json);
103    }
104
105    #[test]
106    fn hierarchy_space_child_deserialization() {
107        let json = json!({
108            "content": {
109                "via": [
110                    "example.org"
111                ]
112            },
113            "origin_server_ts": 1_629_413_349,
114            "sender": "@alice:example.org",
115            "state_key": "!a:example.org",
116            "type": "m.space.child"
117        });
118
119        let ev = from_json_value::<HierarchySpaceChildEvent>(json).unwrap();
120        assert_eq!(ev.origin_server_ts, MilliSecondsSinceUnixEpoch(uint!(1_629_413_349)));
121        assert_eq!(ev.sender, "@alice:example.org");
122        assert_eq!(ev.state_key, "!a:example.org");
123        assert_eq!(ev.content.via, ["example.org"]);
124        assert_eq!(ev.content.order, None);
125        assert!(!ev.content.suggested);
126    }
127}
ruma_events/space/child.rs

ruma_events/space/
child.rs
