CandidateCleanupScheduler.kt

/*
  Copyright (C) 2026 Sber

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  In any derivative products, you must retain the information of
  owner of the original code and provide clear attribution to the project

  https://dochub.info

  The use of this product or its derivatives for any purpose cannot be a secret.


  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

  Maintainers:
      Sergeev Viktor <sergeevviktor017@gmail.com>, Sber - 2026

  Contributors:
      Sergeev Viktor <sergeevviktor017@gmail.com>, Sber - 2026
*/

package org.archtool.fileloader2.service.cleanup

import jakarta.annotation.PostConstruct
import jakarta.annotation.PreDestroy
import org.archtool.fileloader2.configuration.properties.CleanupProperties
import org.archtool.fileloader2.exception.ObjectStorageException
import org.archtool.fileloader2.repository.FileRepository
import org.archtool.fileloader2.service.storage.DeleteObjectCommand
import org.archtool.fileloader2.utils.DateTimeComponent
import org.slf4j.LoggerFactory
import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler
import org.springframework.stereotype.Component

/**
 * Очистка брошенных кандидатов: по расписанию удаляет файлы, не ставшие STORED_S3 за порог abandoned-after
 * (загрузка оборвалась из-за сбоя сервиса, БД или хранилища), вместе с их содержимым в хранилище.
 *
 * Порядок «сначала содержимое, потом запись» выбран намеренно: если удаление прервётся между шагами, запись останется
 * и следующий запуск повторит удаление. Содержимое без записи в хранилище не остаётся.
 *
 * Удаляются все, кто был кандидатом на момент выборки: запись удаляется без проверки статуса. Если загрузка шла дольше
 * порога и успела перевести файл в STORED_S3 после выборки, его содержимое к этому моменту уже удалено, а запись без
 * содержимого не нужна. По плану такая загрузка невозможна: сервис не рассчитан на запросы длиннее порога.
 *
 * При нескольких экземплярах очистка может идти одновременно на всех и брать одних и тех же кандидатов.
 * Блокировки не нужны: удаление отсутствующего содержимого и уже удалённой записи - не ошибка
 */
@Component
class CandidateCleanupScheduler(
    private val fileRepository: FileRepository,
    private val deleteObjectCommand: DeleteObjectCommand,
    private val dateTimeComponent: DateTimeComponent,
    private val cleanupProperties: CleanupProperties,
) {
    private val log = LoggerFactory.getLogger(javaClass)

    // свой планировщик на 1 поток: запуски очистки не пересекаются и не занимают общий планировщик
    private val scheduler = ThreadPoolTaskScheduler().apply {
        poolSize = 1
        setThreadNamePrefix("candidate-cleanup-")
    }

    /**
     * Запускает очистку по расписанию: первый запуск сразу после старта сервиса, следующие - через interval
     * после завершения предыдущего.
     */
    @PostConstruct
    fun start() {
        log.info("Очистка брошенных кандидатов запущена: порог {}, интервал {}", cleanupProperties.abandonedAfter, cleanupProperties.interval)
        scheduler.initialize()
        scheduler.scheduleWithFixedDelay({ cleanup() }, cleanupProperties.interval)
    }

    /**
     * Останавливает расписание при остановке сервиса. Новые запуски не начинаются, а выполняющийся запуск прерывается
     * без ожидания: shutdown() без waitForTasksToCompleteOnShutdown вызывает shutdownNow, поток получает interrupt.
     * Данные остаются согласованными: содержимое удаляется раньше записи, недоудалённых кандидатов обработает
     * следующий запуск после старта.
     */
    @PreDestroy
    fun stop() {
        scheduler.shutdown()
    }

    /**
     * Один запуск очистки: находит кандидатов старше порога и для каждого удаляет содержимое, затем запись.
     * При первой ошибке БД или хранилища запуск прекращается, оставшиеся кандидаты обрабатываются в следующий раз.
     * Если поток прерван остановкой сервиса ([stop]), ошибка обращения к БД или хранилищу - следствие прерывания,
     * а не сбой: пишется INFO. Флаг прерывания не сбрасывается.
     * Исключения не выбрасывает: иначе планировщик отменит следующие запуски.
     */
    fun cleanup() {
        try {
            val abandonedBeforeUtc = dateTimeComponent.nowUtc().minus(cleanupProperties.abandonedAfter)
            val candidateIds = fileRepository.findCandidateIdsCreatedBefore(abandonedBeforeUtc)
            if (candidateIds.isEmpty()) {
                log.debug("Брошенных кандидатов, зарегистрированных раньше {} UTC, нет", abandonedBeforeUtc)
                return
            }
            log.info("Найдено брошенных кандидатов: {}, зарегистрированы раньше {} UTC", candidateIds.size, abandonedBeforeUtc)
            var deleted = 0
            candidateIds.forEach { fileId ->
                try {
                    deleteObjectCommand.delete(fileId)
                    if (fileRepository.delete(fileId) == 0) {
                        // запись удалили после выборки, например очистка другого экземпляра
                        log.debug("Запись брошенного кандидата {} уже удалена не этим сервером, нормальная ситуация если запущено несколько экземпляров", fileId)
                        return@forEach
                    }
                    deleted++
                    log.debug("Брошенный кандидат {} удалён", fileId)
                } catch (e: Exception) {
                    when {
                        Thread.currentThread().isInterrupted ->
                            log.info(INTERRUPTED_MESSAGE, deleted, candidateIds.size)
                        // ошибка со стеком и подробностями S3 уже записана в журнал при обращении к хранилищу
                        e is ObjectStorageException ->
                            log.error(DELETE_FAILED_MESSAGE, fileId, deleted, candidateIds.size, e.message)
                        else ->
                            log.error(DELETE_FAILED_MESSAGE, fileId, deleted, candidateIds.size, e.message, e)
                    }
                    return
                }
            }
            log.info("Удалено брошенных кандидатов: {} из {}", deleted, candidateIds.size)
        } catch (e: Exception) {
            if (Thread.currentThread().isInterrupted) {
                log.info("Очистка брошенных кандидатов прервана остановкой сервиса, повтор после старта")
            } else {
                log.error("Ошибка очистки брошенных кандидатов, повтор при следующем запуске", e)
            }
        }
    }

    companion object {
        private const val DELETE_FAILED_MESSAGE = "Не удалось удалить брошенного кандидата {}, очистка прекращена. " +
                "Удалено {} из {}, оставшиеся будут обработаны при следующем запуске. Причина: {}"
        private const val INTERRUPTED_MESSAGE = "Очистка брошенных кандидатов прервана остановкой сервиса. " +
                "Удалено {} из {}, оставшиеся будут обработаны после старта"
    }
}