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

420 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` без секрета