Files
mtusi2026lab4/openspec/changes/fix-upload-put-flake/specs/object-storage/spec.md
T
ricoromaandClaude Opus 5.5 723b6c3140 fix: address fix-upload-put-flake verify findings
aiohttp 3.14.5 buffers 256 KiB and pauses reading above 512 KiB; name
the aiohttp versions actually checked instead of a range; fix line
references in the idle-connection evidence; the object-storage spec now
exempts the connect timeout from the single call timeout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 02:14:38 +03:00

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