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

132 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/`.