Files
mtusi2026lab4/openspec/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

25 KiB
Raw Blame History

object-storage Specification

Purpose

S3-хранилище байтов стенда с лабы 4. Здесь описано:

  • сервер, его закрепление и служебные интерфейсы вне сети;
  • идемпотентный bootstrap приватного bucket;
  • запрет анонимного доступа и ограниченные учётные данные API;
  • проверка приватности вне API и сохранность данных при рестарте;
  • клиент приложения: сроки вызовов, ошибки и ключи объектов по имени базы.

Requirements

Requirement: S3-хранилище в стенде

Рабочий стенд compose (make run_docker) SHALL включать один S3-совместимый сервер. Его образ SHALL быть закреплён тегом с версией и digest индекса. Данные сервера SHALL храниться в именованном volume. Сервису SHALL быть заданы:

  • healthcheck, который проверяет готовность обслуживать запросы S3, в том числе запись объекта: healthy MUST NOT наступать раньше, чем хранилище томов готово принять запись;
  • лимиты CPU и памяти;
  • перезапуск после сбоя;
  • срок остановки, за который сервер завершается сам, без принудительного завершения.

Сервер SHALL выдерживать одновременную запись 20 объектов по 10 MiB без превышения лимита памяти. Сервер MUST NOT отправлять сведения о стенде внешним сервисам, в том числе анонимную статистику.

Scenario: Сервис S3 запущен

  • WHEN в свежем clone выполнен make run_docker
  • THEN контейнер S3 в состоянии healthy, его образ указан тегом с версией и digest, а данные лежат в именованном volume проекта

Scenario: Первая запись после healthy

  • WHEN контейнер S3 перезапущен с сохранённым volume и стал healthy, и сразу после этого ключом API записывается объект
  • THEN первая запись проходит заметно быстрее срока вызова клиента ([s3] timeout_seconds), а не ждёт регистрации хранилища томов

Scenario: Остановка сервера

  • WHEN выполняется docker compose stop s3
  • THEN контейнер S3 завершается с кодом 0 раньше срока остановки, а не принудительно

Scenario: Одновременная запись

  • WHEN 20 клиентов одновременно записывают ключом API по объекту 10 MiB, затем читают их
  • THEN все записи подтверждены и прочитаны с тем же размером, а контейнер S3 не перезапускался и не был завершён из-за памяти

Scenario: Без внешней статистики

  • WHEN стенд работает
  • THEN у процесса S3 нет соединений с адресами вне сети стенда, а отправка статистики выключена в описании сервиса

Requirement: Служебные интерфейсы вне сети

Из контейнера S3 в сеть compose SHALL быть открыты только порт API S3 и служебный gRPC-порт шлюза S3, без которого шлюз не работает. Консоль администратора, UI и внутренние серверы хранилища (координатор, метаданные, тома) MUST NOT быть доступны ни из сети compose, ни с хоста. Порт API S3 SHALL публиковаться только на 127.0.0.1 хоста, другие порты сервера MUST NOT публиковаться.

Изменение учётных записей и политик через служебный gRPC-порт SHALL требовать токен, подписанный секретным ключом стенда. Без токена вызов MUST NOT менять учётные записи сервера.

Scenario: Порты из сети стенда

  • WHEN из другого контейнера сети compose проверяются порты контейнера S3
  • THEN открыты только порт API S3 и gRPC-порт шлюза, а порты консоли, UI, координатора, метаданных и томов закрыты

Scenario: Порты на хосте

  • WHEN для запущенного контейнера S3 выполняется docker port
  • THEN опубликован только порт API S3 и только на 127.0.0.1

Scenario: Учётная запись через gRPC-порт без токена

  • WHEN клиент из сети стенда без токена передаёт шлюзу S3 через gRPC-порт новую учётную запись с правами администратора
  • THEN вызов отклонён как неаутентифицированный, а запросы S3 с ключами этой записи получают отказ

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: Запрет анонимного доступа

Bucket SHALL быть приватным с первого старта сервера. Анонимный запрос SHALL получать 403 на:

  • чтение объекта и его метаданных;
  • список объектов bucket и список bucket-ов;
  • запись объекта и создание bucket.

Для несуществующего ключа ответ SHALL быть тем же 403: он MUST NOT показывать, есть ли объект. Сервер MUST NOT работать без учётных записей ни в какой момент, в том числе до первого запуска bootstrap.

Scenario: Анонимное чтение

  • WHEN аноним с хоста или из сети стенда запрашивает существующий объект bucket и его метаданные
  • THEN оба ответа 403, байтов объекта в ответе нет

Scenario: Анонимный список и запись

  • WHEN аноним запрашивает список объектов bucket, список bucket-ов или записывает объект
  • THEN каждый ответ 403, и объект не создан

Scenario: Несуществующий ключ

  • WHEN аноним запрашивает ключ, которого в bucket нет
  • THEN ответ 403, как для существующего ключа

Scenario: До bootstrap

  • WHEN сервер только что запущен на пустом volume, а bootstrap ещё не выполнялся
  • THEN анонимное создание bucket и запись объекта получают 403

Requirement: Ограниченные учётные данные API

