forked from mtusi2026/mtusi2026lab3
Tie the grade 5 claim to the final SQLAlchemy revalidation and measured scaling results. Clarify clean-clone setup, failure timings, historical evidence, and operational constraints; record report-stage checks and evidence audits.
90 lines
15 KiB
Markdown
90 lines
15 KiB
Markdown
## Что это за репозиторий
|
||
|
||
Skeleton лабораторной 3 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`. Skeleton даёт задание (`README.md`), нормативный контракт (`contracts/`) и публичные black-box проверки (`tests/`). Реализация API, Dockerfile, compose-стенд, конфигурация балансировщика, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 3 построено переносом решения лабы 2.
|
||
|
||
Лаба 3: несколько взаимозаменяемых реплик API за единой точкой входа — **HAProxy**. Реплики не держат состояния: PostgreSQL остаётся источником истины для пользователей, сессий, чатов и сообщений, Valkey — общий кэш сессий. Каждый ответ API несёт `X-Instance-Id` обслужившей реплики, отправка сообщения требует `Idempotency-Key`, а повтор с тем же ключом через любую реплику не создаёт дубль. Остановка одной реплики не прерывает чтение и запись дольше 10 с.
|
||
|
||
Автор решения — Костылев Артём, БПИ2303. Уровни «3» → «4» → трек «5» завершены последовательно;
|
||
активных OpenSpec changes на момент финализации отчёта нет. Актуальные доказательства:
|
||
|
||
- `evidence/track1-sqlalchemy/revalidation/` — уровни «3»/«4» после оптимизации, код `3fb741e`;
|
||
API идентичен `57744c5`, миграции и инфраструктура с повторного прогона не менялись.
|
||
- `evidence/track1-sqlalchemy/` — 135 измерений с тремя повторами и 12 графиков;
|
||
baseline `5c8f605`, after `57744c5`; API использует кэш компиляции статического Core CTE.
|
||
- `evidence/grade3-*.txt`, `grade4-*.txt` — этапы SQLAlchemy до оптимизации;
|
||
`evidence/track1/` и файлы, отмеченные в индексе как raw asyncpg, — исторический код.
|
||
- `evidence/report-checks.txt` и `report-audit.txt` — проверки финальных документов;
|
||
они не заменяют стендовые и нагрузочные прогоны.
|
||
|
||
## Команды
|
||
|
||
```sh
|
||
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, X-Instance-Id в контракте
|
||
make validate # полная валидация OpenAPI 3.1: openapi-spec-validator из .venv (make install); PYTHON= — свой интерпретатор
|
||
make install # uv sync --group dev
|
||
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
|
||
make student-test # собственные тесты (поднимают одноразовые PostgreSQL и Valkey в Docker)
|
||
make student-test PYTEST_ARGS='-v -k drain' # выборка тестов с именами
|
||
openspec validate --all --strict
|
||
|
||
make secrets # локальные secrets/* и .env из .env.example (не коммитятся)
|
||
make up # docker compose up -d --build --wait: postgres, valkey, migrate, api ×API_REPLICAS, lb; затем ждёт все реплики UP в LB
|
||
make test # публичный smoke через LB (BASE_URL по умолчанию — docker compose port lb 8080, без стенда http://localhost:8080)
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт lb, api, postgres, valkey с сохранением volumes
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики TARGET_INSTANCE_ID под запросами
|
||
make test-faults # тесты стенда лабы 2 через LB (make faults-evidence → evidence/faults.txt)
|
||
make restore # вернуть остановленные реплики и дождаться их в ротации LB
|
||
make lb-check # ≥2 X-Instance-Id на одном токене и 20 гонок одного Idempotency-Key
|
||
make retry-check # потерянный ответ (запись ждёт блокировку чата) на живой и на убитой реплике, повтор тем же ключом
|
||
make limits # уровень 4: лимиты, порты, секреты, volumes, сети против политики scripts/limits.py
|
||
make detection # уровень 4: время обнаружения SIGTERM/kill/pause/PostgreSQL против заявленного максимума
|
||
make failover-each # уровень 4: каждая реплика по очереди под k6 (RATE=100) → evidence/failover-each
|
||
make rolling-update [FROM_REV=<коммит>] # уровень 4: замена реплик по одной под k6, migrate один раз
|
||
make track1 # трек 1: снимок хоста, серии A (1x4/2x2/4x1) и B (1x1/2x1/8x1), до/после на 8x1, контроль, графики; volumes сохраняются
|
||
make track1-control # трек 1: пул 4/8/16 и maxconn 16/32/64 на 8x1; 8x0.5 против 4x1 на одних CPU
|
||
make plots # трек 1: графики и сводка потолков из evidence/track1-sqlalchemy/*/summary.csv
|
||
make down # остановка без удаления данных (с профилем bench); make reset-data — удаление volumes
|
||
```
|
||
|
||
`tests/*.py` и `scripts/*.py` — только stdlib, синтаксис Python 3.9 (`make check` разбирает их системным `python3`). Проверки сами не поднимают стенд. Хуки `scripts/stop-one.sh` и `scripts/restart.sh` запускаются тестом без shell, поэтому исполняемые и с shebang. Данные не удаляются автоматически: каждый прогон smoke создаёт новых синтетических пользователей.
|
||
|
||
Стенд запускать только в собственном `COMPOSE_PROJECT_NAME`, с `LB_HTTP_PORT=18083`,
|
||
`LB_STATS_PORT=23083` и `NO_PROXY=localhost,127.0.0.1,::1` (также `no_proxy`). Остальные
|
||
host-порты — 23000–23999. Проверять занятость до запуска; чужие стенды не останавливать.
|
||
Полный трек требует 16 vCPU Docker VM. `make detection` перезаписывает свой каталог evidence:
|
||
для дополнительного прогона сохранять старое сырьё и задавать новый путь скрипту.
|
||
|
||
## Архитектура skeleton
|
||
|
||
- `lab.json` — единственный источник номера лабы (3). От него зависят `scripts/check_contract.py` (`info.version == 1.3.0`, `X-Instance-Id` во всех ответах) и `tests/client.py` (с lab3 проверяет непустой `X-Instance-Id` на любом ответе и шлёт `Idempotency-Key` в каждом POST сообщения).
|
||
- `tests/resilience.py --mode failover`: `TARGET_INSTANCE_ID` — реплика, обслужившая первое сообщение; 40 `GET /users/me` одним токеном должны дать ≥2 `X-Instance-Id`; hook возвращается <10 с с кодом 0; первая запись после hook — не позже 10 с от его старта; ≥5 записей после; target отсутствует в последних 5 ответах; история без дублей и байт-в-байт равна подтверждённым ответам. Таймаут клиента 2 с, после ошибки повтор с тем же ключом и текстом.
|
||
- `tests/resilience.py --mode persistence`: hook ≤90 с, затем `/health/ready` и `/users/me` прежним токеном до 90 с, сверка истории.
|
||
- `contracts/infrastructure.json` — роли `api` (≥2, без локального состояния), `postgres` (persistent volume), `load_balancer` (единственная публичная точка, readiness backend), опциональный `redis_or_valkey`. `compose.example.yaml` — только worksheet ролей.
|
||
|
||
## Ключевые правила контракта (lab3)
|
||
|
||
- `X-Instance-Id` и `X-Request-Id` — на каждом ответе API, включая health, `204` logout, `404/405` неизвестного маршрута и `500`. `X-Instance-Id` один на реплику (контейнер), стабилен на жизнь процесса и одинаков у всех воркеров gunicorn. Ответы, сгенерированные самим LB, его могут не иметь.
|
||
- `POST /api/v1/chats/{chat_id}/messages` требует `Idempotency-Key` (`^[A-Za-z0-9._:-]{1,128}$`); нет или неверный — `400`. Область ключа — пользователь + метод + путь + ключ, результат хранится ≥24 ч (`IDEMPOTENCY_TTL_SECONDS`). Повтор того же JSON — тот же `201` и тот же `Message` (включая строку `created_at`), другой JSON — `409`. Повтор заново проверяет сессию (`401`) и доступ (`404`). Сохраняется только `201`; запись сообщения и ключа — одна транзакция PostgreSQL.
|
||
- LB и клиент не повторяют прозрачно `POST /users` и `POST /chats`. Балансировка без sticky-сессий.
|
||
- Сохраняются правила lab2: `Basic` только на `POST /api/v1/auth/sessions`, иначе `Bearer`; `WWW-Authenticate` по пути; `X-User-Id` игнорируется; logout `204`, повтор `401`; абсолютный TTL сессии. И lab1: формат ошибки `{"error":{code,message,request_id}}`, посторонний → `404`, keyset `(created_at, id)`, `limit` 1–100, cursor привязан к чату, время RFC 3339 с `Z`.
|
||
|
||
## Правила работы с репозиторием
|
||
|
||
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
|
||
- Код — `src/messenger/`, миграции — `alembic/versions/*.py`, конфигурация LB и нагрузки — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/` (индекс — `evidence/README.md`, первая строка каждого файла — дата и коммит прогона).
|
||
- PostgreSQL — SQLAlchemy 2.0.45 async (`async_sessionmaker`, `DeclarativeBase`), Alembic 1.16.5; версии закреплены в `pyproject.toml` и `uv.lock`, asyncpg только драйвер. ORM/Core остаются в инфраструктуре, домен — dataclass, pydantic — на HTTP-границе. Миграции — только `alembic upgrade head` в one-shot сервисе `migrate`. Старую схему принимает `alembic/legacy.py` после проверки журнала и каталога PostgreSQL; безусловный `stamp` запрещён. Старый журнал сохраняется, volumes не удаляются.
|
||
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
|
||
- Порты реплик API наружу не публикуются: только LB. Нет `container_name`, `hostname` и общего `INSTANCE_ID` у сервиса `api`.
|
||
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов, трек 1, ответы на вопросы защиты. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (`docker ps -a`). Цифры в отчёте берутся только из файлов `evidence/`.
|
||
- Старые результаты сохранять с SHA и пометкой версии кода; не смешивать raw asyncpg, baseline SQLAlchemy и SQLAlchemy с кэшем компиляции. Микробенчмарк компиляции не заменяет HTTP-замер, пик RPS не равен пределу SLO. Rolling с no-op миграцией не доказывает произвольный DDL под нагрузкой.
|
||
- Ветка `solution/bpi2303-kostylev`, коммиты на английском, перед каждым — `make lint`. Никогда не коммитить `.env`, `secrets/`, токены, volumes, дампы.
|
||
- ЛР1/ЛР2 заморожены; менять только текущую лабораторную, WIP и volumes сохранять. Текущую `.pipeline` и её state не менять. Публикация — отдельный этап, только private в MTUCI-Labs; Telegram отправляет runner.
|
||
|
||
## Уровни оценки
|
||
|
||
Решение заявлено на **«5»** с треком 1 «Цена масштабирования»; таблица доказательств — в `REPORT.md`.
|
||
|
||
- **3** — стенд в `compose.yaml`: HAProxy → ≥2 реплики API → общие PostgreSQL и Valkey; разные реплики на одном токене; остановка любой реплики с восстановлением ≤10 с; идемпотентная отправка, включая конкурентный повтор и смену реплики; `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; минимум lab2 сохранён.
|
||
- **4** — согласованные readiness, таймауты и `SIGTERM`, период проверок и время обнаружения; поочерёдная остановка каждой реплики под нагрузкой с RPS, ошибками и временем восстановления; лимиты CPU/RAM, API без опубликованных портов; rolling update под нагрузкой и однократные совместимые миграции.
|
||
- **5** — трек 1: 1/2/4 реплики при фиксированном бюджете CPU/RAM и серия с ростом ресурсов, saturation point БД/LB/пула, графики и одно подтверждённое улучшение.
|