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>
420 lines
25 KiB
Markdown
420 lines
25 KiB
Markdown
# 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` без секрета
|