ruma_client_api/space/
get_hierarchy.rs

1//! `GET /_matrix/client/*/rooms/{roomId}/hierarchy`
2//!
3//! Paginates over the space tree in a depth-first manner to locate child rooms of a given space.
4
5pub mod v1 {
6    //! `/v1/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/client-server-api/#get_matrixclientv1roomsroomidhierarchy
9
10    use js_int::UInt;
11    use ruma_common::{
12        api::{request, response, Metadata},
13        metadata, OwnedRoomId,
14    };
15
16    use crate::space::SpaceHierarchyRoomsChunk;
17
18    const METADATA: Metadata = metadata! {
19        method: GET,
20        rate_limited: true,
21        authentication: AccessToken,
22        history: {
23            unstable => "/_matrix/client/unstable/org.matrix.msc2946/rooms/:room_id/hierarchy",
24            1.2 => "/_matrix/client/v1/rooms/:room_id/hierarchy",
25        }
26    };
27
28    /// Request type for the `hierarchy` endpoint.
29    #[request(error = crate::Error)]
30    pub struct Request {
31        /// The room ID of the space to get a hierarchy for.
32        #[ruma_api(path)]
33        pub room_id: OwnedRoomId,
34
35        /// A pagination token from a previous result.
36        ///
37        /// If specified, `max_depth` and `suggested_only` cannot be changed from the first
38        /// request.
39        #[ruma_api(query)]
40        pub from: Option<String>,
41
42        /// The maximum number of rooms to include per response.
43        #[ruma_api(query)]
44        pub limit: Option<UInt>,
45
46        /// How far to go into the space.
47        ///
48        /// When reached, no further child rooms will be returned.
49        #[ruma_api(query)]
50        pub max_depth: Option<UInt>,
51
52        /// Whether or not the server should only consider suggested rooms.
53        ///
54        /// Suggested rooms are annotated in their `m.space.child` event contents.
55        ///
56        /// Defaults to `false`.
57        #[ruma_api(query)]
58        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
59        pub suggested_only: bool,
60    }
61
62    /// Response type for the `hierarchy` endpoint.
63    #[response(error = crate::Error)]
64    #[derive(Default)]
65    pub struct Response {
66        /// A token to supply to from to keep paginating the responses.
67        ///
68        /// Not present when there are no further results.
69        #[serde(skip_serializing_if = "Option::is_none")]
70        pub next_batch: Option<String>,
71
72        /// A paginated chunk of the space children.
73        pub rooms: Vec<SpaceHierarchyRoomsChunk>,
74    }
75
76    impl Request {
77        /// Creates a new `Request` with the given room ID.
78        pub fn new(room_id: OwnedRoomId) -> Self {
79            Self { room_id, from: None, limit: None, max_depth: None, suggested_only: false }
80        }
81    }
82
83    impl Response {
84        /// Creates an empty `Response`.
85        pub fn new() -> Self {
86            Default::default()
87        }
88    }
89}
90
91#[cfg(all(test, feature = "client"))]
92mod tests {
93    use ruma_common::api::IncomingResponse;
94    use serde_json::{json, to_vec as to_json_vec};
95
96    use super::v1::Response;
97
98    #[test]
99    fn deserialize_response() {
100        let body = json!({
101            "rooms": [
102                {
103                    "room_id": "!room:localhost",
104                    "num_joined_members": 5,
105                    "world_readable": false,
106                    "guest_can_join": false,
107                    "join_rule": "restricted",
108                    "allowed_room_ids": ["!otherroom:localhost"],
109                    "children_state": [
110                        {
111                            "content": {
112                                "via": [
113                                    "example.org"
114                                ]
115                            },
116                            "origin_server_ts": 1_629_413_349,
117                            "sender": "@alice:example.org",
118                            "state_key": "!a:example.org",
119                            "type": "m.space.child"
120                        }
121                    ],
122                },
123            ],
124        });
125        let response = http::Response::new(to_json_vec(&body).unwrap());
126
127        let response = Response::try_from_http_response(response).unwrap();
128        let room = &response.rooms[0];
129        assert_eq!(room.room_id, "!room:localhost");
130        let space_child = room.children_state[0].deserialize().unwrap();
131        assert_eq!(space_child.state_key, "!a:example.org");
132    }
133}
ruma_client_api/space/get_hierarchy.rs

ruma_client_api/space/
get_hierarchy.rs
