# Spec Delta ## MODIFIED Requirements ### Requirement: Приватный bucket создаёт bootstrap Bucket приложения SHALL создавать одноразовый сервис bootstrap стенда. Bootstrap SHALL: - создать bucket, если его нет; - запретить анонимный доступ к bucket; - завести пользователя API с политикой доступа (требование «Ограниченные учётные данные API») и ключами из `.env`; - завести пользователя уборщика с его политикой (требование «Ограниченные учётные данные уборщика») и ключами из `.env`. На рабочем стенде реплики API и уборщик MUST NOT стартовать, пока bootstrap не завершился успешно. Стенды проверок с S3 (`make test_isolated`, `make failure_checks`) запускают bootstrap до своих контейнеров API, а стенд отказов — и до своего уборщика. Повторный запуск SHALL завершаться успешно и не менять уже правильное состояние: bucket и его объекты сохраняются, пользователи не пересоздаются. Если в `.env` изменился секрет API или уборщика, повторный запуск SHALL привести к нему учётные данные этого пользователя, а прежний секрет SHALL перестать действовать. Вывод bootstrap MUST NOT содержать секретов. Ошибка любого шага SHALL давать ненулевой код выхода и сообщение, которое называет шаг. #### Scenario: Первый запуск - **WHEN** стенд поднимается на пустом volume S3 - **THEN** bootstrap создаёт bucket, пользователей API и уборщика и завершается с кодом 0, и только после этого стартуют реплики API и уборщик #### Scenario: Повторный запуск - **WHEN** на работающем стенде bootstrap запускается ещё дважды подряд - **THEN** оба запуска завершаются с кодом 0 и сообщают, что bucket и оба пользователя уже есть, а записанные ранее объекты читаются #### Scenario: Новый секрет API - **WHEN** в `.env` изменён секрет API или секрет уборщика, и bootstrap запущен снова - **THEN** запросы S3 с новым секретом этого пользователя проходят, а с прежним получают отказ #### Scenario: Ошибка bootstrap - **WHEN** bootstrap не может выполнить шаг, например имя bucket недопустимо - **THEN** он завершается с ненулевым кодом и сообщением о шаге, реплики API не стартуют, а в выводе нет секретов ### Requirement: Проверка приватности вне API Приватность bucket и права ключей API и уборщика SHALL проверяться без участия приложения двумя способами. 1. Каждый запуск bootstrap: - ключ API записывает и читает проверочный объект и получает отказ на список и на создание bucket; - ключ уборщика читает и удаляет этот объект и получает отказ на запись и на список; - аноним получает отказ на чтение существующего объекта и на список. При нарушении bootstrap завершается с ненулевым кодом, и реплики API не стартуют. 2. Отдельная команда `make s3_check` на запущенном стенде. Она повторяет проверки bootstrap и добавляет: - анонимные запросы с хоста и из сети стенда; - запросы ключей API и уборщика к чужому bucket; - административные запросы ключей API и уборщика; - запись и список ключом уборщика. Команда SHALL печатать по каждой проверке ожидаемый и полученный код ответа без секретов. При любом нарушении код выхода SHALL быть ненулевым. Свои проверочные объекты и bucket команда SHALL удалять. #### Scenario: Проверка командой - **WHEN** на запущенном стенде выполняется `make s3_check` - **THEN** каждая проверка напечатана с полученным кодом ответа, в том числе проверки ключа уборщика, код выхода 0, а проверочных объектов и bucket после команды нет #### Scenario: Bucket стал публичным - **WHEN** на bucket открыт анонимный доступ на чтение, например административной командой мимо bootstrap - **THEN** `make s3_check` завершается с ненулевым кодом и называет нарушенную проверку, а следующий запуск bootstrap снова закрывает доступ ### Requirement: Клиент хранилища в приложении Процессы приложения SHALL обращаться к S3 с учётными данными своей роли из секции `[s3]`: реплики API — ключами пользователя API, уборщик — ключами пользователя уборщика. Клиент SHALL уметь записать объект, прочитать его потоком, получить метаданные и удалить. Удаление отсутствующего объекта — не ошибка. Каждый вызов SHALL быть ограничен сроком из настроек. После отказа или истечения срока вызов MUST NOT повторяться автоматически. Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в формате контракта, SHALL заканчиваться вызов, если S3: - недоступен; - не ответил за срок; - отклонил учётные данные; - отказал ключу в доступе или не нашёл bucket. Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL отличаться от недоступности: отсутствующий bucket MUST NOT выдаваться за отсутствующий объект у записи, чтения и удаления. После возврата S3 вызовы SHALL проходить без перезапуска приложения. Соединения с S3 SHALL открываться при первом вызове, а при остановке сервиса клиент SHALL закрываться. Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`. Так объекты прогона на временной базе (`make test_isolated`) отделены от объектов рабочей базы. #### Scenario: S3 остановлен - **WHEN** S3 остановлен, и приложение записывает объект - **THEN** вызов за доли секунды завершается ошибкой недоступности, без повторов #### Scenario: S3 завис - **WHEN** контейнер S3 заморожен (`docker pause`), и приложение записывает объект - **THEN** вызов завершается ошибкой недоступности не позже срока вызова #### Scenario: S3 вернулся - **WHEN** S3 снова доступен, а приложение не перезапускалось - **THEN** следующий вызов проходит #### Scenario: Объекта нет - **WHEN** приложение читает ключ, которого в bucket нет - **THEN** клиент сообщает, что объекта нет, а не недоступность S3 #### Scenario: Bucket нет - **WHEN** bucket приложения удалён мимо bootstrap, и приложение записывает, читает или удаляет объект - **THEN** каждый вызов завершается ошибкой недоступности, а не сообщением «объекта нет», и в журнале есть запись уровня `error` #### Scenario: Учётные данные отклонены - **WHEN** секрет API у приложения не совпадает с секретом на сервере S3 - **THEN** вызов завершается ошибкой недоступности, а в журнале есть запись уровня `error` без секрета ## ADDED Requirements ### Requirement: Ограниченные учётные данные уборщика У уборщика (capability `storage-consistency`) SHALL быть свои учётные данные S3, отдельные от учётных данных API и административных. Пользователю уборщика SHALL быть разрешены только чтение и удаление объектов своего bucket. Ему MUST NOT быть разрешены: - запись объектов; - список объектов; - операции с bucket: создание, удаление, политика, ACL; - публичный ACL объекта; - управление учётными записями; - любой доступ к другим bucket. Ключи уборщика MUST NOT передаваться репликам API. Уборщик MUST NOT получать ключи API, административные ключи S3 и ключ подписи. #### Scenario: Работа уборщика с объектами - **WHEN** ключом API записан объект, а ключом уборщика он прочитан, удалён и удалён ещё раз - **THEN** чтение отдаёт те же байты, оба удаления успешны, а объекта после них нет #### Scenario: Запрещённые операции уборщика - **WHEN** ключом уборщика запрашиваются запись объекта, список объектов, создание и удаление bucket, политика и ACL bucket, публичный ACL объекта и объект другого bucket - **THEN** каждый запрос получает 403, а bucket и его доступ не меняются