nero/tsuki
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

docs: documentation for every endpoint

Browse source
This commit is contained in:
Timo Kösters 2021-08-31 19:14:37 +02:00
parent 364820aae4
commit b9eb39a9c6
No known key found for this signature in database
GPG key ID: 24DA7517711A2BA4
35 changed files with 847 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

60
src/client_server/membership.rs
View file

@ -38,6 +38,12 @@ use tracing::{debug, error, warn};
#[cfg(feature = "conduit_bin")]
use rocket::{get, post};
/// # `POST /_matrix/client/r0/rooms/{roomId}/join`
///
/// Tries to join the sender user into a room.
///
/// - If the server knowns about this room: creates the join event and does auth rules locally
/// - If the server does not know about the room: asks other servers over federation
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/join", data = "<body>")
@ -79,6 +85,12 @@ pub async fn join_room_by_id_route(
ret
}
/// # `POST /_matrix/client/r0/join/{roomIdOrAlias}`
///
/// Tries to join the sender user into a room.
///
/// - If the server knowns about this room: creates the join event and does auth rules locally
/// - If the server does not know about the room: asks other servers over federation
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/join/<_>", data = "<body>")
@ -133,6 +145,11 @@ pub async fn join_room_by_id_or_alias_route(
.into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/leave`
///
/// Tries to leave the sender user from a room.
///
/// - This should always work if the user is currently joined.
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/leave", data = "<body>")
@ -151,6 +168,9 @@ pub async fn leave_room_route(
Ok(leave_room::Response::new().into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/invite`
///
/// Tries to send an invite event into the room.
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/invite", data = "<body>")
@ -171,6 +191,9 @@ pub async fn invite_user_route(
}
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/kick`
///
/// Tries to send a kick event into the room.
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/kick", data = "<body>")
@ -234,6 +257,9 @@ pub async fn kick_user_route(
Ok(kick_user::Response::new().into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/ban`
///
/// Tries to send a ban event into the room.
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/ban", data = "<body>")
@ -307,6 +333,9 @@ pub async fn ban_user_route(
Ok(ban_user::Response::new().into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/unban`
///
/// Tries to send an unban event into the room.
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/unban", data = "<body>")
@ -369,6 +398,14 @@ pub async fn unban_user_route(
Ok(unban_user::Response::new().into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/forget`
///
/// Forgets about a room.
///
/// - If the sender user currently left the room: Stops sender user from receiving information about the room
///
/// Note: Other devices of the user have no way of knowing the room was forgotten, so this has to
/// be called from every device
#[cfg_attr(
feature = "conduit_bin",
post("/_matrix/client/r0/rooms/<_>/forget", data = "<body>")
@ -387,6 +424,9 @@ pub async fn forget_room_route(
Ok(forget_room::Response::new().into())
}
/// # `POST /_matrix/client/r0/joined_rooms`
///
/// Lists all rooms the user has joined.
#[cfg_attr(
feature = "conduit_bin",
get("/_matrix/client/r0/joined_rooms", data = "<body>")
@ -408,6 +448,11 @@ pub async fn joined_rooms_route(
.into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/members`
///
/// Lists all joined users in a room (TODO: at a specific point in time, with a specific membership).
///
/// - Only works if the user is currently joined
#[cfg_attr(
feature = "conduit_bin",
get("/_matrix/client/r0/rooms/<_>/members", data = "<body>")
@ -419,6 +464,7 @@ pub async fn get_member_events_route(
) -> ConduitResult<get_member_events::Response> {
let sender_user = body.sender_user.as_ref().expect("user is authenticated");
// TODO: check history visibility?
if !db.rooms.is_joined(sender_user, &body.room_id)? {
return Err(Error::BadRequest(
ErrorKind::Forbidden,
@ -438,6 +484,12 @@ pub async fn get_member_events_route(
.into())
}
/// # `POST /_matrix/client/r0/rooms/{roomId}/joined_members`
///
/// Lists all members of a room.
///
/// - The sender user must be in the room
/// - TODO: An appservice just needs a puppet joined
#[cfg_attr(
feature = "conduit_bin",
get("/_matrix/client/r0/rooms/<_>/joined_members", data = "<body>")
@ -449,11 +501,7 @@ pub async fn joined_members_route(
) -> ConduitResult<joined_members::Response> {
let sender_user = body.sender_user.as_ref().expect("user is authenticated");
if !db
.rooms
.is_joined(&sender_user, &body.room_id)
.unwrap_or(false)
{
if !db.rooms.is_joined(&sender_user, &body.room_id)? {
return Err(Error::BadRequest(
ErrorKind::Forbidden,
"You aren't a member of the room.",
@ -803,7 +851,7 @@ async fn validate_and_add_event_id(
Ok((event_id, value))
}
pub async fn invite_helper<'a>(
pub(crate) async fn invite_helper<'a>(
sender_user: &UserId,
user_id: &UserId,
room_id: &RoomId,