# 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 повторяться автоматически. Ошибкой недоступности, которую 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** приложение читает ключ, которого в bucket нет - **THEN** клиент сообщает, что объекта нет, а не недоступность S3 #### Scenario: Bucket нет - **WHEN** bucket приложения удалён мимо bootstrap, и приложение записывает, читает или удаляет объект либо запрашивает список объектов - **THEN** каждый вызов завершается ошибкой недоступности, а не сообщением «объекта нет» и не пустым списком, и в журнале есть запись уровня `error` #### Scenario: Учётные данные отклонены - **WHEN** секрет API у приложения не совпадает с секретом на сервере S3 - **THEN** вызов завершается ошибкой недоступности, а в журнале есть запись уровня `error` без секрета