5.8 KiB
Spec Delta
MODIFIED Requirements
Requirement: Клиент хранилища в приложении
Процессы приложения SHALL обращаться к S3 с учётными данными своей роли
из секции [s3]: реплики API — ключами пользователя API, уборщик —
ключами пользователя уборщика. Клиент 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без секрета