Files
mtusi2026lab4/openspec/changes/fix-upload-put-flake/specs/object-storage/spec.md
T
2026-10-22 22:52:59 +03:00

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 без секрета