Use ruma-api-macros for the filter endpoints.

Cargo.toml

@@ -29,4 +29,4 @@ rev = "3635fe51ac31b9ff899c70a0d1218caa8cf6a8dc"
 
 [dependencies.ruma-api-macros]
 git = "https://github.com/ruma/ruma-api-macros"
-rev = "58fab938b00d01aeb5e3e8c31731b4e479d5553d"
+rev = "35362e78a6cfef346ad74c4b38c6e0611402231b"

src/lib.rs

@@ -25,7 +25,7 @@ pub mod r0 {
     pub mod contact;
     pub mod context;
     pub mod directory;
-//     pub mod filter;
+    pub mod filter;
 //     pub mod media;
 //     pub mod membership;
 //     pub mod presence;

src/r0/filter.rs

@@ -5,209 +5,231 @@ use ruma_identifiers::{RoomId, UserId};
 /// Format to use for returned events
 #[derive(Copy, Clone, Debug, Deserialize, Serialize)]
 pub enum EventFormat {
-    /// Client format, as described in the Client API
+    /// Client format, as described in the Client API.
-    #[serde(rename="client")]
+    #[serde(rename = "client")]
     Client,
-    /// Raw events from federation
+    /// Raw events from federation.
-    #[serde(rename="federation")]
+    #[serde(rename = "federation")]
-    Federation
+    Federation,
 }
 
 /// Filters to be applied to room events
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct RoomEventFilter {
+    /// A list of event types to exclude.
+    ///
+    /// If this list is absent then no event types are excluded. A matching type will be excluded
+    /// even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any
+    /// sequence of characters.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub not_types: Vec<String>,
+    /// A list of room IDs to exclude.
+    ///
+    /// If this list is absent then no rooms are excluded. A matching room will be excluded even if
+    /// it is listed in the 'rooms' filter.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub not_rooms: Vec<String>,
+    /// The maximum number of events to return.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub limit: Option<u64>,
+    /// A list of room IDs to include.
+    ///
+    /// If this list is absent then all rooms are included.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub rooms: Vec<RoomId>,
+    /// A list of sender IDs to exclude.
+    ///
+    /// If this list is absent then no senders are excluded. A matching sender will be excluded even
+    /// if it is listed in the 'senders' filter.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub not_senders: Vec<UserId>,
+    /// A list of senders IDs to include.
+    ///
+    /// If this list is absent then all senders are included.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub senders: Vec<UserId>,
+    /// A list of event types to include.
+    ///
+    /// If this list is absent then all event types are included. A '*' can be used as a wildcard to
+    /// match any sequence of characters.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
-    pub types: Vec<String>
+    pub types: Vec<String>,
 }
 
 /// Filters to be applied to room data
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct RoomFilter {
+    /// Include rooms that the user has left in the sync.
+    ///
+    /// Defaults to false if not included.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub include_leave: Option<bool>,
+    /// The per user account data to include for rooms.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub account_data: Option<RoomEventFilter>,
+    /// The message and state update events to include for rooms.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub timeline: Option<RoomEventFilter>,
+    /// The events that aren't recorded in the room history, e.g. typing and receipts, to include
+    /// for rooms.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ephemeral: Option<RoomEventFilter>,
+    /// The state events to include for rooms.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub state: Option<RoomEventFilter>,
+    /// A list of room IDs to exclude.
+    ///
+    /// If this list is absent then no rooms are excluded. A matching room will be excluded even if
+    /// it is listed in the 'rooms' filter. This filter is applied before the filters in
+    /// `ephemeral`, `state`, `timeline` or `account_data`.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub not_rooms: Vec<RoomId>,
+    /// A list of room IDs to include.
+    ///
+    /// If this list is absent then all rooms are included. This filter is applied before the
+    /// filters in `ephemeral`, `state`, `timeline` or `account_data`.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
-    pub room: Vec<RoomId>
+    pub room: Vec<RoomId>,
 }
 
 /// Filter for not-room data
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct Filter {
+    /// A list of event types to exclude.
+    ///
+    /// If this list is absent then no event types are excluded. A matching type will be excluded
+    /// even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any
+    /// sequence of characters.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub not_types: Vec<String>,
+    /// The maximum number of events to return.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub limit: Option<u64>,
+    /// A list of senders IDs to include.
+    ///
+    /// If this list is absent then all senders are included.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub senders: Vec<UserId>,
+    /// A list of event types to include.
+    ///
+    /// If this list is absent then all event types are included. A '*' can be used as a wildcard to
+    /// match any sequence of characters.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub types: Vec<String>,
+    /// A list of sender IDs to exclude.
+    ///
+    /// If this list is absent then no senders are excluded. A matching sender will be excluded even
+    /// if it is listed in the 'senders' filter.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
-    pub not_senders: Vec<UserId>
+    pub not_senders: Vec<UserId>,
 }
 
 /// A filter definition
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct FilterDefinition {
+    /// List of event fields to include.
+    ///
+    /// If this list is absent then all fields are included. The entries may include '.' charaters
+    /// to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content'
+    /// object. A literal '.' character in a field name may be escaped using a '\'. A server may
+    /// include more fields than were requested.
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde(default)]
     pub event_fields: Vec<String>,
+    /// The format to use for events.
+    ///
+    /// 'client' will return the events in a format suitable for clients. 'federation' will return
+    /// the raw event as receieved over federation. The default is 'client'.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub event_format: Option<EventFormat>,
+    /// The user account data that isn't associated with rooms to include.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub account_data: Option<Filter>,
+    /// Filters to be applied to room data.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub room: Option<RoomFilter>,
+    /// The presence updates to include.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub presence: Option<Filter>
+    pub presence: Option<Filter>,
 }
 
 /// [POST /_matrix/client/r0/user/{userId}/filter](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-user-userid-filter)
 pub mod create_filter {
+    use ruma_api_macros::ruma_api;
     use ruma_identifiers::UserId;
+
     use super::FilterDefinition;
 
-    /// Details about this API endpoint.
+    ruma_api! {
-    #[derive(Clone, Copy, Debug)]
+        metadata {
-    pub struct Endpoint;
+            description: "Create a new filter for event retrieval.",
-
+            method: Method::Post,
-    /// This API endpoint's path parameters.
+            name: "create_filter",
-    #[derive(Clone, Debug, Deserialize, Serialize)]
+            path: "/_matrix/client/r0/user/:user_id/filter",
-    pub struct PathParams {
+            rate_limited: false,
-        pub user_id: UserId
+            requires_authentication: true,
-    }
-
-    /// This API Response.
-    #[derive(Clone, Debug, Deserialize, Serialize)]
-    pub struct Response {
-        pub filter_id: String
-    }
-
-    impl ::Endpoint for Endpoint {
-        type BodyParams = FilterDefinition;
-        type PathParams = PathParams;
-        type QueryParams = ();
-        type Response = Response;
-
-        fn method() -> ::Method {
-            ::Method::Post
         }
 
-        fn request_path(params: Self::PathParams) -> String {
+        request {
-            format!(
+            /// The filter definition.
-                "/_matrix/client/r0/user/{}/filter",
+            #[ruma_api(body)]
-                params.user_id
+            pub filter: FilterDefinition,
-            )
+            /// The ID of the user uploading the filter.
+            ///
+            /// The access token must be authorized to make requests for this user ID.
+            #[ruma_api(path)]
+            pub user_id: UserId,
         }
 
-        fn router_path() -> &'static str {
+        response {
-            "/_matrix/client/r0/user/:user_id/filter"
+            /// The ID of the filter that was created.
-        }
+            pub filter_id: String,
-
-        fn name() -> &'static str {
-            "create_filter"
-        }
-
-        fn description() -> &'static str {
-            "Create a new filter for event retrieval."
-        }
-
-        fn requires_authentication() -> bool {
-            true
-        }
-
-        fn rate_limited() -> bool {
-            false
         }
     }
 }
 
 /// [GET /_matrix/client/r0/user/{userId}/filter/{filterId}](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-user-userid-filter-filterid)
 pub mod get_filter {
+    use ruma_api_macros::ruma_api;
     use ruma_identifiers::UserId;
+
     use super::FilterDefinition;
 
-    /// Details about this API endpoint.
+    ruma_api! {
-    #[derive(Clone, Copy, Debug)]
+        metadata {
-    pub struct Endpoint;
+            description: "Retrieve a previously created filter.",
-
+            method: Method::Get,
-    /// This API endpoint's path parameters.
+            name: "get_filter",
-    #[derive(Clone, Debug, Deserialize, Serialize)]
+            path: "/_matrix/client/r0/user/:user_id/filter/:filter_id",
-    pub struct PathParams {
+            rate_limited: false,
-        pub user_id: UserId,
+            requires_authentication: false,
-        pub filter_id: String
-    }
-
-    impl ::Endpoint for Endpoint {
-        type BodyParams = ();
-        type PathParams = PathParams;
-        type QueryParams = ();
-        type Response = FilterDefinition;
-
-        fn method() -> ::Method {
-            ::Method::Get
         }
 
-        fn request_path(params: Self::PathParams) -> String {
+        request {
-            format!(
+            /// The ID of the filter to download.
-                "/_matrix/client/r0/user/{}/filter/{}",
+            #[ruma_api(path)]
-                params.user_id,
+            pub filter_id: String,
-                params.filter_id
+            /// The user ID to download a filter for.
-            )
+            #[ruma_api(path)]
+            pub user_id: UserId,
         }
 
-        fn router_path() -> &'static str {
+        response {
-            "/_matrix/client/r0/user/:user_id/filter/:filter_id"
+            /// The filter definition.
-        }
+            #[ruma_api(body)]
-
+            pub filter: FilterDefinition,
-        fn name() -> &'static str {
-            "get_filter"
-        }
-
-        fn description() -> &'static str {
-            "Retrieve a previously created filter."
-        }
-
-        fn requires_authentication() -> bool {
-            // TODO: not sure why, as I guess you should not be able to retrieve
-            // other users filters?
-            false
-        }
-
-        fn rate_limited() -> bool {
-            false
         }
     }
 }