Map GroupNotFoundException to 404 in setUserGroups and document groups semantics

commons/src/main/java/com/deftdevs/bootstrapi/commons/model/UserModel.java

@@ -1,6 +1,7 @@
 package com.deftdevs.bootstrapi.commons.model;
 
 import com.deftdevs.bootstrapi.commons.constants.BootstrAPI;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -44,6 +45,9 @@ public class UserModel {
     private String password;
 
     @XmlElement
+    @Schema(description = "Group memberships keyed by group name. true ensures the user is a member, " +
+            "false ensures the user is not a member, null is a no-op (leaves the membership untouched). " +
+            "Group lifecycle is managed via the top-level groups map; referenced groups must already exist.")
     private Map<String, Boolean> groups;
 
     // Example instances for documentation and tests

confluence/Models/UserModel.md

@@ -10,7 +10,7 @@
 | **email** | **String** |  | [optional] [default to null] |
 | **active** | **Boolean** |  | [optional] [default to null] |
 | **password** | **String** |  | [optional] [default to null] |
-| **groups** | **Map** |  | [optional] [default to null] |
+| **groups** | **Map** | Group memberships keyed by group name. true ensures the user is a member, false ensures the user is not a member, null is a no-op (leaves the membership untouched). Group lifecycle is managed via the top-level groups map; referenced groups must already exist. | [optional] [default to null] |
 
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
 

crowd/Models/UserModel.md

@@ -10,7 +10,7 @@
 | **email** | **String** |  | [optional] [default to null] |
 | **active** | **Boolean** |  | [optional] [default to null] |
 | **password** | **String** |  | [optional] [default to null] |
-| **groups** | **Map** |  | [optional] [default to null] |
+| **groups** | **Map** | Group memberships keyed by group name. true ensures the user is a member, false ensures the user is not a member, null is a no-op (leaves the membership untouched). Group lifecycle is managed via the top-level groups map; referenced groups must already exist. | [optional] [default to null] |
 
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
 

crowd/src/main/java/com/deftdevs/bootstrapi/crowd/service/UsersServiceImpl.java

@@ -448,8 +448,12 @@ Map<String, Boolean> setUserGroups(
                 }
             } catch (DirectoryPermissionException | ReadOnlyGroupException e) {
                 throw new BadRequestException(e);
+            } catch (GroupNotFoundException e) {
+                // the referenced group does not exist - group lifecycle is managed via the top-level
+                // groups map, so a non-existent group here is a client error (404)
+                throw new com.deftdevs.bootstrapi.commons.exception.GroupNotFoundException(groupName);
             } catch (com.atlassian.crowd.exception.DirectoryNotFoundException |
-                     com.atlassian.crowd.exception.UserNotFoundException | GroupNotFoundException |
+                     com.atlassian.crowd.exception.UserNotFoundException |
                      OperationFailedException e) {
                 throw new InternalServerErrorException(e);
             }

crowd/src/test/java/com/deftdevs/bootstrapi/crowd/service/UsersServiceTest.java

@@ -283,6 +283,21 @@ public void testAddUserWithGroupsRemoveNotMember() throws CrowdException, Direct
         assertEquals(false, result.getGroups().get("some-group"));
     }
 
+    @Test
+    public void testAddUserWithGroupsUnknownGroupThrowsNotFound() throws CrowdException, DirectoryPermissionException {
+        // return the same user as the one we are adding
+        doAnswer(invocation -> invocation.getArguments()[1]).when(directoryManager).addUser(anyLong(), any(), any());
+        doThrow(new GroupNotFoundException("unknown-group"))
+                .when(directoryManager).addUserToGroup(anyLong(), anyString(), anyString());
+
+        final UserModel userModel = UserModelUtil.toUserModel(getTestUser());
+        userModel.setPassword("12345");
+        userModel.setGroups(Collections.singletonMap("unknown-group", true));
+
+        assertThrows(com.deftdevs.bootstrapi.commons.exception.GroupNotFoundException.class,
+                () -> usersService.addUser(1L, userModel));
+    }
+
     @Test
     public void testAddUserAlreadyExists() throws CrowdException {
         final User user = getTestUser();

jira/Models/UserModel.md

@@ -10,7 +10,7 @@
 | **email** | **String** |  | [optional] [default to null] |
 | **active** | **Boolean** |  | [optional] [default to null] |
 | **password** | **String** |  | [optional] [default to null] |
-| **groups** | **Map** |  | [optional] [default to null] |
+| **groups** | **Map** | Group memberships keyed by group name. true ensures the user is a member, false ensures the user is not a member, null is a no-op (leaves the membership untouched). Group lifecycle is managed via the top-level groups map; referenced groups must already exist. | [optional] [default to null] |
 
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)