Files
mtusi2026lab3/REPORT.md

18 KiB
Raw Permalink Blame History

Отчёт — лабораторная 3

  • Автор, группа: Кошелев, БВТ2304
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/PR: ветка solution/bvt2304-koshelev, PR в mtusi2026/mtusi2026lab3 (main)
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, asyncpg, redis-py (клиент Valkey), argon2-cffi; HAProxy 3.2 (документация: server-template, resolvers, http-check, retry-on, http-error), Docker Compose reference (deploy.replicas, resources), PostgreSQL INSERT … ON CONFLICT. Код перенесён из собственной lab2. При доработке, тестах и отчёте использовался ИИ-ассистент Claude (Anthropic); решения проверены и объяснимы автором.

Запуск из чистого clone

Требования: Docker Engine + Compose v2 (проверено: Docker Desktop 28.0.1, Compose 2.33.1), Python 3.9+ для тестов (проверено 3.14), make. Стенд: Apple M3, 8 CPU, Docker VM 8 CPU / 7.6 GiB.

Роль Service Образ Health/readiness Volume Сеть / порт Credentials
Балансировщик lb haproxy:3.2.4-alpine monitor-uri /lb-health (внутр. 127.0.0.1:8405) — edge; единственный опубликованный порт 127.0.0.1:${APP_PORT:-8080} нет
API × N api (deploy.replicas: ${API_REPLICAS:-2}) mtusi-messenger:lab3 (сборка из Dockerfile, база python:3.12.8-slim-bookworm) /health/ready (SELECT 1 в PostgreSQL) нет локального состояния edge + data, порт 8080 не публикуется secrets database_url, cache_url
Миграции migrate (one-shot) mtusi-messenger:lab3 exit 0 — data secret database_url
БД (источник истины) postgres postgres:17.6-alpine3.22 pg_isready pgdata data (internal) secret postgres_password
Кэш сессий valkey valkey/valkey:8.1.4-alpine3.22 valkey-cli ping нет (только кэш) data (internal) secret valkey_conf (requirepass)
./scripts/init-secrets.sh            # создаёт ./secrets/* (в .gitignore), значения не печатаются
cp .env.example .env                 # при занятом 8080 поменяйте APP_PORT в .env (у автора: 8088)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait     # postgres/valkey -> migrate -> api x2 -> lb
make test                                               # BASE_URL=http://localhost:8088 при другом порту
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover    ACTION_SCRIPT=scripts/stop-one.sh
./scripts/restore.sh                                    # вернуть остановленную реплику
make test-student                                       # конкурентная идемпотентность через обе реплики
make chaos                                              # поочерёдная остановка каждой реплики под нагрузкой
  • Короткие цели: make secrets, make up (= secrets + up -d --build --wait), make restore, make rolling-update, make down. Пошаговый сценарий защиты с командами — DEMO.md.
  • Масштабирование: API_REPLICAS=4 docker compose up -d --wait (LB подхватывает новые адреса через DNS, до 8 слотов).
  • Rolling update: ./scripts/rolling-update.sh.
  • Безопасная остановка: docker compose stop (или down — volumes сохраняются).
  • Намеренное удаление учебных данных: docker compose down -v (удаляет volume pgdata; только осознанно).

Соответствие .env.example: APP_HOST/APP_PORT — адрес uvicorn внутри контейнера (в контейнере всегда 8080), APP_PORT в .env — опубликованный порт LB; SESSION_TTL_SECONDS → API; DATABASE_URL_FILE, CACHE_URL_FILE → Docker secrets; SESSION_STORE=postgres (Valkey — только кэш); API_REPLICAS → deploy.replicas; IDEMPOTENCY_TTL_SECONDS → API (по умолчанию 86400).

Архитектура и решения

client ──► lb (HAProxy, :8080) ──round-robin──► api-1 ┐
                                 └──────────────► api-2 ┼──► postgres (users, chats, messages, sessions, idempotency_keys)
                     сеть edge                          └──► valkey   (кэш сессий + tombstone отзыва)   сеть data (internal)

Из lab2 перенесено: FastAPI-приложение, PostgreSQL как источник истины, сессии в PostgreSQL (hash токена, expiry), Valkey как общий кэш сессий с tombstone при logout, Argon2id, отдельный сервис миграций с advisory lock.

