Skip to main content

redmine_api/api/
groups.rs

1//! Groups Rest API Endpoint definitions
2//!
3//! [Redmine Documentation](https://www.redmine.org/projects/redmine/wiki/Rest_Groups)
4//!
5//! - [x] all groups endpoint
6//! - [x] specific group endpoint
7//! - [x] create group endpoint
8//! - [x] update group endpoint
9//! - [x] delete group endpoint
10//! - [x] add user to group endpoint
11//! - [x] remove user from group endpoint
12//! - [x] remove users from group endpoint (Redmine 7.0 and later)
13
14use derive_builder::Builder;
15use reqwest::Method;
16use std::borrow::Cow;
17
18use crate::api::custom_fields::CustomField;
19use crate::api::custom_fields::CustomFieldEssentialsWithValue;
20use crate::api::project_memberships::GroupProjectMembership;
21use crate::api::users::UserEssentials;
22use crate::api::{Endpoint, NoPagination, QueryParams, ReturnsJsonResponse};
23use serde::Serialize;
24
25/// a minimal type for Redmine groups used in lists of groups included in
26/// other Redmine objects
27#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
28pub struct GroupEssentials {
29    /// numeric id
30    pub id: u64,
31    /// display name
32    pub name: String,
33}
34
35impl From<Group> for GroupEssentials {
36    fn from(v: Group) -> Self {
37        Self {
38            id: v.id,
39            name: v.name,
40        }
41    }
42}
43
44impl From<&Group> for GroupEssentials {
45    fn from(v: &Group) -> Self {
46        Self {
47            id: v.id,
48            name: v.name.to_owned(),
49        }
50    }
51}
52
53/// a type for groups to use as an API return type
54///
55/// alternatively you can use your own type limited to the fields you need
56#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
57pub struct Group {
58    /// numeric id
59    pub id: u64,
60    /// display name
61    pub name: String,
62    /// users (only with include parameter)
63    #[serde(default, skip_serializing_if = "Option::is_none")]
64    pub users: Option<Vec<UserEssentials>>,
65    /// project memberships (only with include parameter)
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub memberships: Option<Vec<GroupProjectMembership>>,
68    /// custom fields with values
69    #[serde(default, skip_serializing_if = "Option::is_none")]
70    pub custom_fields: Option<Vec<CustomFieldEssentialsWithValue>>,
71}
72
73/// The endpoint for all Redmine groups
74#[derive(Debug, Clone, Builder)]
75#[builder(setter(strip_option))]
76pub struct ListGroups {
77    /// filter for builtin groups
78    #[builder(default)]
79    builtin: Option<bool>,
80}
81
82impl ReturnsJsonResponse for ListGroups {}
83impl NoPagination for ListGroups {}
84
85impl ListGroups {
86    /// Create a builder for the endpoint.
87    #[must_use]
88    pub fn builder() -> ListGroupsBuilder {
89        ListGroupsBuilder::default()
90    }
91}
92
93impl Endpoint for ListGroups {
94    fn method(&self) -> Method {
95        Method::GET
96    }
97
98    fn endpoint(&self) -> Cow<'static, str> {
99        "groups.json".into()
100    }
101
102    fn parameters(&self) -> QueryParams<'_> {
103        let mut params = QueryParams::default();
104        params.push_opt("builtin", self.builtin);
105        params
106    }
107}
108
109/// The types of associated data which can be fetched along with a group
110#[derive(Debug, Clone)]
111pub enum GroupInclude {
112    /// The group members
113    Users,
114    /// The project memberships for this group
115    Memberships,
116}
117
118impl std::fmt::Display for GroupInclude {
119    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
120        match self {
121            Self::Users => {
122                write!(f, "users")
123            }
124            Self::Memberships => {
125                write!(f, "memberships")
126            }
127        }
128    }
129}
130
131/// The endpoint for a specific Redmine group
132#[derive(Debug, Clone, Builder)]
133#[builder(setter(strip_option))]
134pub struct GetGroup {
135    /// id of the group
136    id: u64,
137    /// associated data to include
138    #[builder(default)]
139    include: Option<Vec<GroupInclude>>,
140}
141
142impl ReturnsJsonResponse for GetGroup {}
143impl NoPagination for GetGroup {}
144
145impl GetGroup {
146    /// Create a builder for the endpoint.
147    #[must_use]
148    pub fn builder() -> GetGroupBuilder {
149        GetGroupBuilder::default()
150    }
151}
152
153impl Endpoint for GetGroup {
154    fn method(&self) -> Method {
155        Method::GET
156    }
157
158    fn endpoint(&self) -> Cow<'static, str> {
159        format!("groups/{}.json", self.id).into()
160    }
161
162    fn parameters(&self) -> QueryParams<'_> {
163        let mut params = QueryParams::default();
164        params.push_opt("include", self.include.as_ref());
165        params
166    }
167}
168
169/// The endpoint to create a Redmine group
170#[serde_with::skip_serializing_none]
171#[derive(Debug, Clone, Builder, Serialize)]
172#[builder(setter(strip_option))]
173pub struct CreateGroup<'a> {
174    /// name of the group
175    #[builder(setter(into))]
176    name: Cow<'a, str>,
177    /// whether two-factor authentication is required for this group
178    #[builder(default)]
179    twofa_required: Option<bool>,
180    /// user ids of users to put in the group initially
181    #[builder(default)]
182    user_ids: Option<Vec<u64>>,
183    /// custom field values
184    #[builder(default)]
185    custom_fields: Option<Vec<CustomField<'a>>>,
186}
187
188impl ReturnsJsonResponse for CreateGroup<'_> {}
189impl NoPagination for CreateGroup<'_> {}
190
191impl<'a> CreateGroup<'a> {
192    /// Create a builder for the endpoint.
193    #[must_use]
194    pub fn builder() -> CreateGroupBuilder<'a> {
195        CreateGroupBuilder::default()
196    }
197}
198
199impl Endpoint for CreateGroup<'_> {
200    fn method(&self) -> Method {
201        Method::POST
202    }
203
204    fn endpoint(&self) -> Cow<'static, str> {
205        "groups.json".into()
206    }
207
208    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
209        Ok(Some((
210            "application/json",
211            serde_json::to_vec(&GroupWrapper::<CreateGroup> {
212                group: (*self).to_owned(),
213            })?,
214        )))
215    }
216}
217
218/// The endpoint to update an existing Redmine group
219#[serde_with::skip_serializing_none]
220#[derive(Debug, Clone, Builder, Serialize)]
221#[builder(setter(strip_option))]
222pub struct UpdateGroup<'a> {
223    /// id of the group to update
224    #[serde(skip_serializing)]
225    id: u64,
226    /// name of the group
227    #[builder(setter(into))]
228    name: Cow<'a, str>,
229    /// whether two-factor authentication is required for this group
230    #[builder(default)]
231    twofa_required: Option<bool>,
232    /// user ids of the group members
233    #[builder(default)]
234    user_ids: Option<Vec<u64>>,
235    /// custom field values
236    #[builder(default)]
237    custom_fields: Option<Vec<CustomField<'a>>>,
238}
239
240impl<'a> UpdateGroup<'a> {
241    /// Create a builder for the endpoint.
242    #[must_use]
243    pub fn builder() -> UpdateGroupBuilder<'a> {
244        UpdateGroupBuilder::default()
245    }
246}
247
248impl Endpoint for UpdateGroup<'_> {
249    fn method(&self) -> Method {
250        Method::PUT
251    }
252
253    fn endpoint(&self) -> Cow<'static, str> {
254        format!("groups/{}.json", self.id).into()
255    }
256
257    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
258        Ok(Some((
259            "application/json",
260            serde_json::to_vec(&GroupWrapper::<UpdateGroup> {
261                group: (*self).to_owned(),
262            })?,
263        )))
264    }
265}
266
267/// The endpoint to delete a Redmine group
268#[derive(Debug, Clone, Builder)]
269#[builder(setter(strip_option))]
270pub struct DeleteGroup {
271    /// Id of the group to delete
272    id: u64,
273}
274
275impl DeleteGroup {
276    /// Create a builder for the endpoint.
277    #[must_use]
278    pub fn builder() -> DeleteGroupBuilder {
279        DeleteGroupBuilder::default()
280    }
281}
282
283impl Endpoint for DeleteGroup {
284    fn method(&self) -> Method {
285        Method::DELETE
286    }
287
288    fn endpoint(&self) -> Cow<'static, str> {
289        format!("groups/{}.json", self.id).into()
290    }
291}
292
293/// The endpoint to add a Redmine user to a Redmine group
294#[derive(Debug, Clone, Builder, Serialize)]
295#[builder(setter(strip_option))]
296pub struct AddUserToGroup {
297    /// Group Id to add the user to
298    #[serde(skip_serializing)]
299    group_id: u64,
300    /// User to add to this group
301    user_id: u64,
302}
303
304impl AddUserToGroup {
305    /// Create a builder for the endpoint.
306    #[must_use]
307    pub fn builder() -> AddUserToGroupBuilder {
308        AddUserToGroupBuilder::default()
309    }
310}
311
312impl Endpoint for AddUserToGroup {
313    fn method(&self) -> Method {
314        Method::POST
315    }
316
317    fn endpoint(&self) -> Cow<'static, str> {
318        format!("groups/{}/users.json", self.group_id).into()
319    }
320
321    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
322        Ok(Some(("application/json", serde_json::to_vec(self)?)))
323    }
324}
325
326/// The endpoint to remove a Redmine user from a Redmine group
327///
328/// This works with all supported Redmine versions but is deprecated in
329/// Redmine 7.0 and scheduled for removal in Redmine 8.0. When targeting only
330/// Redmine 7.0 or later prefer [`RemoveUsersFromGroup`].
331///
332/// Starting with Redmine 7.0 this returns a 404 if the user is not a member
333/// of the group.
334#[derive(Debug, Clone, Builder)]
335#[builder(setter(strip_option))]
336pub struct RemoveUserFromGroup {
337    /// Group Id to remove the user from
338    group_id: u64,
339    /// User to remove from the group
340    user_id: u64,
341}
342
343impl RemoveUserFromGroup {
344    /// Create a builder for the endpoint.
345    #[must_use]
346    pub fn builder() -> RemoveUserFromGroupBuilder {
347        RemoveUserFromGroupBuilder::default()
348    }
349}
350
351impl Endpoint for RemoveUserFromGroup {
352    fn method(&self) -> Method {
353        Method::DELETE
354    }
355
356    fn endpoint(&self) -> Cow<'static, str> {
357        format!("groups/{}/users/{}.json", self.group_id, self.user_id).into()
358    }
359}
360
361/// The endpoint to remove one or more Redmine users from a Redmine group
362///
363/// This endpoint requires Redmine 7.0 or later, older versions return a 404.
364/// Use [`RemoveUserFromGroup`] for older versions.
365///
366/// Redmine returns a 404 if none of the given users are members of the group.
367#[derive(Debug, Clone, Builder, Serialize)]
368#[builder(setter(strip_option))]
369pub struct RemoveUsersFromGroup {
370    /// Group Id to remove the users from
371    #[serde(skip_serializing)]
372    group_id: u64,
373    /// Users to remove from the group
374    user_ids: Vec<u64>,
375}
376
377impl RemoveUsersFromGroup {
378    /// Create a builder for the endpoint.
379    #[must_use]
380    pub fn builder() -> RemoveUsersFromGroupBuilder {
381        RemoveUsersFromGroupBuilder::default()
382    }
383}
384
385impl Endpoint for RemoveUsersFromGroup {
386    fn method(&self) -> Method {
387        Method::DELETE
388    }
389
390    fn endpoint(&self) -> Cow<'static, str> {
391        format!("groups/{}/users.json", self.group_id).into()
392    }
393
394    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
395        Ok(Some(("application/json", serde_json::to_vec(self)?)))
396    }
397}
398
399/// helper struct for outer layers with a groups field holding the inner data
400#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
401pub struct GroupsWrapper<T> {
402    /// to parse JSON with groups key
403    pub groups: Vec<T>,
404}
405
406/// A lot of APIs in Redmine wrap their data in an extra layer, this is a
407/// helper struct for outer layers with a group field holding the inner data
408#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
409pub struct GroupWrapper<T> {
410    /// to parse JSON with group key
411    pub group: T,
412}
413
414#[cfg(test)]
415pub(crate) mod test {
416    use super::*;
417    use crate::api::project_memberships::test::PROJECT_MEMBERSHIP_LOCK;
418    use crate::api::test_helpers::{RedmineVersion, current_user_id, redmine_version, with_group};
419    use crate::api::users::test::USER_LOCK;
420    use pretty_assertions::assert_eq;
421    use std::error::Error;
422    use tokio::sync::RwLock;
423    use tracing::trace;
424    use tracing_test::traced_test;
425
426    /// needed so we do not get 404s when listing while
427    /// creating/deleting or creating/updating/deleting
428    pub static GROUP_LOCK: RwLock<()> = RwLock::const_new(());
429
430    #[traced_test]
431    #[test]
432    fn test_list_groups_no_pagination() -> Result<(), Box<dyn Error>> {
433        let _r_groups = GROUP_LOCK.blocking_read();
434        crate::api::test_helpers::setup()?;
435        let redmine = crate::api::Redmine::from_env(
436            reqwest::blocking::Client::builder()
437                .tls_backend_rustls()
438                .build()?,
439        )?;
440        let endpoint = ListGroups::builder().build()?;
441        redmine.json_response_body::<_, GroupsWrapper<Group>>(&endpoint)?;
442        Ok(())
443    }
444
445    #[function_name::named]
446    #[traced_test]
447    #[test]
448    fn test_get_group() -> Result<(), Box<dyn Error>> {
449        let name = format!("unittest_{}", function_name!());
450        with_group(&name, |redmine, id, name| {
451            let endpoint = GetGroup::builder().id(id).build()?;
452            let GroupWrapper { group } =
453                redmine.json_response_body::<_, GroupWrapper<Group>>(&endpoint)?;
454            assert_eq!(group.name, name);
455            Ok(())
456        })?;
457        Ok(())
458    }
459
460    #[function_name::named]
461    #[traced_test]
462    #[test]
463    fn test_create_group() -> Result<(), Box<dyn Error>> {
464        let name = format!("unittest_{}", function_name!());
465        with_group(&name, |_, _, _| Ok(()))?;
466        Ok(())
467    }
468
469    #[function_name::named]
470    #[traced_test]
471    #[test]
472    fn test_update_group() -> Result<(), Box<dyn Error>> {
473        let name = format!("unittest_{}", function_name!());
474        with_group(&name, |redmine, id, _name| {
475            let update_endpoint = super::UpdateGroup::builder()
476                .id(id)
477                .name("unittest_rename_test")
478                .build()?;
479            redmine.ignore_response_body::<_>(&update_endpoint)?;
480            Ok(())
481        })?;
482        Ok(())
483    }
484
485    /// returns the ids of the users in the group
486    fn group_user_ids(
487        redmine: &crate::api::Redmine,
488        group_id: u64,
489    ) -> Result<Vec<u64>, Box<dyn Error>> {
490        let endpoint = GetGroup::builder()
491            .id(group_id)
492            .include(vec![GroupInclude::Users])
493            .build()?;
494        let GroupWrapper { group } =
495            redmine.json_response_body::<_, GroupWrapper<Group>>(&endpoint)?;
496        Ok(group
497            .users
498            .unwrap_or_default()
499            .into_iter()
500            .map(|u| u.id)
501            .collect())
502    }
503
504    /// creates a group, adds the current user to it, calls the function with
505    /// the group id and the user id and deletes the group afterwards
506    ///
507    /// this uses the current user instead of creating a user because deleting
508    /// users can take a very long time on large Redmine instances
509    fn with_current_user_in_group<F>(name: &str, f: F) -> Result<(), Box<dyn Error>>
510    where
511        F: FnOnce(&crate::api::Redmine, u64, u64) -> Result<(), Box<dyn Error>>,
512    {
513        with_group(name, |redmine, group_id, _name| {
514            let user_id = current_user_id(redmine)?;
515            let add_endpoint = AddUserToGroup::builder()
516                .group_id(group_id)
517                .user_id(user_id)
518                .build()?;
519            redmine.ignore_response_body::<_>(&add_endpoint)?;
520            assert_eq!(group_user_ids(redmine, group_id)?, vec![user_id]);
521            f(redmine, group_id, user_id)
522        })
523    }
524
525    /// checks whether the Redmine instance has the route used by
526    /// [`RemoveUsersFromGroup`] (Redmine 7.0 and later)
527    ///
528    /// sends the request without any users to an empty group, Redmine 7.0 and
529    /// later answers this with an empty API 404 response while older versions
530    /// do not have the route at all and answer with the HTML 404 page
531    fn has_remove_users_from_group_route(group_id: u64) -> Result<bool, Box<dyn Error>> {
532        let url = std::env::var("REDMINE_URL")?;
533        let api_key = std::env::var("REDMINE_API_KEY")?;
534        let response = reqwest::blocking::Client::builder()
535            .tls_backend_rustls()
536            .build()?
537            .delete(format!(
538                "{}/groups/{group_id}/users.json",
539                url.trim_end_matches('/')
540            ))
541            .header("X-Redmine-API-Key", api_key)
542            .send()?;
543        let content_type = response
544            .headers()
545            .get(reqwest::header::CONTENT_TYPE)
546            .and_then(|v| v.to_str().ok())
547            .unwrap_or_default()
548            .to_owned();
549        trace!(status = %response.status(), %content_type, "RemoveUsersFromGroup probe");
550        Ok(response.status() == reqwest::StatusCode::NOT_FOUND
551            && content_type.starts_with("application/json"))
552    }
553
554    #[function_name::named]
555    #[traced_test]
556    #[test]
557    fn test_add_and_remove_user_from_group() -> Result<(), Box<dyn Error>> {
558        let name = format!("unittest_{}", function_name!());
559        with_current_user_in_group(&name, |redmine, group_id, user_id| {
560            let remove_endpoint = RemoveUserFromGroup::builder()
561                .group_id(group_id)
562                .user_id(user_id)
563                .build()?;
564            redmine.ignore_response_body::<_>(&remove_endpoint)?;
565            assert_eq!(group_user_ids(redmine, group_id)?, Vec::<u64>::new());
566            Ok(())
567        })
568    }
569
570    /// the endpoint was added in Redmine 7.0, on older versions (according to
571    /// `REDMINE_VERSION`) this only checks that the endpoint does not exist yet
572    #[function_name::named]
573    #[traced_test]
574    #[test]
575    fn test_add_and_remove_users_from_group() -> Result<(), Box<dyn Error>> {
576        let version = redmine_version()?;
577        let name = format!("unittest_{}", function_name!());
578        with_group(&name, |redmine, group_id, _name| {
579            let has_route = has_remove_users_from_group_route(group_id)?;
580            if version < RedmineVersion::new(7, 0, 0) {
581                assert!(
582                    !has_route,
583                    "REDMINE_VERSION is {version} but the Redmine instance has the \
584                     RemoveUsersFromGroup endpoint added in Redmine 7.0, \
585                     is REDMINE_VERSION correct?"
586                );
587                return Ok(());
588            }
589            assert!(
590                has_route,
591                "REDMINE_VERSION is {version} but the Redmine instance does not have the \
592                 RemoveUsersFromGroup endpoint added in Redmine 7.0, \
593                 is REDMINE_VERSION correct?"
594            );
595            let user_id = current_user_id(redmine)?;
596            let add_endpoint = AddUserToGroup::builder()
597                .group_id(group_id)
598                .user_id(user_id)
599                .build()?;
600            redmine.ignore_response_body::<_>(&add_endpoint)?;
601            assert_eq!(group_user_ids(redmine, group_id)?, vec![user_id]);
602            let remove_endpoint = RemoveUsersFromGroup::builder()
603                .group_id(group_id)
604                .user_ids(vec![user_id])
605                .build()?;
606            redmine.ignore_response_body::<_>(&remove_endpoint)?;
607            assert_eq!(group_user_ids(redmine, group_id)?, Vec::<u64>::new());
608            Ok(())
609        })
610    }
611
612    /// this tests if any of the results contain a field we are not deserializing
613    ///
614    /// this will only catch fields we missed if they are part of the response but
615    /// it is better than nothing
616    #[traced_test]
617    #[test]
618    fn test_completeness_group_type() -> Result<(), Box<dyn Error>> {
619        let _r_groups = GROUP_LOCK.blocking_read();
620        crate::api::test_helpers::setup()?;
621        let redmine = crate::api::Redmine::from_env(
622            reqwest::blocking::Client::builder()
623                .tls_backend_rustls()
624                .build()?,
625        )?;
626        let endpoint = ListGroups::builder().build()?;
627        let GroupsWrapper { groups: values } =
628            redmine.json_response_body::<_, GroupsWrapper<serde_json::Value>>(&endpoint)?;
629        for value in values {
630            let o: Group = serde_json::from_value(value.clone())?;
631            let reserialized = serde_json::to_value(o)?;
632            assert_eq!(value, reserialized);
633        }
634        Ok(())
635    }
636
637    /// this tests if any of the results contain a field we are not deserializing
638    ///
639    /// this will only catch fields we missed if they are part of the response but
640    /// it is better than nothing
641    ///
642    /// this version of the test will load all groups and the individual
643    /// groups for each via GetGroup
644    #[traced_test]
645    #[test]
646    fn test_completeness_group_type_all_group_details() -> Result<(), Box<dyn Error>> {
647        let _r_user = USER_LOCK.blocking_read();
648        let _r_groups = GROUP_LOCK.blocking_read();
649        let _r_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_read();
650        crate::api::test_helpers::setup()?;
651        let redmine = crate::api::Redmine::from_env(
652            reqwest::blocking::Client::builder()
653                .tls_backend_rustls()
654                .build()?,
655        )?;
656        let endpoint = ListGroups::builder().build()?;
657        let GroupsWrapper { groups } =
658            redmine.json_response_body::<_, GroupsWrapper<Group>>(&endpoint)?;
659        for group in groups {
660            let get_endpoint = GetGroup::builder()
661                .id(group.id)
662                .include(vec![GroupInclude::Users, GroupInclude::Memberships])
663                .build()?;
664            let GroupWrapper { group: value } =
665                redmine.json_response_body::<_, GroupWrapper<serde_json::Value>>(&get_endpoint)?;
666            let o: Group = serde_json::from_value(value.clone())?;
667            let reserialized = serde_json::to_value(o)?;
668            assert_eq!(value, reserialized);
669        }
670        Ok(())
671    }
672}