docs: endpoint documentation

4 years ago · f40f1d9f75
parent cfda76860b
commit f40f1d9f75
6 changed files with 83 additions and 3 deletions
--- 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 = "<body>")
@ -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 = "<body>")
@ -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 = "<body>")
@ -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 = "<body>")
@ -237,6 +264,14 @@ pub fn whoami_route(body: Ruma<whoami::Request>) -> ConduitResult<whoami::Respon
    .into())
 }

+/// # `POST /_matrix/client/r0/account/deactivate`
+///
+/// Deactivate this user's account
+///
+/// - Leaves all rooms and rejects all invitations
+/// - Invalidates all access tokens
+/// - Deletes all devices
+/// - Removes ability to log in again
 #[cfg_attr(
    feature = "conduit_bin",
    post("/_matrix/client/r0/account/deactivate", data = "<body>")
--- a/src/client_server/capabilities.rs
+++ b/src/client_server/capabilities.rs
@ -5,6 +5,9 @@ use std::collections::BTreeMap;
 #[cfg(feature = "conduit_bin")]
 use rocket::get;

+/// # `GET /_matrix/client/r0/capabilities`
+///
+/// Get information on this server's supported feature set and other relevent capabilities.
 #[cfg_attr(feature = "conduit_bin", get("/_matrix/client/r0/capabilities"))]
 pub fn get_capabilities_route() -> ConduitResult<get_capabilities::Response> {
    let mut available = BTreeMap::new();
--- 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<get_login_types::Response> {
+pub fn get_login_types_route() -> ConduitResult<get_login_types::Response> {
    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 = "<body>")
@ -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 = "<body>")
@ -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 = "<body>")
--- 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<get_supported_versions::Response> {
    let mut unstable_features = BTreeMap::new();
--- 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
--- 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,