Skip to main content

redmine_api/api/
users.rs

1//! Users Rest API Endpoint definitions
2//!
3//! [Redmine Documentation](https://www.redmine.org/projects/redmine/wiki/Rest_Users)
4//!
5//! - [x] all users endpoint
6//!   - [x] status filter
7//!   - [x] name filter
8//!   - [x] group_id filter
9//! - [x] specific user endpoint
10//!   - [x] by user id
11//!   - [x] current
12//! - [x] create user endpoint
13//! - [x] update user endpoint
14//! - [x] delete user endpoint
15
16use derive_builder::Builder;
17use reqwest::Method;
18use std::borrow::Cow;
19
20use crate::api::custom_fields::CustomFieldEssentialsWithValue;
21use crate::api::groups::GroupEssentials;
22use crate::api::project_memberships::UserProjectMembership;
23use crate::api::{
24    CustomFieldFilter, DateTimeFilterPast, Endpoint, NoPagination, Pageable, QueryParams,
25    ReturnsJsonResponse,
26};
27use serde::Serialize;
28
29/// a minimal type for Redmine users used in
30/// other Redmine objects (e.g. issue author)
31#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
32pub struct UserEssentials {
33    /// numeric id
34    pub id: u64,
35    /// display name
36    pub name: String,
37}
38
39/// a type for user to use as an API return type
40///
41/// alternatively you can use your own type limited to the fields you need
42#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
43pub struct User {
44    /// numeric id
45    pub id: u64,
46    /// user status
47    #[serde(default, skip_serializing_if = "Option::is_none")]
48    pub status: Option<UserStatus>,
49    /// login name
50    pub login: String,
51    /// is this user an admin
52    pub admin: bool,
53    /// user's firstname
54    pub firstname: String,
55    /// user's lastname
56    pub lastname: String,
57    /// primary email of the user
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub mail: Option<String>,
60    /// the user's API key
61    #[serde(default, skip_serializing_if = "Option::is_none")]
62    pub api_key: Option<String>,
63    /// user's 2FA scheme
64    #[serde(default)]
65    pub twofa_scheme: Option<String>,
66    /// allows setting users to be e.g. LDAP users
67    #[serde(default, skip_serializing_if = "Option::is_none")]
68    auth_source_id: Option<u64>,
69    /// The time when this user was created
70    #[serde(
71        serialize_with = "crate::api::serialize_rfc3339",
72        deserialize_with = "crate::api::deserialize_rfc3339"
73    )]
74    pub created_on: time::OffsetDateTime,
75    /// The time when this user was last updated
76    #[serde(
77        serialize_with = "crate::api::serialize_rfc3339",
78        deserialize_with = "crate::api::deserialize_rfc3339"
79    )]
80    pub updated_on: time::OffsetDateTime,
81    /// The time when this user's password was last changed
82    #[serde(
83        serialize_with = "crate::api::serialize_optional_rfc3339",
84        deserialize_with = "crate::api::deserialize_optional_rfc3339"
85    )]
86    pub passwd_changed_on: Option<time::OffsetDateTime>,
87    /// the time when this user last logged in
88    #[serde(
89        serialize_with = "crate::api::serialize_optional_rfc3339",
90        deserialize_with = "crate::api::deserialize_optional_rfc3339"
91    )]
92    pub last_login_on: Option<time::OffsetDateTime>,
93    /// custom fields with values
94    #[serde(default, skip_serializing_if = "Option::is_none")]
95    pub custom_fields: Option<Vec<CustomFieldEssentialsWithValue>>,
96    /// groups (only if include is specified)
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub groups: Option<Vec<GroupEssentials>>,
99    /// memberships (only if include is specified)
100    #[serde(default, skip_serializing_if = "Option::is_none")]
101    pub memberships: Option<Vec<UserProjectMembership>>,
102}
103
104/// The user status values
105#[derive(Debug, Clone, PartialEq, Eq)]
106pub enum UserStatus {
107    /// User can login and use their account (default)
108    Active,
109    /// User has registered but not yet confirmed their email address or was not yet activated by an administrator. User can not login
110    Registered,
111    /// User was once active and is now locked, User can not login
112    Locked,
113}
114
115impl serde::Serialize for UserStatus {
116    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
117    where
118        S: serde::Serializer,
119    {
120        match self {
121            Self::Active => serializer.serialize_u64(1),
122            Self::Registered => serializer.serialize_u64(2),
123            Self::Locked => serializer.serialize_u64(3),
124        }
125    }
126}
127
128impl<'de> serde::Deserialize<'de> for UserStatus {
129    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
130    where
131        D: serde::Deserializer<'de>,
132    {
133        let status_code = u64::deserialize(deserializer)?;
134        match status_code {
135            1 => Ok(Self::Active),
136            2 => Ok(Self::Registered),
137            3 => Ok(Self::Locked),
138            _ => Err(serde::de::Error::custom(format!(
139                "unknown user status code: {status_code}"
140            ))),
141        }
142    }
143}
144
145/// The user status values for filtering
146#[derive(Debug, Clone)]
147pub enum UserStatusFilter {
148    /// User can login and use their account (default)
149    Active,
150    /// User has registered but not yet confirmed their email address or was not yet activated by an administrator. User can not login
151    Registered,
152    /// User was once active and is now locked, User can not login
153    Locked,
154    /// Specify this to get users with any status
155    Any,
156}
157
158impl std::fmt::Display for UserStatusFilter {
159    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
160        match self {
161            Self::Active => {
162                write!(f, "1")
163            }
164            Self::Registered => {
165                write!(f, "2")
166            }
167            Self::Locked => {
168                write!(f, "3")
169            }
170            Self::Any => {
171                write!(f, "*")
172            }
173        }
174    }
175}
176
177impl From<UserStatus> for UserStatusFilter {
178    fn from(value: UserStatus) -> Self {
179        match value {
180            UserStatus::Active => Self::Active,
181            UserStatus::Registered => Self::Registered,
182            UserStatus::Locked => Self::Locked,
183        }
184    }
185}
186
187/// The endpoint for all users
188#[derive(Debug, Clone, Builder)]
189#[builder(setter(strip_option))]
190pub struct ListUsers<'a> {
191    /// Filter by user status
192    #[builder(default)]
193    status: Option<UserStatusFilter>,
194    #[builder(default)]
195    /// Filter by name, this matches login, firstname, lastname, mail and if it contains a space also firstname and lastname
196    #[builder(setter(into))]
197    name: Option<Cow<'a, str>>,
198    /// Users need to be members of this group
199    #[builder(default)]
200    group_id: Option<u64>,
201    /// Filter by authentication source
202    #[builder(default)]
203    auth_source_id: Option<u64>,
204    /// Filter by the two-factor authentication scheme
205    #[builder(default)]
206    #[builder(setter(into))]
207    twofa_scheme: Option<Cow<'a, str>>,
208    /// A boolean filter to find only administrators
209    #[builder(default)]
210    admin: Option<bool>,
211    /// Filter by creation time
212    #[builder(default)]
213    created_on: Option<DateTimeFilterPast>,
214    /// Filter by last login time
215    #[builder(default)]
216    last_login_on: Option<DateTimeFilterPast>,
217    /// Filter by login
218    #[builder(default)]
219    #[builder(setter(into))]
220    login: Option<Cow<'a, str>>,
221    /// Filter by firstname
222    #[builder(default)]
223    #[builder(setter(into))]
224    firstname: Option<Cow<'a, str>>,
225    /// Filter by lastname
226    #[builder(default)]
227    #[builder(setter(into))]
228    lastname: Option<Cow<'a, str>>,
229    /// Filter by mail
230    #[builder(default)]
231    #[builder(setter(into))]
232    mail: Option<Cow<'a, str>>,
233    /// Filter by custom fields
234    #[builder(default)]
235    custom_field_filters: Option<Vec<CustomFieldFilter>>,
236}
237
238impl ReturnsJsonResponse for ListUsers<'_> {}
239impl Pageable for ListUsers<'_> {
240    fn response_wrapper_key(&self) -> String {
241        "users".to_string()
242    }
243}
244
245impl<'a> ListUsers<'a> {
246    /// Create a builder for the endpoint.
247    #[must_use]
248    pub fn builder() -> ListUsersBuilder<'a> {
249        ListUsersBuilder::default()
250    }
251}
252
253impl Endpoint for ListUsers<'_> {
254    fn method(&self) -> Method {
255        Method::GET
256    }
257
258    fn endpoint(&self) -> Cow<'static, str> {
259        "users.json".into()
260    }
261
262    fn parameters(&self) -> QueryParams<'_> {
263        let mut params = QueryParams::default();
264        params.push_opt("status", self.status.as_ref().map(|s| s.to_string()));
265        params.push_opt("name", self.name.as_ref());
266        params.push_opt("group_id", self.group_id);
267        params.push_opt("auth_source_id", self.auth_source_id);
268        params.push_opt("twofa_scheme", self.twofa_scheme.as_ref());
269        params.push_opt("admin", self.admin);
270        params.push_opt(
271            "created_on",
272            self.created_on.as_ref().map(|s| s.to_string()),
273        );
274        params.push_opt(
275            "last_login_on",
276            self.last_login_on.as_ref().map(|s| s.to_string()),
277        );
278        params.push_opt("login", self.login.as_ref());
279        params.push_opt("firstname", self.firstname.as_ref());
280        params.push_opt("lastname", self.lastname.as_ref());
281        params.push_opt("mail", self.mail.as_ref());
282        if let Some(filters) = self.custom_field_filters.as_ref() {
283            for filter in filters {
284                params.push(format!("cf_{}", filter.id), filter.value.to_string());
285            }
286        }
287        params
288    }
289}
290
291/// The types of associated data which can be fetched along with a user
292#[derive(Debug, Clone)]
293pub enum UserInclude {
294    /// The project memberships of this user
295    Memberships,
296    /// The groups where this user is a member
297    Groups,
298}
299
300impl std::fmt::Display for UserInclude {
301    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
302        match self {
303            Self::Memberships => {
304                write!(f, "memberships")
305            }
306            Self::Groups => {
307                write!(f, "groups")
308            }
309        }
310    }
311}
312
313/// The endpoint for a specific user
314#[derive(Debug, Clone, Builder)]
315#[builder(setter(strip_option))]
316pub struct GetUser {
317    /// User id to fetch, if not specified will fetch the current user
318    #[builder(default)]
319    id: Option<u64>,
320    /// Include associated data
321    #[builder(default)]
322    include: Option<Vec<UserInclude>>,
323}
324
325impl ReturnsJsonResponse for GetUser {}
326impl NoPagination for GetUser {}
327
328impl GetUser {
329    /// Create a builder for the endpoint.
330    #[must_use]
331    pub fn builder() -> GetUserBuilder {
332        GetUserBuilder::default()
333    }
334}
335
336impl Endpoint for GetUser {
337    fn method(&self) -> Method {
338        Method::GET
339    }
340
341    fn endpoint(&self) -> Cow<'static, str> {
342        match self.id {
343            Some(id) => format!("users/{id}.json").into(),
344            None => "users/current.json".into(),
345        }
346    }
347
348    fn parameters(&self) -> QueryParams<'_> {
349        let mut params = QueryParams::default();
350        params.push_opt("include", self.include.as_ref());
351        params
352    }
353}
354
355/// Possible values for mail notification options for a user
356#[derive(Debug, Clone, Serialize)]
357#[serde(rename_all = "snake_case")]
358pub enum MailNotificationOptions {
359    /// Get notified by all events (visible to user)
360    All,
361    /// This allows to be notified only by selected projects, not sure if those can be selected via the API
362    Selected,
363    /// Only get notifications for events caused by the user's own actions
364    OnlyMyEvents,
365    /// Only get notifications for events in issues assigned to the user
366    OnlyAssigned,
367    /// Only get notifications for events in issues owned by the user
368    OnlyOwner,
369    /// Only get notifications for events in objects watched by the user
370    /// (Redmine 7.0 and later)
371    OnlyMyWatches,
372    /// Do not get any notifications
373    #[serde(rename = "none")]
374    NoMailNotifications,
375}
376
377/// The endpoint to create a Redmine user
378#[serde_with::skip_serializing_none]
379#[derive(Debug, Clone, Builder, Serialize)]
380#[builder(setter(strip_option))]
381pub struct CreateUser<'a> {
382    /// The login for the user
383    #[builder(setter(into))]
384    login: Cow<'a, str>,
385    /// The user's password
386    ///
387    /// It is recommended to use generate_password instead
388    #[builder(setter(into), default)]
389    password: Option<Cow<'a, str>>,
390    /// The user's firstname
391    #[builder(setter(into))]
392    firstname: Cow<'a, str>,
393    /// The user's lastname
394    #[builder(setter(into))]
395    lastname: Cow<'a, str>,
396    /// The users primary email address
397    #[builder(setter(into))]
398    mail: Cow<'a, str>,
399    /// allows setting users to be e.g. LDAP users
400    #[builder(default)]
401    auth_source_id: Option<u64>,
402    /// what kind of mail notifications should be sent to the user
403    #[builder(default)]
404    mail_notification: Option<MailNotificationOptions>,
405    /// if set the user must change their password after the next login
406    #[builder(default)]
407    must_change_passwd: Option<bool>,
408    /// generate a random password
409    #[builder(default)]
410    generate_password: Option<bool>,
411    /// Send account information to the user
412    #[builder(default)]
413    #[serde(skip_serializing)]
414    send_information: Option<bool>,
415    /// Make the user a Redmine administrator
416    #[builder(default)]
417    admin: Option<bool>,
418}
419
420impl ReturnsJsonResponse for CreateUser<'_> {}
421impl NoPagination for CreateUser<'_> {}
422
423impl<'a> CreateUser<'a> {
424    /// Create a builder for the endpoint.
425    #[must_use]
426    pub fn builder() -> CreateUserBuilder<'a> {
427        CreateUserBuilder::default()
428    }
429}
430
431impl Endpoint for CreateUser<'_> {
432    fn method(&self) -> Method {
433        Method::POST
434    }
435
436    fn endpoint(&self) -> Cow<'static, str> {
437        "users.json".into()
438    }
439
440    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
441        Ok(Some((
442            "application/json",
443            serde_json::to_vec(&UserWrapperWithSendInformation::<CreateUser> {
444                user: (*self).to_owned(),
445                send_information: self.send_information,
446            })?,
447        )))
448    }
449}
450
451/// The endpoint to update an existing Redmine user
452#[serde_with::skip_serializing_none]
453#[derive(Debug, Clone, Builder, Serialize)]
454#[builder(setter(strip_option))]
455pub struct UpdateUser<'a> {
456    /// The id of the user to update
457    #[serde(skip_serializing)]
458    id: u64,
459    /// The login for the user
460    #[builder(setter(into))]
461    login: Cow<'a, str>,
462    /// The user's password
463    ///
464    /// It is recommended to use generate_password instead
465    #[builder(setter(into), default)]
466    password: Option<Cow<'a, str>>,
467    /// The user's firstname
468    #[builder(default, setter(into))]
469    firstname: Option<Cow<'a, str>>,
470    /// The user's lastname
471    #[builder(default, setter(into))]
472    lastname: Option<Cow<'a, str>>,
473    /// The users primary email address
474    #[builder(default, setter(into))]
475    mail: Option<Cow<'a, str>>,
476    /// allows setting users to be e.g. LDAP users
477    #[builder(default)]
478    auth_source_id: Option<u64>,
479    /// what kind of mail notifications should be sent to the user
480    #[builder(default)]
481    mail_notification: Option<MailNotificationOptions>,
482    /// if set the user must change their password after the next login
483    #[builder(default)]
484    must_change_passwd: Option<bool>,
485    /// generate a random password
486    #[builder(default)]
487    generate_password: Option<bool>,
488    /// Send account information to the user
489    #[builder(default)]
490    #[serde(skip_serializing)]
491    send_information: Option<bool>,
492    /// Make the user a Redmine administrator
493    #[builder(default)]
494    admin: Option<bool>,
495}
496
497impl<'a> UpdateUser<'a> {
498    /// Create a builder for the endpoint.
499    #[must_use]
500    pub fn builder() -> UpdateUserBuilder<'a> {
501        UpdateUserBuilder::default()
502    }
503}
504
505impl Endpoint for UpdateUser<'_> {
506    fn method(&self) -> Method {
507        Method::PUT
508    }
509
510    fn endpoint(&self) -> Cow<'static, str> {
511        format!("users/{}.json", self.id).into()
512    }
513
514    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
515        Ok(Some((
516            "application/json",
517            serde_json::to_vec(&UserWrapperWithSendInformation::<UpdateUser> {
518                user: (*self).to_owned(),
519                send_information: self.send_information,
520            })?,
521        )))
522    }
523}
524
525/// The endpoint to delete a Redmine user
526#[derive(Debug, Clone, Builder)]
527#[builder(setter(strip_option))]
528pub struct DeleteUser {
529    /// The id of the user to delete
530    id: u64,
531}
532
533impl DeleteUser {
534    /// Create a builder for the endpoint.
535    #[must_use]
536    pub fn builder() -> DeleteUserBuilder {
537        DeleteUserBuilder::default()
538    }
539}
540
541impl Endpoint for DeleteUser {
542    fn method(&self) -> Method {
543        Method::DELETE
544    }
545
546    fn endpoint(&self) -> Cow<'static, str> {
547        format!("users/{}.json", self.id).into()
548    }
549}
550
551/// helper struct for outer layers with a users field holding the inner data
552#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
553pub struct UsersWrapper<T> {
554    /// to parse JSON with users key
555    pub users: Vec<T>,
556}
557
558/// A lot of APIs in Redmine wrap their data in an extra layer, this is a
559/// helper struct for outer layers with a user field holding the inner data
560#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
561pub struct UserWrapper<T> {
562    /// to parse JSON with user key
563    pub user: T,
564}
565
566/// a special version of the UserWrapper to use with [CreateUser] and [UpdateUser]
567/// because Redmine puts the send_information flag outside the user object for
568/// some reason
569#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
570pub struct UserWrapperWithSendInformation<T> {
571    /// to parse JSON with user key
572    pub user: T,
573    /// send information flag in [CreateUser] and [UpdateUser]
574    #[serde(default, skip_serializing_if = "Option::is_none")]
575    pub send_information: Option<bool>,
576}
577
578#[cfg(test)]
579pub(crate) mod test {
580    use crate::api::{
581        ResponsePage, groups::test::GROUP_LOCK, project_memberships::test::PROJECT_MEMBERSHIP_LOCK,
582    };
583
584    use super::*;
585    use pretty_assertions::assert_eq;
586    use std::error::Error;
587    use tokio::sync::RwLock;
588    use tracing_test::traced_test;
589
590    /// needed so we do not get 404s when listing while
591    /// creating/deleting or creating/updating/deleting
592    pub static USER_LOCK: RwLock<()> = RwLock::const_new(());
593
594    #[traced_test]
595    #[test]
596    fn test_list_users_first_page() -> Result<(), Box<dyn Error>> {
597        let _r_user = USER_LOCK.blocking_read();
598        crate::api::test_helpers::setup()?;
599        let redmine = crate::api::Redmine::from_env(
600            reqwest::blocking::Client::builder()
601                .tls_backend_rustls()
602                .build()?,
603        )?;
604        let endpoint = ListUsers::builder().build()?;
605        redmine.json_response_body_page::<_, User>(&endpoint, 0, 25)?;
606        Ok(())
607    }
608
609    #[traced_test]
610    #[test]
611    fn test_list_users_all_pages() -> Result<(), Box<dyn Error>> {
612        let _r_user = USER_LOCK.blocking_read();
613        crate::api::test_helpers::setup()?;
614        let redmine = crate::api::Redmine::from_env(
615            reqwest::blocking::Client::builder()
616                .tls_backend_rustls()
617                .build()?,
618        )?;
619        let endpoint = ListUsers::builder().build()?;
620        redmine.json_response_body_all_pages::<_, User>(&endpoint)?;
621        Ok(())
622    }
623
624    #[traced_test]
625    #[test]
626    fn test_get_user() -> Result<(), Box<dyn Error>> {
627        let _r_user = USER_LOCK.blocking_read();
628        crate::api::test_helpers::setup()?;
629        let redmine = crate::api::Redmine::from_env(
630            reqwest::blocking::Client::builder()
631                .tls_backend_rustls()
632                .build()?,
633        )?;
634        let endpoint = GetUser::builder().id(1).build()?;
635        redmine.json_response_body::<_, UserWrapper<User>>(&endpoint)?;
636        Ok(())
637    }
638
639    #[function_name::named]
640    #[traced_test]
641    #[test]
642    fn test_create_user() -> Result<(), Box<dyn Error>> {
643        let _w_user = USER_LOCK.blocking_write();
644        let name = format!("unittest_{}", function_name!());
645        crate::api::test_helpers::setup()?;
646        let redmine = crate::api::Redmine::from_env(
647            reqwest::blocking::Client::builder()
648                .tls_backend_rustls()
649                .build()?,
650        )?;
651        let list_endpoint = ListUsers::builder().name(name.clone()).build()?;
652        let users: Vec<User> = redmine.json_response_body_all_pages(&list_endpoint)?;
653        for user in users {
654            let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
655            redmine.ignore_response_body::<_>(&delete_endpoint)?;
656        }
657        let create_endpoint = CreateUser::builder()
658            .login(name.clone())
659            .firstname("Unit")
660            .lastname("Test")
661            .mail(format!("unit-test_{name}@example.org"))
662            .build()?;
663        let UserWrapper { user } =
664            redmine.json_response_body::<_, UserWrapper<User>>(&create_endpoint)?;
665        let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
666        redmine.ignore_response_body::<_>(&delete_endpoint)?;
667        Ok(())
668    }
669
670    // this test causes emails to be sent so we comment it out, mainly it was
671    // meant to check if the send_information attribute is inside or outside the
672    // user object in CreateUser (the docs in the wiki say outside and that really
673    // seems to be the case)
674    // #[function_name::named]
675    // #[traced_test]
676    // #[test]
677    // fn test_create_user_send_account_info() -> Result<(), Box<dyn Error>> {
678    //     let _w_user = USER_LOCK.blocking_write();
679    //     let name = format!("unittest_{}", function_name!());
680    //     crate::api::test_helpers::setup()?;
681    //     let redmine = crate::api::Redmine::from_env()?;
682    //     let list_endpoint = ListUsers::builder().name(name.clone()).build()?;
683    //     let UsersWrapper { users } =
684    //         redmine.json_response_body::<_, UsersWrapper<User>>(&list_endpoint)?;
685    //     for user in users {
686    //         let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
687    //         redmine.ignore_response_body::<_>(&delete_endpoint)?;
688    //     }
689    //     let create_endpoint = CreateUser::builder()
690    //         .login(name.clone())
691    //         .firstname("Unit")
692    //         .lastname("Test Send Account Info")
693    //         .mail(format!("{}@example.org", name)) // apparently there is a 60 character limit on the email in Redmine
694    //         .send_information(true)
695    //         .build()?;
696    //     let UserWrapper { user } =
697    //         redmine.json_response_body::<_, UserWrapper<User>>(&create_endpoint)?;
698    //     let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
699    //     redmine.ignore_response_body::<_>(&delete_endpoint)?;
700    //     Ok(())
701    // }
702
703    // this test causes emails to be sent so we comment it out, mainly it was
704    // meant to check if the admin attribute is inside or outside the user object
705    // in CreateUser (the docs on the wiki say outside but inside seems
706    // to be correct)
707    // #[function_name::named]
708    // #[traced_test]
709    // #[test]
710    // fn test_create_admin_user() -> Result<(), Box<dyn Error>> {
711    //     let _w_user = USER_LOCK.blocking_write();
712    //     let name = format!("unittest_{}", function_name!());
713    //     crate::api::test_helpers::setup()?;
714    //     let redmine = crate::api::Redmine::from_env()?;
715    //     let list_endpoint = ListUsers::builder().name(name.clone()).build()?;
716    //     let UsersWrapper { users } =
717    //         redmine.json_response_body::<_, UsersWrapper<User>>(&list_endpoint)?;
718    //     for user in users {
719    //         let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
720    //         redmine.ignore_response_body::<_>(&delete_endpoint)?;
721    //     }
722    //     let create_endpoint = CreateUser::builder()
723    //         .login(name.clone())
724    //         .firstname("Unit")
725    //         .lastname("Test Admin")
726    //         .mail(format!("unit-test_{}@example.org", name))
727    //         .admin(true)
728    //         .build()?;
729    //     let UserWrapper { user } =
730    //         redmine.json_response_body::<_, UserWrapper<User>>(&create_endpoint)?;
731    //     let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
732    //     redmine.ignore_response_body::<_>(&delete_endpoint)?;
733    //     Ok(())
734    // }
735
736    #[function_name::named]
737    #[traced_test]
738    #[test]
739    fn test_update_user() -> Result<(), Box<dyn Error>> {
740        let _w_user = USER_LOCK.blocking_write();
741        let name = format!("unittest_{}", function_name!());
742        crate::api::test_helpers::setup()?;
743        let redmine = crate::api::Redmine::from_env(
744            reqwest::blocking::Client::builder()
745                .tls_backend_rustls()
746                .build()?,
747        )?;
748        let list_endpoint = ListUsers::builder().name(name.clone()).build()?;
749        let users: Vec<User> = redmine.json_response_body_all_pages(&list_endpoint)?;
750        for user in users {
751            let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
752            redmine.ignore_response_body::<_>(&delete_endpoint)?;
753        }
754        let create_endpoint = CreateUser::builder()
755            .login(name.clone())
756            .firstname("Unit")
757            .lastname("Test")
758            .mail(format!("unit-test_{name}@example.org"))
759            .build()?;
760        let UserWrapper { user } =
761            redmine.json_response_body::<_, UserWrapper<User>>(&create_endpoint)?;
762        let update_endpoint = super::UpdateUser::builder()
763            .id(user.id)
764            .login(format!("new_{name}"))
765            .build()?;
766        redmine.ignore_response_body::<_>(&update_endpoint)?;
767        let delete_endpoint = DeleteUser::builder().id(user.id).build()?;
768        redmine.ignore_response_body::<_>(&delete_endpoint)?;
769        Ok(())
770    }
771
772    /// this tests if any of the results contain a field we are not deserializing
773    ///
774    /// this will only catch fields we missed if they are part of the response but
775    /// it is better than nothing
776    #[traced_test]
777    #[test]
778    fn test_completeness_user_type_first_page() -> Result<(), Box<dyn Error>> {
779        let _r_user = USER_LOCK.blocking_read();
780        crate::api::test_helpers::setup()?;
781        let redmine = crate::api::Redmine::from_env(
782            reqwest::blocking::Client::builder()
783                .tls_backend_rustls()
784                .build()?,
785        )?;
786        let endpoint = ListUsers::builder().build()?;
787        let ResponsePage {
788            values,
789            total_count: _,
790            offset: _,
791            limit: _,
792        } = redmine.json_response_body_page::<_, serde_json::Value>(&endpoint, 0, 100)?;
793        for value in values {
794            let o: User = serde_json::from_value(value.clone())?;
795            let reserialized = serde_json::to_value(o)?;
796            assert_eq!(value, reserialized);
797        }
798        Ok(())
799    }
800
801    /// this tests if any of the results contain a field we are not deserializing
802    ///
803    /// this will only catch fields we missed if they are part of the response but
804    /// it is better than nothing
805    ///
806    /// this version of the test will load all pages of users and the individual
807    /// users for each via GetUser
808    #[traced_test]
809    #[test]
810    fn test_completeness_user_type_all_pages_all_user_details() -> Result<(), Box<dyn Error>> {
811        let _r_user = USER_LOCK.blocking_read();
812        let _r_groups = GROUP_LOCK.blocking_read();
813        let _r_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_read();
814        crate::api::test_helpers::setup()?;
815        let redmine = crate::api::Redmine::from_env(
816            reqwest::blocking::Client::builder()
817                .tls_backend_rustls()
818                .build()?,
819        )?;
820        let endpoint = ListUsers::builder().build()?;
821        let users = redmine.json_response_body_all_pages::<_, User>(&endpoint)?;
822        for user in users {
823            let get_endpoint = GetUser::builder()
824                .id(user.id)
825                .include(vec![UserInclude::Memberships, UserInclude::Groups])
826                .build()?;
827            let UserWrapper { user: value } =
828                redmine.json_response_body::<_, UserWrapper<serde_json::Value>>(&get_endpoint)?;
829            let o: User = serde_json::from_value(value.clone())?;
830            let reserialized = serde_json::to_value(o)?;
831            assert_eq!(value, reserialized);
832        }
833        Ok(())
834    }
835}