GlobalExceptionHandler.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.controller

import io.micrometer.tracing.Tracer
import jakarta.servlet.ServletException
import org.archtool.fileloader2.controller.api.dto.ApiError
import org.archtool.fileloader2.exception.ContentLostException
import org.archtool.fileloader2.exception.ObjectStorageException
import org.archtool.fileloader2.exception.SecurityDataException
import org.archtool.fileloader2.exception.ServiceOverloadedException
import org.archtool.fileloader2.exception.UserDataException
import org.springframework.http.MediaType
import org.slf4j.LoggerFactory
import org.springframework.http.HttpStatus
import org.springframework.http.HttpStatusCode
import org.springframework.http.ResponseEntity
import org.springframework.web.ErrorResponse
import org.springframework.web.bind.annotation.ControllerAdvice
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.context.request.async.AsyncRequestNotUsableException
import org.springframework.web.multipart.MaxUploadSizeExceededException
import org.springframework.web.multipart.MultipartException

/**
 * Глобальный обработчик исключений для всех контроллеров.
 * Ошибка клиента - 400 с причиной, ошибка сервиса или смежной системы (БД, S3) - 500 без подробностей.
 * Тело ответа с ошибкой, сформированного этим обработчиком, всегда JSON ([ApiError]). Отказ в аутентификации (401)
 * формирует Spring Security до вызова контроллера, этот ответ уходит без тела.
 */
