193 lines
12 KiB
Markdown
193 lines
12 KiB
Markdown
# 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 и его доступ не
|
|
меняются
|