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.
15 KiB
Что это за репозиторий
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 графиков; baseline5c8f605, after57744c5; API использует кэш компиляции статического Core CTE.evidence/grade3-*.txt,grade4-*.txt— этапы SQLAlchemy до оптимизации;evidence/track1/и файлы, отмеченные в индексе как raw asyncpg, — исторический код.evidence/report-checks.txtиreport-audit.txt— проверки финальных документов; они не заменяют стендовые и нагрузочные прогоны.
Команды
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— реплика, обслужившая первое сообщение; 40GET /users/meодним токеном должны дать ≥2X-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,204logout,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игнорируется; logout204, повтор401; абсолютный TTL сессии. И lab1: формат ошибки{"error":{code,message,request_id}}, посторонний →404, keyset(created_at, id),limit1–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/пула, графики и одно подтверждённое улучшение.