mas_handlers/admin/v1/users/
list.rs

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

mas_handlers/admin/v1/users/
list.rs
