Files
mtusi2026lab2/AGENTS.md
T
ArtyomandClaude Opus 5.5 e88673dfec Archive the scaling cost change
Track 1 of grade 5 is closed. At a fixed 4 CPU / 2 GiB the 1x4, 2x2
and 4x1 layouts peak at 5 375, 4 964 and 4 724 rps: within the
hypothesised 15 percent, yet smaller replicas cost a third more CPU
per request and reach a long tail earlier. Growing one-CPU replicas
gives 1 720, 2 936, 4 724 and only 4 260 rps at eight, a retrograde
curve with USL sigma 0.014 and kappa 0.038. The saturation point is
the chat row lock in PostgreSQL: at eight replicas 47.5 of 64
connections wait for it while the API, the balancer and the database
CPU still have room. Writing a message with one statement removed the
application round trips from under the lock: p95 at 3 600 rps fell
from 64.5 to 3.7 ms and the peak rose by 15 % with the same resources.

The new lab3-scaling-cost spec is synced to openspec/specs, with the
compare scenario stated as measured: below the knee fewer lock waits
and a lower p95, past it a higher peak. AGENTS.md lists make track1
and make plots. The neighbour CPU sampler is stopped and its file
closed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-29 01:42:38 +03:00

11 KiB
Raw Blame History

Что это за репозиторий

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 с.

Команды

make check                      # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, X-Instance-Id в контракте
make validate PYTHON=.venv/bin/python   # полная валидация OpenAPI 3.1 (venv с requirements-dev.txt)
make install                    # uv sync --group dev
make lint                       # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test               # собственные тесты (поднимают одноразовые PostgreSQL и Valkey в Docker)

make secrets                    # локальные secrets/* и .env из .env.example (не коммитятся)
make up                         # docker compose up -d --build --wait: postgres, valkey, migrate, api ×API_REPLICAS, lb
make test                       # публичный smoke через LB (BASE_URL, по умолчанию 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 restore                    # вернуть остановленные реплики и дождаться их в ротации LB
make lb-check                   # ≥2 X-Instance-Id на одном токене и 20 гонок одного Idempotency-Key
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, графики (≈2,5 ч)
make plots                      # трек 1: графики и сводка потолков из evidence/track1/*/summary.csv
make down                       # остановка без удаления данных; 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 создаёт новых синтетических пользователей.

Архитектура 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/, миграции — src/messenger/migrations/NNNN_*.sql, конфигурация LB и нагрузки — infra/, хуки и обвязка стенда — scripts/, собственные тесты — student-tests/, обезличенные доказательства — evidence/.
  • Без комментариев в коде; отступы — пробелы ([tool.ruff.format]); Python 3.14 без from __future__ import annotations и TYPE_CHECKING.
  • Порты реплик API наружу не публикуются: только LB. Нет container_name, hostname и общего INSTANCE_ID у сервиса api.
  • REPORT.md: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (docker ps -a).
  • Ветка solution/bpi2303-kostylev, коммиты на английском, перед каждым — make lint. Никогда не коммитить .env, secrets/, токены, volumes, дампы.

Уровни оценки

Решение заявлено на «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/пула, графики и одно подтверждённое улучшение.