[Feature] Add optimistic locking based on versions for tasks and task assignments (#571)

* feat: add new migration for task and assignment versioning

* feat: add new exception for stale task versions

* feat: add version field to TaskBody entity

* feat: add version field to dtos

* feat: add version check into service methods

* feat: add new exception for stale assignment version

* feat: add version field to TaskAssignment entity

* feat: add version field to dtos

* feat: add version check to service methods

* test: update unit tests

* docs: update OpenAPI documentation

* fix: remove unused import

* fix: audit owner changes with updated_at and updated_by fields

* test: update unit tests

* fix: coderabbitai issue

* fix: coderabbitai issue

Author: solenuk

src/main/java/com/itasocialacademy/oitassist/task/config/file.txt

@@ -127,7 +127,11 @@ public ResponseEntity<PageResponse<TaskResponseDTO>> getMyTasks(
                 schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Task not found",
             content = @Content(mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class)))
+                schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PutMapping("/{taskId}")
     @PreAuthorize("hasAnyRole('ADMIN', 'ORG')")
@@ -152,7 +156,11 @@ public ResponseEntity<TaskResponseDTO> updateTask(@PathVariable Long taskId,
                 schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Task or user not found",
             content = @Content(mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class)))
+                schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PatchMapping("/{taskId}/add-owner")
     @PreAuthorize("hasRole('ADMIN')")
@@ -177,7 +185,11 @@ public ResponseEntity<TaskResponseDTO> addOwner(@PathVariable Long taskId,
                 schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Task or user not found",
             content = @Content(mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class)))
+                schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PatchMapping("/{taskId}/remove-owner")
     @PreAuthorize("hasRole('ADMIN')")

src/main/java/com/itasocialacademy/oitassist/task/controller/TaskController.java

@@ -46,6 +46,10 @@ public class TaskBody {
     @Column(name = "updated_at")
     private Instant updatedAt;
 
+    @Version
+    @Column(name = "version", nullable = false)
+    private Long version;
+
     @OneToMany(
         mappedBy = "task",
         cascade = CascadeType.ALL,

src/main/java/com/itasocialacademy/oitassist/task/dao/model/TaskBody.java

@@ -3,11 +3,15 @@
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
 
 @Schema(description = "DTO for adding task owner")
 public record AddOwnerRequestDTO(
     @Schema(
         description = "Email address of the new task owner. The user must have ADMIN or ORG role",
         example = "example@mail.com",
-        requiredMode = Schema.RequiredMode.REQUIRED) @NotBlank @Email String newOwnerEmail) {
+        requiredMode = Schema.RequiredMode.REQUIRED) @NotBlank @Email String newOwnerEmail,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = Schema.RequiredMode.REQUIRED) @NotNull Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/task/dto/request/AddOwnerRequestDTO.java

@@ -3,11 +3,15 @@
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
 
 @Schema(description = "DTO for removing task owner")
 public record RemoveOwnerRequestDTO(
     @Schema(
         description = "Email address of the task owner.",
         example = "example@mail.com",
-        requiredMode = Schema.RequiredMode.REQUIRED) @NotBlank @Email String ownerEmail) {
+        requiredMode = Schema.RequiredMode.REQUIRED) @NotBlank @Email String ownerEmail,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = Schema.RequiredMode.REQUIRED) @NotNull Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/task/dto/request/RemoveOwnerRequestDTO.java

@@ -2,6 +2,7 @@
 
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
 import java.util.List;
 
 @Schema(description = "DTO for updating an already existing task")
@@ -21,5 +22,7 @@ public record UpdateTaskRequestDTO(
     @Schema(
         description = "File ids to be detached from task",
         example = "[52]",
-        requiredMode = Schema.RequiredMode.NOT_REQUIRED) List<Long> removedFileIds) {
+        requiredMode = Schema.RequiredMode.NOT_REQUIRED) List<Long> removedFileIds,
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = Schema.RequiredMode.REQUIRED) @NotNull Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/task/dto/request/UpdateTaskRequestDTO.java

@@ -34,5 +34,7 @@ public record TaskResponseDTO(
 
     @Schema(
         description = "Ids of task's current owners",
-        example = "[1,2,3]") Set<Long> ownerIds) {
+        example = "[1,2,3]") Set<Long> ownerIds,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates") Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/task/dto/response/TaskResponseDTO.java

@@ -0,0 +1,11 @@
+package com.itasocialacademy.oitassist.task.exceptions;
+
+import com.itasocialacademy.oitassist.core.enums.ErrorCode;
+import com.itasocialacademy.oitassist.core.exceptions.BusinessException;
+
+public class StaleTaskVersionException extends BusinessException {
+    public StaleTaskVersionException(Long taskId) {
+        super("Task with id %d has been modified by another user. ".formatted(taskId),
+            ErrorCode.ENTITY_VERSION_CONFLICT);
+    }
+}

src/main/java/com/itasocialacademy/oitassist/task/exceptions/StaleTaskVersionException.java

