# Отчёт — лабораторная 3 - Автор, группа: Сарибекян, БПИ2303 - Целевая оценка: 4 - Commit/PR: см. ветку `solution/БПИ2303-Сарибекян` - Использованные источники, библиотеки и помощь ИИ: та же база, что в лабе 2 (FastAPI/asyncpg/redis-py/argon2-cffi) плюс Nginx как балансировщик. Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено локальным запуском `make check/test/test-persistence/test-failover/validate`. ## Запуск из чистого clone Версии: Python 3.12.7, PostgreSQL 16.4, Redis 7.4.1, Nginx 1.27.2. Docker Engine + Compose v2. ```sh git clone <ваш форк> cd mtusi2026lab3 mkdir -p secrets openssl rand -hex 20 > secrets/postgres_password.txt printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt printf 'redis://redis:6379/0' > secrets/cache_url.txt chmod 600 secrets/*.txt printf 'SESSION_TTL_SECONDS=3600\n' > .env docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build curl -s localhost:8080/health/ready make test chmod +x scripts/restart.sh scripts/stop-one.sh make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh # после отказа одной реплики: docker compose start api1 (или api2), повторить make test-failover для второй. ``` Остановка: `docker compose stop`. Намеренное удаление учебных данных: `docker compose down -v`. ## Архитектура и решения ``` Клиент → lb (Nginx, :8080) → api1 / api2 (FastAPI) → PostgreSQL (общий) + Redis (общие сессии) ``` - **Балансировщик**: Nginx, upstream с двумя явными backend (`api1:8080`, `api2:8080`), `max_fails=1 fail_timeout=3s` — пассивная проверка здоровья: один неудачный запрос выводит backend из ротации на 3 секунды, что укладывается в бюджет обнаружения отказа <10с. `worker_processes 1` — намеренное решение: с несколькими worker-процессами у каждого свой независимый round-robin счётчик, и балансировка на малом числе реплик визуально "залипала" на одном backend (воспроизведено и исправлено, см. ограничения). - **Почему две явные службы `api1`/`api2`, а не `--scale api=2`**: с явными именами легко детерминированно остановить ровно одну реплику по алиасу (`TARGET_INSTANCE_ID`), и `INSTANCE_ID` передаётся как переменная окружения напрямую, без догадок по hostname контейнера. - **Общие хранилища**: Postgres и Redis — те же роли, что в lab2, без изменений схемы (см. `migrations/0001_init.sql`), плюс новая таблица `idempotency_keys` (`migrations/0002_idempotency.sql`). - **Локальных сессий в API не осталось**: обе реплики читают/пишут один и тот же Redis по `CACHE_URL_FILE`; ни один стейт не держится в памяти процесса API (кроме пула соединений). - **Идемпотентность** (`app/idempotency.py`): таблица `idempotency_keys` с PK `(user_id, method, path, idem_key)`. На POST: `INSERT ... ON CONFLICT DO NOTHING` внутри той же транзакции, что и создание сообщения; если конфликт — читаем существующую запись: совпадает хеш запроса → при необходимости дождаться `status='done'` (конкурентная уже выполняющаяся транзакция блокирует INSERT до своего COMMIT/ROLLBACK на уровне PostgreSQL — поэтому конкурентные повторы с одним ключом естественно сериализуются самой БД, без ручных блокировок в приложении) и вернуть тот же результат; не совпадает — `409`. При ошибке внутри `perform()` строка идемпотентности откатывается вместе со всей транзакцией — повтор не блокируется навечно. - **Транзиентные ошибки не коммитятся как факт**: побочный эффект (вставка сообщения) и фиксация результата идемпотентности — одна транзакция `asyncpg`; при любой ошибке всё откатывается целиком. - **Миграции без гонки реплик**: `app/db.py` берёт `pg_advisory_lock` перед применением миграций — без этого обе реплики, стартующие одновременно, пытались создать одну и ту же таблицу и падали с `UniqueViolationError` (воспроизведено и исправлено, см. ограничения). - **Ресурсы**: `deploy.resources.limits` на каждый сервис (`compose.yaml`) — Compose v2 применяет их и без Swarm. - **Graceful shutdown**: `uvicorn --timeout-graceful-shutdown 5` — после SIGTERM процесс донашивает текущие запросы до 5 секунд, не принимая новые. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | ≥2 реплики, одна точка входа, общая БД/сессии | `docker compose ps`; 8 последовательных `GET /health/live` через LB | чередование `X-Instance-Id: api1/api2` | ручной прогон, см. ниже | | Публичный smoke | `make test` | `PASS: lab3 public API scenario...` | вывод команды | | Персистентность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session.` | вывод команды | | Failover (≥2 наблюдаемых реплики, запись не прерывается >10с) | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, для обеих реплик по очереди | `observed_instances_before: 2`; 1-й прогон: `successful_writes: 97, failed_attempts: 0, first_recovery_seconds: 0.899`; 2-й прогон (другая реплика): `successful_writes: 101, failed_attempts: 0, first_recovery_seconds: 0.885` | вывод команды, `evidence/failover_both_replicas.txt` | | Идемпотентность при конкурентном повторе через разные реплики | 5 параллельных `curl` POST с одним `Idempotency-Key` | все 5 ответов — один и тот же `id` сообщения; в БД `SELECT count(*)` = 1 | `evidence/idempotency_concurrent.txt` | | Разный body под тем же ключом → 409 | повтор с тем же ключом, другим `text` | `409 conflict` | `evidence/idempotency_concurrent.txt` | | Health/readiness, graceful shutdown | `uvicorn --timeout-graceful-shutdown 5`; Nginx `max_fails=1 fail_timeout=3s` | код/конфиг; поведение подтверждено failover-тестом (восстановление <1с) | `Dockerfile`, `infra/nginx/nginx.conf` | | Нет публикации портов API в обход LB | `compose.yaml`: `api1`/`api2` без секции `ports` | только `lb` публикует `8080:8080` | `compose.yaml` | | Ресурсные лимиты | `deploy.resources.limits` на каждый сервис | код ревью | `compose.yaml` | ## Эксперименты и отказы **Последовательная остановка каждой реплики (уровень 4).** `scripts/stop-one.sh` получает `TARGET_INSTANCE_ID` от теста и останавливает именно её контейнер (`docker compose stop api1|api2`). Прогнано дважды — по разу на каждую реплику, с восстановлением (`docker compose start`) между прогонами. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | Остановка `api1` (пока работает `api2`) | Запись продолжается <10с, нет дублей | `successful_writes=97, failed_attempts=0, first_recovery_seconds=0.899` | восстановление записи 0.9с, потерь нет | | Остановка `api2` (пока работает `api1`) | То же | `successful_writes=101, failed_attempts=0, first_recovery_seconds=0.885` | восстановление записи 0.89с, потерь нет | | `docker compose restart postgres redis api1 api2 lb` (последовательно) | Сообщения и активная сессия сохраняются | `PASS` в `make test-persistence`, тот же Bearer-токен работает | восстановление <90с (бюджет теста), без потери данных | | 5 параллельных POST, один `Idempotency-Key` | Ровно одно сообщение | 1 строка в `messages`, все 5 ответов идентичны | без дублей | **Ограничение:** нагрузочный тест (`tests/load.py`) и исследовательский трек уровня 5 не выполнялись — цель лабы — оценка 4. ## Ограничения и следующие шаги - При разработке найдены и исправлены два реальных бага concurrency, оба стоит знать на защите: 1. **Гонка миграций**: обе реплики при одновременном первом старте пытались создать одинаковые таблицы и падали с `UniqueViolationError`. Исправлено `pg_advisory_lock` в `app/db.py` перед прогоном миграций. 2. **"Залипание" балансировки на одной реплике**: при `worker_processes auto` у Nginx каждый worker-процесс ведёт свой независимый round-robin счётчик, и на малом числе запросов казалось, что трафик идёт только на `api1`. Исправлено `worker_processes 1` (демонстративно для лабы — на реальной нагрузке это стало бы ограничением пропускной способности самого LB, что подходящий компромисс не для production, а именно здесь задокументирован явно). 3. **Рестарт целого стека падал**: `docker compose restart` перезапускает контейнеры параллельно, и Nginx (резолвит upstream-хосты только при своём старте) иногда стартовал раньше, чем Docker DNS успевал зарегистрировать `api1`/`api2` после их параллельного перезапуска, и падал насмерть (`host not found in upstream`). Исправлено явной последовательностью в `scripts/restart.sh`: сначала БД/Redis, затем `api1`/`api2`, и только потом `lb`. - Трек исследования уровня 5 (цена масштабирования / отказ узла) не реализован. - Rolling update под нагрузкой не прогонялся отдельным сценарием (ограничение времени); качественно это покрывается failover-тестом, который и есть частный случай замены одной реплики. - Nginx open-source не делает активных health-check проб — только пассивные (по факту неудачного реального запроса); для прод-уровня здесь нужен Nginx Plus/HAProxy/Traefik с активными пробами.