ruma_client_api/message/get_message_events.rs
1//! `GET /_matrix/client/*/rooms/{roomId}/messages`
2//!
3//! Get message events for a room.
4
5pub mod v3 {
6 //! `/v3/` ([spec])
7 //!
8 //! [spec]: https://spec.matrix.org/latest/client-server-api/#get_matrixclientv3roomsroomidmessages
9
10 use js_int::{UInt, uint};
11 use ruma_common::{
12 OwnedRoomId,
13 api::{Direction, auth_scheme::AccessToken, request, response},
14 metadata,
15 serde::Raw,
16 };
17 use ruma_events::{AnyStateEvent, AnyTimelineEvent};
18
19 use crate::filter::RoomEventFilter;
20
21 metadata! {
22 method: GET,
23 rate_limited: false,
24 authentication: AccessToken,
25 history: {
26 1.0 => "/_matrix/client/r0/rooms/{room_id}/messages",
27 1.1 => "/_matrix/client/v3/rooms/{room_id}/messages",
28 }
29 }
30
31 /// Request type for the `get_message_events` endpoint.
32 #[request(error = crate::Error)]
33 pub struct Request {
34 /// The room to get events from.
35 #[ruma_api(path)]
36 pub room_id: OwnedRoomId,
37
38 /// The token to start returning events from.
39 ///
40 /// This token can be obtained from a `prev_batch` token returned for each room by the
41 /// sync endpoint, or from a `start` or `end` token returned by a previous request to
42 /// this endpoint.
43 ///
44 /// If this is `None`, the server will return messages from the start or end of the
45 /// history visible to the user, depending on the value of [`dir`][Self::dir].
46 #[ruma_api(query)]
47 pub from: Option<String>,
48
49 /// The token to stop returning events at.
50 ///
51 /// This token can be obtained from a `prev_batch` token returned for each room by the
52 /// sync endpoint, or from a `start` or `end` token returned by a previous request to
53 /// this endpoint.
54 #[serde(skip_serializing_if = "Option::is_none")]
55 #[ruma_api(query)]
56 pub to: Option<String>,
57
58 /// The direction to return events from.
59 #[ruma_api(query)]
60 pub dir: Direction,
61
62 /// The maximum number of events to return.
63 ///
64 /// Default: `10`.
65 #[ruma_api(query)]
66 #[serde(default = "default_limit", skip_serializing_if = "is_default_limit")]
67 pub limit: UInt,
68
69 /// A [`RoomEventFilter`] to filter returned events with.
70 #[ruma_api(query)]
71 #[serde(
72 with = "ruma_common::serde::json_string",
73 default,
74 skip_serializing_if = "RoomEventFilter::is_empty"
75 )]
76 pub filter: RoomEventFilter,
77 }
78
79 /// Response type for the `get_message_events` endpoint.
80 #[response(error = crate::Error)]
81 #[derive(Default)]
82 pub struct Response {
83 /// The token the pagination starts from.
84 pub start: String,
85
86 /// The token the pagination ends at.
87 #[serde(skip_serializing_if = "Option::is_none")]
88 pub end: Option<String>,
89
90 /// A list of room events.
91 #[serde(default)]
92 pub chunk: Vec<Raw<AnyTimelineEvent>>,
93
94 /// A list of state events relevant to showing the `chunk`.
95 #[serde(default, skip_serializing_if = "Vec::is_empty")]
96 pub state: Vec<Raw<AnyStateEvent>>,
97 }
98
99 impl Request {
100 /// Creates a new `Request` with the given room ID and direction.
101 ///
102 /// All other parameters will be defaulted.
103 pub fn new(room_id: OwnedRoomId, dir: Direction) -> Self {
104 Self {
105 room_id,
106 from: None,
107 to: None,
108 dir,
109 limit: default_limit(),
110 filter: RoomEventFilter::default(),
111 }
112 }
113
114 /// Creates a new `Request` with the given room ID and `dir` set to `Backward`.
115 ///
116 /// If the returned request is sent without `from` being set, pagination will start at the
117 /// end of (the accessible part of) the room timeline.
118 ///
119 /// # Example
120 ///
121 /// ```rust
122 /// # use ruma_client_api::message::get_message_events;
123 /// # let room_id = ruma_common::owned_room_id!("!a:example.org");
124 /// # let token = "prev_batch token".to_owned();
125 /// let request = get_message_events::v3::Request::backward(room_id).from(token);
126 /// ```
127 pub fn backward(room_id: OwnedRoomId) -> Self {
128 Self::new(room_id, Direction::Backward)
129 }
130
131 /// Creates a new `Request` with the given room ID and `dir` set to `Forward`.
132 ///
133 /// If the returned request is sent without `from` being set, pagination will start at the
134 /// beginning of (the accessible part of) the room timeline.
135 ///
136 /// # Example
137 ///
138 /// ```rust
139 /// # use ruma_client_api::message::get_message_events;
140 /// # let room_id = ruma_common::owned_room_id!("!a:example.org");
141 /// # let token = "end token".to_owned();
142 /// let request = get_message_events::v3::Request::forward(room_id).from(token);
143 /// ```
144 pub fn forward(room_id: OwnedRoomId) -> Self {
145 Self::new(room_id, Direction::Forward)
146 }
147
148 /// Creates a new `Request` from `self` with the `from` field set to the given value.
149 ///
150 /// Since the field is public, you can also assign to it directly. This method merely acts
151 /// as a shorthand for that, because it is very common to set this field.
152 pub fn from(self, from: impl Into<Option<String>>) -> Self {
153 Self { from: from.into(), ..self }
154 }
155 }
156
157 impl Response {
158 /// Creates an empty `Response`.
159 pub fn new() -> Self {
160 Default::default()
161 }
162 }
163
164 fn default_limit() -> UInt {
165 uint!(10)
166 }
167
168 #[allow(clippy::trivially_copy_pass_by_ref)]
169 fn is_default_limit(val: &UInt) -> bool {
170 *val == default_limit()
171 }
172
173 #[cfg(all(test, feature = "client"))]
174 mod tests {
175 use std::borrow::Cow;
176
177 use js_int::uint;
178 use ruma_common::{
179 api::{
180 Direction, MatrixVersion, OutgoingRequest, SupportedVersions,
181 auth_scheme::SendAccessToken,
182 },
183 owned_room_id,
184 };
185
186 use super::Request;
187 use crate::filter::{LazyLoadOptions, RoomEventFilter};
188
189 #[test]
190 fn serialize_some_room_event_filter() {
191 let room_id = owned_room_id!("!roomid:example.org");
192 let rooms = vec![room_id.to_owned()];
193 let filter = RoomEventFilter {
194 lazy_load_options: LazyLoadOptions::Enabled { include_redundant_members: true },
195 rooms: Some(rooms),
196 not_rooms: vec![
197 owned_room_id!("!room:example.org"),
198 owned_room_id!("!room2:example.org"),
199 owned_room_id!("!room3:example.org"),
200 ],
201 not_types: vec!["type".into()],
202 ..Default::default()
203 };
204 let req = Request {
205 room_id,
206 from: Some("token".to_owned()),
207 to: Some("token2".to_owned()),
208 dir: Direction::Backward,
209 limit: uint!(0),
210 filter,
211 };
212 let supported = SupportedVersions {
213 versions: [MatrixVersion::V1_1].into(),
214 features: Default::default(),
215 };
216
217 let request: http::Request<Vec<u8>> = req
218 .try_into_http_request(
219 "https://homeserver.tld",
220 SendAccessToken::IfRequired("auth_tok"),
221 Cow::Owned(supported),
222 )
223 .unwrap();
224 assert_eq!(
225 "from=token\
226 &to=token2\
227 &dir=b\
228 &limit=0\
229 &filter=%7B%22not_types%22%3A%5B%22type%22%5D%2C%22not_rooms%22%3A%5B%22%21room%3Aexample.org%22%2C%22%21room2%3Aexample.org%22%2C%22%21room3%3Aexample.org%22%5D%2C%22rooms%22%3A%5B%22%21roomid%3Aexample.org%22%5D%2C%22lazy_load_members%22%3Atrue%2C%22include_redundant_members%22%3Atrue%7D",
230 request.uri().query().unwrap()
231 );
232 }
233
234 #[test]
235 fn serialize_default_room_event_filter() {
236 let room_id = owned_room_id!("!roomid:example.org");
237 let req = Request {
238 room_id,
239 from: Some("token".to_owned()),
240 to: Some("token2".to_owned()),
241 dir: Direction::Backward,
242 limit: uint!(0),
243 filter: RoomEventFilter::default(),
244 };
245 let supported = SupportedVersions {
246 versions: [MatrixVersion::V1_1].into(),
247 features: Default::default(),
248 };
249
250 let request = req
251 .try_into_http_request::<Vec<u8>>(
252 "https://homeserver.tld",
253 SendAccessToken::IfRequired("auth_tok"),
254 Cow::Owned(supported),
255 )
256 .unwrap();
257 assert_eq!("from=token&to=token2&dir=b&limit=0", request.uri().query().unwrap(),);
258 }
259 }
260}