1use 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#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
28pub struct GroupEssentials {
29 pub id: u64,
31 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#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
57pub struct Group {
58 pub id: u64,
60 pub name: String,
62 #[serde(default, skip_serializing_if = "Option::is_none")]
64 pub users: Option<Vec<UserEssentials>>,
65 #[serde(default, skip_serializing_if = "Option::is_none")]
67 pub memberships: Option<Vec<GroupProjectMembership>>,
68 #[serde(default, skip_serializing_if = "Option::is_none")]
70 pub custom_fields: Option<Vec<CustomFieldEssentialsWithValue>>,
71}
72
73#[derive(Debug, Clone, Builder)]
75#[builder(setter(strip_option))]
76pub struct ListGroups {
77 #[builder(default)]
79 builtin: Option<bool>,
80}
81
82impl ReturnsJsonResponse for ListGroups {}
83impl NoPagination for ListGroups {}
84
85impl ListGroups {
86 #[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#[derive(Debug, Clone)]
111pub enum GroupInclude {
112 Users,
114 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#[derive(Debug, Clone, Builder)]
133#[builder(setter(strip_option))]
134pub struct GetGroup {
135 id: u64,
137 #[builder(default)]
139 include: Option<Vec<GroupInclude>>,
140}
141
142impl ReturnsJsonResponse for GetGroup {}
143impl NoPagination for GetGroup {}
144
145impl GetGroup {
146 #[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#[serde_with::skip_serializing_none]
171#[derive(Debug, Clone, Builder, Serialize)]
172#[builder(setter(strip_option))]
173pub struct CreateGroup<'a> {
174 #[builder(setter(into))]
176 name: Cow<'a, str>,
177 #[builder(default)]
179 twofa_required: Option<bool>,
180 #[builder(default)]
182 user_ids: Option<Vec<u64>>,
183 #[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 #[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#[serde_with::skip_serializing_none]
220#[derive(Debug, Clone, Builder, Serialize)]
221#[builder(setter(strip_option))]
222pub struct UpdateGroup<'a> {
223 #[serde(skip_serializing)]
225 id: u64,
226 #[builder(setter(into))]
228 name: Cow<'a, str>,
229 #[builder(default)]
231 twofa_required: Option<bool>,
232 #[builder(default)]
234 user_ids: Option<Vec<u64>>,
235 #[builder(default)]
237 custom_fields: Option<Vec<CustomField<'a>>>,
238}
239
240impl<'a> UpdateGroup<'a> {
241 #[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#[derive(Debug, Clone, Builder)]
269#[builder(setter(strip_option))]
270pub struct DeleteGroup {
271 id: u64,
273}
274
275impl DeleteGroup {
276 #[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#[derive(Debug, Clone, Builder, Serialize)]
295#[builder(setter(strip_option))]
296pub struct AddUserToGroup {
297 #[serde(skip_serializing)]
299 group_id: u64,
300 user_id: u64,
302}
303
304impl AddUserToGroup {
305 #[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#[derive(Debug, Clone, Builder)]
335#[builder(setter(strip_option))]
336pub struct RemoveUserFromGroup {
337 group_id: u64,
339 user_id: u64,
341}
342
343impl RemoveUserFromGroup {
344 #[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#[derive(Debug, Clone, Builder, Serialize)]
368#[builder(setter(strip_option))]
369pub struct RemoveUsersFromGroup {
370 #[serde(skip_serializing)]
372 group_id: u64,
373 user_ids: Vec<u64>,
375}
376
377impl RemoveUsersFromGroup {
378 #[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#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
401pub struct GroupsWrapper<T> {
402 pub groups: Vec<T>,
404}
405
406#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
409pub struct GroupWrapper<T> {
410 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 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 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 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 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 #[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 #[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 #[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}