Изменено в lab3:

  1. Нет локального состояния в API. Сессии/сообщения/ключи идемпотентности — в PostgreSQL, кэш — общий Valkey. Единственное in-memory — краткий список «незаписанных tombstone» при сбое Valkey, он лишь ужесточает проверку (кэш обходится, решение принимает БД). Поэтому sticky sessions не нужны и не используются: один токен обслуживают обе реплики (evidence/topology.txt).
  2. X-Instance-Id. Случайный alias api-xxxxxxxx, генерируется при старте процесса (без hostname/IP), добавляется middleware к каждому ответу, включая ошибки и health. Alias пишется в /tmp/instance-id в контейнере — так scripts/stop-one.sh сопоставляет TARGET_INSTANCE_ID с контейнером через docker exec.
  3. Идемпотентность (migrations/0002_idempotency.sql, Store.create_message). Таблица idempotency_keys(user_id, chat_id, key) — PK = пользователь + путь чата + ключ (метод один — POST messages). В одной транзакции: удалить запись этого ключа старше IDEMPOTENCY_TTL_SECONDS → INSERT … ON CONFLICT DO NOTHING (захват ключа, тут же проверка членства) → INSERT сообщения (FK на сообщение DEFERRABLE INITIALLY DEFERRED). Конкурентный дубль блокируется на уникальном индексе до COMMIT/ROLLBACK первого; затем читает зафиксированный результат новым снимком (READ COMMITTED) и возвращает тот же 201 Message. Отпечаток тела — SHA-256 канонического JSON (сортировка ключей), другой body → 409. Сбой/таймаут до COMMIT не оставляет ни ключа, ни сообщения → повтор безопасен; после COMMIT повтор получает сохранённый результат. Повтор заново проходит аутентификацию и проверку членства (JOIN с chat_members).
  4. Миграции — только one-shot сервис migrate; api стартует по service_completed_successfully. Реплики схему не трогают, гонки нет. 0002 аддитивна: старый код lab2 работает на новой схеме.
  5. LB (HAProxy): адреса реплик из Docker DNS (server-template api 8 api:8080 resolvers docker, hold valid 2s) — масштабирование и пересоздание контейнеров без reload. Активная проверка GET /health/ready: inter 1s, fall 2, rise 2, timeout check 1s. timeout connect 1s, retries 3, option redispatch 1, retry-on conn-failure empty-response — неудавшееся соединение повторяется на другой реплике. Ошибки, созданные самим LB (502/503/504), имеют JSON-формат API и X-Request-Id (evidence/lb-no-backends.txt).
  6. Graceful shutdown: uvicorn — PID 1 (exec), по SIGTERM сразу закрывает listen-сокет (новые соединения → refused → LB повторяет на другой реплике), дорабатывает начатые запросы до 8 с (--timeout-graceful-shutdown 8), stop_grace_period: 10s > 8 с. Keep-alive uvicorn 30 с > idle-пул HAProxy, чтобы не было гонки переиспользования закрытого соединения.

Тайминги обнаружения отказа: health-check каждые 1 с, сервер выводится после 2 неудач → ≤ ~3 с (2 × (1 с интервал) + 1 с таймаут). Остановленный контейнер также пропадает из DNS (hold 2 с). До этого запросы к нему получают таймаут соединения 1 с и повторяются на другой реплике — поэтому наблюдаемые пики латентности ≈1 с, но без ошибок.

