Sync the rolling-update delta specs into db-migrations, graceful-shutdown, load-balancing and load-benchmark, move the change to the archive, mark it in PLAN.md and update the transitional state and code map in AGENTS.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
493 lines
57 KiB
Markdown
493 lines
57 KiB
Markdown
# MTUSI Messenger
|
||
|
||
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
|
||
переносится через все семь лабораторных курса и на каждой обрастает
|
||
инфраструктурой. Текущая работа — **лаба 3** (`lab.json`): балансировщик,
|
||
≥2 взаимозаменяемые API-реплики, общие сессии, обязательный
|
||
`Idempotency-Key` на отправке сообщения и `X-Instance-Id` в ответах
|
||
(`README.md`, `COURSE.md`, переход 2 → 3). Код перенесён из лабы 2
|
||
(репозиторий `mtusi2026lab2-safronov`, ветка `solution/bvt2301-safronov`,
|
||
commit `c6ad34d`): PostgreSQL как источник истины, вход по Basic →
|
||
Bearer-сессия, Valkey — кэш карточек чатов, трек 2 лабы 2 (план запроса
|
||
и восстановление) в `bench/`. Change `instance-id-idempotency` добавил
|
||
`X-Instance-Id` и `Idempotency-Key`, `replicas-lb` — HAProxy перед
|
||
двумя репликами API, лимиты, `scripts/stop-one.sh`,
|
||
`graceful-failover` — обоснованная и замеренная цепочка таймаутов,
|
||
стенд `bench/` на HAProxy + N реплик и профиль `failover`,
|
||
`rolling-update` — поочерёдная замена реплик с дренажём через runtime
|
||
API HAProxy (`make rolling_update`), expand-миграция и профиль
|
||
`rollout`; дальше — changes из `PLAN.md`. Переход на lab2 завершён changes OpenSpec, они в
|
||
`openspec/changes/archive/`. Стек:
|
||
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
|
||
(JSON в stdout), redis-py (клиент Valkey).
|
||
|
||
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
|
||
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
|
||
тесты и `REPORT.md` пишем мы.
|
||
|
||
## Обязательные правила
|
||
|
||
- Контракт и skeleton не менять: `contracts/`, `tests/`, `scripts/`
|
||
(кроме своих `scripts/restart.sh` и `scripts/stop-one.sh` по образцам
|
||
`restart.example.sh` и `stop-one.example.sh`),
|
||
`lab.json`, `README.md`, `COURSE.md`, `CONTRIBUTING.md`,
|
||
`MAINTAINERS.md`, `.github/`, `compose.example.yaml`,
|
||
`infra/README.md`, цели `check` / `validate` / `test` / `load` /
|
||
`test-persistence` / `test-failover` в `Makefile`. Если публичный тест упал, чиним
|
||
приложение, а не тест. Если в контракте противоречие — сказать
|
||
пользователю (это вопрос преподавателю), не выбирать трактовку самому.
|
||
Ответ преподавателя записать в «Согласования с преподавателем».
|
||
- Git не трогать без явной просьбы: никаких commit, push, checkout,
|
||
reset, stash. Смотреть можно (`git status`, `git diff`, `git log`).
|
||
Замер или evidence для отчёта снимается с закоммиченного кода, но
|
||
коммит — только после подтверждения пользователя: показать изменения,
|
||
предложить сообщение, ждать ок (`.claude/rules/bench.md`, «Измеренное
|
||
состояние — commit»).
|
||
- Перед завершением задачи с кодом — `make lint`. Правки API проверять на
|
||
запущенном сервере (`make run_dev` или контейнер, затем `make test` и
|
||
`make student_test`), а не «на глаз».
|
||
- Тесты пишем, но только black-box по HTTP в `student-tests/`
|
||
(`.claude/rules/student-tests.md`). В bp_proxies тесты были запрещены,
|
||
здесь они часть рубрики уровня 4.
|
||
- Упавший тест — сначала разбор, потом правка. Воспроизвести падение,
|
||
прочитать вывод и назвать причину: дефект приложения, ошибка в самом
|
||
тесте или стенд (чужой сервис на порту, старый образ, не тот
|
||
`BASE_URL`). Только после этого что-то менять, а в итоге задачи
|
||
сказать, в чём была причина.
|
||
- Если тест упал, чинится код, а не тест. Упавший тест из
|
||
`student-tests/` правится только в крайнем случае:
|
||
- поведение меняется намеренно: так записано в дельте спека
|
||
OpenSpec change или в контракте новой лабы. Тест правится вместе со
|
||
спеком;
|
||
- тест ошибочен сам: противоречит спеку или контракту либо зависит от
|
||
случайного (порядок тестов, время, чужие данные на стенде). В итоге
|
||
задачи назвать, чему именно он противоречит.
|
||
|
||
«Тест красный» — не причина его править. Нельзя ослаблять проверку,
|
||
подгонять ожидание под фактический ответ, ставить `skip` / `xfail`
|
||
или удалять тест, чтобы прогон позеленел. Дефект приложения вне
|
||
текущей задачи записывается в `KNOWN_ISSUES.md` (правило ниже), а
|
||
тест остаётся как есть. Если причина неясна или правка теста спорная —
|
||
остановиться и спросить.
|
||
- Лаба 2: источник истины — PostgreSQL, SQLite его не заменяет.
|
||
Пользователи, чаты, участники, сообщения и ещё действующие сессии
|
||
переживают рестарт API и хранилищ без удаления volumes. Basic — только
|
||
на `POST /auth/sessions`, остальное — Bearer; `X-User-Id` доступа не
|
||
даёт; пароли — только через password KDF (`auth.md`). Valkey — на
|
||
«4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey —
|
||
обход кэша, а не ошибка (`infra.md`). Всё это сохраняется в лабе 3.
|
||
- Лаба 3: ≥2 взаимозаменяемые реплики `api` за HAProxy — единственной
|
||
публичной точкой входа; порты реплик наружу не публикуются, sticky
|
||
session нет. В памяти процесса нет ничего, от чего зависит
|
||
корректность: сессии, данные и ключи идемпотентности — в Postgres,
|
||
Valkey — общий кэш неизменяемых карточек. В каждом ответе API —
|
||
`X-Instance-Id`. `POST` сообщения требует `Idempotency-Key`; ключ и
|
||
сообщение пишутся в одной транзакции (`api-contract.md`,
|
||
`service-layer.md`). Миграции — однократно, отдельным сервисом, не
|
||
репликами, и только расширяют схему: старые реплики работают на новой
|
||
(`migrations.md`). Новый код доходит до реплик без простоя через `make
|
||
rolling_update`. Стенд и отказы — `balancer.md`. В каждом процессе
|
||
uvicorn по-прежнему один worker: масштабирование — числом реплик.
|
||
- `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни
|
||
в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные
|
||
выводы команд.
|
||
- Найденный попутно дефект не чинить без просьбы: записать в
|
||
`KNOWN_ISSUES.md` (завести при первой находке) с путём и предложением
|
||
правки.
|
||
- OpenSpec: если команде `/opsx:*` подходит больше одного изменения
|
||
(change) — несколько активных в `openspec/changes/`, имя совпало
|
||
частично, из контекста подходят несколько, — не выполнять её для всех
|
||
подряд и не выбирать самому. Спросить, для какого изменения запустить:
|
||
варианты — каждое по имени, последним — «все». То же при нескольких
|
||
подходящих спеках (capability).
|
||
|
||
## Переходное состояние
|
||
|
||
Лаба 3 закрыта не целиком. Этот файл и `.claude/rules/` описывают
|
||
целевое состояние лабы 3, поэтому стенд с ними пока расходится. План
|
||
работ, решения и трек «5» — `PLAN.md`. Стенд — проект compose
|
||
`mtusi-lab3` со своей базой: HAProxy перед двумя репликами `api`
|
||
(change `replicas-lb`) с согласованной цепочкой таймаутов (change
|
||
`graceful-failover`); `make test`, `make test-persistence` и `make
|
||
test-failover` проходят через LB, новый код доходит до реплик без
|
||
простоя через `make rolling_update` (change `rolling-update`). Все три
|
||
change — в архиве. После замен реплики называются `api-N` с растущим
|
||
номером (compose нумерует новые контейнеры сервиса по возрастанию):
|
||
штатные цели с ними работают, `make down` + `make run_docker` снова
|
||
дают `api-1`, `api-2`.
|
||
|
||
- Стенд `bench/` уже на HAProxy + N реплик, но нагрузка трека 1
|
||
(открытая модель, серии A/B, метрики LB и PostgreSQL по репликам) —
|
||
change `scaling-bench`.
|
||
- `REPORT.md` заполнен для уровней «3» и «4»; трек «5» — впереди.
|
||
|
||
Закрытый пункт убрать отсюда, закрытый переход — удалить раздел.
|
||
|
||
## Согласования с преподавателем
|
||
|
||
Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`
|
||
и перенести в следующую лабу вместе с этим файлом, если она ещё
|
||
действует.
|
||
|
||
| Дата | Договорённость | Где учтено |
|
||
|---|---|---|
|
||
| 2026-09-26 | Лабы можно делать на FastAPI, несмотря на расхождения с контрактом (лишний 422, другой порядок кодов ошибок). Публичный smoke при этом должен проходить | `.claude/rules/api-contract.md`, раздел «FastAPI» |
|
||
| 2026-09-29 | Конфиг через pydantic-settings: окружение → `.env` → `config.toml` → дефолты. `config.toml` не в git и не в образе, монтируется read-only при запуске. Это подходит под «конфигурация приходит из окружения» (README лабы 1, п. 3) и п. 6 `Dockerfile.example`. Требование «только env» — упрощение курса, `config.toml` можно использовать | `.claude/rules/settings.md`, `.claude/rules/docker.md` |
|
||
|
||
## Задание и контракт: важные файлы
|
||
|
||
| Файл | Что в нём |
|
||
|---|---|
|
||
| `README.md` | задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR |
|
||
| `PLAN.md` | наш план лабы 3 на «5»: рубрика → change, ключевые решения, трек 1, порядок changes, риски; удаляется, когда все changes закрыты |
|
||
| `COURSE.md` | карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений |
|
||
| `contracts/openapi.json` | нормативный OpenAPI 3.1: пути, схемы, коды ответов |
|
||
| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`; разделы lab4+ — на будущее |
|
||
| `contracts/examples.json`, `infrastructure.json` | примеры тел (проверяет `make validate`); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer; Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются |
|
||
| `lab.json` | номер лабы (3); по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность) |
|
||
| `tests/smoke.py`, `tests/client.py` | публичный сквозной сценарий `make test`; что он проверяет и чего нет — `tests/README.md` |
|
||
| `tests/resilience.py` | `make test-persistence`: данные и прежний токен после restart hook; `make test-failover`: ≥2 реплики, запись во время остановки одной, повтор с тем же ключом, без дублей |
|
||
| `tests/load.py` | closed-loop нагрузка POST сообщений (`make load`); для трека 5 одного его мало |
|
||
| `scripts/check_contract.py`, `scripts/validate_openapi.py` | `make check` / `make validate` |
|
||
| `scripts/restart.example.sh` | образец restart hook; свой — `scripts/restart.sh`: перезапуск API и всех хранилищ без удаления volumes |
|
||
| `scripts/stop-one.example.sh` | образец failover hook; свой — `scripts/stop-one.sh`: остановить одну API-реплику по `TARGET_INSTANCE_ID` и оставить её остановленной |
|
||
| `compose.example.yaml` | список ролей с пустым `services`, не стенд; свой стенд — свой compose-файл |
|
||
| `infra/README.md` | куда класть конфигурации сервисов и что сопоставить в `REPORT.md` |
|
||
| `REPORT.md` | отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
|
||
| `evidence/` | сохранённые выводы проверок и измерений (что можно класть — `evidence/README.md`) |
|
||
| `CONTRIBUTING.md` | fork/PR, имя ветки, что переносить в следующую лабу |
|
||
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает |
|
||
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
|
||
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2 и новые lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS`) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`) |
|
||
| `examples/requests.http` | ручные запросы для HTTP-клиента IDE |
|
||
|
||
## Где лежат инструкции
|
||
|
||
Четыре уровня, не дублировать их друг в друге:
|
||
|
||
- **`AGENTS.md`** (этот файл): инварианты, команды, карта кода.
|
||
`CLAUDE.md` импортирует его.
|
||
- **`.claude/rules/*.md`**: правила по слоям. Подгружаются автоматически,
|
||
когда открыт файл из `paths:` во фронтматтере. Проект пишется с нуля,
|
||
а при создании файла через Write правило само не подгрузится. Поэтому
|
||
перед созданием первого файла слоя его правило нужно прочитать руками.
|
||
|
||
| Файл | Действует на |
|
||
|---|---|
|
||
| `api-contract.md` | `src/api/**`, `src/core/**`, `src/schemas/**`, `student-tests/**`: что требует контракт и где FastAPI по умолчанию его нарушает |
|
||
| `api-layer.md` | `src/api/**`, `src/main.py`: роутеры, зависимости, middlewares, обработчики ошибок |
|
||
| `service-layer.md` | `src/core/services/**` |
|
||
| `repo-layer.md` | `src/core/repos/**` |
|
||
| `dto.md` | `src/schemas/**` |
|
||
| `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиенты |
|
||
| `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии |
|
||
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
|
||
| `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть |
|
||
| `run-modes.md` | точки входа, `Makefile`, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM |
|
||
| `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`: мультистейдж, non-root, пины, healthcheck, стенд compose, volumes, restart hook |
|
||
| `balancer.md` | `docker-compose.yml`, `infra/haproxy/**`, `scripts/stop-one.sh`, `scripts/rolling-update.sh`: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3) |
|
||
| `student-tests.md` | `student-tests/**`: обязательные проверки уровня 4, black-box по HTTP, особый стенд |
|
||
| `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний |
|
||
| `migrations.md` | `migrations/**`, `alembic.ini`, `src/infra/db/models/**`: схема до запросов, ограничения, индексы, повторный запуск миграций |
|
||
|
||
- **`openspec/`** (схема `spec-driven`, язык артефактов — русский, см.
|
||
`openspec/config.yaml`): что система делает и зачем.
|
||
`specs/<capability>/spec.md` — текущее поведение, `changes/<change>/` —
|
||
предложения (`proposal.md`, `design.md`, `tasks.md`, дельты спеков),
|
||
`changes/archive/` — внедрённые. Крупную работу ведут командами
|
||
`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`
|
||
(ещё `explore`, `update`, `sync`). Команды в `.claude/commands/opsx/`
|
||
ставит `openspec update`, руками их не править. Спеки не пересказывают
|
||
контракт и правила: в `tasks.md` ссылаться на `contracts/` и
|
||
`.claude/rules/`, а не копировать их.
|
||
- **Граф кода** (`graphify-out/`, CLI graphify; локальный, не в git и
|
||
не в образе, состав — `.graphifyignore`): для вопросов о структуре и
|
||
связях — где используется, кто вызывает, что затронет правка.
|
||
Команды: `graphify query "<вопрос>"`, `graphify path "A" "B"`,
|
||
`graphify explain "X"`, `graphify affected "X"`. Граф — подсказка, а
|
||
не источник правды: до обновления он отстаёт от кода.
|
||
- Перед правкой — Read файла, как без графа: иначе правило слоя из
|
||
`.claude/rules/` не подгрузится. Граф этого не заменяет.
|
||
- Граф строится без LLM: код — по AST, markdown — по структуре
|
||
(разделы становятся узлами). Раздел правила или спеки связан
|
||
(`references`, INFERRED) с символами кода, упомянутыми в его тексте
|
||
в обратных кавычках. Полной карты «правило → код» в графе нет — она
|
||
в таблице выше и в `paths:` правил.
|
||
- `query` ищет узлы по подстроке метки. В запрос — имена символов
|
||
кода (`"ChatService ChatNotFound chat"`), а не пересказ вопроса:
|
||
тогда в ответе и код, и разделы правил и спек.
|
||
- В граф не попадают `.json` / `.yaml` / `.yml` (`contracts/openapi.json`,
|
||
`docker-compose.yml`), `Dockerfile`, `Makefile` и шаблоны конфигов:
|
||
их CLI не разбирает. По ним — `grep`.
|
||
- Только CLI `graphify update .`. Не запускать скилл `/graphify` и
|
||
`graphify extract`: семантический разбор документов через LLM
|
||
стоит сотни тысяч токенов, а следующий `graphify update .` всё равно
|
||
заменяет его структурным. Не запускать `graphify install`,
|
||
`graphify claude install`, `graphify hook install` и `graphify
|
||
watch`: первые два пишут секцию в `CLAUDE.md` и PreToolUse-хук на
|
||
Read, остальные пересобирают граф без спроса.
|
||
|
||
## Окружение и команды
|
||
|
||
- Python 3.12 (`.python-version`), зависимости через uv (`uv sync`,
|
||
`uv run ...`), lock в `uv.lock`. ruff глобальный
|
||
(`/opt/homebrew/bin/ruff`, им же пользуется PyCharm), в проекте он в
|
||
extra `dev`.
|
||
- Конфиг: `.env` (то, что читают compose и контейнеры зависимостей) +
|
||
`config.toml` (то, что читает только приложение). Читает их
|
||
`src/config/settings.py` (pydantic-settings), все поля — в секциях.
|
||
Приоритет: окружение > `.env` > `config.toml` > дефолты. Параметры
|
||
приложения в `.env` пишутся в формате настроек (`APP__PORT`), без
|
||
секции — только то, что приложение не читает (`APP_OUT_PORT`).
|
||
`config.toml` в образ не копируется, а монтируется на старте. Режим
|
||
`APP__RUN_MODE` (`console` / `docker`) в `.env` не хранится.
|
||
Подробно — `settings.md`, `docker.md` и `run-modes.md`.
|
||
- Точка входа: `python -m src` (`src/__main__.py` → `src/main.py`), порт
|
||
8080.
|
||
- `make test` ходит на `http://localhost:8080`. Если там отвечает чужой
|
||
сервис, smoke упадёт с 404 на `/health/live` вместо ошибки соединения.
|
||
Проверить, кто занял порт: `lsof -nP -iTCP:8080 -sTCP:LISTEN`,
|
||
`docker ps`.
|
||
- graphify (граф кода, «Где лежат инструкции») — вне проекта, в
|
||
`uv tool`, версия закреплена:
|
||
- CLI: `uv tool install --python 3.12 'graphifyy==0.9.72'`. Без
|
||
`--python 3.12` uv берёт free-threaded 3.14t, и установка падает на
|
||
сборке `tree-sitter-rust`.
|
||
- Сборка и обновление — одна команда `graphify update .` в корне:
|
||
без LLM и токенов, около секунды, работает и в чистом clone. Граф
|
||
обновляется вручную, после заметной работы (новый слой, закрыт
|
||
change). Попутно `update` кладёт копию прошлого графа в
|
||
`graphify-out/<дата>/` и называет кластеры по центральному узлу.
|
||
|
||
| Команда | Что делает |
|
||
|---|---|
|
||
| `make check` | офлайн-проверка структуры skeleton, JSON и синтаксиса Python-проверок |
|
||
| `make validate PYTHON=.venv/bin/python` | полная валидация OpenAPI и примеров (валидатор стоит в dev-группе uv) |
|
||
| `make test [BASE_URL=...]` | публичный smoke против запущенного сервера |
|
||
| `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` |
|
||
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`tests/README.md`) |
|
||
| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | отказ одной API-реплики через LB: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (`tests/README.md`). `STOP_MODE=kill` — без graceful, `STOP_ONE_LOG=<файл>` — какой `TARGET_INSTANCE_ID` и контейнер остановлен. Между прогонами — `make replicas` |
|
||
| `make run_dev` | `make upgrade` (Postgres из compose и миграции) и `make start_cache`, затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload |
|
||
| `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` |
|
||
| `make env_setup` | `.env.example` → `.env` со случайными `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) |
|
||
| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey → migrate → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf` и `infra/haproxy/haproxy.cfg` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` |
|
||
| `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся |
|
||
| `make logs` | журнал всех реплик API, каждая строка — JSON (`--no-log-prefix`), реплика — поле `instance_id` |
|
||
| `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) |
|
||
| `make instances` | вход одним синтетическим пользователем, 12 × `GET /users/me` через LB: `X-Instance-Id` каждого ответа и итог по репликам |
|
||
| `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) |
|
||
| `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) |
|
||
| `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` |
|
||
| `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст |
|
||
| `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) |
|
||
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
|
||
| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` |
|
||
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе (`student-tests.md`) |
|
||
| `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
|
||
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
|
||
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
|
||
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
|
||
| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` |
|
||
| `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 |
|
||
| `make bench_failover [FAILOVER_LABEL=...]` | уровень 4, отказ реплик под нагрузкой (~6 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах `stop`, `kill`, `pause` с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом — `evidence/failover/<метка>/`. Перед запуском — проверка хоста (`bench.md`) |
|
||
| `make bench_failover_quick` | то же короче, режимы `stop` и `kill` (~2 мин), метка `quick-failover-<время>`, в git не идёт |
|
||
| `make bench_rollout [ROLLOUT_LABEL=...]` | уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` как у `bench_failover`, реплики на образе прежнего commit (`Profile.rollout_from`, `git archive`), та же нагрузка; посреди неё `scripts/rolling-update.sh` меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей — `evidence/rollout/<метка>/`. Перед запуском — проверка хоста (`bench.md`) |
|
||
| `make bench_rollout_quick` | то же с короткими окнами (~2 мин), метка `quick-rollout-<время>`, в git не идёт |
|
||
| `make bench_ab BEFORE=... AFTER=... REAPPLY=<commit>` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита |
|
||
| `make bench_compare BEFORE=... AFTER=... [AA=...]` | дельта двух меток `make bench` по ячейкам матрицы; метки с разной методикой не сравнивает (в том числе метку без LB с меткой стенда на LB); с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` |
|
||
|
||
Разовая подмена внешнего порта — аргументом make:
|
||
`make run_docker APP_OUT_PORT=8090`, затем
|
||
`make test BASE_URL=http://localhost:8090`. Префикс окружения
|
||
(`APP_OUT_PORT=8090 make ...`) не работает: Makefile подключает `.env`
|
||
(`run-modes.md`, Troubleshooting).
|
||
|
||
## Карта кода
|
||
|
||
Файлы домена называются одинаково во всех слоях (`user`, `chat`,
|
||
`message`, `session`, `idempotency` и т.д.).
|
||
|
||
```
|
||
src/
|
||
__main__.py # python -m src → main.main()
|
||
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
|
||
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] idle_in_transaction_timeout_ms, [idempotency] ttl_seconds
|
||
api/
|
||
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
|
||
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py)
|
||
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта
|
||
dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
|
||
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id
|
||
middlewares/ # X-Request-Id, X-Instance-Id и access-лог
|
||
core/
|
||
repos/<domain>.py # атомарный доступ к хранилищу, модульные функции
|
||
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
|
||
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
|
||
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией
|
||
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
|
||
infra/
|
||
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
|
||
password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
|
||
db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping
|
||
db/session.py # глобалы engine и session_factory процесса API
|
||
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
|
||
db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit
|
||
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
|
||
cache/instance.py # глобал cache процесса API
|
||
schemas/
|
||
dataclasses/<domain>.py # DTO между repo → service → api
|
||
enums/<domain>.py # StrEnum доменов, RunModeEnum
|
||
utils/
|
||
constants.py # лимиты контракта, размер страницы, префиксы путей
|
||
utc.py # utcnow() (aware UTC), формат RFC 3339 с Z
|
||
cursor.py # непрозрачный keyset-курсор: кодирование и разбор
|
||
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test
|
||
conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
|
||
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message — с Idempotency-Key
|
||
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_replicas
|
||
test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py)
|
||
test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику
|
||
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
|
||
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
|
||
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
|
||
test_failures.py # проверки отказов (маркер fault): только make failure_checks
|
||
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
|
||
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, уборка (stdlib)
|
||
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений (stdlib)
|
||
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB)
|
||
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout
|
||
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover, профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker), метрики (сумма по репликам), runs.csv / phases.csv / summary.md / meta.json
|
||
failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md
|
||
rollout.py # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md
|
||
bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
|
||
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей)
|
||
k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
|
||
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB
|
||
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд
|
||
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
|
||
infra/ # конфигурации сервисов стенда; README.md — skeleton
|
||
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
|
||
haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене)
|
||
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey
|
||
scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
|
||
scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
|
||
Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
|
||
docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам
|
||
.dockerignore
|
||
config_example.toml, .env.example
|
||
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone
|
||
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
|
||
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
|
||
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
|
||
evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md
|
||
evidence/idempotency/ # повтор, 409, гонка, таблица ключей, X-Instance-Id
|
||
evidence/replicas/ # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах
|
||
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ
|
||
evidence/failover/<метка>/ # результаты make bench_failover: паспорт, phases.csv, посекундная timeline.csv, summary.md, итоги k6 и журнал LB по фазам
|
||
evidence/rollout/ # совместимость старого образа с новой схемой, make rolling_update и жизненный цикл стенда после замены, отказы скрипта (Ctrl+C, слоты, lock_timeout миграции)
|
||
evidence/rollout/<метка>/ # результаты make bench_rollout: паспорт с контейнерами, образами и ревизией до и после, rollout.csv, replicas.csv, timeline.csv, summary.md, строки скрипта, журнал LB
|
||
evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
|
||
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
|
||
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
|
||
```
|
||
|
||
`evidence/` перенесён без содержимого лабы 2 (оно осталось в
|
||
репозитории `mtusi2026lab2-safronov`). Каталоги выше появляются заново
|
||
по мере changes.
|
||
|
||
## Архитектура в двух словах
|
||
|
||
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис
|
||
(логика, проверки доступа, id и время, логи) → repo (одна атомарная
|
||
операция над хранилищем, отдаёт DTO) → PostgreSQL через
|
||
`AsyncSession` (`src/infra/db/`). Подробности — в правилах слоёв.
|
||
- Отличия от bp_proxies. Из `core/` вынесены инфраструктура
|
||
(`src/infra/`: логгер, хранилища, клиенты), утилиты (`src/utils/`),
|
||
настройки (`src/config/` вместо `src/data/`) и HTTP-модели
|
||
(`src/api/schemas/` вместо `schemas/pydantic/`). В `core/` остались
|
||
доменные слои: repos, services, exceptions. Бота, loader и контроллера
|
||
нет; фоновая работа появится в лабе 5 отдельным worker.
|
||
- Ошибки: сервис бросает доменное исключение. `src/api/errors.py` одной
|
||
таблицей переводит его в статус и `code` и отдаёт тело
|
||
`{"error": {...}}` с `request_id`. `HTTPException` в сервисах и ручках
|
||
не используется.
|
||
- Конкурентность: все ручки и зависимости — `async def`, один event
|
||
loop, один worker в процессе, процессов — `API_REPLICAS` за HAProxy.
|
||
Атомарность и защиту от гонок, в том числе между репликами, дают
|
||
транзакции и ограничения Postgres (уникальность, `ON CONFLICT`),
|
||
транзакцией управляет сервис. Повтор `POST` сообщения через другую
|
||
реплику находит тот же ключ идемпотентности в Postgres. На лабе 1 ту же роль играло отсутствие `await`
|
||
внутри repo-функции над `MemoryStore`. KDF пароля — в потоке, чтобы
|
||
не останавливать event loop.
|
||
- Request id генерирует middleware. Тот же id уходит в заголовок
|
||
`X-Request-Id`, в `request_id` тела ошибки и в каждую строку лога.
|
||
|
||
## Соглашения по коду
|
||
|
||
- ruff: 79 символов, py312, набор правил в `pyproject.toml` (isort,
|
||
bugbear, comprehensions, unused-arguments, pyupgrade, simplify,
|
||
quotes). Кавычки как в файле (quote-style preserve), trailing comma
|
||
обязательна.
|
||
- Типизация везде: `X | None`, `list[...]`, `UUID` и `datetime` вместо
|
||
строк. Методы сервисов keyword-only (`*,`); repo и сервисы вызываются
|
||
только именованными аргументами.
|
||
- Комментарии и докстринги короткие, на русском. Сообщения логов и
|
||
тексты ошибок API (`error.message`) — на английском.
|
||
- Константы (лимиты контракта, размер страницы, пути) — в
|
||
`src/utils/constants.py`, не литералами в коде.
|
||
- Время только через `utcnow()` из `src/utils/utc.py`: aware UTC. В
|
||
bp_proxies был naive UTC, здесь контракт требует `...Z`, а с лабы 2 —
|
||
`timestamptz`.
|
||
- Коммиты (когда попросят): английский, conventional style
|
||
(`feat: ...`, `fix: ...`, `refactor: ...`).
|
||
|
||
## Дорожная карта лаб
|
||
|
||
Каждая лаба — отдельный skeleton-репозиторий; переходы API — `COURSE.md`
|
||
нового skeleton. Что меняется в коде:
|
||
|
||
| Лаба | Что появляется | Где в коде |
|
||
|---|---|---|
|
||
| 1 | in-memory API, Dockerfile | `infra/memory.py`, `X-User-Id` в `get_current_user` |
|
||
| 2 | PostgreSQL, Basic → Bearer-сессия; Valkey на «4» | `infra/db/`, `migrations/`, repo на `AsyncSession`; `password` при регистрации (KDF); `get_current_user` на Bearer; `SESSION_TTL_SECONDS`; кэш карточки чата — `infra/cache/`, `repos/chat_cache.py` |
|
||
| 3 | балансировщик, ≥2 реплики, идемпотентность | middleware `X-Instance-Id`; `Idempotency-Key` на POST сообщения; никакого состояния в памяти процесса |
|
||
| 4 | приватный S3, вложения | клиент в `infra/`, домен `attachment` |
|
||
| 5 | брокер, worker, превью | отдельная точка входа worker; загрузка отвечает 202 |
|
||
| 6 | OTel Collector, Grafana | телеметрия в `infra/` |
|
||
| 7 | Argon2id, TLS/mTLS, OpenBao | HTTPS, секреты из OpenBao |
|
||
|
||
## Переход в следующую лабу
|
||
|
||
По `CONTRIBUTING.md`: fork нового skeleton, ветка
|
||
`solution/<group>-<surname>`, затем перенести своё.
|
||
|
||
- Переносить: `src/`, `student-tests/`, `migrations/`, `alembic.ini`,
|
||
`Dockerfile`, `docker-compose.yml`, `infra/valkey/`,
|
||
`infra/haproxy/` (без `infra/README.md` skeleton), свои
|
||
`scripts/restart.sh`, `scripts/stop-one.sh` и
|
||
`scripts/rolling-update.sh` (без примеров и проверок skeleton в
|
||
`scripts/`), `pyproject.toml`, `uv.lock`, `.python-version`,
|
||
`config_example.toml`, `AGENTS.md`, `CLAUDE.md`, `.claude/`,
|
||
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`.
|
||
- Сливать, а не копировать поверх: `Makefile`, `.env.example`,
|
||
`.gitignore`, `.dockerignore`. Берём версию нового skeleton (в ней
|
||
новые цели и проверки) и дописываем свои секции.
|
||
- Не копировать: `.git`, `.env`, `config.toml`, volumes, `README.md`,
|
||
`COURSE.md`, `tests/`, `contracts/`, `lab.json`, `REPORT.md`,
|
||
`evidence/` (доказательства остаются в репозитории своей лабы),
|
||
`graphify-out/` (граф собирается заново).
|
||
- Сначала прочитать переходы API в `COURSE.md` и `contracts/README.md`
|
||
нового skeleton, потом править код. Обновить этот файл: номер лабы,
|
||
таблицу важных файлов, новые правила.
|
||
|
||
## Ветки и PR
|
||
|
||
Git — только по просьбе. Когда просят, порядок такой:
|
||
|
||
- Работа идёт в ветке `solution/bvt2301-safronov` от ветки skeleton.
|
||
- PR — в исходный репозиторий преподавателя. Заголовок
|
||
`ЛР N — Группа — Фамилия — на 3/4/5`, тело — по
|
||
`.github/pull_request_template.md`. Перед PR выполнить `make check`,
|
||
`make test` на собранном из чистого clone образе и заполнить
|
||
`REPORT.md`, включая использование ИИ.
|