From 392dc69b1732c69e56ad63c1f9928c9481574f9b Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Sun, 21 May 2017 02:19:54 -0700 Subject: [PATCH] Use ruma-api-macros for the filter endpoints. --- Cargo.toml | 2 +- src/lib.rs | 2 +- src/r0/filter.rs | 224 ++++++++++++++++++++++++++--------------------- 3 files changed, 125 insertions(+), 103 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 8b6af2fc..62cf9ec1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -29,4 +29,4 @@ rev = "3635fe51ac31b9ff899c70a0d1218caa8cf6a8dc" [dependencies.ruma-api-macros] git = "https://github.com/ruma/ruma-api-macros" -rev = "58fab938b00d01aeb5e3e8c31731b4e479d5553d" +rev = "35362e78a6cfef346ad74c4b38c6e0611402231b" diff --git a/src/lib.rs b/src/lib.rs index ec0780b0..1ec0e41f 100644 --- a/src/lib.rs +++ b/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; diff --git a/src/r0/filter.rs b/src/r0/filter.rs index dac73e7e..4ee3265a 100644 --- a/src/r0/filter.rs +++ b/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 - #[serde(rename="client")] + /// Client format, as described in the Client API. + #[serde(rename = "client")] Client, - /// Raw events from federation - #[serde(rename="federation")] - Federation + /// Raw events from federation. + #[serde(rename = "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, + /// 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, + /// The maximum number of events to return. #[serde(skip_serializing_if = "Option::is_none")] pub limit: Option, + /// 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, + /// 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, + /// 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, + /// 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 + pub types: Vec, } /// 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, + /// The per user account data to include for rooms. #[serde(skip_serializing_if = "Option::is_none")] pub account_data: Option, + /// The message and state update events to include for rooms. #[serde(skip_serializing_if = "Option::is_none")] pub timeline: Option, + /// 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, + /// The state events to include for rooms. #[serde(skip_serializing_if = "Option::is_none")] pub state: Option, + /// 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, + /// 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 + pub room: Vec, } /// 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, + /// The maximum number of events to return. #[serde(skip_serializing_if = "Option::is_none")] pub limit: Option, + /// 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, + /// 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, + /// 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 + pub not_senders: Vec, } /// 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, + /// 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, + /// The user account data that isn't associated with rooms to include. #[serde(skip_serializing_if = "Option::is_none")] pub account_data: Option, + /// Filters to be applied to room data. #[serde(skip_serializing_if = "Option::is_none")] pub room: Option, + /// The presence updates to include. #[serde(skip_serializing_if = "Option::is_none")] - pub presence: Option + pub presence: Option, } /// [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. - #[derive(Clone, Copy, Debug)] - pub struct Endpoint; - - /// This API endpoint's path parameters. - #[derive(Clone, Debug, Deserialize, Serialize)] - pub struct PathParams { - pub user_id: UserId - } - - /// 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 + ruma_api! { + metadata { + description: "Create a new filter for event retrieval.", + method: Method::Post, + name: "create_filter", + path: "/_matrix/client/r0/user/:user_id/filter", + rate_limited: false, + requires_authentication: true, } - fn request_path(params: Self::PathParams) -> String { - format!( - "/_matrix/client/r0/user/{}/filter", - params.user_id - ) + request { + /// The filter definition. + #[ruma_api(body)] + 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 { - "/_matrix/client/r0/user/:user_id/filter" - } - - 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 + response { + /// The ID of the filter that was created. + pub filter_id: String, } } } /// [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. - #[derive(Clone, Copy, Debug)] - pub struct Endpoint; - - /// This API endpoint's path parameters. - #[derive(Clone, Debug, Deserialize, Serialize)] - pub struct PathParams { - pub user_id: UserId, - pub filter_id: String - } - - impl ::Endpoint for Endpoint { - type BodyParams = (); - type PathParams = PathParams; - type QueryParams = (); - type Response = FilterDefinition; - - fn method() -> ::Method { - ::Method::Get + ruma_api! { + metadata { + description: "Retrieve a previously created filter.", + method: Method::Get, + name: "get_filter", + path: "/_matrix/client/r0/user/:user_id/filter/:filter_id", + rate_limited: false, + requires_authentication: false, } - fn request_path(params: Self::PathParams) -> String { - format!( - "/_matrix/client/r0/user/{}/filter/{}", - params.user_id, - params.filter_id - ) + request { + /// The ID of the filter to download. + #[ruma_api(path)] + pub filter_id: String, + /// The user ID to download a filter for. + #[ruma_api(path)] + pub user_id: UserId, } - fn router_path() -> &'static str { - "/_matrix/client/r0/user/:user_id/filter/:filter_id" - } - - 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 + response { + /// The filter definition. + #[ruma_api(body)] + pub filter: FilterDefinition, } } }