@@ -22,6 +22,7 @@
 import com.itasocialacademy.oitassist.task.dto.request.RemoveOwnerRequestDTO;
 import com.itasocialacademy.oitassist.task.dto.request.UpdateTaskRequestDTO;
 import com.itasocialacademy.oitassist.task.dto.response.TaskResponseDTO;
+import com.itasocialacademy.oitassist.task.exceptions.StaleTaskVersionException;
 import com.itasocialacademy.oitassist.task.exceptions.TaskAccessRestrictedException;
 import com.itasocialacademy.oitassist.task.exceptions.TaskNotFoundException;
 import com.itasocialacademy.oitassist.task.mapper.TaskBodyMapper;
@@ -30,6 +31,7 @@
 import com.itasocialacademy.oitassist.user.api.interfaces.UserFacade;
 import com.itasocialacademy.oitassist.user.dao.enums.Role;
 import com.itasocialacademy.oitassist.user.exceptions.UserNotFoundException;
+import java.time.Instant;
 import java.util.*;
 import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
@@ -128,10 +130,12 @@ public TaskResponseDTO updateTask(Long taskId, UpdateTaskRequestDTO requestDTO)
             .map(o -> o.getId().getOwnerId()).collect(Collectors.toSet()),
             existingTask.getId());
 
+        checkTaskVersion(existingTask.getVersion(), requestDTO.version(), existingTask.getId());
+
         existingTask.setTitle(requestDTO.title());
         existingTask.setDescription(requestDTO.description());
 
-        TaskBody updatedTask = taskBodyRepository.save(existingTask);
+        TaskBody updatedTask = taskBodyRepository.saveAndFlush(existingTask);
         log.debug("Updated Task: Id {}, Title - {}", updatedTask.getId(), updatedTask.getTitle());
 
         Long currentUserId = securityFacade.getCurrentUserId()
@@ -161,6 +165,8 @@ public TaskResponseDTO addTaskOwner(Long taskId, AddOwnerRequestDTO addOwnerRequ
             throw new ValidationException("Provided user is not ADMIN nor ORG", ErrorCode.COMMON_VALIDATION_FAILED);
         }
 
+        checkTaskVersion(task.getVersion(), addOwnerRequest.version(), task.getId());
+
         if (task.getOwners().stream()
             .anyMatch(owner -> owner.getId().getOwnerId().equals(userDetails.id()))) {
             return getResponse(task);
@@ -171,6 +177,7 @@ public TaskResponseDTO addTaskOwner(Long taskId, AddOwnerRequestDTO addOwnerRequ
             .build();
 
         task.addOwner(owner);
+        auditOwnersUpdate(task);
 
         log.debug("User {} added to task`s {} owners", userDetails.id(), task.getId());
 
@@ -190,20 +197,24 @@ public TaskResponseDTO removeTaskOwner(Long taskId, RemoveOwnerRequestDTO remove
         UserAuthDetails userDetails = userFacade.findByEmail(removeOwnerRequest.ownerEmail())
             .orElseThrow(UserNotFoundException::new);
 
+        checkTaskVersion(task.getVersion(), removeOwnerRequest.version(), task.getId());
+
         Optional<TaskOwner> toRemove = task.getOwners().stream()
             .filter(o -> o.getId().getOwnerId().equals(userDetails.id())).findFirst();
 
-        if (toRemove.isPresent()) {
-            if (task.getOwners().size() == 1) {
-                throw new ValidationException(
-                    "Cannot remove the last owner of a task",
-                    ErrorCode.COMMON_VALIDATION_FAILED);
-            }
-            task.removeOwner(toRemove.get());
-        } else {
+        if (toRemove.isEmpty()) {
             return getResponse(task);
         }
 
+        if (task.getOwners().size() == 1) {
+            throw new ValidationException(
+                "Cannot remove the last owner of a task",
+                ErrorCode.COMMON_VALIDATION_FAILED);
+        }
+
+        task.removeOwner(toRemove.get());
+        auditOwnersUpdate(task);
+
         log.debug("User {} removed from task`s {} owners", userDetails.id(), task.getId());
 
         return getResponse(task);
@@ -333,4 +344,16 @@ private String getNormalizedSearch(String search) {
                 .replace("%", "\\%")
                 .replace("_", "\\_");
     }
+
+    private void checkTaskVersion(Long actualVersion, Long providedVersion, Long taskId) {
+        if (!Objects.equals(actualVersion, providedVersion)) {
+            throw new StaleTaskVersionException(taskId);
+        }
+    }
+
+    private void auditOwnersUpdate(TaskBody taskBody) {
+        taskBody.setUpdatedAt(Instant.now());
+        taskBody.setUpdatedBy(securityFacade.getCurrentUserId().orElseThrow(UserNotFoundException::new));
+        taskBodyRepository.saveAndFlush(taskBody);
+    }
 }

src/main/java/com/itasocialacademy/oitassist/task/service/TaskServiceImpl.java

@@ -148,7 +148,11 @@ public ResponseEntity<List<LinkedToursResponseDTO>> getLinkedTours(@PathVariable
                 schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Task assignment not found",
             content = @Content(mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class)))
+                schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PatchMapping("/task-assignments/{assignmentId}")
     @PreAuthorize("hasAnyRole('ADMIN', 'ORG')")