Files
mtusi2026lab4/openspec/changes/s3-storage/proposal.md
T
2026-10-20 19:26:52 +03:00

9.4 KiB
Raw Blame History

Proposal

Why

Лаба 4 требует S3-совместимое хранилище в общем стенде: закреплённая версия, persistent volume, приватный bucket с описанным созданием (рубрика «3»). Рубрика «4» добавляет идемпотентный bootstrap, отдельные ограниченные учётные данные API, консоль не в общей сети и проверку приватности bucket вне API (README.md). Вложения (change attachments) строятся поверх этого: сначала хранилище, клиент и стенды, потом домен.

Сервер выбран заранее — SeaweedFS (PLAN.md, решение 1). Проба закреплённой версии показала три места, где он по умолчанию не приватен. Без учётных записей S3 открыт анониму целиком. Служебные серверы (master, filer, volume) слушают все интерфейсы. gRPC-порт S3 без ключа подписи принимает от любого контейнера сети учётную запись администратора. Change закрывает все три, а не только создаёт bucket.

What Changes

  • В стенде появляется S3: сервис s3 на SeaweedFS 4.48 с тегом и digest индекса, именованным volume, healthcheck, лимитами CPU и памяти и плавной остановкой.
    • Служебные серверы слушают только loopback контейнера, наружу и в сеть compose выходит один порт S3.
    • Порт S3 публикуется только на 127.0.0.1 хоста для запуска в консоли. Консоль и UI не публикуются и в сети недоступны.
    • Учётная запись администратора задана с первого старта: анонимного окна нет.
    • Административные RPC закрыты ключом подписи, телеметрия и необязательные эндпоинты выключены.
  • Одноразовый сервис s3-bootstrap на том же образе создаёт приватный bucket, запрещает анонимный доступ и заводит пользователя API с политикой «только объекты своего bucket: чтение, запись, удаление».
    • Реплики API ждут его успешного завершения, как миграций.
    • Повторный запуск ничего не ломает и сводит состояние к .env.
    • В конце каждого запуска bootstrap проверяет права и приватность вне API и завершается ошибкой, если bucket не приватен.
  • make s3_check — та же проверка приватности вне API отдельной командой, для защиты и evidence. Она добавляет проверки с хоста и из сети стенда, против чужого bucket и административных операций.
  • Учётные данные разделены по ролям. Административная пара ключей S3 есть только у сервера s3, ключ подписи — у s3 и s3-bootstrap, ключи API — у s3-bootstrap и реплик API. LB, миграции, PostgreSQL и Valkey секретов S3 не получают. Значения лежат в .env, make env_setup генерирует их для нового .env, в приложение они приходят мостами S3__*.
  • Секция [s3] настроек: адрес, порт, bucket, ключи API, регион, сроки и пул. Значения из config.toml — в config_example.toml.
  • Клиент хранилища в src/infra/s3/ на aiobotocore для следующих changes. Операции — запись, чтение потоком, метаданные, удаление; у каждого вызова свой срок, повторов нет. Отказ, таймаут и отказ в учётных данных — 503 unavailable. Ключи объектов начинаются с имени базы, как ключи кэша. Клиент создаётся при старте и закрывается при остановке.
  • /health/ready от S3 не зависит (PLAN.md, решение 3): S3 не нужен обязательному синхронному пути.
  • Все стенды знают о S3:
    • scripts/restart.sh перезапускает и S3;
    • make run_dev поднимает S3 и bootstrap;
    • make test_isolated работает с S3 рабочего стенда, его объекты лежат под префиксом временной базы и удаляются при уборке;
    • у make failure_checks свой S3 и новая проверка «S3 недоступен — готовность 200»;
    • bench/ получает секреты S3 на прогон, а профили лаб 2–3 S3 не запускают, и их методика не меняется;
    • make wipe_data удаляет и volume S3.
  • BREAKING (для оператора): в существующий .env нужно перенести строки S3 из .env.example, без них compose не стартует. make env_setup существующий .env не меняет. Для нового .env секреты генерируются сами.

Не входит: таблица и ручки вложений, домен attachment, attachment_ids — это change attachments. Намерение pending, компенсация и уборщик с его S3-пользователем — upload-consistency. Лимиты памяти и сроки загрузки — upload-memory. Reconciler — трек 2.

Capabilities

New Capabilities

  • object-storage: S3-хранилище стенда — сервер и его закрепление, служебные интерфейсы вне сети, идемпотентный bootstrap приватного bucket, запрет анонимного доступа, ограниченные права API, проверка приватности вне API, сохранность при рестарте и клиент приложения (сроки, ошибки, ключи по имени базы).

Modified Capabilities

  • container-run: S3 и bootstrap в стенде compose, порты S3 из .env, публикация только порта S3 на 127.0.0.1, рестарт hook-ом, лимиты и секреты по сервисам, запуск в консоли с S3, удаление данных вместе с volume S3.
  • service-configuration: подключение к S3 (секция [s3], секреты из .env, генерация в make env_setup), консоль и docker без правки файлов.
  • health: готовность не зависит от S3.
  • service-logging: учётные данные S3 и подписи запросов к нему в журнал не попадают.
  • student-tests: прогон на временной базе с префиксом объектов и его уборкой; стенд отказов со своим S3 и проверкой готовности без него.

Impact

  • Код: src/infra/s3/ (клиент, глобал), src/config/settings.py ([s3]), src/main.py (старт, закрытие, запись о старте), src/infra/logger.py (журналы botocore — WARNING), доменное исключение отсутствующего объекта.
  • Зависимости: aiobotocore (тянет botocore и aiohttp), uv.lock.
  • Инфраструктура:
    • docker-compose.yml — сервисы s3, s3-bootstrap, якорь x-s3-env и volume;
    • infra/s3/bootstrap.sh;
    • .env.example и config_example.toml;
    • Makefile — env_setup, start_s3, stop_s3, s3_check, run_dev, test_isolated, wipe_data;
    • scripts/restart.sh.
  • Стенды:
    • student-tests/run_isolated.py, run_failures.py, failures.compose.yml, fault_hook.py, test_failures.py;
    • bench/run.py — секреты, фильтр секретов в паспорте;
    • bench/bench.compose.yml, bench/bench.env.
  • Документы:
    • правила infra.md, docker.md, settings.md, run-modes.md, logging.md, student-tests.md, bench.md, balancer.md;
    • AGENTS.md, скилл run-mtusi-messenger;
    • REPORT.md — роль S3, таблица роль → сервис → версия → healthcheck → volume → порт → credentials, bootstrap и его повтор, критичные зависимости, соответствие имён skeleton S3_*;
    • evidence/s3/.