@ControllerAdvice
class GlobalExceptionHandler(
    private val tracer: Tracer
) {

    private val log = LoggerFactory.getLogger(javaClass)

    /**
     * Любая непредвиденная ошибка сервиса или БД. Подробности пишутся в журнал, клиенту не отдаются.
     *
     * @param ex исключение
     * @return ответ 500
     */
    @ExceptionHandler(Exception::class)
    fun handleGeneralException(ex: Exception): ResponseEntity<ApiError> {
        log.error("Необработанное исключение: {}", ex.message, ex)
        return error(status = HttpStatus.INTERNAL_SERVER_ERROR, message = INTERNAL_ERROR_MESSAGE)
    }

    /**
     * Хранилище S3 недоступно или ответило ошибкой. Ошибка со стеком и подробностями S3 уже записана в журнал
     * при обращении к хранилищу, здесь - одна строка без стека, чтобы не дублировать её.
     *
     * @param ex исключение обращения к хранилищу
     * @return ответ 500
     */
    @ExceptionHandler(ObjectStorageException::class)
    fun handleObjectStorageException(ex: ObjectStorageException): ResponseEntity<ApiError> {
        log.error("Запрос завершён ошибкой из-за хранилища S3: {}", ex.message)
        return error(status = HttpStatus.INTERNAL_SERVER_ERROR, message = INTERNAL_ERROR_MESSAGE)
    }

    /**
     * Содержимое файла утрачено. Клиенту причина не раскрывается: общий ответ 500 с traceId, по которому поддержка
     * найдёт в журнале идентификатор файла. Стек не пишется: причина полностью описана в сообщении.
     *
     * @param ex исключение с идентификатором файла
     * @return ответ 500
     */
    @ExceptionHandler(ContentLostException::class)
    fun handleContentLostException(ex: ContentLostException): ResponseEntity<ApiError> {
        log.error("Скачивание не выполнено: {}", ex.message)
        return error(status = HttpStatus.INTERNAL_SERVER_ERROR, message = INTERNAL_ERROR_MESSAGE)
    }

    /**
     * Пул записи в S3 не принял задачу: очередь переполнена (перегрузка) или сервис останавливается.
     * Стек не пишется: причина известна, а частое повторение при перегрузке засорило бы журнал.
     *
     * @param ex отказ пула
     * @return ответ 500
     */
    @ExceptionHandler(ServiceOverloadedException::class)
    fun handleServiceOverloadedException(ex: ServiceOverloadedException): ResponseEntity<ApiError> {
        log.warn("{}. Очередь переполнена или сервис останавливается", ex.message)
        return error(status = HttpStatus.INTERNAL_SERVER_ERROR, message = INTERNAL_ERROR_MESSAGE)
    }

    /**
     * Клиент оборвал соединение во время передачи ответа, например прервал скачивание. Штатный сценарий, а не ошибка
     * сервиса. Spring оборачивает в это исключение любую ошибку записи в ответ. Ответ уже начат, а соединение
     * закрыто, поэтому тело с ошибкой не пишется.
     *
     * @param ex исключение записи в ответ
     * @return null: ответ не формируется
     */
    @ExceptionHandler(AsyncRequestNotUsableException::class)
    fun handleAsyncRequestNotUsableException(ex: AsyncRequestNotUsableException): ResponseEntity<ApiError>? {
        log.debug("Клиент оборвал соединение во время передачи ответа: {}", ex.message)
        return null
    }

    /**
     * Ошибка в запросе клиента: сообщение исключения отдаётся клиенту как причина.
     *
     * @param ex исключение с причиной
     * @return ответ 400
     */
    @ExceptionHandler(UserDataException::class)
    fun handleUserDataException(ex: UserDataException): ResponseEntity<ApiError> {
        log.debug("Ошибка в запросе пользователя {}", ex.message, ex)
        return error(status = HttpStatus.BAD_REQUEST, message = ex.message)
    }

    /**
     * Файл не прошёл проверку типа. Подробности пишутся в журнал, клиенту - общая причина без подробностей.
     * Стек не пишется: причина полностью описана в сообщении.
     *
     * @param ex исключение с подробной причиной
     * @return ответ 400
     */
    @ExceptionHandler(SecurityDataException::class)
    fun handleSecurityDataException(ex: SecurityDataException): ResponseEntity<ApiError> {
        log.warn("Файл не прошёл проверку типа: {}", ex.message)
        return error(status = HttpStatus.BAD_REQUEST, message = FILE_VALIDATION_FAILED_MESSAGE)
    }

    /**
     * Файл или запрос больше spring.servlet.multipart.max-file-size / max-request-size. Контроллер не вызывался.
     *
     * @param ex исключение разбора multipart
     * @return ответ 400
     */
    @ExceptionHandler(MaxUploadSizeExceededException::class)
    fun handleMaxUploadSizeExceededException(ex: MaxUploadSizeExceededException): ResponseEntity<ApiError> {
        log.debug("Превышен размер файла или запроса {}", ex.message, ex)
        return error(status = HttpStatus.BAD_REQUEST, message = "Размер файла или запроса превышает допустимый")
    }

    /**
     * Ошибка разбора multipart, в том числе обрыв соединения клиентом во время передачи файлов.
     * Контроллер не вызывался, ничего не сохранено.
     *
     * @param ex исключение разбора multipart
     * @return ответ 400 (если клиент оборвал соединение, ответ не будет доставлен)
     */
    @ExceptionHandler(MultipartException::class)
    fun handleMultipartException(ex: MultipartException): ResponseEntity<ApiError> {
        log.debug("Не удалось разобрать multipart запрос {}", ex.message, ex)
        return error(status = HttpStatus.BAD_REQUEST, message = ex.message ?: BAD_REQUEST)
    }

    /**
     * Ошибка в запросе до попадания в контроллер. У исключений Spring MVC со своим кодом (ErrorResponse) код сохраняется:
     * несуществующий адрес остаётся 404, неподдерживаемый метод - 405. Остальные - 400.
     * Исключения Spring MVC (NoResourceFoundException, HttpRequestMethodNotSupportedException и др.) наследуют
     * ServletException и одновременно реализуют ErrorResponse, поэтому приведение к ErrorResponse срабатывает.
     *
     * @param ex исключение Spring MVC
     * @return ответ с кодом исключения или 400
     */
    @ExceptionHandler(ServletException::class)
    fun handleServletException(ex: ServletException): ResponseEntity<ApiError> {
        log.debug("Ошибка в запросе пользователя, до попадания в контроллер {}", ex.message, ex)
        val status = (ex as? ErrorResponse)?.statusCode ?: HttpStatus.BAD_REQUEST
        return error(status = status, message = ex.message ?: BAD_REQUEST)
    }

    /**
     * Формирует ответ с ошибкой в JSON. Тип задан явно: у скачивания нет produces, и без этого тип ответа с ошибкой
     * зависел бы от заголовка Accept клиента.
     *
     * @param status код ответа
     * @param message причина для клиента
     * @return ответ с [ApiError] и traceId текущего запроса
     */
    private fun error(status: HttpStatusCode, message: String): ResponseEntity<ApiError> {
        return ResponseEntity.status(status)
            .contentType(MediaType.APPLICATION_JSON)
            .body(
                ApiError(
                    status = status.value(),
                    error = HttpStatus.resolve(status.value())?.reasonPhrase ?: status.toString(),
                    message = message,
                    traceId = tracer.currentSpan()?.context()?.traceId() ?: "not set",
                )
            )
    }

    companion object {
        private const val BAD_REQUEST = "Bad request"
        private const val INTERNAL_ERROR_MESSAGE = "Произошла непредвиденная ошибка. Попробуйте позже."
        private const val FILE_VALIDATION_FAILED_MESSAGE = "Файл не прошёл проверку"
    }
}