Implement search endpoints.

2016-12-30 18:54:45 -08:00 · 2016-12-30 18:54:45 -08:00 · 130a4b5a98
commit 130a4b5a98
parent 0b295fe0f0
1 changed files with 230 additions and 0 deletions
--- a/src/r0/search.rs
+++ b/src/r0/search.rs
@ -1 +1,231 @@
 //! Endpoints for event searches.
+
+/// [POST /_matrix/client/r0/search](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-search)
+pub mod search_events {
+    use ruma_events::collections::all::Event;
+    use ruma_identifiers::{EventId, RoomId, UserId};
+
+    use r0::filter::RoomEventFilter;
+    use r0::profile::get_profile::Response as UserProfile;
+
+    use std::collections::HashMap;
+
+    /// This API endpoint's body parameters.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct BodyParams {
+        /// Describes which categories to search in and their criteria.
+        pub search_categories: Categories,
+    }
+
+    /// Categories of events that can be searched for.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct Categories {
+        /// Criteria for searching a category of events.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub room_events: Option<Criteria>
+    }
+
+    /// Criteria for searching a category of events.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct Criteria {
+        /// Configures whether any context for the events returned are included in the response.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub event_context: Option<EventContext>,
+        /// A `Filter` to apply to the search.
+        // TODO: "timeline" key might need to be included.
+        // See https://github.com/matrix-org/matrix-doc/issues/598.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub filter: Option<RoomEventFilter>,
+        /// Requests that the server partitions the result set based on the provided list of keys.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub groupings: Option<Groupings>,
+        /// Requests the server return the current state for each room returned.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub include_state: Option<bool>,
+        /// The keys to search for. Defaults to all keys.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub keys: Option<Vec<SearchKeys>>,
+        /// The order in which to search for results.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub order_by: Option<OrderBy>,
+        /// The string to search events for.
+        pub search_term: String,
+    }
+
+
+    /// Details about this API endpoint.
+    #[derive(Clone, Copy, Debug)]
+    pub struct Endpoint;
+
+    /// Configures whether any context for the events returned are included in the response.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct EventContext {
+        /// How many events after the result are returned.
+        pub after_limit: u64,
+        /// How many events before the result are returned.
+        pub before_limit: u64,
+        /// Requests that the server returns the historic profile information for the users that
+        /// sent the events that were returned.
+        pub include_profile: bool,
+    }
+
+    /// Context for search results, if requested.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct EventContextResult {
+        /// Pagination token for the end of the chunk.
+        pub end: String,
+        /// Events just after the result.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub events_after: Option<Vec<Event>>,
+        /// Events just before the result.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub events_before: Option<Vec<Event>>,
+        /// The historic profile information of the users that sent the events returned.
+        // TODO: Not sure this is right. https://github.com/matrix-org/matrix-doc/issues/773
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub profile_info: Option<HashMap<UserId, UserProfile>>,
+        /// Pagination token for the start of the chunk.
+        pub start: String,
+    }
+
+    /// A grouping for partioning the result set.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct Grouping {
+        /// The key within events to use for this grouping.
+        pub key: GroupingKey
+    }
+
+    /// The key within events to use for this grouping.
+    #[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+    pub enum GroupingKey {
+        /// `room_id`
+        #[serde(rename="room_id")]
+        RoomId,
+        /// `sender`
+        #[serde(rename="sender")]
+        Sender,
+    }
+
+    /// Requests that the server partitions the result set based on the provided list of keys.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct Groupings {
+        /// List of groups to request.
+        pub group_by: Vec<Grouping>,
+    }
+
+    /// The keys to search for.
+    #[derive(Clone, Copy, Debug, Deserialize, Serialize)]
+    pub enum SearchKeys {
+        /// content.body
+        #[serde(rename="content.body")]
+        ContentBody,
+        /// content.name
+        #[serde(rename="content.name")]
+        ContentName,
+        /// content.topic
+        #[serde(rename="content.topic")]
+        ContentTopic,
+    }
+
+    /// The order in which to search for results.
+    #[derive(Clone, Copy, Debug, Deserialize, Serialize)]
+    pub enum OrderBy {
+        /// Prioritize events by a numerical ranking of how closely they matched the search
+        /// criteria.
+        #[serde(rename="rank")]
+        Rank,
+        /// Prioritize recent events.
+        #[serde(rename="recent")]
+        Recent,
+    }
+
+    /// This API endpoint's query string parameters.
+    #[derive(Clone, Debug)]
+    pub struct QueryParams {
+        /// The point to return events from.
+        ///
+        /// If given, this should be a `next_batch` result from a previous call to this endpoint.
+        pub next_batch: Option<String>,
+    }
+
+    /// This API endpoint's response.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct Response {
+        /// A grouping of search results by category.
+        pub search_categories: ResultCategories,
+    }
+
+    /// Categories of events that can be searched for.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct ResultCategories {
+        /// Room event results.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub room_events: Option<RoomEventResults>,
+    }
+
+    /// Categories of events that can be searched for.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct RoomEventResults {
+        /// An approximate count of the total number of results found.
+        pub count: u64,
+        /// Any groups that were requested.
+        // TODO: Not sure this is right. https://github.com/matrix-org/matrix-doc/issues/773
+        pub groups: HashMap<GroupingKey, HashMap<RoomId, ResultGroup>>,
+        /// Token that can be used to get the next batch of results, by passing as the `next_batch`
+        /// parameter to the next call. If this field is absent, there are no more results.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub next_batch: Option<String>,
+        /// List of results in the requested order.
+        pub results: Vec<SearchResult>,
+        /// The current state for every room in the results. This is included if the request had the
+        /// `include_state` key set with a value of `true`.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        // TODO: Major WTF here. https://github.com/matrix-org/matrix-doc/issues/773
+        pub state: Option<()>,
+    }
+
+    /// A grouping of results, if requested.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct ResultGroup {
+        /// Token that can be used to get the next batch of results in the group, by passing as the
+        /// `next_batch` parameter to the next call. If this field is absent, there are no more
+        /// results in this group.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub next_batch: Option<String>,
+        /// Key that can be used to order different groups.
+        pub order: u64,
+        /// Which results are in this group.
+        pub results: Vec<EventId>,
+    }
+
+    /// A search result.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct SearchResult {
+        /// Context for result, if requested.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub context: Option<EventContextResult>,
+        /// A number that describes how closely this result matches the search. Higher is closer.
+        pub rank: f64,
+        /// The event that matched.
+        pub result: Event,
+    }
+
+    impl ::Endpoint for Endpoint {
+        type BodyParams = BodyParams;
+        type PathParams = ();
+        type QueryParams = QueryParams;
+        type Response = Response;
+
+        fn method() -> ::Method {
+            ::Method::Post
+        }
+
+        fn request_path(_params: Self::PathParams) -> String {
+            Self::router_path()
+        }
+
+        fn router_path() -> String {
+            "/_matrix/client/r0/search".to_string()
+        }
+    }
+}