ruma_client_api/search/
search_events.rs

Help
1//! `POST /_matrix/client/*/search`
2//!
3//! Search events.
4
5pub mod v3 {
6    //! `/v3/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3search
9
10    use std::collections::BTreeMap;
11
12    use js_int::{uint, UInt};
13    use ruma_common::{
14        api::{request, response, Metadata},
15        metadata,
16        serde::{Raw, StringEnum},
17        OwnedEventId, OwnedMxcUri, OwnedRoomId, OwnedUserId,
18    };
19    use ruma_events::{AnyStateEvent, AnyTimelineEvent};
20    use serde::{Deserialize, Serialize};
21
22    use crate::{filter::RoomEventFilter, PrivOwnedStr};
23
24    const METADATA: Metadata = metadata! {
25        method: POST,
26        rate_limited: true,
27        authentication: AccessToken,
28        history: {
29            1.0 => "/_matrix/client/r0/search",
30            1.1 => "/_matrix/client/v3/search",
31        }
32    };
33
34    /// Request type for the `search` endpoint.
35    #[request(error = crate::Error)]
36    pub struct Request {
37        /// The point to return events from.
38        ///
39        /// If given, this should be a `next_batch` result from a previous call to this endpoint.
40        #[ruma_api(query)]
41        pub next_batch: Option<String>,
42
43        /// Describes which categories to search in and their criteria.
44        pub search_categories: Categories,
45    }
46
47    /// Response type for the `search` endpoint.
48    #[response(error = crate::Error)]
49    pub struct Response {
50        /// A grouping of search results by category.
51        pub search_categories: ResultCategories,
52    }
53
54    impl Request {
55        /// Creates a new `Request` with the given categories.
56        pub fn new(search_categories: Categories) -> Self {
57            Self { next_batch: None, search_categories }
58        }
59    }
60
61    impl Response {
62        /// Creates a new `Response` with the given search results.
63        pub fn new(search_categories: ResultCategories) -> Self {
64            Self { search_categories }
65        }
66    }
67
68    /// Categories of events that can be searched for.
69    #[derive(Clone, Debug, Default, Deserialize, Serialize)]
70    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
71    pub struct Categories {
72        /// Criteria for searching room events.
73        #[serde(skip_serializing_if = "Option::is_none")]
74        pub room_events: Option<Criteria>,
75    }
76
77    impl Categories {
78        /// Creates an empty `Categories`.
79        pub fn new() -> Self {
80            Default::default()
81        }
82    }
83
84    /// Criteria for searching a category of events.
85    #[derive(Clone, Debug, Deserialize, Serialize)]
86    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
87    pub struct Criteria {
88        /// The string to search events for.
89        pub search_term: String,
90
91        /// The keys to search for.
92        ///
93        /// Defaults to all keys.
94        #[serde(skip_serializing_if = "Option::is_none")]
95        pub keys: Option<Vec<SearchKeys>>,
96
97        /// A `Filter` to apply to the search.
98        #[serde(skip_serializing_if = "RoomEventFilter::is_empty")]
99        pub filter: RoomEventFilter,
100
101        /// The order in which to search for results.
102        #[serde(skip_serializing_if = "Option::is_none")]
103        pub order_by: Option<OrderBy>,
104
105        /// Configures whether any context for the events returned are included in the response.
106        #[serde(default, skip_serializing_if = "EventContext::is_default")]
107        pub event_context: EventContext,
108
109        /// Requests the server return the current state for each room returned.
110        #[serde(skip_serializing_if = "Option::is_none")]
111        pub include_state: Option<bool>,
112
113        /// Requests that the server partitions the result set based on the provided list of keys.
114        #[serde(default, skip_serializing_if = "Groupings::is_empty")]
115        pub groupings: Groupings,
116    }
117
118    impl Criteria {
119        /// Creates a new `Criteria` with the given search term.
120        pub fn new(search_term: String) -> Self {
121            Self {
122                search_term,
123                keys: None,
124                filter: RoomEventFilter::default(),
125                order_by: None,
126                event_context: Default::default(),
127                include_state: None,
128                groupings: Default::default(),
129            }
130        }
131    }
132
133    /// Configures whether any context for the events returned are included in the response.
134    #[derive(Clone, Debug, Deserialize, Serialize)]
135    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
136    pub struct EventContext {
137        /// How many events before the result are returned.
138        #[serde(
139            default = "default_event_context_limit",
140            skip_serializing_if = "is_default_event_context_limit"
141        )]
142        pub before_limit: UInt,
143
144        /// How many events after the result are returned.
145        #[serde(
146            default = "default_event_context_limit",
147            skip_serializing_if = "is_default_event_context_limit"
148        )]
149        pub after_limit: UInt,
150
151        /// Requests that the server returns the historic profile information for the users that
152        /// sent the events that were returned.
153        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
154        pub include_profile: bool,
155    }
156
157    fn default_event_context_limit() -> UInt {
158        uint!(5)
159    }
160
161    #[allow(clippy::trivially_copy_pass_by_ref)]
162    fn is_default_event_context_limit(val: &UInt) -> bool {
163        *val == default_event_context_limit()
164    }
165
166    impl EventContext {
167        /// Creates an `EventContext` with all-default values.
168        pub fn new() -> Self {
169            Self {
170                before_limit: default_event_context_limit(),
171                after_limit: default_event_context_limit(),
172                include_profile: false,
173            }
174        }
175
176        /// Returns whether all fields have their default value.
177        pub fn is_default(&self) -> bool {
178            self.before_limit == default_event_context_limit()
179                && self.after_limit == default_event_context_limit()
180                && !self.include_profile
181        }
182    }
183
184    impl Default for EventContext {
185        fn default() -> Self {
186            Self::new()
187        }
188    }
189
190    /// Context for search results, if requested.
191    #[derive(Clone, Debug, Default, Deserialize, Serialize)]
192    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
193    pub struct EventContextResult {
194        /// Pagination token for the end of the chunk.
195        #[serde(skip_serializing_if = "Option::is_none")]
196        pub end: Option<String>,
197
198        /// Events just after the result.
199        #[serde(default, skip_serializing_if = "Vec::is_empty")]
200        pub events_after: Vec<Raw<AnyTimelineEvent>>,
201
202        /// Events just before the result.
203        #[serde(default, skip_serializing_if = "Vec::is_empty")]
204        pub events_before: Vec<Raw<AnyTimelineEvent>>,
205
206        /// The historic profile information of the users that sent the events returned.
207        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
208        pub profile_info: BTreeMap<OwnedUserId, UserProfile>,
209
210        /// Pagination token for the start of the chunk.
211        #[serde(skip_serializing_if = "Option::is_none")]
212        pub start: Option<String>,
213    }
214
215    impl EventContextResult {
216        /// Creates an empty `EventContextResult`.
217        pub fn new() -> Self {
218            Default::default()
219        }
220
221        /// Returns whether all fields are `None` or an empty list.
222        pub fn is_empty(&self) -> bool {
223            self.end.is_none()
224                && self.events_after.is_empty()
225                && self.events_before.is_empty()
226                && self.profile_info.is_empty()
227                && self.start.is_none()
228        }
229    }
230
231    /// A grouping for partitioning the result set.
232    #[derive(Clone, Default, Debug, Deserialize, Serialize)]
233    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
234    pub struct Grouping {
235        /// The key within events to use for this grouping.
236        pub key: Option<GroupingKey>,
237    }
238
239    impl Grouping {
240        /// Creates an empty `Grouping`.
241        pub fn new() -> Self {
242            Default::default()
243        }
244
245        /// Returns whether `key` is `None`.
246        pub fn is_empty(&self) -> bool {
247            self.key.is_none()
248        }
249    }
250
251    /// The key within events to use for this grouping.
252    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
253    #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
254    #[ruma_enum(rename_all = "snake_case")]
255    #[non_exhaustive]
256    pub enum GroupingKey {
257        /// `room_id`
258        RoomId,
259
260        /// `sender`
261        Sender,
262
263        #[doc(hidden)]
264        _Custom(PrivOwnedStr),
265    }
266
267    /// Requests that the server partitions the result set based on the provided list of keys.
268    #[derive(Clone, Default, Debug, Deserialize, Serialize)]
269    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
270    pub struct Groupings {
271        /// List of groups to request.
272        #[serde(default, skip_serializing_if = "<[_]>::is_empty")]
273        pub group_by: Vec<Grouping>,
274    }
275
276    impl Groupings {
277        /// Creates an empty `Groupings`.
278        pub fn new() -> Self {
279            Default::default()
280        }
281
282        /// Returns `true` if all fields are empty.
283        pub fn is_empty(&self) -> bool {
284            self.group_by.is_empty()
285        }
286    }
287
288    /// The keys to search for.
289    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
290    #[derive(Clone, PartialEq, Eq, StringEnum)]
291    #[non_exhaustive]
292    pub enum SearchKeys {
293        /// content.body
294        #[ruma_enum(rename = "content.body")]
295        ContentBody,
296
297        /// content.name
298        #[ruma_enum(rename = "content.name")]
299        ContentName,
300
301        /// content.topic
302        #[ruma_enum(rename = "content.topic")]
303        ContentTopic,
304
305        #[doc(hidden)]
306        _Custom(PrivOwnedStr),
307    }
308
309    /// The order in which to search for results.
310    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
311    #[derive(Clone, PartialEq, Eq, StringEnum)]
312    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
313    #[ruma_enum(rename_all = "snake_case")]
314    pub enum OrderBy {
315        /// Prioritize recent events.
316        Recent,
317
318        /// Prioritize events by a numerical ranking of how closely they matched the search
319        /// criteria.
320        Rank,
321
322        #[doc(hidden)]
323        _Custom(PrivOwnedStr),
324    }
325
326    /// Categories of events that can be searched for.
327    #[derive(Clone, Default, Debug, Deserialize, Serialize)]
328    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
329    pub struct ResultCategories {
330        /// Room event results.
331        #[serde(default, skip_serializing_if = "ResultRoomEvents::is_empty")]
332        pub room_events: ResultRoomEvents,
333    }
334
335    impl ResultCategories {
336        /// Creates an empty `ResultCategories`.
337        pub fn new() -> Self {
338            Default::default()
339        }
340    }
341
342    /// Categories of events that can be searched for.
343    #[derive(Clone, Debug, Default, Deserialize, Serialize)]
344    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
345    pub struct ResultRoomEvents {
346        /// An approximate count of the total number of results found.
347        #[serde(skip_serializing_if = "Option::is_none")]
348        pub count: Option<UInt>,
349
350        /// Any groups that were requested.
351        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
352        pub groups: BTreeMap<GroupingKey, BTreeMap<OwnedRoomIdOrUserId, ResultGroup>>,
353
354        /// Token that can be used to get the next batch of results, by passing as the `next_batch`
355        /// parameter to the next call.
356        ///
357        /// If this field is absent, there are no more results.
358        #[serde(skip_serializing_if = "Option::is_none")]
359        pub next_batch: Option<String>,
360
361        /// List of results in the requested order.
362        #[serde(default, skip_serializing_if = "Vec::is_empty")]
363        pub results: Vec<SearchResult>,
364
365        /// The current state for every room in the results.
366        ///
367        /// This is included if the request had the `include_state` key set with a value of `true`.
368        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
369        pub state: BTreeMap<OwnedRoomId, Vec<Raw<AnyStateEvent>>>,
370
371        /// List of words which should be highlighted, useful for stemming which may
372        /// change the query terms.
373        #[serde(default, skip_serializing_if = "Vec::is_empty")]
374        pub highlights: Vec<String>,
375    }
376
377    impl ResultRoomEvents {
378        /// Creates an empty `ResultRoomEvents`.
379        pub fn new() -> Self {
380            Default::default()
381        }
382
383        /// Returns `true` if all fields are empty / `None`.
384        pub fn is_empty(&self) -> bool {
385            self.count.is_none()
386                && self.groups.is_empty()
387                && self.next_batch.is_none()
388                && self.results.is_empty()
389                && self.state.is_empty()
390                && self.highlights.is_empty()
391        }
392    }
393
394    /// A grouping of results, if requested.
395    #[derive(Clone, Debug, Default, Deserialize, Serialize)]
396    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
397    pub struct ResultGroup {
398        /// Token that can be used to get the next batch of results in the group, by passing as the
399        /// `next_batch` parameter to the next call.
400        ///
401        /// If this field is absent, there are no more results in this group.
402        #[serde(skip_serializing_if = "Option::is_none")]
403        pub next_batch: Option<String>,
404
405        /// Key that can be used to order different groups.
406        #[serde(skip_serializing_if = "Option::is_none")]
407        pub order: Option<UInt>,
408
409        /// Which results are in this group.
410        #[serde(default, skip_serializing_if = "Vec::is_empty")]
411        pub results: Vec<OwnedEventId>,
412    }
413
414    impl ResultGroup {
415        /// Creates an empty `ResultGroup`.
416        pub fn new() -> Self {
417            Default::default()
418        }
419
420        /// Returns `true` if all fields are empty / `None`.
421        pub fn is_empty(&self) -> bool {
422            self.next_batch.is_none() && self.order.is_none() && self.results.is_empty()
423        }
424    }
425
426    /// A search result.
427    #[derive(Clone, Debug, Default, Deserialize, Serialize)]
428    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
429    pub struct SearchResult {
430        /// Context for result, if requested.
431        #[serde(skip_serializing_if = "EventContextResult::is_empty")]
432        pub context: EventContextResult,
433
434        /// A number that describes how closely this result matches the search.
435        ///
436        /// Higher is closer.
437        #[serde(skip_serializing_if = "Option::is_none")]
438        pub rank: Option<f64>,
439
440        /// The event that matched.
441        #[serde(skip_serializing_if = "Option::is_none")]
442        pub result: Option<Raw<AnyTimelineEvent>>,
443    }
444
445    impl SearchResult {
446        /// Creates an empty `SearchResult`.
447        pub fn new() -> Self {
448            Default::default()
449        }
450
451        /// Returns `true` if all fields are empty / `None`.
452        pub fn is_empty(&self) -> bool {
453            self.context.is_empty() && self.rank.is_none() && self.result.is_none()
454        }
455    }
456
457    /// A user profile.
458    #[derive(Clone, Debug, Default, Deserialize, Serialize)]
459    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
460    pub struct UserProfile {
461        /// The user's avatar URL, if set.
462        ///
463        /// If you activate the `compat-empty-string-null` feature, this field being an empty
464        /// string in JSON will result in `None` here during deserialization.
465        #[serde(skip_serializing_if = "Option::is_none")]
466        #[cfg_attr(
467            feature = "compat-empty-string-null",
468            serde(default, deserialize_with = "ruma_common::serde::empty_string_as_none")
469        )]
470        pub avatar_url: Option<OwnedMxcUri>,
471
472        /// The user's display name, if set.
473        #[serde(skip_serializing_if = "Option::is_none")]
474        pub displayname: Option<String>,
475    }
476
477    impl UserProfile {
478        /// Creates an empty `UserProfile`.
479        pub fn new() -> Self {
480            Default::default()
481        }
482
483        /// Returns `true` if all fields are `None`.
484        pub fn is_empty(&self) -> bool {
485            self.avatar_url.is_none() && self.displayname.is_none()
486        }
487    }
488
489    /// Represents either a room or user ID for returning grouped search results.
490    #[derive(Clone, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
491    #[allow(clippy::exhaustive_enums)]
492    pub enum OwnedRoomIdOrUserId {
493        /// Represents a room ID.
494        RoomId(OwnedRoomId),
495
496        /// Represents a user ID.
497        UserId(OwnedUserId),
498    }
499}
ruma_client_api/search/search_events.rs

ruma_client_api/search/
search_events.rs
