S3ErrorHandler.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.storage

import java.util.UUID
import org.archtool.fileloader2.configuration.properties.S3Properties
import org.archtool.fileloader2.exception.ContentNotFoundException
import org.archtool.fileloader2.exception.ObjectStorageException
import org.slf4j.LoggerFactory
import org.springframework.stereotype.Component
import software.amazon.awssdk.core.exception.AbortedException
import software.amazon.awssdk.core.exception.SdkException
import software.amazon.awssdk.services.s3.model.NoSuchKeyException
import software.amazon.awssdk.services.s3.model.S3Exception

/**
 * Перевод ошибок AWS SDK в исключения сервиса для любой операции с объектом в S3. Каждая команда хранилища
 * оборачивает свой вызов SDK в [wrap], поэтому обработка ошибок и журнал одинаковы для всех операций.
 */
@Component
class S3ErrorHandler(
    s3Properties: S3Properties,
) {
    private val log = LoggerFactory.getLogger(javaClass)
    val bucket = s3Properties.bucketName

    /**
     * Выполняет вызов SDK. Содержимое считается отсутствующим только при коде NoSuchKey: HTTP 404 приходит
     * и при неверном bucket, 403 - при любых проблемах с правами. Остальные ошибки S3 и сети пишутся в журнал
     * со стеком и подробностями S3 (код ошибки, HTTP-статус, x-amz-request-id); выше их стек не повторяют.
     * Прерванный вызов (поток прерван) пишется в DEBUG без стека: это не сбой хранилища.
     *
     * @param operation название операции для журнала и сообщения об ошибке, например PutObject
     * @param fileId идентификатор файла
     * @param key ключ объекта
     * @param action вызов SDK
     * @return результат вызова
     * @throws ContentNotFoundException код ошибки NoSuchKey
     * @throws ObjectStorageException любая другая ошибка S3 или сети
     */
    fun <T> wrap(operation: String, fileId: UUID, key: String, action: () -> T): T {
        try {
            return action()
        } catch (_: NoSuchKeyException) {
            throw ContentNotFoundException(fileId, key)
        } catch (e: S3Exception) {
            // NoSuchBucket, AccessDenied, InvalidAccessKeyId, SignatureDoesNotMatch, 5xx - недоступность хранилища
            log.error(
                "Ошибка S3 при операции {}: id файла {}, ключ {}, bucket {}, код ошибки {}, HTTP-статус {}, x-amz-request-id {}",
                operation, fileId, key, bucket, e.awsErrorDetails()?.errorCode(), e.statusCode(), e.requestId(), e
            )
            throw ObjectStorageException("Хранилище S3 ответило ошибкой при операции $operation файла $fileId", e)
        } catch (e: AbortedException) {
            // SDK бросает его, когда поток прерван: запрос отменил запись остальных файлов после сбоя одного из них
            // (сбой уже записан в журнал) или сервис останавливается. Стек отменённой задачи - шум, к тому же после ответа клиенту
            log.debug("Операция {} прервана: id файла {}, ключ {}", operation, fileId, key)
            throw ObjectStorageException("Операция $operation файла $fileId прервана", e)
        } catch (e: SdkException) {
            log.error("Ошибка обращения к S3 при операции {}: id файла {}, ключ {}, bucket {}", operation, fileId, key, bucket, e)
            throw ObjectStorageException("Хранилище S3 недоступно при операции $operation файла $fileId", e)
        }
    }
}