chris/ruwuma
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add missing docs, fix a bunch of bugs and inconsistencies.

Browse Source
This commit is contained in:
Jimmy Cuadra 2017-07-04 22:47:14 -07:00
parent c447a612d3
commit 6aceca259e
4 changed files with 156 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/lib.rs
View File

@ -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;

30
src/r0/room.rs
View File

@ -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<CreationContent>,
/// 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<UserId>,
/// 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<String>,
/// Convenience parameter for setting various default state events based on a preset.
#[serde(skip_serializing_if = "Option::is_none")]
pub preset: Option<RoomPreset>,
/// The desired room alias local part.
#[serde(skip_serializing_if = "Option::is_none")]
pub room_alias_name: Option<String>,
/// 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<String>,
/// 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<String>, // TODO: should be an enum ["public", "private"]
pub visibility: Option<Visibility>,
// 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<bool>,
@ -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,
}
}

33
src/r0/session.rs
View File

@ -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<LoginMedium>,
/// Type of login to do
pub medium: Option<Medium>,
/// 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<String>
}
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<String>,
/// 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 {}
}
}

137
src/r0/sync.rs
View File

@ -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<only::StateEvent>,
}
}
@ -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<MemberEvent>
}
}
@ -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
/// 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
/// 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<String>,
/// 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<u64>,
}
response {
/// The token the pagination starts from.
pub start: String,
/// A list of room events.
pub chunk: Vec<only::RoomEvent>,
/// 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<Filter>,
/// A point in time to continue a sync from.
#[serde(skip_serializing_if = "Option::is_none")]
pub since: Option<String>,
/// 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<bool>,
/// Controls whether the client is automatically marked as online by polling this API.
#[serde(skip_serializing_if = "Option::is_none")]
pub set_presence: Option<SetPresence>,
/// The maximum time to poll in milliseconds before returning this request.
#[serde(skip_serializing_if = "Option::is_none")]
pub timeout: Option<u64>,
}
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<RoomId, LeftRoom>,
/// The rooms that the user has joined.
pub join: HashMap<RoomId, JoinedRoom>,
/// The rooms that the user has been invited to.
pub invite: HashMap<RoomId, InvitedRoom>,
}
/// 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<all::StateEvent>,
}
/// 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<only::StateEvent>,
}
/// 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<only::Event>,
}
/// 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<only::Event>,
}
/// 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<only::StateEvent>,
}
/// 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<only::Event>,
}
}