- s3 healthcheck and fault hook probe wait for the volume server to register with master (first write after restart no longer waits ~5 s) - s3-bootstrap mounts /data as tmpfs: no anonymous volume per container - S3 client: NoSuchBucket and AccessDenied are 503 with their own error logs, not a missing object or rejected credentials; delete ignores only a missing key - test_isolated verifies prefix removal (weed shell exits 0 on errors) - s3_check derives ports from listening sockets in the s3 container - readiness without S3 is also checked with s3 paused Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
Spec Delta
Purpose
S3-хранилище байтов стенда с лабы 4. Здесь описано:
- сервер, его закрепление и служебные интерфейсы вне сети;
- идемпотентный bootstrap приватного bucket;
- запрет анонимного доступа и ограниченные учётные данные API;
- проверка приватности вне API и сохранность данных при рестарте;
- клиент приложения: сроки вызовов, ошибки и ключи объектов по имени базы.
ADDED Requirements
Requirement: S3-хранилище в стенде
Рабочий стенд compose (make run_docker) SHALL включать один
S3-совместимый сервер. Его образ SHALL быть закреплён тегом с версией и
digest индекса. Данные сервера SHALL
храниться в именованном volume. Сервису SHALL быть заданы:
- healthcheck, который проверяет готовность обслуживать запросы S3, в
том числе запись объекта:
healthyMUST 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.
На рабочем стенде реплики 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: Проверка приватности вне API
Приватность bucket и права ключа API SHALL проверяться без участия приложения двумя способами.
- Каждый запуск bootstrap. Ключ API записывает, читает и удаляет проверочный объект и получает отказ на список и на создание bucket. Аноним получает отказ на чтение существующего объекта и на список. При нарушении bootstrap завершается с ненулевым кодом, и реплики API не стартуют.
- Отдельная команда
make s3_checkна запущенном стенде. Она повторяет проверки bootstrap и добавляет:- анонимные запросы с хоста и из сети стенда;
- запросы ключа API к чужому bucket;
- административные запросы ключа API.
Команда 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 с учётными данными API из секции
[s3]. Клиент SHALL уметь записать объект, прочитать его потоком,
получить метаданные и удалить. Удаление отсутствующего объекта — не
ошибка. Каждый вызов SHALL быть ограничен сроком из настроек. После
отказа или истечения срока вызов MUST NOT повторяться автоматически.
Ошибкой недоступности, которую API отдаёт как 503 unavailable в
формате контракта, SHALL заканчиваться вызов, если S3:
- недоступен;
- не ответил за срок;
- отклонил учётные данные;
- отказал ключу API в доступе или не нашёл bucket.
Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL отличаться от недоступности: отсутствующий bucket MUST NOT выдаваться за отсутствующий объект у записи, чтения и удаления. После возврата 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без секрета