mas_handlers/admin/v1/users/
list.rs

1// Copyright 2024 New Vector Ltd.
2// Copyright 2024 The Matrix.org Foundation C.I.C.
3//
4// SPDX-License-Identifier: AGPL-3.0-only
5// Please see LICENSE in the repository root for full details.
6
7use aide::{OperationIo, transform::TransformOperation};
8use axum::{
9    Json,
10    extract::{Query, rejection::QueryRejection},
11    response::IntoResponse,
12};
13use axum_macros::FromRequestParts;
14use hyper::StatusCode;
15use mas_axum_utils::record_error;
16use mas_storage::{Page, user::UserFilter};
17use schemars::JsonSchema;
18use serde::Deserialize;
19
20use crate::{
21    admin::{
22        call_context::CallContext,
23        model::{Resource, User},
24        params::Pagination,
25        response::{ErrorResponse, PaginatedResponse},
26    },
27    impl_from_error_for_route,
28};
29
30#[derive(Deserialize, JsonSchema, Clone, Copy)]
31#[serde(rename_all = "snake_case")]
32enum UserStatus {
33    Active,
34    Locked,
35    Deactivated,
36}
37
38impl std::fmt::Display for UserStatus {
39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
40        match self {
41            Self::Active => write!(f, "active"),
42            Self::Locked => write!(f, "locked"),
43            Self::Deactivated => write!(f, "deactivated"),
44        }
45    }
46}
47
48#[derive(FromRequestParts, Deserialize, JsonSchema, OperationIo)]
49#[serde(rename = "UserFilter")]
50#[aide(input_with = "Query<FilterParams>")]
51#[from_request(via(Query), rejection(RouteError))]
52pub struct FilterParams {
53    /// Retrieve users with (or without) the `admin` flag set
54    #[serde(rename = "filter[admin]")]
55    admin: Option<bool>,
56
57    /// Retrieve the items with the given status
58    ///
59    /// Defaults to retrieve all users, including locked ones.
60    ///
61    /// * `active`: Only retrieve active users
62    ///
63    /// * `locked`: Only retrieve locked users (includes deactivated users)
64    ///
65    /// * `deactivated`: Only retrieve deactivated users
66    #[serde(rename = "filter[status]")]
67    status: Option<UserStatus>,
68}
69
70impl std::fmt::Display for FilterParams {
71    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
72        let mut sep = '?';
73
74        if let Some(admin) = self.admin {
75            write!(f, "{sep}filter[admin]={admin}")?;
76            sep = '&';
77        }
78        if let Some(status) = self.status {
79            write!(f, "{sep}filter[status]={status}")?;
80            sep = '&';
81        }
82
83        let _ = sep;
84        Ok(())
85    }
86}
87
88#[derive(Debug, thiserror::Error, OperationIo)]
89#[aide(output_with = "Json<ErrorResponse>")]
90pub enum RouteError {
91    #[error(transparent)]
92    Internal(Box<dyn std::error::Error + Send + Sync + 'static>),
93
94    #[error("Invalid filter parameters")]
95    InvalidFilter(#[from] QueryRejection),
96}
97
98impl_from_error_for_route!(mas_storage::RepositoryError);
99
100impl IntoResponse for RouteError {
101    fn into_response(self) -> axum::response::Response {
102        let error = ErrorResponse::from_error(&self);
103        let sentry_event_id = record_error!(self, Self::Internal(_));
104        let status = match self {
105            Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
106            Self::InvalidFilter(_) => StatusCode::BAD_REQUEST,
107        };
108        (status, sentry_event_id, Json(error)).into_response()
109    }
110}
111
112pub fn doc(operation: TransformOperation) -> TransformOperation {
113    operation
114        .id("listUsers")
115        .summary("List users")
116        .tag("user")
117        .response_with::<200, Json<PaginatedResponse<User>>, _>(|t| {
118            let users = User::samples();
119            let pagination = mas_storage::Pagination::first(users.len());
120            let page = Page {
121                edges: users.into(),
122                has_next_page: true,
123                has_previous_page: false,
124            };
125
126            t.description("Paginated response of users")
127                .example(PaginatedResponse::new(page, pagination, 42, User::PATH))
128        })
129}
130
131#[tracing::instrument(name = "handler.admin.v1.users.list", skip_all)]
132pub async fn handler(
133    CallContext { mut repo, .. }: CallContext,
134    Pagination(pagination): Pagination,
135    params: FilterParams,
136) -> Result<Json<PaginatedResponse<User>>, RouteError> {
137    let base = format!("{path}{params}", path = User::PATH);
138    let filter = UserFilter::default();
139
140    let filter = match params.admin {
141        Some(true) => filter.can_request_admin_only(),
142        Some(false) => filter.cannot_request_admin_only(),
143        None => filter,
144    };
145
146    let filter = match params.status {
147        Some(UserStatus::Active) => filter.active_only(),
148        Some(UserStatus::Locked) => filter.locked_only(),
149        Some(UserStatus::Deactivated) => filter.deactivated_only(),
150        None => filter,
151    };
152
153    let page = repo.user().list(filter, pagination).await?;
154    let count = repo.user().count(filter).await?;
155
156    Ok(Json(PaginatedResponse::new(
157        page.map(User::from),
158        pagination,
159        count,
160        &base,
161    )))
162}
mas_handlers/admin/v1/users/list.rs

mas_handlers/admin/v1/users/
list.rs
