Files
mtusi2026lab4/openspec/specs/object-storage/spec.md
T

24 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 повторяться автоматически.

Ошибкой недоступности, которую 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 без секрета