У API SHALL быть свои учётные данные S3, отдельные от административных. Пользователю API SHALL быть разрешены только чтение, запись и удаление объектов своего bucket. Ему MUST NOT быть разрешены:

  • список объектов;
  • операции с bucket: создание, удаление, политика, ACL;
  • публичный ACL объекта;
  • управление учётными записями;
  • любой доступ к другим bucket.

Административные учётные данные S3 MUST NOT передаваться репликам API.

Scenario: Работа с объектами

  • WHEN ключом API в своём bucket записывается объект, читаются он и его метаданные, затем объект удаляется
  • THEN все операции проходят, а прочитанные байты совпадают с записанными по SHA-256

Scenario: Запрещённые операции

  • WHEN ключом API запрашиваются список объектов, создание и удаление bucket, политика и ACL bucket и публичный ACL объекта
  • THEN каждый запрос получает 403, а bucket и его доступ не меняются

Scenario: Чужой bucket

  • WHEN на сервере есть другой bucket, и ключом API в нём читается объект, записывается объект и запрашивается список
  • THEN каждый запрос получает 403

Scenario: Ключи реплик API

  • WHEN проверяющий смотрит окружение реплик API в docker compose config
  • THEN там есть ключи пользователя API и нет административных ключей S3 и ключа подписи

Requirement: Ограниченные учётные данные уборщика

У уборщика (capability storage-consistency) SHALL быть свои учётные данные S3, отдельные от учётных данных API и административных. Пользователю уборщика SHALL быть разрешены только:

  • чтение и удаление объектов своего bucket;
  • список объектов своего bucket с префиксом вложений своей базы, <имя базы>/attachments/, — для сверки bucket и БД.

Префикс задаёт bootstrap по имени базы стенда.

Пользователю уборщика MUST NOT быть разрешены:

  • запись объектов;
  • список объектов без этого префикса или с другим префиксом, в том числе с префиксом другой базы;
  • операции с bucket: создание, удаление, политика, ACL;
  • публичный ACL объекта;
  • управление учётными записями;
  • любой доступ к другим bucket.

Ключи уборщика MUST NOT передаваться репликам API. Уборщик MUST NOT получать ключи API, административные ключи S3 и ключ подписи.

Scenario: Работа уборщика с объектами

  • WHEN ключом API записан объект, а ключом уборщика он прочитан, удалён и удалён ещё раз, и запрошен список объектов с префиксом вложений базы
  • THEN чтение отдаёт те же байты, оба удаления успешны, объекта после них нет, а список отвечает 200

Scenario: Запрещённые операции уборщика

  • WHEN ключом уборщика запрашиваются:
    • запись объекта;
    • список объектов всего bucket и с префиксом, не принадлежащим вложениям его базы;
    • создание и удаление bucket, политика и ACL bucket;
    • публичный ACL объекта;
    • объект другого bucket и его список
  • THEN каждый запрос получает 403, а bucket и его доступ не меняются

Requirement: Проверка приватности вне API

Приватность bucket и права ключей API и уборщика SHALL проверяться без участия приложения двумя способами.

  1. Каждый запуск bootstrap:

    • ключ API записывает и читает проверочный объект и получает отказ на список и на создание bucket;
    • ключ уборщика читает и удаляет этот объект. Он получает отказ на запись и на список всего bucket, а список с префиксом вложений своей базы у него проходит;
    • аноним получает отказ на чтение существующего объекта и на список.

    При нарушении bootstrap завершается с ненулевым кодом, и реплики API не стартуют.

  2. Отдельная команда make s3_check на запущенном стенде. Она повторяет проверки bootstrap и добавляет:

    • анонимные запросы с хоста и из сети стенда;
    • запросы ключей API и уборщика к чужому bucket;
    • административные запросы ключей API и уборщика;
    • запись ключом уборщика;
    • его список всего bucket и с чужим префиксом — отказ, с префиксом вложений своей базы — 200.

Команда SHALL печатать по каждой проверке ожидаемый и полученный код ответа без секретов. При любом нарушении код выхода SHALL быть ненулевым. Свои проверочные объекты и bucket команда SHALL удалять.

Scenario: Проверка командой

  • WHEN на запущенном стенде выполняется make s3_check
  • THEN каждая проверка напечатана с полученным кодом ответа, в том числе проверки списка ключом уборщика по своему и чужому префиксу, код выхода 0, а проверочных объектов и bucket после команды нет

Scenario: Bucket стал публичным

  • WHEN на bucket открыт анонимный доступ на чтение, например административной командой мимо bootstrap
  • THEN make s3_check завершается с ненулевым кодом и называет нарушенную проверку, а следующий запуск bootstrap снова закрывает доступ

Requirement: Данные хранилища переживают рестарт

Bucket, учётные записи и объекты SHALL переживать перезапуск сервера S3 и всего стенда с сохранённым volume. Объекты с подтверждённой записью SHALL сохраняться и после принудительного завершения процесса S3.

Scenario: Рестарт стенда

  • WHEN объект записан ключом API, затем выполнен scripts/restart.sh
  • THEN контейнер S3 перезапущен (новое время старта), объект читается тем же ключом с тем же SHA-256, bucket и пользователь API на месте

Scenario: Принудительное завершение

  • WHEN сразу после подтверждённых записей контейнер S3 завершён сигналом KILL и запущен снова
  • THEN все подтверждённые объекты читаются с тем же SHA-256

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