12 KiB
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 проверяться без участия приложения двумя способами.
-
Каждый запуск bootstrap:
- ключ API записывает и читает проверочный объект и получает отказ на список и на создание bucket;
- ключ уборщика читает и удаляет этот объект и получает отказ на запись и на список;
- аноним получает отказ на чтение существующего объекта и на список.
При нарушении bootstrap завершается с ненулевым кодом, и реплики API не стартуют.
-
Отдельная команда
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 и его доступ не меняются