15 KiB
Spec Delta
MODIFIED Requirements
Requirement: Приватный bucket создаёт bootstrap
Bucket приложения SHALL создавать одноразовый сервис bootstrap стенда. Bootstrap SHALL:
- создать bucket, если его нет;
- запретить анонимный доступ к bucket;
- завести пользователя API с политикой доступа (требование
«Ограниченные учётные данные API») и ключами из
.env; - завести пользователя уборщика с его политикой (требование
«Ограниченные учётные данные уборщика») и ключами из
.env; - завести пользователя worker с его политикой (требование
«Ограниченные учётные данные worker») и ключами из
.env.
На рабочем стенде реплики API, уборщик и worker MUST NOT стартовать, пока
bootstrap не завершился успешно. Стенды проверок с S3 (make test_isolated, make failure_checks) запускают bootstrap до своих
контейнеров API и worker, а стенд отказов — и до своего уборщика.
Повторный запуск SHALL завершаться успешно и не менять уже правильное
состояние: bucket и его объекты сохраняются, пользователи не
пересоздаются. Если в .env изменился секрет API, уборщика или worker,
повторный запуск SHALL привести к нему учётные данные этого
пользователя, а прежний секрет SHALL перестать действовать.
Вывод bootstrap MUST NOT содержать секретов. Ошибка любого шага SHALL давать ненулевой код выхода и сообщение, которое называет шаг.
Scenario: Первый запуск
- WHEN стенд поднимается на пустом volume S3
- THEN bootstrap создаёт bucket, пользователей API, уборщика и worker и завершается с кодом 0, и только после этого стартуют реплики API, уборщик и worker
Scenario: Повторный запуск
- WHEN на работающем стенде bootstrap запускается ещё дважды подряд
- THEN оба запуска завершаются с кодом 0 и сообщают, что bucket и все три пользователя уже есть, а записанные ранее объекты читаются
Scenario: Новый секрет API
- WHEN в
.envизменён секрет API, уборщика или worker, и bootstrap запущен снова - THEN запросы S3 с новым секретом этого пользователя проходят, а с прежним получают отказ
Scenario: Ошибка bootstrap
- WHEN bootstrap не может выполнить шаг, например имя bucket недопустимо
- THEN он завершается с ненулевым кодом и сообщением о шаге, реплики API не стартуют, а в выводе нет секретов
Requirement: Проверка приватности вне API
Приватность bucket и права ключей API, уборщика и worker SHALL проверяться без участия приложения двумя способами.
-
Каждый запуск bootstrap:
- ключ API записывает и читает проверочный объект и получает отказ на список и на создание bucket;
- ключ worker записывает и читает проверочный объект и получает отказ на удаление, на список и на создание bucket;
- ключ уборщика читает и удаляет проверочный объект. Он получает отказ на запись и на список всего bucket, а список с префиксом вложений своей базы у него проходит;
- аноним получает отказ на чтение существующего объекта и на список.
При нарушении bootstrap завершается с ненулевым кодом, и реплики API не стартуют.
-
Отдельная команда
make s3_checkна запущенном стенде. Она повторяет проверки bootstrap и добавляет:- анонимные запросы с хоста и из сети стенда;
- запросы ключей API, уборщика и worker к чужому bucket;
- административные запросы ключей API, уборщика и worker;
- запись ключом уборщика;
- его список всего bucket и с чужим префиксом — отказ, с префиксом вложений своей базы — 200.
Команда SHALL печатать по каждой проверке ожидаемый и полученный код ответа без секретов. При любом нарушении код выхода SHALL быть ненулевым. Свои проверочные объекты и bucket команда SHALL удалять.
Scenario: Проверка командой
- WHEN на запущенном стенде выполняется
make s3_check - THEN каждая проверка напечатана с полученным кодом ответа, в том числе проверки списка ключом уборщика по своему и чужому префиксу и отказ ключу worker на удаление и список, код выхода 0, а проверочных объектов и bucket после команды нет
Scenario: Bucket стал публичным
- WHEN на bucket открыт анонимный доступ на чтение, например административной командой мимо bootstrap
- THEN
make s3_checkзавершается с ненулевым кодом и называет нарушенную проверку, а следующий запуск bootstrap снова закрывает доступ
Requirement: Клиент хранилища в приложении
Процессы приложения SHALL обращаться к S3 с учётными данными своей роли
из секции [s3]: реплики API — ключами пользователя API, уборщик —
ключами пользователя уборщика, worker — ключами пользователя worker. Клиент
SHALL уметь:
- записать объект;
- прочитать его потоком;
- получить метаданные;
- удалить объект;
- перечислить объекты с заданным префиксом страницами, с размером и временем изменения каждого объекта.
Удаление отсутствующего объекта — не ошибка. Каждый вызов, в том числе каждая страница списка, SHALL быть ограничен сроком из настроек. После отказа или истечения срока вызов MUST NOT повторяться автоматически.
Срок из настроек SHALL быть единственным сроком вызова, кроме срока установки соединения, и он заканчивается вместе с вызовом: у потокового чтения он действует на каждый блок. Соединение, которое простаивает в пуле клиента, MUST NOT ломаться от срока прошлого вызова. Поэтому вызов после простоя S3 дольше срока вызова SHALL проходить, если S3 доступен, в том числе после потокового чтения большого объекта. Ошибкой недоступности такой вызов SHALL заканчиваться только по причинам из списка ниже.
Ошибкой недоступности, которую API отдаёт как 503 unavailable в
формате контракта, SHALL заканчиваться вызов, если S3:
- недоступен;
- не ответил за срок;
- отклонил учётные данные;
- отказал ключу в доступе или не нашёл bucket.
Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL отличаться от недоступности. Отсутствующий bucket MUST NOT выдаваться за отсутствующий объект у записи, чтения, удаления и списка: список без bucket — ошибка, а не пустая страница. После возврата 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 приложение одновременно прочитало потоком несколько объектов по несколько MiB, затем дольше срока вызова, но меньше срока жизни простаивающего соединения не обращалось к S3, а S3 всё это время доступен
- THEN следующие записи объектов проходят, ни одна не завершается ошибкой недоступности
- AND S3 получает тело каждой записи целиком
Scenario: Объекта нет
- WHEN приложение читает ключ, которого в bucket нет
- THEN клиент сообщает, что объекта нет, а не недоступность S3
Scenario: Bucket нет
- WHEN bucket приложения удалён мимо bootstrap, и приложение записывает, читает или удаляет объект либо запрашивает список объектов
- THEN каждый вызов завершается ошибкой недоступности, а не
сообщением «объекта нет» и не пустым списком, и в журнале есть запись
уровня
error
Scenario: Учётные данные отклонены
- WHEN секрет API у приложения не совпадает с секретом на сервере S3
- THEN вызов завершается ошибкой недоступности, а в журнале есть
запись уровня
errorбез секрета
ADDED Requirements
Requirement: Ограниченные учётные данные worker
У worker (capability attachment-processing) SHALL быть свои учётные данные
S3, отдельные от учётных данных API, уборщика и административных. Пользователю
worker SHALL быть разрешены только чтение и запись объектов своего bucket: он
читает staging и пишет в конечный префикс.
Пользователю worker MUST NOT быть разрешены:
- удаление объектов;
- список объектов;
- операции с bucket: создание, удаление, политика, ACL;
- публичный ACL объекта;
- управление учётными записями;
- любой доступ к другим bucket.
Ключи worker MUST NOT передаваться репликам API и уборщику. Worker MUST NOT получать ключи API и уборщика, административные ключи S3 и ключ подписи.
Scenario: Работа worker с объектами
- WHEN ключом worker записан объект и прочитан, в том числе объект, записанный ключом API
- THEN все операции проходят, а прочитанные байты совпадают с записанными
Scenario: Запрещённые операции worker
- WHEN ключом worker запрашиваются:
- удаление объекта;
- список объектов, в том числе с префиксом вложений базы;
- создание и удаление bucket, политика и ACL bucket;
- публичный ACL объекта;
- объект другого bucket и его список
- THEN каждый запрос получает 403, объект на месте, а bucket и его доступ не меняются