Files
mtusi2026lab2/AGENTS.md
T
ArtyomandClaude Opus 5.5 472ce5b9ea Report the second review fixes and the new records
The header names the code and harness commits of the second review
cycle and states that every level 3 and 4 record and the clean clone
run are on e049c26. Row 4.1 now carries the detection ranges and the
SIGTERM window of the current records, the 503 answer to a request
cancelled at shutdown replaces the 500 everywhere, and the launch block
loses the manual LB wait now done by make up and gains retry-check and
storage-evidence, so the clean clone run follows it verbatim. Rows 3.4
rest on the stand reproduction of a lost answer instead of failover runs
that never failed, a new row proves the contract, public tests and task
untouched against upstream and names the CI job, and the level 4
experiments state their repeats, data volume and resource snapshots.

Track 1: errors are attributed to the replicas that returned them, with
a failure column in the pool control table; the pool control states its
fixed variant order and growing base, pool 4 is a lower bound and no
longer compared with 4x1; the write command times are call-weighted over
all statement rows; the 3 600 rps comparison names the uneven foreign
load and rests on lock waits and CPU per request; the limits name the
database sizes behind the series A peaks and what host-others.csv
covers. AGENTS.md lists retry-check and the LB wait of make up.

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

12 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                   # полная валидация 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'   # выборка тестов с именами

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, контроль, графики (≈3,5 ч)
make track1-control             # трек 1: пул 4/8/16 и maxconn 16/32/64 на 8x1; 8x0.5 против 4x1 на одних CPU
make plots                      # трек 1: графики и сводка потолков из evidence/track1/*/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 создаёт новых синтетических пользователей.

Архитектура 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/ (индекс — evidence/README.md, первая строка каждого файла — дата и коммит прогона).
  • Без комментариев в коде; отступы — пробелы ([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/.
  • Ветка 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/пула, графики и одно подтверждённое улучшение.