Транзакционные границы: сообщение + ключ идемпотентности — одна транзакция; создание чата + участники — одна транзакция; логин/logout — одна строка sessions (+ tombstone в Valkey; при сбое Valkey logout отвечает 503 и ретраит tombstone в фоне).

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test через LB PASS lab3 evidence/smoke.txt
Стенд в compose.yaml, ≥2 API, одна точка входа, общие БД и сессии docker compose up -d --build --wait; docker compose ps 2 × api, порт опубликован только у lb evidence/topology.txt
Разные запросы одной сессии — разные реплики без повторного входа 6 × GET /users/me одним токеном X-Instance-Id чередуется api-255e07d5/api-624de536 evidence/topology.txt
Остановка любой реплики, записи ≤10 с make test-failover ACTION_SCRIPT=scripts/stop-one.sh ×6 + restore.sh PASS все 6 раз; 0 ошибок, восстановление 1.6–3.4 с; остановлены и api-2, и api-1 evidence/failover.txt, evidence/stop-one.txt
Повтор POST с тем же ключом без дубля, в т.ч. конкурентно и через другую реплику student-tests/idempotency_test.py 5 раундов × 32 одновременных запроса (16/16 по репликам) → ровно 1 сообщение; другой body → 409; область ключа user+chat; 400 на плохой ключ; 401/404 при повторе evidence/idempotency.txt
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt изменился у api, lb, postgres, valkey; volume pgdata тот же; токен прежний evidence/persistence.txt
(4) health/readiness, timeouts, SIGTERM, LB исключает backend конфиг infra/haproxy/haproxy.cfg, Dockerfile период проверки 1 с, обнаружение ≤ ~3 с; после стопа последние ответы только от живой реплики evidence/failover-load/*.json (instances_last_5s)
(4) Поочерёдная остановка каждой реплики под нагрузкой: RPS, ошибки, восстановление chaos_load.py --action "scripts/stop-container.sh messenger-lab3-api-N" см. таблицу ниже evidence/failover-load/stop-api-1.json, stop-api-2.json
(4) CPU/RAM-лимиты, нет портов API, нет container_name, data-сеть internal docker inspect, compose.yaml api 0.5 CPU/256M, pg 1 CPU/512M, valkey 0.25/96M, lb 0.5/128M; postgres недоступен из lb evidence/topology.txt
(4) Rolling update под нагрузкой, однократные совместимые миграции chaos_load.py --action scripts/rolling-update.sh api-1,2 заменены на api-3,4 по одной; 0 ошибок из 41 154 запросов evidence/rolling-update-load.json
Базовая нагрузка tests/load.py --duration 30 --concurrency 4 840.8 успешных RPS, 0 ошибок, p50/p95/p99 = 4.4/6.4/10.3 мс evidence/load.json

Эксперименты и отказы

Методика: student-tests/chaos_load.py, closed loop, 8 потоков; каждый поток по кругу делает POST message (неподтверждённый POST повторяется с тем же ключом и телом) и GET history?limit=20, таймаут клиента 2 с. Действие запускается на 5-й секунде. После прогона вся история читается и сверяется: каждое подтверждённое сообщение есть ровно один раз, дублей текста нет. Лимиты — как в таблице выше; набор данных — новый чат на каждый прогон (7–20 тыс. сообщений). Один прогон на сценарий: это демонстрация, не статистическое исследование.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop api-1 под нагрузкой краткие ошибки/задержки, затем всё на api-2 15 020 запросов, 0 ошибок, 600 RPS, p50/p95/p99 = 7.9/45/59 мс, max 1019 мс (16 запросов > 0.5 с) ≤ 2.7 с; потерь и дублей нет
docker stop api-2 под нагрузкой то же 15 264 запросов, 0 ошибок, 610 RPS, p99 57 мс, max 1020 мс ≤ 2.5 с; потерь и дублей нет
Rolling update (N→N+1→N, дважды) без ошибок 41 154 запросов, 0 ошибок, 823 RPS, p99 54 мс, max 1023 мс пики ≈1 с в момент каждой остановки; потерь нет
Публичный failover-тест ×6 запись ≤10 с 0 failed attempts, first_recovery 1.6–3.4 с (время включает выполнение hook ≈0.6–0.9 с) данные и токен сохранены
Рестарт всего стенда данные и сессия живы PASS ≈7 с; потерь нет
Обе реплики остановлены LB отвечает сам 503 JSON unavailable с X-Request-Id до restore.sh

Объяснение пиков ≈1 с: IP остановленного контейнера не отвечает RST, поэтому первый запрос к нему ждёт timeout connect 1s, после чего HAProxy повторяет его на другой реплике (redispatch). Через ≤ 2 health-check сервер выводится из ротации, и пики прекращаются. CPU во время отказа: оставшаяся реплика ~51% (из лимита 0.5 CPU — упирается в лимит), PostgreSQL 21–30%, LB 13%.

Ограничения и следующие шаги

  • Выдерживается отказ одного процесса/контейнера API. Не выдерживаются: отказ PostgreSQL, отказ LB, отказ Docker-host — это единые точки отказа (один узел, одна БД без реплики, один HAProxy).
  • Valkey без persistence: его рестарт лишь сбрасывает кэш, источник истины — PostgreSQL. При недоступности Valkey API работает через БД, но logout отвечает 503, пока tombstone не записан.
  • Задержка до 1 с у части запросов во время отказа: можно уменьшить timeout connect или добавить pre-stop drain (readiness 503 → пауза → SIGTERM); не сделано, т.к. ошибок нет и цель ≤10 с выполняется с запасом.
  • Очистка истёкших ключей идемпотентности выполняется лениво (при повторе того же ключа); фоновой очистки таблицы нет — для учебного объёма достаточно, есть индекс created_at для будущего batch-удаления.
  • Миграции совместимы только при аддитивных изменениях; разрушающая миграция потребовала бы expand/contract в несколько релизов.
  • scripts/rolling-update.sh — эквивалент rolling update для Compose (Compose сам не умеет поочерёдную замену), использует --scale N+1 и docker stop/rm старых контейнеров; после него контейнеры называются api-3, api-4 — это нормально.
  • Тестовый порт у автора 8088, т.к. 8080 занят посторонним контейнером; конфигурация по умолчанию — 8080.