Files
mtusi2026lab2/AGENTS.md
T
ArtyomandClaude Opus 5.5 0ec2f9dae3 Carry over the agent context and openspec history from lab 2
Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 and lab 2 specs and the
archived lab 1 and lab 2 changes into the lab 3 skeleton, so lab 3
continues the same spec history instead of starting from scratch.

Rewrite AGENTS.md and the openspec context and rules for lab 3:
HAProxy in front of several stateless API replicas, X-Instance-Id on
every response, a mandatory Idempotency-Key for messages shared by all
replicas through PostgreSQL, explicit stop-one and restart hooks, Out
of scope moved to labs 4-7 plus Swarm and HA storage, and rules on
retry policy, timeout chains and replica-local state.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 11:23:53 +03:00

58 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Что это за репозиторий
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 с.
## Команды
```sh
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 на одном токене и гонка одного Idempotency-Key
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/пула, графики и одно подтверждённое улучшение.