Skip to main content

redmine_api/api/
project_memberships.rs

1//! Project Memberships Rest API Endpoint definitions
2//!
3//! [Redmine Documentation](https://www.redmine.org/projects/redmine/wiki/Rest_Memberships)
4//!
5//! - [x] list of project memberships endpoint
6//! - [x] get specific membership endpoint
7//! - [x] create project membership endpoint
8//! - [x] update specific membership endpoint
9//! - [x] delete specific membership endpoint
10
11use derive_builder::Builder;
12use reqwest::Method;
13use std::borrow::Cow;
14
15use crate::api::groups::GroupEssentials;
16use crate::api::projects::ProjectEssentials;
17use crate::api::roles::RoleEssentials;
18use crate::api::users::UserEssentials;
19use crate::api::{Endpoint, NoPagination, Pageable, ReturnsJsonResponse};
20use serde::Serialize;
21
22/// a minimal type for project memberships to be used in lists of memberships
23/// returned as part of the user
24#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
25pub struct UserProjectMembership {
26    /// numeric id
27    pub id: u64,
28    /// the project
29    pub project: ProjectEssentials,
30    /// the roles the user has in the project
31    pub roles: Vec<RoleEssentials>,
32}
33
34/// a minimal type for project memberships to be used in lists of memberships
35/// returned as part of the group
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
37pub struct GroupProjectMembership {
38    /// numeric id
39    pub id: u64,
40    /// the project
41    pub project: ProjectEssentials,
42    /// the roles the group has in the project
43    pub roles: Vec<RoleEssentials>,
44}
45
46/// a type for project memberships to use as an API return type
47///
48/// alternatively you can use your own type limited to the fields you need
49#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
50pub struct ProjectMembership {
51    /// numeric id
52    pub id: u64,
53    /// the project
54    pub project: ProjectEssentials,
55    /// the user (project member), optional because alternatively we could have a group
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub user: Option<UserEssentials>,
58    /// the group (project member), optional because alternatively we could have a user
59    #[serde(default, skip_serializing_if = "Option::is_none")]
60    pub group: Option<GroupEssentials>,
61    /// the roles the user or group has in the project
62    pub roles: Vec<RoleEssentials>,
63}
64
65/// The endpoint for all memberships in a Redmine project
66#[derive(Debug, Clone, Builder)]
67#[builder(setter(strip_option))]
68pub struct ListProjectMemberships<'a> {
69    /// project id or name as it appears in the URL
70    #[builder(setter(into))]
71    project_id_or_name: Cow<'a, str>,
72}
73
74impl ReturnsJsonResponse for ListProjectMemberships<'_> {}
75impl Pageable for ListProjectMemberships<'_> {
76    fn response_wrapper_key(&self) -> String {
77        "memberships".to_string()
78    }
79}
80
81impl<'a> ListProjectMemberships<'a> {
82    /// Create a builder for the endpoint.
83    #[must_use]
84    pub fn builder() -> ListProjectMembershipsBuilder<'a> {
85        ListProjectMembershipsBuilder::default()
86    }
87}
88
89impl Endpoint for ListProjectMemberships<'_> {
90    fn method(&self) -> Method {
91        Method::GET
92    }
93
94    fn endpoint(&self) -> Cow<'static, str> {
95        format!("projects/{}/memberships.json", self.project_id_or_name).into()
96    }
97}
98
99/// The endpoint for a specific Redmine project membership
100#[derive(Debug, Clone, Builder)]
101#[builder(setter(strip_option))]
102pub struct GetProjectMembership {
103    /// id of the project membership to retrieve
104    id: u64,
105}
106
107impl ReturnsJsonResponse for GetProjectMembership {}
108impl NoPagination for GetProjectMembership {}
109
110impl GetProjectMembership {
111    /// Create a builder for the endpoint.
112    #[must_use]
113    pub fn builder() -> GetProjectMembershipBuilder {
114        GetProjectMembershipBuilder::default()
115    }
116}
117
118impl Endpoint for GetProjectMembership {
119    fn method(&self) -> Method {
120        Method::GET
121    }
122
123    fn endpoint(&self) -> Cow<'static, str> {
124        format!("memberships/{}.json", self.id).into()
125    }
126}
127
128/// The endpoint to create a Redmine project membership (add a user or group to a project)
129#[serde_with::skip_serializing_none]
130#[derive(Debug, Clone, Builder, Serialize)]
131#[builder(setter(strip_option))]
132pub struct CreateProjectMembership<'a> {
133    /// project id or name as it appears in the URL
134    #[builder(setter(into))]
135    #[serde(skip_serializing)]
136    project_id_or_name: Cow<'a, str>,
137    /// users to add to the project
138    user_ids: Vec<u64>,
139    /// roles for the user to add to the project
140    role_ids: Vec<u64>,
141}
142
143impl ReturnsJsonResponse for CreateProjectMembership<'_> {}
144impl NoPagination for CreateProjectMembership<'_> {}
145
146impl<'a> CreateProjectMembership<'a> {
147    /// Create a builder for the endpoint.
148    #[must_use]
149    pub fn builder() -> CreateProjectMembershipBuilder<'a> {
150        CreateProjectMembershipBuilder::default()
151    }
152}
153
154impl Endpoint for CreateProjectMembership<'_> {
155    fn method(&self) -> Method {
156        Method::POST
157    }
158
159    fn endpoint(&self) -> Cow<'static, str> {
160        format!("projects/{}/memberships.json", self.project_id_or_name).into()
161    }
162
163    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
164        Ok(Some((
165            "application/json",
166            serde_json::to_vec(&MembershipWrapper::<CreateProjectMembership> {
167                membership: (*self).to_owned(),
168            })?,
169        )))
170    }
171}
172
173/// The endpoint to update an existing Redmine project membership (change roles)
174#[serde_with::skip_serializing_none]
175#[derive(Debug, Clone, Builder, Serialize)]
176#[builder(setter(strip_option))]
177pub struct UpdateProjectMembership {
178    /// id of the project membership to update
179    #[serde(skip_serializing)]
180    id: u64,
181    /// roles for the user to add to the project
182    role_ids: Vec<u64>,
183}
184
185impl UpdateProjectMembership {
186    /// Create a builder for the endpoint.
187    #[must_use]
188    pub fn builder() -> UpdateProjectMembershipBuilder {
189        UpdateProjectMembershipBuilder::default()
190    }
191}
192
193impl Endpoint for UpdateProjectMembership {
194    fn method(&self) -> Method {
195        Method::PUT
196    }
197
198    fn endpoint(&self) -> Cow<'static, str> {
199        format!("memberships/{}.json", self.id).into()
200    }
201
202    fn body(&self) -> Result<Option<(&'static str, Vec<u8>)>, crate::Error> {
203        Ok(Some((
204            "application/json",
205            serde_json::to_vec(&MembershipWrapper::<Self> {
206                membership: (*self).to_owned(),
207            })?,
208        )))
209    }
210}
211
212/// The endpoint to delete a membership in a Redmine project
213#[derive(Debug, Clone, Builder)]
214#[builder(setter(strip_option))]
215pub struct DeleteProjectMembership {
216    /// id of the project membership to delete
217    id: u64,
218}
219
220impl DeleteProjectMembership {
221    /// Create a builder for the endpoint.
222    #[must_use]
223    pub fn builder() -> DeleteProjectMembershipBuilder {
224        DeleteProjectMembershipBuilder::default()
225    }
226}
227
228impl Endpoint for DeleteProjectMembership {
229    fn method(&self) -> Method {
230        Method::DELETE
231    }
232
233    fn endpoint(&self) -> Cow<'static, str> {
234        format!("memberships/{}.json", self.id).into()
235    }
236}
237
238/// helper struct for outer layers with a memberships field holding the inner data
239#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
240pub struct MembershipsWrapper<T> {
241    /// to parse JSON with memberships key
242    pub memberships: Vec<T>,
243}
244
245/// A lot of APIs in Redmine wrap their data in an extra layer, this is a
246/// helper struct for outer layers with a membership field holding the inner data
247#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
248pub struct MembershipWrapper<T> {
249    /// to parse JSON with membership key
250    pub membership: T,
251}
252
253#[cfg(test)]
254pub(crate) mod test {
255    use super::*;
256    use crate::api::test_helpers::{current_user_id, with_project};
257    use pretty_assertions::assert_eq;
258    use std::error::Error;
259    use tokio::sync::RwLock;
260    use tracing_test::traced_test;
261
262    /// needed so we do not get 404s when listing while
263    /// creating/deleting or creating/updating/deleting
264    pub static PROJECT_MEMBERSHIP_LOCK: RwLock<()> = RwLock::const_new(());
265
266    /// returns the ids of all roles which can be given to project members
267    fn role_ids(redmine: &crate::api::Redmine) -> Result<Vec<u64>, Box<dyn Error>> {
268        use crate::api::roles::{ListRoles, RolesWrapper};
269        let endpoint = ListRoles::builder().build()?;
270        let RolesWrapper { roles } =
271            redmine.json_response_body::<_, RolesWrapper<RoleEssentials>>(&endpoint)?;
272        if roles.is_empty() {
273            return Err("no roles found".into());
274        }
275        Ok(roles.into_iter().map(|r| r.id).collect())
276    }
277
278    #[function_name::named]
279    #[traced_test]
280    #[test]
281    fn test_list_project_memberships_first_page() -> Result<(), Box<dyn Error>> {
282        let _r_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_read();
283        let name = format!("unittest_{}", function_name!());
284        with_project(&name, |redmine, _project_id, name| {
285            let endpoint = ListProjectMemberships::builder()
286                .project_id_or_name(name)
287                .build()?;
288            let page = redmine.json_response_body_page::<_, ProjectMembership>(&endpoint, 0, 25)?;
289            assert!(!page.values.is_empty());
290            Ok(())
291        })?;
292        Ok(())
293    }
294
295    #[function_name::named]
296    #[traced_test]
297    #[test]
298    fn test_list_project_memberships_all_pages() -> Result<(), Box<dyn Error>> {
299        let _r_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_read();
300        let name = format!("unittest_{}", function_name!());
301        with_project(&name, |redmine, _project_id, name| {
302            let endpoint = ListProjectMemberships::builder()
303                .project_id_or_name(name)
304                .build()?;
305            let memberships =
306                redmine.json_response_body_all_pages::<_, ProjectMembership>(&endpoint)?;
307            assert!(!memberships.is_empty());
308            Ok(())
309        })?;
310        Ok(())
311    }
312
313    #[function_name::named]
314    #[traced_test]
315    #[test]
316    fn test_get_project_membership() -> Result<(), Box<dyn Error>> {
317        let _r_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_read();
318        let name = format!("unittest_{}", function_name!());
319        with_project(&name, |redmine, _project_id, name| {
320            let list_endpoint = ListProjectMemberships::builder()
321                .project_id_or_name(name)
322                .build()?;
323            let memberships =
324                redmine.json_response_body_all_pages::<_, ProjectMembership>(&list_endpoint)?;
325            let membership = memberships.first().ok_or("no project membership found")?;
326            let endpoint = GetProjectMembership::builder().id(membership.id).build()?;
327            redmine.json_response_body::<_, MembershipWrapper<ProjectMembership>>(&endpoint)?;
328            Ok(())
329        })?;
330        Ok(())
331    }
332
333    /// returns the membership of the current user in the project created by
334    /// [`with_project`]
335    fn current_user_membership(
336        redmine: &crate::api::Redmine,
337        project_id: u64,
338    ) -> Result<ProjectMembership, Box<dyn Error>> {
339        let user_id = current_user_id(redmine)?;
340        let endpoint = ListProjectMemberships::builder()
341            .project_id_or_name(project_id.to_string())
342            .build()?;
343        let memberships =
344            redmine.json_response_body_all_pages::<_, ProjectMembership>(&endpoint)?;
345        memberships
346            .into_iter()
347            .find(|m| m.user.as_ref().is_some_and(|u| u.id == user_id))
348            .ok_or_else(|| "current user is not a member of the test project".into())
349    }
350
351    /// the project created by [`with_project`] already has the current user as
352    /// a member so we remove that membership first and then create it again
353    /// to avoid having to create a user (which is slow to delete on large
354    /// Redmine instances)
355    #[function_name::named]
356    #[traced_test]
357    #[test]
358    fn test_create_project_membership() -> Result<(), Box<dyn Error>> {
359        let _w_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_write();
360        let name = format!("unittest_{}", function_name!());
361        with_project(&name, |redmine, project_id, _name| {
362            let membership = current_user_membership(redmine, project_id)?;
363            let delete_endpoint = super::DeleteProjectMembership::builder()
364                .id(membership.id)
365                .build()?;
366            redmine.ignore_response_body::<_>(&delete_endpoint)?;
367            let create_endpoint = super::CreateProjectMembership::builder()
368                .project_id_or_name(project_id.to_string())
369                .user_ids(vec![current_user_id(redmine)?])
370                .role_ids(membership.roles.iter().map(|r| r.id).collect())
371                .build()?;
372            redmine
373                .json_response_body::<_, MembershipWrapper<ProjectMembership>>(&create_endpoint)?;
374            Ok(())
375        })?;
376        Ok(())
377    }
378
379    #[function_name::named]
380    #[traced_test]
381    #[test]
382    fn test_update_project_membership() -> Result<(), Box<dyn Error>> {
383        let _w_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_write();
384        let name = format!("unittest_{}", function_name!());
385        with_project(&name, |redmine, project_id, _name| {
386            let membership = current_user_membership(redmine, project_id)?;
387            let mut new_role_ids: Vec<u64> = membership.roles.iter().map(|r| r.id).collect();
388            if let Some(extra_role_id) = role_ids(redmine)?
389                .into_iter()
390                .find(|id| !new_role_ids.contains(id))
391            {
392                new_role_ids.push(extra_role_id);
393            }
394            let update_endpoint = super::UpdateProjectMembership::builder()
395                .id(membership.id)
396                .role_ids(new_role_ids.clone())
397                .build()?;
398            redmine.ignore_response_body::<_>(&update_endpoint)?;
399            let get_endpoint = GetProjectMembership::builder().id(membership.id).build()?;
400            let MembershipWrapper { membership } = redmine
401                .json_response_body::<_, MembershipWrapper<ProjectMembership>>(&get_endpoint)?;
402            for role_id in new_role_ids {
403                assert!(membership.roles.iter().any(|r| r.id == role_id));
404            }
405            Ok(())
406        })?;
407        Ok(())
408    }
409
410    /// this tests if any of the results contain a field we are not deserializing
411    ///
412    /// this will only catch fields we missed if they are part of the response but
413    /// it is better than nothing
414    #[function_name::named]
415    #[traced_test]
416    #[test]
417    fn test_completeness_project_membership_type() -> Result<(), Box<dyn Error>> {
418        let _r_project_memberships = PROJECT_MEMBERSHIP_LOCK.blocking_read();
419        let name = format!("unittest_{}", function_name!());
420        with_project(&name, |redmine, _project_id, name| {
421            let endpoint = ListProjectMemberships::builder()
422                .project_id_or_name(name)
423                .build()?;
424            let values: Vec<serde_json::Value> = redmine.json_response_body_all_pages(&endpoint)?;
425            assert!(!values.is_empty());
426            for value in values {
427                let o: ProjectMembership = serde_json::from_value(value.clone())?;
428                let reserialized = serde_json::to_value(o)?;
429                assert_eq!(value, reserialized);
430            }
431            Ok(())
432        })?;
433        Ok(())
434    }
435}