From f40f1d9f7528c72c2b1bc40d9e36e5ebaa6235d0 Mon Sep 17 00:00:00 2001 From: timokoesters Date: Fri, 31 Jul 2020 14:40:28 +0200 Subject: [PATCH] docs: endpoint documentation --- src/client_server/account.rs | 35 +++++++++++++++++++++++++++++++ src/client_server/capabilities.rs | 3 +++ src/client_server/session.rs | 32 +++++++++++++++++++++++++++- src/client_server/unversioned.rs | 10 +++++++++ src/database/users.rs | 4 +++- src/main.rs | 2 +- 6 files changed, 83 insertions(+), 3 deletions(-) diff --git a/src/client_server/account.rs b/src/client_server/account.rs index 8764446..15efab8 100644 --- a/src/client_server/account.rs +++ b/src/client_server/account.rs @@ -20,6 +20,12 @@ use rocket::{get, post}; const GUEST_NAME_LENGTH: usize = 10; +/// # `GET /_matrix/client/r0/register/available` +/// +/// Checks if a username is valid and available on this server. +/// +/// - Returns true if no user or appservice on this server claimed this username +/// - This will not reserve the username, so the username might become invalid when trying to register #[cfg_attr( feature = "conduit_bin", get("/_matrix/client/r0/register/available", data = "") @@ -53,6 +59,15 @@ pub fn get_register_available_route( Ok(get_username_availability::Response { available: true }.into()) } +/// # `GET /_matrix/client/r0/register` +/// +/// Register an account on this homeserver. +/// +/// - Returns the device id and access_token unless `inhibit_login` is true +/// - When registering a guest account, all parameters except initial_device_display_name will be +/// ignored +/// - Creates a new account and a device for it +/// - The account will be populated with default account data #[cfg_attr( feature = "conduit_bin", post("/_matrix/client/r0/register", data = "") @@ -168,6 +183,13 @@ pub fn register_route( .into()) } +/// # `POST /_matrix/client/r0/account/password` +/// +/// Changes the password of this account. +/// +/// - Invalidates all other access tokens if logout_devices is true +/// - Deletes all other devices and most of their data (to-device events, last seen, etc.) if +/// logout_devices is true #[cfg_attr( feature = "conduit_bin", post("/_matrix/client/r0/account/password", data = "") @@ -225,6 +247,11 @@ pub fn change_password_route( Ok(change_password::Response.into()) } +/// # `GET _matrix/client/r0/account/whoami` +/// +/// Get user_id of this account. +/// +/// - Also works for Application Services #[cfg_attr( feature = "conduit_bin", get("/_matrix/client/r0/account/whoami", data = "") @@ -237,6 +264,14 @@ pub fn whoami_route(body: Ruma) -> ConduitResult ConduitResult { let mut available = BTreeMap::new(); diff --git a/src/client_server/session.rs b/src/client_server/session.rs index a431d23..4011058 100644 --- a/src/client_server/session.rs +++ b/src/client_server/session.rs @@ -12,14 +12,28 @@ use ruma::{ #[cfg(feature = "conduit_bin")] use rocket::{get, post}; +/// # `GET /_matrix/client/r0/login` +/// +/// Get the homeserver's supported login types. One of these should be used as the `type` field +/// when logging in. #[cfg_attr(feature = "conduit_bin", get("/_matrix/client/r0/login"))] -pub fn get_login_route() -> ConduitResult { +pub fn get_login_types_route() -> ConduitResult { Ok(get_login_types::Response { flows: vec![get_login_types::LoginType::Password], } .into()) } +/// # `POST /_matrix/client/r0/login` +/// +/// Authenticates the user and returns an access token it can use in subsequent requests. +/// +/// - The returned access token is associated with the user and device +/// - Old access tokens of that device should be invalidated +/// - If `device_id` is unknown, a new device will be created +/// +/// Note: You can use [`GET /_matrix/client/r0/login`](fn.get_supported_versions_route.html) to see +/// supported login types. #[cfg_attr( feature = "conduit_bin", post("/_matrix/client/r0/login", data = "") @@ -74,6 +88,7 @@ pub fn login_route( // Generate a new token for the device let token = utils::random_string(TOKEN_LENGTH); + // TODO: Don't always create a new device // Add device db.users.create_device( &user_id, @@ -92,6 +107,12 @@ pub fn login_route( .into()) } +/// # `POST /_matrix/client/r0/logout` +/// +/// Log out the current device. +/// +/// - Invalidates the access token +/// - Deletes the device and most of it's data (to-device events, last seen, etc.) #[cfg_attr( feature = "conduit_bin", post("/_matrix/client/r0/logout", data = "") @@ -108,6 +129,15 @@ pub fn logout_route( Ok(logout::Response.into()) } +/// # `POST /_matrix/client/r0/logout/all` +/// +/// Log out all devices of this user. +/// +/// - Invalidates all access tokens +/// - Deletes devices and most of their data (to-device events, last seen, etc.) +/// +/// Note: This is equivalent to calling [`GET /_matrix/client/r0/logout`](fn.logout_route.html) +/// from each device of this user. #[cfg_attr( feature = "conduit_bin", post("/_matrix/client/r0/logout/all", data = "") diff --git a/src/client_server/unversioned.rs b/src/client_server/unversioned.rs index e71c194..3ff8bec 100644 --- a/src/client_server/unversioned.rs +++ b/src/client_server/unversioned.rs @@ -5,6 +5,16 @@ use std::collections::BTreeMap; #[cfg(feature = "conduit_bin")] use rocket::get; +/// # `GET /_matrix/client/versions` +/// +/// Get the versions of the specification and unstable features supported by this server. +/// +/// - Versions take the form MAJOR.MINOR.PATCH +/// - Only the latest PATCH release will be reported for each MAJOR.MINOR value +/// - Unstable features should be namespaced and may include version information in their name +/// +/// Note: Unstable features are used while developing new features. Clients should avoid using +/// unstable features in their stable releases #[cfg_attr(feature = "conduit_bin", get("/_matrix/client/versions"))] pub fn get_supported_versions_route() -> ConduitResult { let mut unstable_features = BTreeMap::new(); diff --git a/src/database/users.rs b/src/database/users.rs index 594cc2d..2500b4c 100644 --- a/src/database/users.rs +++ b/src/database/users.rs @@ -859,7 +859,9 @@ impl Users { self.remove_device(&user_id, &device_id?)?; } - // Set the password to "" to indicate a deactivated account + // Set the password to "" to indicate a deactivated account. Hashes will never result in an + // empty string, so the user will not be able to log in again. Systems like changing the + // password without logging in should check if the account is deactivated. self.userid_password.insert(user_id.to_string(), "")?; // TODO: Unhook 3PID diff --git a/src/main.rs b/src/main.rs index f91a10f..c7cd837 100644 --- a/src/main.rs +++ b/src/main.rs @@ -26,7 +26,7 @@ fn setup_rocket() -> rocket::Rocket { client_server::get_supported_versions_route, client_server::get_register_available_route, client_server::register_route, - client_server::get_login_route, + client_server::get_login_types_route, client_server::login_route, client_server::whoami_route, client_server::logout_route,