1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
//! `GET /_matrix/client/*/rooms/{roomId}/threads`
//!
//! Retrieve a list of threads in a room, with optional filters.
pub mod v1 {
//! `/v1/` ([spec])
//!
//! [spec]: https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1roomsroomidthreads
use js_int::UInt;
use ruma_common::{
OwnedRoomId,
api::{auth_scheme::AccessToken, request, response},
metadata,
serde::{Raw, StringEnum},
};
use ruma_events::AnyTimelineEvent;
use crate::PrivOwnedStr;
metadata! {
method: GET,
rate_limited: true,
authentication: AccessToken,
history: {
unstable => "/_matrix/client/unstable/org.matrix.msc3856/rooms/{room_id}/threads",
1.4 => "/_matrix/client/v1/rooms/{room_id}/threads",
}
}
/// Request type for the `get_thread_roots` endpoint.
#[request]
pub struct Request {
/// The room ID where the thread roots are located.
#[ruma_api(path)]
pub room_id: OwnedRoomId,
/// The pagination token to start returning results from.
///
/// If `None`, results start at the most recent topological event visible to the user.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub from: Option<String>,
/// Which thread roots are of interest to the caller.
#[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
#[ruma_api(query)]
pub include: IncludeThreads,
/// The maximum number of results to return in a single `chunk`.
///
/// Servers should apply a default value, and impose a maximum value to avoid resource
/// exhaustion.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub limit: Option<UInt>,
}
/// Response type for the `get_thread_roots` endpoint.
#[response]
pub struct Response {
/// The thread roots, ordered by the `latest_event` in each event's aggregation bundle.
///
/// All events returned include bundled aggregations.
pub chunk: Vec<Raw<AnyTimelineEvent>>,
/// An opaque string to provide to `from` to keep paginating the responses.
///
/// If this is `None`, there are no more results to fetch and the client should stop
/// paginating.
#[serde(skip_serializing_if = "Option::is_none")]
pub next_batch: Option<String>,
}
impl Request {
/// Creates a new `Request` with the given room ID.
pub fn new(room_id: OwnedRoomId) -> Self {
Self { room_id, from: None, include: IncludeThreads::default(), limit: None }
}
}
impl Response {
/// Creates a new `Response` with the given chunk.
pub fn new(chunk: Vec<Raw<AnyTimelineEvent>>) -> Self {
Self { chunk, next_batch: None }
}
}
/// Which threads to include in the response.
#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
#[derive(Clone, Default, StringEnum)]
#[ruma_enum(rename_all = "lowercase")]
#[non_exhaustive]
pub enum IncludeThreads {
/// `all`
///
/// Include all thread roots found in the room.
///
/// This is the default.
#[default]
All,
/// `participated`
///
/// Only include thread roots for threads where [`current_user_participated`] is `true`.
///
/// [`current_user_participated`]: https://spec.matrix.org/v1.19/client-server-api/#server-side-aggregation-of-mthread-relationships
Participated,
#[doc(hidden)]
_Custom(PrivOwnedStr),
}
}
#[cfg(all(test, feature = "server"))]
mod tests {
use ruma_common::{api::IncomingRequestExt as _, room_id};
use super::v1::{IncludeThreads, Request};
#[test]
// Testing when the include parameter is omitted from uri
// It should default to IncludeThreads::All
fn deserialize_request_without_include() {
let http_req = http::Request::builder()
.method(http::Method::GET)
.uri("/_matrix/client/v1/rooms/!room:example.com/threads")
.body(&[] as &[u8])
.unwrap();
let req = Request::try_from_http_request(http_req, &["!room:example.com"]).unwrap();
assert_eq!(req.room_id, room_id!("!room:example.com"));
assert_eq!(req.from, None);
assert_eq!(req.limit, None);
assert_eq!(req.include, IncludeThreads::All);
}
#[test]
// Testing when the include parameter is explicitly provided
fn deserialize_request_explicit_include() {
let http_req = http::Request::builder()
.method(http::Method::GET)
.uri("/_matrix/client/v1/rooms/!room:example.com/threads?include=participated")
.body(&[] as &[u8])
.unwrap();
let req = Request::try_from_http_request(http_req, &["!room:example.com"]).unwrap();
assert_eq!(req.room_id, room_id!("!room:example.com"));
assert_eq!(req.include, IncludeThreads::Participated);
}
}