From 6aceca259ec459c4992e8d4dba9abd2f72f03d0d Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Tue, 4 Jul 2017 22:47:14 -0700 Subject: [PATCH] Add missing docs, fix a bunch of bugs and inconsistencies. --- src/lib.rs | 3 +- src/r0/room.rs | 30 +++++++++- src/r0/session.rs | 33 +++++++---- src/r0/sync.rs | 141 ++++++++++++++++++++++++++++++++++------------ 4 files changed, 156 insertions(+), 51 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 85a42828..d5a123f8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,9 +2,8 @@ //! endpoint in the [Matrix](https://matrix.org/) client API specification. These types can be //! shared by client and server code. -#![deny(missing_debug_implementations)] +#![deny(missing_debug_implementations, missing_docs)] #![feature(associated_consts, proc_macro, try_from)] -#![warn(missing_docs)] extern crate futures; extern crate hyper; diff --git a/src/r0/room.rs b/src/r0/room.rs index de6fbf13..a7da4473 100644 --- a/src/r0/room.rs +++ b/src/r0/room.rs @@ -16,25 +16,39 @@ pub mod create_room { } request { + /// Extra keys to be added to the content of the `m.room.create`. #[serde(skip_serializing_if = "Option::is_none")] pub creation_content: Option, + /// A list of user IDs to invite to the room. + /// + /// This will tell the server to invite everyone in the list to the newly created room. #[serde(skip_serializing_if = "Vec::is_empty")] #[serde(default)] pub invite: Vec, + /// If this is included, an `m.room.name` event will be sent into the room to indicate + /// the name of the room. #[serde(skip_serializing_if = "Option::is_none")] pub name: Option, + /// Convenience parameter for setting various default state events based on a preset. #[serde(skip_serializing_if = "Option::is_none")] pub preset: Option, + /// The desired room alias local part. #[serde(skip_serializing_if = "Option::is_none")] pub room_alias_name: Option, + /// If this is included, an `m.room.topic` event will be sent into the room to indicate + /// the topic for the room. #[serde(skip_serializing_if = "Option::is_none")] pub topic: Option, + /// A public visibility indicates that the room will be shown in the published room + /// list. A private visibility will hide the room from the published room list. Rooms + /// default to private visibility if this key is not included. #[serde(skip_serializing_if = "Option::is_none")] - pub visibility: Option, // TODO: should be an enum ["public", "private"] + pub visibility: Option, // TODO: missing `invite_3pid`, `initial_state` } response { + /// The created room's ID. pub room_id: RoomId, } } @@ -42,6 +56,9 @@ pub mod create_room { /// Extra options to be added to the `m.room.create` event. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct CreationContent { + /// Whether users on other servers can join this room. + /// + /// Defaults to `true` if key does not exist. #[serde(rename="m.federate")] #[serde(skip_serializing_if = "Option::is_none")] pub federate: Option, @@ -60,4 +77,15 @@ pub mod create_room { #[serde(rename="trusted_private_chat")] TrustedPrivateChat, } + + /// Whether or not a newly created room will be listed in the room directory. + #[derive(Clone, Copy, Debug, Deserialize, Serialize)] + pub enum Visibility { + /// Indicates that the room will be shown in the published room list. + #[serde(rename = "public")] + Public, + /// Indicates that the room from the published room list. + #[serde(rename = "private")] + Private, + } } diff --git a/src/r0/session.rs b/src/r0/session.rs index 63285be2..c74a850e 100644 --- a/src/r0/session.rs +++ b/src/r0/session.rs @@ -13,40 +13,49 @@ pub mod login { rate_limited: true, requires_authentication: false, } + request { - /// Password of the user + /// The user's password. pub password: String, - /// Medium of 3rd party login to use + /// When logging in using a third party identifier, the medium of the identifier. #[serde(skip_serializing_if = "Option::is_none")] - pub medium: Option, - /// Type of login to do + pub medium: Option, + /// The authentication mechanism. #[serde(rename = "type")] - pub kind: LoginKind, - /// Localpart or full matrix user id of the user + pub login_type: LoginType, + /// The fully qualified user ID or just local part of the user ID. pub user: String, - /// 3rd party identifier for the user + /// Third party identifier for the user. #[serde(skip_serializing_if = "Option::is_none")] pub address: Option } + response { + /// An access token for the account. pub access_token: String, + /// The hostname of the homeserver on which the account has been registered. pub home_server: String, + /// A refresh token may be exchanged for a new access token using the /tokenrefresh API + /// endpoint. #[serde(skip_serializing_if = "Option::is_none")] pub refresh_token: Option, + /// The fully-qualified Matrix ID that has been registered. pub user_id: String, } } - /// Possible login mediums for 3rd party ID + /// The medium of a third party identifier. #[derive(Clone, Debug, Deserialize, Serialize)] - pub enum LoginMedium { + pub enum Medium { + /// An email address. #[serde(rename = "email")] Email, } - /// Possible kinds of login + /// The authentication mechanism. #[derive(Clone, Debug, Deserialize, Serialize)] - pub enum LoginKind { + pub enum LoginType { + /// A password is supplied to authenticate. #[serde(rename = "m.login.password")] Password, } @@ -65,7 +74,9 @@ pub mod logout { rate_limited: false, requires_authentication: true, } + request {} + response {} } } diff --git a/src/r0/sync.rs b/src/r0/sync.rs index 87ff903a..b846f99a 100644 --- a/src/r0/sync.rs +++ b/src/r0/sync.rs @@ -3,8 +3,8 @@ /// [GET /_matrix/client/r0/rooms/{roomId}/state](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-state) pub mod get_state_events { use ruma_api_macros::ruma_api; - use ruma_identifiers::RoomId; use ruma_events::collections::only; + use ruma_identifiers::RoomId; ruma_api! { metadata { @@ -15,11 +15,18 @@ pub mod get_state_events { rate_limited: false, requires_authentication: true, } + request { + /// The room to look up the state for. #[ruma_api(path)] pub room_id: RoomId, } + response { + /// If the user is a member of the room this will be the current state of the room as a + /// list of events. If the user has left the room then this will be the state of the + /// room when they left as a list of events. + #[ruma_api(body)] pub room_state: Vec, } } @@ -28,8 +35,8 @@ pub mod get_state_events { /// [GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-state-eventtype) pub mod get_state_events_for_empty_key { use ruma_api_macros::ruma_api; - use ruma_identifiers::RoomId; use ruma_events::EventType; + use ruma_identifiers::RoomId; ruma_api! { metadata { @@ -40,15 +47,19 @@ pub mod get_state_events_for_empty_key { rate_limited: false, requires_authentication: true, } + request { - /// The room to query for events + /// The room to look up the state for. #[ruma_api(path)] pub room_id: RoomId, - /// The type of state to look up + /// The type of state to look up. #[ruma_api(path)] pub event_type: EventType, } + response { + /// The content of the state event. + #[ruma_api(body)] pub content: ::serde_json::Value, } } @@ -68,8 +79,9 @@ pub mod get_state_events_for_key { rate_limited: false, requires_authentication: true, } + request { - /// The room to look up the state in. + /// The room to look up the state for. #[ruma_api(path)] pub room_id: RoomId, /// The type of state to look up. @@ -79,7 +91,10 @@ pub mod get_state_events_for_key { #[ruma_api(path)] pub state_key: String, } + response { + /// The content of the state event. + #[ruma_api(body)] pub content: ::serde_json::Value, } } @@ -88,8 +103,8 @@ pub mod get_state_events_for_key { /// [GET /_matrix/client/r0/rooms/{roomId}/members](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-members) pub mod get_member_events { use ruma_api_macros::ruma_api; - use ruma_identifiers::RoomId; use ruma_events::room::member::MemberEvent; + use ruma_identifiers::RoomId; ruma_api! { metadata { @@ -103,12 +118,15 @@ pub mod get_member_events { // will return a 403 error is user is not a member of the // room anyway... } + request { - /// The room to look up the state in. + /// The room to get the member events for. #[ruma_api(path)] pub room_id: RoomId, } + response { + /// A list of member events. pub chunk: Vec } } @@ -117,8 +135,8 @@ pub mod get_member_events { /// [GET /_matrix/client/r0/rooms/{roomId}/messages](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-messages) pub mod get_message_events { use ruma_api_macros::ruma_api; - use ruma_identifiers::RoomId; use ruma_events::collections::only; + use ruma_identifiers::RoomId; ruma_api! { metadata { @@ -129,38 +147,50 @@ pub mod get_message_events { rate_limited: false, requires_authentication: true, } + request { - // NOTE: The non-macro version of this call included two path params, where the spec only - // has one, room_id. I've followed the spec here. -- rschulman 6/30/2017 - /// The room to look up the state in. + /// The room to get events from. #[ruma_api(path)] pub room_id: RoomId, - /// Required. The token to start returning events from. This token can be obtained from a - /// prev_batch token returned for each room by the sync API, or from a start or end token + /// The token to start returning events from. + /// + /// This token can be obtained from a + /// prev_batch token returned for each room by the sync API, or from a start or end token /// returned by a previous request to this endpoint. pub from: String, - /// The token to stop returning events at. This token can be obtained from a prev_batch - /// token returned for each room by the sync endpoint, or from a start or end token returned + /// The token to stop returning events at. + /// + /// This token can be obtained from a prev_batch + /// token returned for each room by the sync endpoint, or from a start or end token returned /// by a previous request to this endpoint. #[serde(skip_serializing_if = "Option::is_none")] pub to: Option, - /// Required. The direction to return events from. One of: ["b", "f"] + /// The direction to return events from. pub dir: Direction, - /// The maximum number of events to return. Default: 10. + /// The maximum number of events to return. + /// + /// Default: 10. #[serde(skip_serializing_if = "Option::is_none")] pub limit: Option, } + response { + /// The token the pagination starts from. pub start: String, + /// A list of room events. pub chunk: Vec, + /// The token the pagination ends at. pub end: String, } } + /// The direction to return events from. #[derive(Clone, Debug, Deserialize, Serialize)] pub enum Direction { + /// Return events backwards in time from the requested `from` token. #[serde(rename="b")] Backward, + /// Return events forwards in time from the requested `from` token. #[serde(rename="f")] Forward, } @@ -168,12 +198,12 @@ pub mod get_message_events { /// [GET /_matrix/client/r0/sync](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-sync) pub mod sync_events { - use ruma_api_macros::ruma_api; - use ruma_events::collections::only; - use ruma_identifiers::RoomId; - use std::collections::HashMap; + use ruma_api_macros::ruma_api; + use ruma_events::collections::{all, only}; + use ruma_identifiers::RoomId; + use r0::filter::FilterDefinition; ruma_api! { @@ -185,21 +215,31 @@ pub mod sync_events { rate_limited: false, requires_authentication: true, } + request { + /// A filter represented either as its full JSON definition or the ID of a saved filter. #[serde(skip_serializing_if = "Option::is_none")] pub filter: Option, + /// A point in time to continue a sync from. #[serde(skip_serializing_if = "Option::is_none")] pub since: Option, + /// Controls whether to include the full state for all rooms the user is a member of. #[serde(skip_serializing_if = "Option::is_none")] pub full_state: Option, + /// Controls whether the client is automatically marked as online by polling this API. #[serde(skip_serializing_if = "Option::is_none")] pub set_presence: Option, + /// The maximum time to poll in milliseconds before returning this request. #[serde(skip_serializing_if = "Option::is_none")] pub timeout: Option, } + response { + /// The batch token to supply in the `since` param of the next `/sync` request. pub next_batch: String, + /// Updates to rooms. pub rooms: Rooms, + /// Updates to the presence status of other users. pub presence: Presence, } @@ -208,6 +248,7 @@ pub mod sync_events { /// Whether to set presence or not during sync. #[derive(Clone, Debug, Deserialize, Serialize)] pub enum SetPresence { + /// Do not set the presence of the user calling this API. #[serde(rename="offline")] Offline, } @@ -221,79 +262,105 @@ pub mod sync_events { FilterId(String), } - /// Updates to rooms + /// Updates to rooms. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct Rooms { + /// The rooms that the user has left or been banned from. pub leave: HashMap, + /// The rooms that the user has joined. pub join: HashMap, + /// The rooms that the user has been invited to. pub invite: HashMap, } - /// Historical updates to left rooms + /// Historical updates to left rooms. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct LeftRoom { + /// The timeline of messages and state changes in the room up to the point when the user + /// left. pub timeline: Timeline, + /// The state updates for the room up to the start of the timeline. pub state: State, } - /// Updates to joined rooms + /// Updates to joined rooms. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct JoinedRoom { + /// Counts of unread notifications for this room. pub unread_notifications: UnreadNotificationsCount, + /// The timeline of messages and state changes in the room. pub timeline: Timeline, + /// Updates to the state, between the time indicated by the `since` parameter, and the start + /// of the `timeline` (or all state up to the start of the `timeline`, if `since` is not + /// given, or `full_state` is true). pub state: State, + /// The private data that this user has attached to this room. pub account_data: AccountData, + /// The ephemeral events in the room that aren't recorded in the timeline or state of the + /// room. e.g. typing. pub ephemeral: Ephemeral, } /// unread notifications count #[derive(Clone, Debug, Deserialize, Serialize)] pub struct UnreadNotificationsCount { + /// The number of unread notifications for this room with the highlight flag set. pub highlight_count: u64, + /// The total number of unread notifications for this room. pub notification_count: u64, } - /// timeline + /// Events in the room. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct Timeline { + /// True if the number of events returned was limited by the `limit` on the filter. pub limited: bool, + /// A token that can be supplied to to the `from` parameter of the + /// `/rooms/{roomId}/messages` endpoint. pub prev_batch: String, - pub events: only::RoomEvent, + /// A list of events. + pub events: Vec, } - /// state + /// State events in the room. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct State { - pub events: only::StateEvent, + /// A list of state events. + pub events: Vec, } - /// account data + /// The private data that this user has attached to this room. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct AccountData { - pub events: only::Event, + /// A list of events. + pub events: Vec, } - /// ephemeral + /// Ephemeral events not recorded in the timeline or state of the room. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct Ephemeral { - pub events: only::Event, + /// A list of events. + pub events: Vec, } - /// invited room updates + /// Updates to the rooms that the user has been invited to. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct InvitedRoom { + /// The state of a room that the user has been invited to. pub invite_state: InviteState, } - /// invite state + /// The state of a room that the user has been invited to. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct InviteState { - pub events: only::StateEvent, + /// A list of state events. + pub events: Vec, } - /// presence + /// Updates to the presence status of other users. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct Presence { - pub events: only::Event, + /// A list of events. + pub events: Vec, } }