[Feature] add pessimistic locking on the Competition aggregate root (#558)

* feat: add findByIdForUpdate() to CompetitionRepository with pessimistic lock

* feat: set timeout for locking in application.yaml

* feat: add lockCompetitionForUpdate() to HierarchyValidator

* feat: update changeStatus() in CompetitionServiceImpl so that it uses lockCompetitionForUpdate() from HierarchyValidator

* feat: add handlePessimisticLockingFailure() handler to GlobalExceptionHandler

* chore: fix formatter

* feat: update unit tests in CompetitionServiceTest

* feat: update unit tests in CompetitionControllerTest & HierarchyValidatorTest

* chore: fix formatter

Author: antonpampukha

src/main/java/com/itasocialacademy/oitassist/competition/dao/repository/CompetitionRepository.java

@@ -2,13 +2,28 @@
 
 import com.itasocialacademy.oitassist.competition.dao.enums.CompetitionStatus;
 import com.itasocialacademy.oitassist.competition.dao.model.Competition;
+import jakarta.persistence.LockModeType;
+import java.util.Optional;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
 @Repository
 public interface CompetitionRepository extends JpaRepository<Competition, Long>, JpaSpecificationExecutor<Competition> {
     Page<Competition> findAllByCompetitionStatus(CompetitionStatus status, Pageable pageable);
+
+    /**
+     * Fetches a Competition with a pessimistic write lock (SELECT ... FOR UPDATE),
+     * used as the entry point for any structural hierarchy mutation or status
+     * transition, to serialize concurrent changes on the same competition and close
+     * the write-skew window between publish/finish and delete of a Stage/Tour.
+     */
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query("SELECT c from Competition c where c.id = :id")
+    Optional<Competition> findByIdForUpdate(@Param("id") Long id);
 }

src/main/java/com/itasocialacademy/oitassist/competition/service/CompetitionServiceImpl.java

@@ -96,8 +96,7 @@ public Page<CompetitionResponse> getArchived(CompetitionSearchFilter filter, Pag
     @Override
     @Transactional
     public CompetitionResponse changeStatus(Long competitionId, ChangeCompetitionStatusRequest request) {
-        Competition competition = competitionRepository.findById(competitionId)
-            .orElseThrow(() -> new CompetitionNotFoundException(competitionId));
+        Competition competition = validator.lockCompetitionForUpdate(competitionId);
 
         validator.validateEntityVersion(request.version(), competition.getVersion(), Competition.class, competitionId);
         CompetitionStatus currentStatus = competition.getCompetitionStatus();

src/main/java/com/itasocialacademy/oitassist/competition/validation/HierarchyValidator.java

@@ -89,14 +89,13 @@ public void checkIfStageInProgress(Long stageId, ExecutionStatus targetTourStatu
 
     /**
      * Checks whether it is allowed to change the hierarchy (add/remove stages and
-     * tours).
+     * tours). Locks the Competition row for the duration of the transaction.
      *
      * @param competitionId ID of a competition
      */
-    @Transactional(readOnly = true)
+    @Transactional
     public void validateImmutabilityByCompetitionId(Long competitionId) {
-        Competition competition = competitionRepository.findById(competitionId)
-            .orElseThrow(() -> new CompetitionNotFoundException(competitionId));
+        Competition competition = lockCompetitionForUpdate(competitionId);
 
         if (competition.getCompetitionStatus() == CompetitionStatus.ARCHIVED) {
             throw new CompetitionHierarchyValidationException(
@@ -360,4 +359,19 @@ public void validateEntityVersion(Long expectedVersion, Long actualVersion, Clas
             throw new StaleEntityVersionException(entityClass, entityId);
         }
     }
+
+    /**
+     * Fetches and locks the Competition row (SELECT ... FOR UPDATE) for the
+     * duration of the current transaction. Must be called before any structural
+     * hierarchy mutation or lifecycle status transition, to serialize concurrent
+     * changes on the same competition.
+     *
+     * @param competitionId Competition ID
+     * @return the locked Competition entity
+     */
+    @Transactional
+    public Competition lockCompetitionForUpdate(Long competitionId) {
+        return competitionRepository.findByIdForUpdate(competitionId)
+            .orElseThrow(() -> new CompetitionNotFoundException(competitionId));
+    }
 }

src/main/java/com/itasocialacademy/oitassist/core/web/GlobalExceptionHandler.java

@@ -1,14 +1,20 @@
 package com.itasocialacademy.oitassist.core.web;
 
 import com.itasocialacademy.oitassist.core.enums.ErrorCode;
-import com.itasocialacademy.oitassist.core.exceptions.*;
+import com.itasocialacademy.oitassist.core.exceptions.AuthenticationException;
+import com.itasocialacademy.oitassist.core.exceptions.BusinessException;
 import com.itasocialacademy.oitassist.core.exceptions.SecurityException;
 import com.itasocialacademy.oitassist.core.exceptions.TechnicalException;
 import jakarta.servlet.http.HttpServletRequest;
+import java.time.Instant;
+import java.util.Map;
+import java.util.Objects;
+import java.util.stream.Collectors;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.slf4j.MDC;
 import org.springframework.dao.OptimisticLockingFailureException;
+import org.springframework.dao.PessimisticLockingFailureException;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.http.converter.HttpMessageNotReadableException;
@@ -20,10 +26,6 @@
 import org.springframework.web.bind.MissingServletRequestParameterException;
 import org.springframework.web.bind.annotation.ControllerAdvice;
 import org.springframework.web.bind.annotation.ExceptionHandler;
-import java.time.Instant;
-import java.util.Map;
-import java.util.Objects;
-import java.util.stream.Collectors;
 import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
 import org.springframework.web.multipart.support.MissingServletRequestPartException;
 
@@ -240,6 +242,19 @@ public ResponseEntity<ErrorResponse> handleOptimisticLockingFailure(
                 null));
     }
 
+    @ExceptionHandler(PessimisticLockingFailureException.class)
+    public ResponseEntity<ErrorResponse> handlePessimisticLockingFailure(
+        PessimisticLockingFailureException ex, HttpServletRequest request) {
+        log.warn("Pessimistic locking conflict: traceId={}", MDC.get(TRACE_ID_MDC));
+        return ResponseEntity.status(HttpStatus.CONFLICT)
+            .body(buildResponse(
+                request,
+                ErrorCode.COMMON_CONFLICT,
+                "This competition is currently being edited; please try again.",
+                HttpStatus.CONFLICT.value(),
+                null));
+    }
+
     /**
      * Handles {@link MissingServletRequestPartException} by generating an
      * appropriate error response. This exception is thrown when a required part of

src/main/resources/application.yaml

@@ -19,6 +19,10 @@ spring:
     show-sql: ${JPA_SHOW_SQL}
     open-in-view: false
     properties:
+      jakarta:
+        persistence:
+          lock:
+            timeout: 3000
       hibernate.default_batch_fetch_size: 50
     hibernate:
       ddl-auto: ${JPA_HIBERNATE_DDL_AUTO:validate}

src/test/java/com/itasocialacademy/oitassist/competition/controller/CompetitionControllerTest.java

@@ -31,6 +31,7 @@
 import org.mockito.ArgumentCaptor;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
+import org.springframework.dao.PessimisticLockingFailureException;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageImpl;
 import org.springframework.data.domain.Pageable;
@@ -259,6 +260,19 @@ void changeStatus_staleVersion_shouldReturn409() throws Exception {
             .andExpect(status().isConflict());
     }
 
+    @Test
+    void changeStatus_pessimisticLockConflict_shouldReturn409() throws Exception {
+        ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.PUBLISHED, 1L);
+
+        when(competitionService.changeStatus(eq(1L), eq(request)))
+            .thenThrow(new PessimisticLockingFailureException("Lock wait timeout exceeded"));
+
+        mockMvc.perform(patch("/api/v1/competitions/{id}/status", 1L)
+            .contentType(MediaType.APPLICATION_JSON)
+            .content(objectMapper.writeValueAsString(request)))
+            .andExpect(status().isConflict());
+    }
+
     @Test
     void changeStatus_invalidRequest_nullVersion_shouldReturn400() throws Exception {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.PUBLISHED, null);

src/test/java/com/itasocialacademy/oitassist/competition/service/CompetitionServiceTest.java

@@ -98,7 +98,7 @@ void setUp() {
     @Test
     void changeStatus_draftToEnrollment_shouldSucceed() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.ENROLLMENT, 1L);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
 
         when(stageRepository.existsByCompetitionId(1L)).thenReturn(true);
         when(stageRepository.countStagesWithoutTours(1L)).thenReturn(0L);
@@ -115,7 +115,7 @@ void changeStatus_draftToEnrollment_shouldSucceed() {
     @Test
     void changeStatus_draftToPublished_directly_shouldThrowInvalidTransition() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.PUBLISHED, 1L);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
 
         doThrow(new CompetitionHierarchyValidationException("Invalid status transition from DRAFT to PUBLISHED"))
             .when(validator).validateCompetitionStatusTransition(CompetitionStatus.DRAFT, CompetitionStatus.PUBLISHED);
@@ -133,7 +133,8 @@ void changeStatus_enrollmentToPublished_withValidHierarchy_shouldSucceed() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.PUBLISHED, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.ENROLLMENT);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
+
         when(stageRepository.existsByCompetitionId(1L)).thenReturn(true);
         when(stageRepository.countStagesWithoutTours(1L)).thenReturn(0L);
         when(competitionRepository.save(any(Competition.class))).thenReturn(competition);
@@ -150,7 +151,7 @@ void changeStatus_enrollmentToPublished_withNoStages_shouldThrowException() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.PUBLISHED, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.ENROLLMENT);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
         when(stageRepository.existsByCompetitionId(1L)).thenReturn(false);
 
         CompetitionHierarchyValidationException exception = assertThrows(
@@ -166,7 +167,7 @@ void changeStatus_enrollmentToPublished_withEmptyStages_shouldThrowException() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.PUBLISHED, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.ENROLLMENT);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
         when(stageRepository.existsByCompetitionId(1L)).thenReturn(true);
         when(stageRepository.countStagesWithoutTours(1L)).thenReturn(2L);
 
@@ -183,7 +184,7 @@ void changeStatus_enrollmentToDraft_shouldThrowInvalidTransition() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.DRAFT, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.ENROLLMENT);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
 
         doThrow(new CompetitionHierarchyValidationException("Invalid status transition from ENROLLMENT to DRAFT"))
             .when(validator).validateCompetitionStatusTransition(CompetitionStatus.ENROLLMENT, CompetitionStatus.DRAFT);
@@ -200,7 +201,7 @@ void changeStatus_invalidTransition_publishedToDraft_shouldThrowException() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.DRAFT, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.PUBLISHED);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
 
         doThrow(new CompetitionHierarchyValidationException("Invalid status transition from PUBLISHED to DRAFT"))
             .when(validator).validateCompetitionStatusTransition(CompetitionStatus.PUBLISHED, CompetitionStatus.DRAFT);
@@ -219,7 +220,7 @@ void changeStatus_publishedToFinished_withAllStagesCompleted_shouldSucceed() {
             CompetitionStatus.FINISHED, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.PUBLISHED);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
         when(competitionRepository.save(any(Competition.class))).thenReturn(competition);
         when(mapper.toResponse(any(Competition.class))).thenReturn(getCompetitionResponse());
 
@@ -236,7 +237,7 @@ void changeStatus_publishedToFinished_withIncompleteStage_shouldThrowException()
             CompetitionStatus.FINISHED, 1L);
 
         competition.setCompetitionStatus(CompetitionStatus.PUBLISHED);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
 
         doThrow(new CompetitionHierarchyValidationException(
             "Cannot finish competition: Not all stages are completed. "
@@ -283,7 +284,7 @@ void create_validRequest_shouldSetDraftStatusAndSave() {
     @Test
     void changeStatus_versionMismatch_shouldThrowStaleEntityVersionException() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.ENROLLMENT, 5L);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
 
         doThrow(new StaleEntityVersionException(Competition.class, 1L))
             .when(validator).validateEntityVersion(anyLong(), anyLong(), any(), anyLong());
@@ -297,7 +298,7 @@ void changeStatus_versionMismatch_shouldThrowStaleEntityVersionException() {
     @Test
     void changeStatus_versionMatches_shouldProceedToTransitionValidation() {
         ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.ENROLLMENT, 1L);
-        when(competitionRepository.findById(1L)).thenReturn(Optional.of(competition));
+        when(validator.lockCompetitionForUpdate(1L)).thenReturn(competition);
         when(stageRepository.existsByCompetitionId(1L)).thenReturn(true);
         when(stageRepository.countStagesWithoutTours(1L)).thenReturn(0L);
         when(competitionRepository.save(any(Competition.class))).thenReturn(competition);
@@ -308,6 +309,16 @@ void changeStatus_versionMatches_shouldProceedToTransitionValidation() {
         verify(validator).validateCompetitionStatusTransition(CompetitionStatus.DRAFT, CompetitionStatus.ENROLLMENT);
     }
 
+    @Test
+    void changeStatus_competitionNotFound_shouldPropagateFromValidator() {
+        ChangeCompetitionStatusRequest request = new ChangeCompetitionStatusRequest(CompetitionStatus.ENROLLMENT, 1L);
+        when(validator.lockCompetitionForUpdate(99L)).thenThrow(new CompetitionNotFoundException(99L));
+
+        assertThrows(CompetitionNotFoundException.class, () -> competitionService.changeStatus(99L, request));
+
+        verify(competitionRepository, never()).save(any());
+    }
+
     // ---- getVisibleById ----
 
     @Test