char/conduit
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: endpoint documentation

Browse source
This commit is contained in:
timokoesters 2020-07-31 14:40:28 +02:00 committed by Timo
parent cfda76860b
commit f40f1d9f75
No known key found for this signature in database
GPG key ID: 24DA7517711A2BA4
6 changed files with 83 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
src/client_server/account.rs
View file

@ -20,6 +20,12 @@ use rocket::{get, post};
const GUEST_NAME_LENGTH: usize = 10; 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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
get("/_matrix/client/r0/register/available", data = "<body>") 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()) 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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
post("/_matrix/client/r0/register", data = "<body>") post("/_matrix/client/r0/register", data = "<body>")
@ -168,6 +183,13 @@ pub fn register_route(
.into()) .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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
post("/_matrix/client/r0/account/password", data = "<body>") post("/_matrix/client/r0/account/password", data = "<body>")
@ -225,6 +247,11 @@ pub fn change_password_route(
Ok(change_password::Response.into()) Ok(change_password::Response.into())
} }
/// # `GET _matrix/client/r0/account/whoami`
///
/// Get user_id of this account.
///
/// - Also works for Application Services
#[cfg_attr( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
get("/_matrix/client/r0/account/whoami", data = "<body>") get("/_matrix/client/r0/account/whoami", data = "<body>")
@ -237,6 +264,14 @@ pub fn whoami_route(body: Ruma<whoami::Request>) -> ConduitResult<whoami::Respon
.into()) .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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
post("/_matrix/client/r0/account/deactivate", data = "<body>") post("/_matrix/client/r0/account/deactivate", data = "<body>")

3
src/client_server/capabilities.rs
View file

@ -5,6 +5,9 @@ use std::collections::BTreeMap;
#[cfg(feature = "conduit_bin")] #[cfg(feature = "conduit_bin")]
use rocket::get; 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"))] #[cfg_attr(feature = "conduit_bin", get("/_matrix/client/r0/capabilities"))]
pub fn get_capabilities_route() -> ConduitResult<get_capabilities::Response> { pub fn get_capabilities_route() -> ConduitResult<get_capabilities::Response> {
let mut available = BTreeMap::new(); let mut available = BTreeMap::new();

32
src/client_server/session.rs
View file

@ -12,14 +12,28 @@ use ruma::{
#[cfg(feature = "conduit_bin")] #[cfg(feature = "conduit_bin")]
use rocket::{get, post}; 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"))] #[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 { Ok(get_login_types::Response {
flows: vec![get_login_types::LoginType::Password], flows: vec![get_login_types::LoginType::Password],
} }
.into()) .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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
post("/_matrix/client/r0/login", data = "<body>") post("/_matrix/client/r0/login", data = "<body>")
@ -74,6 +88,7 @@ pub fn login_route(
// Generate a new token for the device // Generate a new token for the device
let token = utils::random_string(TOKEN_LENGTH); let token = utils::random_string(TOKEN_LENGTH);
// TODO: Don't always create a new device
// Add device // Add device
db.users.create_device( db.users.create_device(
&user_id, &user_id,
@ -92,6 +107,12 @@ pub fn login_route(
.into()) .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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
post("/_matrix/client/r0/logout", data = "<body>") post("/_matrix/client/r0/logout", data = "<body>")
@ -108,6 +129,15 @@ pub fn logout_route(
Ok(logout::Response.into()) 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( #[cfg_attr(
feature = "conduit_bin", feature = "conduit_bin",
post("/_matrix/client/r0/logout/all", data = "<body>") post("/_matrix/client/r0/logout/all", data = "<body>")

10
src/client_server/unversioned.rs
View file

@ -5,6 +5,16 @@ use std::collections::BTreeMap;
#[cfg(feature = "conduit_bin")] #[cfg(feature = "conduit_bin")]
use rocket::get; 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"))] #[cfg_attr(feature = "conduit_bin", get("/_matrix/client/versions"))]
pub fn get_supported_versions_route() -> ConduitResult<get_supported_versions::Response> { pub fn get_supported_versions_route() -> ConduitResult<get_supported_versions::Response> {
let mut unstable_features = BTreeMap::new(); let mut unstable_features = BTreeMap::new();

4
src/database/users.rs
View file

@ -859,7 +859,9 @@ impl Users {
self.remove_device(&user_id, &device_id?)?; 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(), "")?; self.userid_password.insert(user_id.to_string(), "")?;
// TODO: Unhook 3PID // TODO: Unhook 3PID

2
src/main.rs
View file

@ -26,7 +26,7 @@ fn setup_rocket() -> rocket::Rocket {
client_server::get_supported_versions_route, client_server::get_supported_versions_route,
client_server::get_register_available_route, client_server::get_register_available_route,
client_server::register_route, client_server::register_route,
client_server::get_login_route, client_server::get_login_types_route,
client_server::login_route, client_server::login_route,
client_server::whoami_route, client_server::whoami_route,
client_server::logout_route, client_server::logout_route,