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}
36
37impl std::fmt::Display for UserStatus {
38    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
39        match self {
40            Self::Active => write!(f, "active"),
41            Self::Locked => write!(f, "locked"),
42        }
43    }
44}
45
46#[derive(FromRequestParts, Deserialize, JsonSchema, OperationIo)]
47#[serde(rename = "UserFilter")]
48#[aide(input_with = "Query<FilterParams>")]
49#[from_request(via(Query), rejection(RouteError))]
50pub struct FilterParams {
51    /// Retrieve users with (or without) the `admin` flag set
52    #[serde(rename = "filter[admin]")]
53    admin: Option<bool>,
54
55    /// Retrieve the items with the given status
56    ///
57    /// Defaults to retrieve all users, including locked ones.
58    ///
59    /// * `active`: Only retrieve active users
60    ///
61    /// * `locked`: Only retrieve locked users
62    #[serde(rename = "filter[status]")]
63    status: Option<UserStatus>,
64}
65
66impl std::fmt::Display for FilterParams {
67    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68        let mut sep = '?';
69
70        if let Some(admin) = self.admin {
71            write!(f, "{sep}filter[admin]={admin}")?;
72            sep = '&';
73        }
74        if let Some(status) = self.status {
75            write!(f, "{sep}filter[status]={status}")?;
76            sep = '&';
77        }
78
79        let _ = sep;
80        Ok(())
81    }
82}
83
84#[derive(Debug, thiserror::Error, OperationIo)]
85#[aide(output_with = "Json<ErrorResponse>")]
86pub enum RouteError {
87    #[error(transparent)]
88    Internal(Box<dyn std::error::Error + Send + Sync + 'static>),
89
90    #[error("Invalid filter parameters")]
91    InvalidFilter(#[from] QueryRejection),
92}
93
94impl_from_error_for_route!(mas_storage::RepositoryError);
95
96impl IntoResponse for RouteError {
97    fn into_response(self) -> axum::response::Response {
98        let error = ErrorResponse::from_error(&self);
99        let sentry_event_id = record_error!(self, Self::Internal(_));
100        let status = match self {
101            Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
102            Self::InvalidFilter(_) => StatusCode::BAD_REQUEST,
103        };
104        (status, sentry_event_id, Json(error)).into_response()
105    }
106}
107
108pub fn doc(operation: TransformOperation) -> TransformOperation {
109    operation
110        .id("listUsers")
111        .summary("List users")
112        .tag("user")
113        .response_with::<200, Json<PaginatedResponse<User>>, _>(|t| {
114            let users = User::samples();
115            let pagination = mas_storage::Pagination::first(users.len());
116            let page = Page {
117                edges: users.into(),
118                has_next_page: true,
119                has_previous_page: false,
120            };
121
122            t.description("Paginated response of users")
123                .example(PaginatedResponse::new(page, pagination, 42, User::PATH))
124        })
125}
126
127#[tracing::instrument(name = "handler.admin.v1.users.list", skip_all)]
128pub async fn handler(
129    CallContext { mut repo, .. }: CallContext,
130    Pagination(pagination): Pagination,
131    params: FilterParams,
132) -> Result<Json<PaginatedResponse<User>>, RouteError> {
133    let base = format!("{path}{params}", path = User::PATH);
134    let filter = UserFilter::default();
135
136    let filter = match params.admin {
137        Some(true) => filter.can_request_admin_only(),
138        Some(false) => filter.cannot_request_admin_only(),
139        None => filter,
140    };
141
142    let filter = match params.status {
143        Some(UserStatus::Active) => filter.active_only(),
144        Some(UserStatus::Locked) => filter.locked_only(),
145        None => filter,
146    };
147
148    let page = repo.user().list(filter, pagination).await?;
149    let count = repo.user().count(filter).await?;
150
151    Ok(Json(PaginatedResponse::new(
152        page.map(User::from),
153        pagination,
154        count,
155        &base,
156    )))
157}
mas_handlers/admin/v1/users/list.rs

mas_handlers/admin/v1/users/
list.rs
