UploadService.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

  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.
*/

package org.archtool.fileloader2.service.upload

import com.github.f4b6a3.uuid.UuidCreator
import java.time.LocalDateTime
import javax.crypto.CipherInputStream
import org.archtool.fileloader2.repository.FileRecord
import org.archtool.fileloader2.repository.FileRepository
import org.archtool.fileloader2.repository.FileTableColumnLength
import org.archtool.fileloader2.service.concurrent.ParallelTaskRunner
import org.archtool.fileloader2.service.crypto.FileCipher
import org.archtool.fileloader2.service.storage.PutObjectCommand
import org.archtool.fileloader2.utils.DateTimeComponent
import org.slf4j.LoggerFactory
import org.springframework.stereotype.Service
import org.springframework.transaction.support.TransactionTemplate
import org.springframework.web.multipart.MultipartFile

/**
 * Загрузка файлов. Файлы запроса сохраняются по принципу «всё или ничего»: либо все в STORED_S3, либо ни один.
 *
 * Транзакция БД не держится открытой на время записи в S3: кандидаты регистрируются одной транзакцией,
 * содержимое пишется без транзакции, перевод в STORED_S3 - второй транзакцией.
 * При любой ошибке после регистрации кандидаты остаются, их вместе с содержимым удаляет фоновая очистка
 * брошенных кандидатов. Повтор загрузки клиентом безопасен: создаются новые кандидаты.
 */
@Service
class UploadService(
    private val uploadValidator: UploadValidator,
    private val fileRepository: FileRepository,
    private val putObjectCommand: PutObjectCommand,
    private val fileCipher: FileCipher,
    private val transactionTemplate: TransactionTemplate,
    private val dateTimeComponent: DateTimeComponent,
    private val parallelTaskRunner: ParallelTaskRunner,
) {
    private val log = LoggerFactory.getLogger(javaClass)

    /**
     * Проверяет запрос, регистрирует кандидатов, записывает зашифрованное содержимое и переводит файлы в STORED_S3.
     *
     * @param files файлы запроса, от 1 до N
     * @param uploadedBy кто загружает (sub из токена); null или пусто - ошибка, файл без автора не принимается
     * @return сохранённые файлы в порядке частей запроса
     * @throws org.archtool.fileloader2.exception.UserDataException запрос не прошёл проверку, ничего не сохранено
     * @throws org.archtool.fileloader2.exception.ObjectStorageException хранилище недоступно, файлы не сохранены
     * @throws IllegalStateException sub в токене нет, он пустой или длиннее колонки uploaded_by - ошибка провайдера токенов,
     * ничего не сохранено;
     * в STORED_S3 переведены не все файлы, перевод отменён
     */
    fun upload(files: List<MultipartFile>, uploadedBy: String?): List<UploadedFile> {
        // sub выдаёт провайдер токенов: пользователь не может это исправить, поэтому ответ 500, а не 400
        check(!uploadedBy.isNullOrBlank()) {
            "В токене нет идентификатора пользователя (sub): файл без автора не принимается"
        }
        check(uploadedBy.length <= FileTableColumnLength.UPLOADED_BY) {
            "Идентификатор пользователя (sub) в токене длиннее ${FileTableColumnLength.UPLOADED_BY} символов - размера колонки uploaded_by"
        }
        val validatedFiles = uploadValidator.validate(files)

        val createdAtUtc = dateTimeComponent.nowUtc()
        val candidates = validatedFiles.map { validated ->
            UploadCandidate(validated.file, newCandidateRecord(validated, uploadedBy, createdAtUtc))
        }
        val ids = candidates.map { it.record.id }

        transactionTemplate.executeWithoutResult {
            fileRepository.insertAll(
                candidates.map { it.record }
            )
        }
        log.debug("Зарегистрированы кандидаты {}, загружает {}", ids, uploadedBy)

        writeContent(candidates)

        transactionTemplate.executeWithoutResult {
            val countUpdatedRows = fileRepository.updateStatus(ids, from = FileRecord.FileStatus.CANDIDATE, to = FileRecord.FileStatus.STORED_S3)
            if (countUpdatedRows != ids.size) {
                // кандидата удалила очистка или изменил другой запрос: не сохраняем часть файлов, откатываем транзакцию
                throw IllegalStateException(
                    "В статус STORED_S3 переведено $countUpdatedRows файлов из ${ids.size}, фиксация отменена. Кандидаты $ids"
                )
            }
        }
        log.info("Сохранены файлы {}, загрузил {}", ids, uploadedBy)

        return candidates.map { UploadedFile(id = it.record.id, name = it.record.originalName) }
    }

    /**
     * Готовит запись кандидата: новый идентификатор UUID v7 (упорядочен по времени), случайные соль и IV.
     * Тип содержимого - определённый при проверке запроса.
     *
     * @param validated файл из запроса, прошедший проверку
     * @param uploadedBy кто загружает, проверен: не пустой и не длиннее колонки
     * @param createdAtUtc время регистрации, одно для всех файлов запроса
     * @return запись в статусе CANDIDATE
     */
    private fun newCandidateRecord(validated: ValidatedFile, uploadedBy: String, createdAtUtc: LocalDateTime): FileRecord {
        val file = validated.file
        return FileRecord(
            id = UuidCreator.getTimeOrderedEpoch(),
            status = FileRecord.FileStatus.CANDIDATE,
            originalName = validated.name,
            contentType = validated.contentType,
            sizeBytes = file.size,
            encryptionSalt = fileCipher.generateSalt(),
            encryptionIv = fileCipher.generateIv(),
            uploadedBy = uploadedBy,
            createdAtUtc = createdAtUtc,
        )
    }

    /**
     * Записывает содержимое файлов в хранилище: один файл - в потоке запроса, несколько - параллельно.
     * Запрос ждёт записи всех своих файлов. Если запись одного файла не удалась, остальные записи отменяются,
     * уже записанные объекты удалит очистка вместе с кандидатами.
     *
     * @param candidates файлы запроса с их записями
     * @throws org.archtool.fileloader2.exception.ObjectStorageException запись хотя бы одного файла не удалась
     * @throws InterruptedException поток запроса прерван во время ожидания записи
     */
    private fun writeContent(candidates: List<UploadCandidate>) {
        parallelTaskRunner.runAll(candidates.map { candidate -> { writeOne(candidate) } })
    }

    /**
     * Шифрует содержимое файла на лету и записывает его в хранилище. Длина объекта - исходный размер плюс тег AES-GCM.
     * Ключ получается один раз на файл и живёт только на время записи: при повторе запроса SDK заново открывается
     * только файл и создаётся шифратор из готового ключа.
     *
     * @param candidate файл и его запись с параметрами шифрования
     * @throws org.archtool.fileloader2.exception.ObjectStorageException хранилище недоступно или ответило ошибкой
     */
    private fun writeOne(candidate: UploadCandidate) {
        val record = candidate.record
        val key = fileCipher.deriveKey(record.id, record.encryptionSalt)
        putObjectCommand.put(record.id, record.sizeBytes + FileCipher.ENCRYPTION_OVERHEAD_BYTES) {
            // лямбда должна возвращать каждый раз новый inputStream т.к. вызывается на каждую попытку SDK:
            // новый поток и новый шифратор, тот же ключ и IV дают тот же шифротекст
            CipherInputStream(candidate.file.inputStream, fileCipher.encryptor(key, record.encryptionIv))
        }
        log.debug("Содержимое файла {} записано в хранилище", record.id)
    }

    /**
     * Файл из запроса и подготовленная для него запись
     */
    private class UploadCandidate(
        val file: MultipartFile,
        val record: FileRecord,
    )
}