DownloadService.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.download

import java.security.GeneralSecurityException
import org.archtool.fileloader2.configuration.properties.DownloadProperties
import org.archtool.fileloader2.exception.ContentLostException
import org.archtool.fileloader2.exception.ContentNotFoundException
import org.archtool.fileloader2.exception.UserDataException
import org.archtool.fileloader2.repository.FileRecord
import org.archtool.fileloader2.repository.FileRepository
import org.archtool.fileloader2.service.crypto.FileCipher
import org.archtool.fileloader2.service.storage.GetObjectCommand
import org.archtool.fileloader2.utils.UuidUtils
import org.slf4j.LoggerFactory
import org.springframework.stereotype.Service

/**
 * Скачивание файла. Файл отдаётся одинаково любому аутентифицированному пользователю, знающему идентификатор.
 * Код 404 для файлов не используется (он остаётся за несуществующим адресом): если файл выдать нельзя
 * по причине на стороне клиента - 400 с причиной.
 *
 * Смена статуса - одна инструкция UPDATE с условием на текущий статус, отдельная транзакция не нужна
 */
@Service
class DownloadService(
    private val fileRepository: FileRepository,
    private val getObjectCommand: GetObjectCommand,
    private val fileCipher: FileCipher,
    private val downloadProperties: DownloadProperties,
) {
    private val log = LoggerFactory.getLogger(javaClass)

    /**
     * Получает содержимое файла из хранилища и расшифровывает его целиком до начала ответа клиенту, поэтому
     * сбои хранилища и расшифровки всегда обнаруживаются до передачи. Файл с пометкой CONTENT_LOST в хранилище
     * не запрашивается, если не включено ignore-content-lost; при включённом - восстановленному файлу возвращается STORED_S3,
     * если его содержимое расшифровалось.
     *
     * @param rawFileId идентификатор файла из запроса
     * @return расшифрованное содержимое с исходным именем, типом и размером
     * @throws UserDataException идентификатор не UUID, файла нет (или он кандидат)
     * @throws ContentLostException содержимое утрачено
     * @throws org.archtool.fileloader2.exception.ObjectStorageException хранилище недоступно, статус не меняется
     * @throws IllegalStateException содержимое не расшифровывается, статус не меняется
     */
    fun download(rawFileId: String): DownloadedFile {
        val fileId = UuidUtils.tryParseUuid(rawFileId)
            ?: throw UserDataException("Идентификатор файла должен быть UUID")

        val record = fileRepository.findById(fileId)
        // кандидат ещё не сохранён или его загрузка оборвалась: для клиента такого файла нет
        if (record == null || record.status == FileRecord.FileStatus.CANDIDATE) {
            throw UserDataException("Файл не найден")
        }
        val ignoreContentLost = downloadProperties.ignoreContentLost
        if (record.status == FileRecord.FileStatus.CONTENT_LOST && !ignoreContentLost) {
            throw ContentLostException(fileId)
        }

        val encrypted = try {
            getObjectCommand.get(fileId)
        } catch (e: ContentNotFoundException) {
            onContentNotFound(record, ignoreContentLost, e.key)
        }

        // статус возвращается только после расшифровки: битое или чужое содержимое не должно сделать файл STORED_S3
        val content = decrypt(record, encrypted)

        // содержимое вернули в хранилище, например из резервной копии
        if (record.status == FileRecord.FileStatus.CONTENT_LOST) {
            fileRepository.updateStatus(listOf(fileId), from = FileRecord.FileStatus.CONTENT_LOST, to = FileRecord.FileStatus.STORED_S3)
            log.info("Содержимое файла {} снова есть в хранилище, файлу возвращён статус STORED_S3", fileId)
        }
        return DownloadedFile(
            name = record.originalName,
            contentType = record.contentType,
            sizeBytes = record.sizeBytes,
            content = content,
        )
    }

    /**
     * Обрабатывает отсутствие содержимого в хранилище: помечает сохранённый файл как CONTENT_LOST, чтобы
     * не обращаться за ним в хранилище при следующих запросах. При включённом ignore-content-lost пометка не ставится.
     * Если БД недоступна при пометке, ошибка БД уходит клиенту как 500, файл будет помечен при следующем запросе.
     *
     * @param record запись файла
     * @param ignoreContentLost включено ли игнорирование пометки
     * @param key ключ объекта, по которому не нашлось содержимого
     * @throws ContentLostException всегда: содержимое утрачено
     */
    private fun onContentNotFound(record: FileRecord, ignoreContentLost: Boolean, key: String): Nothing {
        if (ignoreContentLost) {
            log.warn("Содержимого файла {} нет в хранилище (ключ {}), пометка не ставится: включено ignore-content-lost", record.id, key)
        } else if (record.status == FileRecord.FileStatus.STORED_S3) {
            fileRepository.updateStatus(listOf(record.id), from = FileRecord.FileStatus.STORED_S3, to = FileRecord.FileStatus.CONTENT_LOST)
            log.warn("Содержимого файла {} нет в хранилище (ключ {}), файл помечен CONTENT_LOST", record.id, key)
        }
        throw ContentLostException(record.id)
    }

    /**
     * Расшифровывает содержимое и проверяет его целостность. Причину ошибки - изменённую фразу шифрования
     * или повреждённые данные - сервис не различает, разбор выполняется вручную. Статус файла не меняется.
     *
     * @param record запись файла с параметрами шифрования
     * @param encrypted содержимое из хранилища
     * @return исходное содержимое
     * @throws IllegalStateException содержимое не расшифровывается
     */
    private fun decrypt(record: FileRecord, encrypted: ByteArray): ByteArray {
        try {
            return fileCipher.decryptor(record.id, record.encryptionSalt, record.encryptionIv).doFinal(encrypted)
        } catch (e: GeneralSecurityException) {
            throw IllegalStateException("Не удалось расшифровать содержимое файла ${record.id}, требуется ручной разбор", e)
        }
    }
}