Skip to main content

ruma_client_api/threads/
get_thread_updates.rs

1//! `GET /_matrix/client/*/thread_updates`
2//!
3//! Retrieve a paginated range of thread updates across all joined rooms.
4
5pub mod msc4360 {
6    //! `/unstable/io.element.msc4360/` ([MSC])
7    //!
8    //! [MSC]: https://github.com/matrix-org/matrix-spec-proposals/pull/4360
9
10    use std::collections::BTreeMap;
11
12    use js_int::UInt;
13    use ruma_common::{
14        OwnedEventId, OwnedRoomId,
15        api::{Direction, auth_scheme::AccessToken, request, response},
16        metadata,
17        serde::Raw,
18    };
19    use ruma_events::AnySyncTimelineEvent;
20    use serde::{Deserialize, Serialize};
21
22    metadata! {
23        method: GET,
24        rate_limited: true,
25        authentication: AccessToken,
26        history: {
27            unstable => "/_matrix/client/unstable/io.element.msc4360/thread_updates",
28        }
29    }
30
31    /// Request type for the `get_thread_updates` endpoint.
32    #[request]
33    pub struct Request {
34        /// The direction to use for pagination.
35        ///
36        /// Only `Direction::Backward` is meant to be supported, which is why this field is
37        /// private.
38        #[ruma_api(query)]
39        // Because this field is private, it is never read.
40        #[allow(dead_code)]
41        dir: Direction,
42
43        /// A token to continue pagination from.
44        ///
45        /// This token can be acquired from a previous `/thread_updates` response, or the
46        /// `prev_batch` in a sliding sync response's `threads` field.
47        ///
48        /// The token is opaque and has no client-discernible meaning.
49        ///
50        /// If not provided, then the pagination starts from the "end".
51        #[ruma_api(query)]
52        #[serde(skip_serializing_if = "Option::is_none")]
53        pub from: Option<String>,
54
55        /// A token used to limit the pagination.
56        ///
57        /// The token can be set to the value of a sliding sync `pos` field used in a request that
58        /// returned thread updates with a `prev_batch` token.
59        #[ruma_api(query)]
60        #[serde(skip_serializing_if = "Option::is_none")]
61        pub to: Option<String>,
62
63        /// A maximum number of thread updates to fetch in one response.
64        ///
65        /// Defaults to 100, if not provided. Servers may impose a smaller limit than requested.
66        #[ruma_api(query)]
67        #[serde(skip_serializing_if = "Option::is_none")]
68        pub limit: Option<UInt>,
69    }
70
71    /// Response type for the `get_thread_updates` endpoint.
72    #[response]
73    pub struct Response {
74        /// The thread updates, by room ID and thread root event ID.
75        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
76        pub chunk: BTreeMap<OwnedRoomId, BTreeMap<OwnedEventId, ThreadUpdate>>,
77
78        /// If there are still more results to fetch, this is the token to use as the next `from`
79        /// value.
80        #[serde(skip_serializing_if = "Option::is_none")]
81        pub next_batch: Option<String>,
82    }
83
84    impl Request {
85        /// Creates a new empty `Request`.
86        pub fn new() -> Self {
87            Self { dir: Direction::Backward, from: None, to: None, limit: None }
88        }
89    }
90
91    impl Response {
92        /// Creates a new empty `Response`.
93        pub fn new() -> Self {
94            Self { chunk: BTreeMap::new(), next_batch: None }
95        }
96    }
97
98    /// An update to a thread.
99    #[derive(Clone, Debug, Serialize, Deserialize)]
100    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
101    pub struct ThreadUpdate {
102        /// The thread root event, with the bundled `m.thread` aggregation.
103        pub thread_root: Raw<AnySyncTimelineEvent>,
104
105        /// A token to paginate the other updates in this thread with the `/relations` endpoint.
106        #[serde(skip_serializing_if = "Option::is_none")]
107        pub prev_batch: Option<String>,
108    }
109
110    impl ThreadUpdate {
111        /// Creates a new `ThreadUpdate` with the given thread root.
112        pub fn new(thread_root: Raw<AnySyncTimelineEvent>) -> Self {
113            Self { thread_root, prev_batch: None }
114        }
115    }
116}
117
118#[cfg(all(test, feature = "server"))]
119mod tests {
120    use ruma_common::api::IncomingRequestExt as _;
121
122    use super::msc4360::Request;
123
124    #[test]
125    fn deserialize_request() {
126        let http_req = http::Request::builder()
127            .method(http::Method::GET)
128            .uri("/_matrix/client/unstable/io.element.msc4360/thread_updates?dir=b&from=s1&to=s2&limit=10")
129            .body(&[] as &[u8])
130            .unwrap();
131
132        let req = Request::try_from_http_request(http_req, &[] as &[&str]).unwrap();
133
134        assert_eq!(req.from.as_deref(), Some("s1"));
135        assert_eq!(req.to.as_deref(), Some("s2"));
136        assert_eq!(req.limit, Some(js_int::uint!(10)));
137    }
138}