ruma_federation_api/space/
get_hierarchy.rs

1//! `GET /_matrix/federation/*/hierarchy/{roomId}`
2//!
3//! Get 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/server-server-api/#get_matrixfederationv1hierarchyroomid
9
10    use ruma_common::{
11        api::{request, response, Metadata},
12        metadata, OwnedRoomId,
13    };
14
15    use crate::space::{SpaceHierarchyChildSummary, SpaceHierarchyParentSummary};
16
17    const METADATA: Metadata = metadata! {
18        method: GET,
19        rate_limited: false,
20        authentication: ServerSignatures,
21        history: {
22            unstable => "/_matrix/federation/unstable/org.matrix.msc2946/hierarchy/:room_id",
23            1.2 => "/_matrix/federation/v1/hierarchy/:room_id",
24        }
25    };
26
27    /// Request type for the `hierarchy` endpoint.
28    #[request]
29    pub struct Request {
30        /// The room ID of the space to get a hierarchy for.
31        #[ruma_api(path)]
32        pub room_id: OwnedRoomId,
33
34        /// Whether or not the server should only consider suggested rooms.
35        ///
36        /// Suggested rooms are annotated in their `m.space.child` event contents.
37        #[ruma_api(query)]
38        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
39        pub suggested_only: bool,
40    }
41
42    /// Response type for the `hierarchy` endpoint.
43    #[response]
44    pub struct Response {
45        /// A summary of the space’s children.
46        ///
47        /// Rooms which the requesting server cannot peek/join will be excluded.
48        pub children: Vec<SpaceHierarchyChildSummary>,
49
50        /// The list of room IDs the requesting server doesn’t have a viable way to peek/join.
51        ///
52        /// Rooms which the responding server cannot provide details on will be outright
53        /// excluded from the response instead.
54        pub inaccessible_children: Vec<OwnedRoomId>,
55
56        /// A summary of the requested room.
57        pub room: SpaceHierarchyParentSummary,
58    }
59
60    impl Request {
61        /// Creates a `Request` with the given room ID.
62        pub fn new(room_id: OwnedRoomId) -> Self {
63            Self { room_id, suggested_only: false }
64        }
65    }
66
67    impl Response {
68        /// Creates a new `Response` with the given room summary.
69        pub fn new(room_summary: SpaceHierarchyParentSummary) -> Self {
70            Self { children: Vec::new(), inaccessible_children: Vec::new(), room: room_summary }
71        }
72    }
73}
ruma_federation_api/space/get_hierarchy.rs

ruma_federation_api/space/
get_hierarchy.rs
