Files
mtusi2026lab3/REPORT.md
T
2026-10-20 21:31:57 +03:00

65 KiB
Raw Blame History

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

Балансировка и отказ API-реплики

  • Автор, группа: Максимова Мария, БВТ2303
  • Целевая оценка: 4
  • Commit/PR: ветка solution/maksimova_bvt2303
  • Использованные средства: Python 3.12.7 (в Docker), FastAPI, uvicorn, SQLAlchemy 2 (async) + asyncpg, argon2-cffi, redis-py (клиент Valkey) — всё из lab2; PostgreSQL 16.4, Valkey 8.0.1, HAProxy 3.0.11, Docker Desktop 29.3.0 + Compose v5.1.0.
  • Источники: документация HAProxy 3.0 (resolvers, server-template, http-check, retry-on, http-error), Docker Compose (deploy.replicas, resources, depends_on conditions, secrets), uvicorn (Server, graceful shutdown), PostgreSQL (INSERT … ON CONFLICT, advisory locks).
  • Помощь ИИ: Claude Code использовался для переноса lab2 под lab3 (идемпотентность, drain при SIGTERM, X-Instance-Id), конфигурации HAProxy, операторских скриптов, собственных тестов и черновика отчёта. Измерения выполнены на моём стенде 2026-10-13 (сырые результаты — в evidence/), все команды раздела 3 повторно проверены 2026-10-20.

1. Коротко и простыми словами

Раньше (lab2) был один процесс API. Если он падал — мессенджер не работал. В lab3 процессов API два, а перед ними стоит балансировщик HAProxy. Клиент всегда ходит на один адрес localhost:8080, а HAProxy по очереди отправляет запросы то в одну реплику, то в другую. Если одна реплика умирает, HAProxy это замечает и отправляет всё в живую.

Чтобы такое работало, API не должен ничего важного хранить «у себя в памяти». Всё хранится в общих местах:

  • PostgreSQL — все данные, сессии (токены входа) и ключи идемпотентности;
  • Valkey — только быстрый кэш сессий (если его потерять, ничего не сломается — данные возьмутся из PostgreSQL).

Поэтому неважно, какая реплика обработала запрос: обе видят одни и те же данные и один и тот же токен.

Вторая проблема — повторы. Клиент отправил сообщение, реплика упала, ответа нет. Сообщение сохранилось или нет? Клиент не знает и повторяет запрос. Чтобы повтор не создал дубль, клиент передаёт заголовок Idempotency-Key — уникальную строку на одно сообщение. Сервер запоминает ключ в PostgreSQL вместе с сообщением. Если пришёл тот же ключ ещё раз, сервер не создаёт новое сообщение, а возвращает уже сохранённое.

Что Результат
Публичные тесты make check, make validate, make test PASS
Запросы одного пользователя обслуживают разные реплики да, X-Instance-Id чередуется, повторный вход не нужен
Остановка каждой реплики (make test-failover) PASS для обеих, 0 ошибок, запись снова работает через 4.3–4.5 s
Перезапуск всего стенда (make test-persistence) PASS, данные и прежний токен сохранились
16 одновременных POST с одним ключом, 10 раз каждый раз ровно 1 сообщение, запросы шли через обе реплики
Остановка/убийство реплик под нагрузкой (4 прогона) 1 ошибка на ~11 600 запросов (при SIGKILL), потерь и дублей 0
Rolling update (замена обеих реплик новой версией) 70 s под нагрузкой, 0 ошибок, 4 826 записей, потерь и дублей 0

1.1 О чём лаба?

В прошлой лабе у меня был один сервер API. Если он падал — падал весь мессенджер. В этой лабе я запустила два одинаковых сервера API (реплики), а перед ними поставила балансировщик HAProxy. Пользователь всегда отправляет запросы на один адрес. HAProxy по очереди отдаёт их то первой реплике, то второй. Если одна реплика ломается, HAProxy это замечает и отправляет всё на вторую — пользователь ничего не замечает. Чтобы это работало, реплики ничего не хранят у себя: все данные, сессии и ключи лежат в общей базе PostgreSQL. Поэтому неважно, какая реплика ответила.

Какая реплика ответила — видно по заголовку X-Instance-Id (это имя контейнера).

Схема: Клиент → HAProxy (:8080) → api × 2 → PostgreSQL + Valkey.

1.2 Как сделана отказоустойчивость?

  1. Балансировка round-robin. В конфиге HAProxy balance roundrobin — запросы раздаются по кругу: 1-й на первую реплику, 2-й на вторую, 3-й снова на первую. Это встроенный алгоритм HAProxy. Sticky session (привязки клиента к одной реплике) нет — она не нужна, потому что всё состояние общее.
  2. Проверка здоровья (health check). HAProxy каждую секунду сам спрашивает у каждой реплики /health/ready — «ты готова?». 2 неудачи подряд — реплика считается мёртвой, запросы ей больше не идут. 2 успеха подряд — возвращается обратно. В конфиге это inter 1s fall 2 rise 2.
  3. Повтор на другую реплику. Если запрос не дошёл до реплики (она упала), HAProxy сам повторяет его на другой реплике (retries 2, option redispatch, retry-on). Пользователь ошибки не видит. Повтор уже отправленного запроса разрешён только для GET и для отправки сообщения с Idempotency-Key — чтобы не создать дубль.
  4. Реплики находятся сами через DNS Docker. IP-адреса не прописаны вручную. HAProxy спрашивает у DNS Docker «какие адреса у сервиса api?» и получает адреса всех живых реплик (server-template api 8 api:8080 + resolvers docker). Новая реплика попадает в пул сама.
  5. Мягкое выключение (graceful shutdown). При остановке реплика не выключается сразу: 3 секунды продолжает работать, но на проверку здоровья отвечает «я не готова» (503). За это время HAProxy убирает её из пула, и только потом она закрывается. Поэтому при остановке реплики у пользователей 0 ошибок.

Итог с цифрами: остановка каждой реплики под нагрузкой — 0 ошибок; жёсткое убийство (kill -9) — 1 ошибка на ~11 600 запросов; сообщения не потерялись и не задвоились.

Время обнаружения отказа: упавшая реплика — на первом же запросе (или ≤ 2 s по проверкам); «жива, но не готова» — ≤ 3 s; зависла — ≈ 4 s.

1.3 Почему HAProxy, а не nginx? Какие альтернативы?

Я выбрала HAProxy, потому что это специализированный балансировщик, и бесплатно в нём есть:

  1. Активная проверка здоровья — он сам опрашивает реплики. В бесплатном nginx такой проверки нет (только в платном NGINX Plus), есть только пассивная — по ошибкам реальных запросов.
  2. Сам находит новые реплики через DNS Docker. Бесплатный nginx узнаёт адреса один раз при запуске и после пересоздания контейнера продолжает слать запросы на старый адрес.
  3. Гибкая настройка повторов (какие запросы можно повторять, какие нельзя).
  4. Страница статистики /stats — видно, какая реплика живая (UP), а какая нет (DOWN).

Альтернативы:

Что Что это
Nginx веб-сервер, который тоже умеет балансировать (round-robin, least_conn, ip_hash)
Traefik сам находит контейнеры в Docker/Kubernetes по меткам
Envoy мощный современный прокси, на нём работает Istio
Caddy простой конфиг, сам делает HTTPS
Docker Swarm / Kubernetes встроенная балансировка оркестратора
Облачные AWS ALB/NLB, Yandex Application Load Balancer

Другие алгоритмы балансировки: leastconn (на сервер с наименьшим числом соединений), source (по IP клиента — фактически sticky), random, веса weight.

1.4 Что такое Idempotency-Key?

Пользователь отправил сообщение, реплика упала, ответа нет. Он не знает, сохранилось ли сообщение, и отправляет ещё раз. Без защиты будет два одинаковых сообщения. Поэтому клиент шлёт заголовок Idempotency-Key — уникальную строку на каждое сообщение. Сервер сохраняет ключ в базе вместе с сообщением, в одной транзакции. Пришёл тот же ключ ещё раз — сервер не создаёт новое, а возвращает старое сообщение (заголовок Idempotent-Replayed: true). Тот же ключ, но другой текст — ошибка 409. Ключ хранится в общей базе, поэтому защита работает, даже если повтор пришёл на другую реплику. Если два одинаковых запроса пришли одновременно на разные реплики, второй ждёт в PostgreSQL (на уникальном ключе), пока первый закончит. Проверено: 16 одновременных запросов с одним ключом — каждый раз ровно 1 сообщение.

1.5 Вопросы-ответы

Чем отказ процесса отличается от отказа узла? Процесс — одна программа (у меня один контейнер API). Упал — вторая реплика работает. Узел — целый компьютер: выключился — выключилось всё. У меня всё на одном компьютере, поэтому отказ узла стенд не переживёт (для этого нужны несколько машин и копия базы).

Почему depends_on и healthcheck — не балансировщик? depends_on задаёт только порядок запуска (сначала база, потом API). Healthcheck только ставит метку healthy/unhealthy. Ни то, ни другое не принимает запросы, не распределяет их и не переключает на живую реплику. Это делает только балансировщик.

Какие POST можно повторять после timeout? Только те, повтор которых не создаст дубль: у меня это отправка сообщения с Idempotency-Key. Создание пользователя, чата, входа — повторять нельзя, создастся второй объект. (Если запрос даже не дошёл до сервера — ошибка соединения, — повторять можно любой.)

Что сломается, если сессии хранить в памяти реплики? Вошёл через первую реплику — сессия есть только у неё. Следующий запрос уйдёт на вторую — она пользователя не знает → 401, «выкинет». Выход на одной реплике не сработает на другой. При перезапуске реплики все её сессии пропадут. Поэтому сессии у меня в общей базе.

  • Миграции — выполняет отдельный контейнер migrate один раз перед запуском API, чтобы реплики не делали это одновременно.
  • Почему у api нет ports — чтобы к репликам нельзя было обратиться в обход балансировщика.
  • Почему нет container_name — имя контейнера должно быть уникальным, с ним нельзя запустить 2 копии.
  • Rolling update — по очереди заменяю старые реплики новыми: запускаю новую, жду, пока она здорова, потом останавливаю старую. Получилось 0 ошибок.
  • docker stop и docker kill — stop шлёт SIGTERM, и приложение успевает аккуратно закрыться; kill -9 (SIGKILL) убивает мгновенно, начатые запросы обрываются.
  • Почему был важен Dockerfile — в lab2 был CMD ["sh","-c","uvicorn …"]: главным процессом был sh, он не передавал SIGTERM, и мягкое выключение не работало. Стало CMD ["python","-m","app.server"].
  • Слабые места (SPOF) — балансировщик один, база одна, компьютер один. Как исправить: два HAProxy + keepalived (общий IP), репликация PostgreSQL (Patroni), несколько узлов.
  • Почему X-Instance-Id — не доказательство — заголовок пишет само приложение; поэтому после остановки показываю docker ps -a: у нужного контейнера статус Exited.

1.6 Защита

  1. Поднять стенд, docker compose ps — 2 контейнера api.
  2. Показать, что X-Instance-Id чередуется (раздел 3.4).
  3. make test-failover → docker ps -a (остановлен реальный контейнер) → start-api.sh → то же для второй реплики.
  4. make test-persistence.
  5. Для «4»: тест идемпотентности, серия отказов, страница http://127.0.0.1:8404/stats, результаты rolling update.

2. Что сделано

Из lab2 перенесены app/, миграции 001–002, scripts/migrate.py, scripts/init-secrets.sh, requirements.txt. Новое в lab3:

  1. HAProxy (infra/haproxy/haproxy.cfg) — единственная публичная точка входа :8080. Сервис Compose api запускается в 2 экземплярах (deploy.replicas: 2), у него нет ports и нет container_name.
  2. HAProxy сам находит реплики через встроенный DNS Docker: имя api возвращает IP всех работающих контейнеров сервиса (server-template api 8 api:8080 … resolvers docker). Каждую секунду HAProxy проверяет у каждой реплики /health/ready. Балансировка — обычный round-robin, без sticky session.
  3. В процессе API нет локального состояния: всё в PostgreSQL и общем Valkey.
  4. Каждый ответ API содержит заголовок X-Instance-Id = hostname контейнера (короткий Docker ID). По нему видно, какая реплика ответила.
  5. POST /chats/{id}/messages требует Idempotency-Key (миграция 003_idempotency_keys.sql, код — app/repositories.py: create_message_idempotent).
  6. Graceful shutdown (app/server.py): получив SIGTERM, реплика 3 s продолжает работать, но отвечает 503 на /health/ready. За это время HAProxy выводит её из пула, и только потом она закрывает порт и дорабатывает начатые запросы.
  7. Миграции выполняет отдельный одноразовый сервис migrate до старта API, а не каждая реплика сама. pg_advisory_lock защищает от двух одновременных запусков.
  8. Операторские скрипты: stop-one.sh (остановить одну реплику), kill-one.sh (убить SIGKILL), start-api.sh (вернуть), restart.sh (перезапуск всего стенда), rolling-update.sh (поочерёдная замена реплик).
  9. Argon2 (хеширование пароля, ~0.5–1 s CPU) выполняется в отдельном потоке (asyncio.to_thread), чтобы регистрация/вход не блокировали event loop и /health/ready реплики продолжал отвечать.

Исправления в коде lab2, найденные при переносе:

  • Dockerfile: было CMD ["sh","-c","uvicorn …"], стало CMD ["python","-m","app.server"]. При sh -c процессом №1 в контейнере был sh: он не передавал SIGTERM в uvicorn, и docker stop убивал процесс без graceful shutdown (проверено через docker top).
  • CreateChat.title: максимум 255 → 100 символов, как в контракте.
  • init-secrets.sh: файлы секретов 0644 внутри каталога 0700. На Linux пользователь контейнера appuser не мог прочитать файл 0600, смонтированный как secret.
  • migrate.py: повтор подключения к БД и pg_advisory_lock.

Исправления по замечаниям ревью:

  • POST /auth/sessions принимает только Authorization: Basic без тела (contracts/README.md). Раньше тело игнорировалось: {bad или {} с действительным Basic давали 201. Теперь любое непустое тело → 400 invalid_request до проверки пароля (app/main.py, login). Без тела (в т.ч. с Content-Type: application/json) — по-прежнему 201.
  • CreateChat.member_ids: добавлен максимум 100 элементов, как maxItems: 100 в contracts/openapi.json (app/models.py). 101 участник → 400 invalid_request, ровно 100 → 201.
  • Проверка обоих сценариев: docker compose --profile tools run --rm tester python3 student-tests/contract_edge_cases.py (6 проверок, PASS: тело при входе и лимит участников соответствуют контракту).
  • Проверено 2026-10-20 на пересобранном стенде: оба сценария ревью, make check/validate/test — PASS, make test-failover — PASS (failed_attempts: 0), идемпотентность — PASS.

3. Все команды

Все образы закреплены версиями:

Роль Service Образ Health/readiness Volume Сеть / порт Секреты
LB lb haproxy:3.0.11-alpine wget /lb-health (:8404) — edge; LB_PORT (8080) публично, 8404 только 127.0.0.1 нет
API ×2 api messenger-lab3-api:<APP_VERSION> (сборка из Dockerfile, база python:3.12.7-slim) GET /health/ready (БД доступна и нет drain) — edge + backend, порт не публикуется database_url, cache_url
Миграции migrate тот же образ завершается с кодом 0 — backend database_url
БД db postgres:16.4-alpine pg_isready postgres_data backend (internal) postgres_password
Кэш сессий valkey valkey/valkey:8.0.1-alpine valkey-cli ping нет (это кэш) backend (internal) valkey_password
Проверки tester (profile tools) сборка student-tests/Dockerfile.tester (python:3.12.11-alpine3.22 + docker CLI 28.5.1) — — edge docker.sock (только учебный стенд)

Сеть backend — internal: true: у PostgreSQL и Valkey нет выхода наружу, и HAProxy к ней не подключён. Наружу опубликован только порт балансировщика.

Команды ниже — для Windows PowerShell (мой стенд). Отличия для Linux/macOS — в разделе 3.8.

3.1 Что нужно установить

  • Docker Desktop (Compose v2);
  • Git for Windows — даёт команду sh для скриптов *.sh;
  • make: winget install ezwinports.make;
  • Python 3.11 или 3.12 (на 3.14 не ставятся закреплённые pydantic-core/asyncpg — для них нет готовых wheel).

3.2 Первый запуск из чистого clone

git clone https://gitea.privcloud.tech/Mariia_Maksimova/mtusi2026lab3.git
cd mtusi2026lab3
git checkout solution/maksimova_bvt2303

# Секреты: создаются один раз в infra/secrets/, в Git не попадают, значения не печатаются
sh scripts/init-secrets.sh

# Параметры стенда (секретов не содержит)
Copy-Item .env.example .env
# Если порт 8080 занят (у меня его держит служба Windows AgentService.exe) —
# в .env поставить LB_PORT=8081

# Проверка конфигурации, сборка, миграции (сервис migrate) и запуск;
# --wait ждёт, пока все сервисы станут healthy
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
docker compose ps

В docker compose ps должно быть: api ×2, db, valkey, lb — healthy; migrate — Exited (0).

3.3 Настройка окна PowerShell для проверок

# Один раз: виртуальное окружение (нужно для make validate; make check/test используют только stdlib)
py -3.11 -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements-dev.txt

# В КАЖДОМ новом окне PowerShell — до любых make (без этого будет "Error 9009")
$env:PYTHONUTF8 = "1"                           # иначе Python читает openapi.json в cp1251 -> UnicodeDecodeError
$env:PYTHON = ".venv/Scripts/python.exe"        # в Windows нет python3, который Makefile вызывает по умолчанию
$env:BASE_URL = "http://localhost:8080"         # или http://localhost:8081, если в .env LB_PORT=8081

Makefile берёт PYTHON и BASE_URL из окружения (PYTHON ?= python3, BASE_URL ?= http://localhost:8080), поэтому после этих трёх строк make check/validate/test запускаются без дополнительных параметров. На контейнер tester эти переменные не влияют: у него свои BASE_URL=http://lb:8080 и python3.

3.4 Проверки уровня 3

# Публичные проверки с хоста
make check
make validate
make test

# Разные реплики через один LB: X-Instance-Id чередуется
1..4 | ForEach-Object { curl.exe -s -D - -o NUL "$env:BASE_URL/health/live" | findstr /i "x-instance-id" }

# Отказ реплики №1: тест сам выбирает реплику и вызывает scripts/stop-one.sh
docker compose --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh

# Доказательство: какой контейнер реально остановлен (Exited (0))
docker ps -a --filter "label=com.docker.compose.project=messenger-lab3" --filter "label=com.docker.compose.service=api" --format "table {{.Names}}\t{{.ID}}\t{{.Status}}"

# Вернуть остановленную реплику
docker compose --profile tools run --rm tester sh scripts/start-api.sh

# Отказ реплики №2: один лишний запрос сдвигает round-robin, тест выберет другую реплику
curl.exe -s -o NUL "$env:BASE_URL/health/live"
docker compose --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker ps -a --filter "label=com.docker.compose.project=messenger-lab3" --filter "label=com.docker.compose.service=api" --format "table {{.Names}}\t{{.ID}}\t{{.Status}}"
docker compose --profile tools run --rm tester sh scripts/start-api.sh

# Перезапуск всего стенда с сохранением volume и прежнего токена
docker compose --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh

Почему failover/persistence запускаются в контейнере tester: публичный тест вызывает .sh-скрипт через subprocess.Popen, а Windows не умеет исполнять .sh напрямую. В tester есть Python, make и docker CLI, а BASE_URL = http://lb:8080 — тот же балансировщик, только изнутри Docker-сети (поэтому LB_PORT хоста здесь не важен). Сами тесты не менялись.

3.5 Проверки уровня 4

# Идемпотентность: 10 раундов × 16 одновременных POST с одним ключом -> ровно 1 сообщение
docker compose --profile tools run --rm tester python3 student-tests/idempotency_concurrency.py --output evidence/idempotency-concurrency.json

# Серия отказов под нагрузкой: stop и kill каждой реплики по очереди, с восстановлением
# (результаты: evidence/failover-stop-*.json, evidence/failover-kill-*.json)
docker compose --profile tools run --rm tester sh student-tests/run-failover-series.sh

# Жёсткий отказ одной реплики вручную (ID взять из docker ps), потом вернуть
docker compose --profile tools run --rm -e TARGET_INSTANCE_ID=<12 символов ID> tester sh scripts/kill-one.sh
docker compose --profile tools run --rm tester sh scripts/start-api.sh


# Нагрузка (справочно) и потребление ресурсов
docker compose --profile tools run --rm tester make load
docker stats --no-stream

Rolling update под нагрузкой — два окна PowerShell:

# Окно 1: нагрузка 70 s
docker compose --profile tools run --rm tester python3 student-tests/failover_load.py --duration 70 --label rolling-update --output evidence/rolling-update-load.json

# Окно 2 (сразу после старта нагрузки): сборка новой версии, миграции один раз, поочерёдная замена реплик
$env:APP_VERSION = "v3"
sh scripts/rolling-update.sh

После rolling update реплики работают на образе messenger-lab3-api:v3. Все дальнейшие docker compose up нужно выполнять с тем же APP_VERSION ($env:APP_VERSION = "v3" или строка APP_VERSION=v3 в .env), иначе Compose пересоздаст реплики на образе dev.

3.6 Наблюдение и логи

# Состояние реплик в LB (UP/DOWN, счётчики ошибок и повторов) — открыть в браузере:
#   http://127.0.0.1:8404/stats
docker compose logs lb --tail 30          # строки "Server api/apiN is DOWN/UP"
docker compose logs api --tail 30         # "draining for 3.0 s", "drain finished: closing listener"
docker compose ps

3.7 Остановка стенда

docker compose down        # безопасно: данные остаются в volume postgres_data
docker compose down -v     # ОСТОРОЖНО: удаляет volume с базой

3.8 Linux/macOS

Всё то же, но: cp .env.example .env; python3 -m venv .venv && .venv/bin/python -m pip install -r requirements-dev.txt; export PYTHON=.venv/bin/python (или по умолчанию python3); PYTHONUTF8 не нужен; curl -s -D - -o /dev/null "$BASE_URL/health/live" | grep -i x-instance-id. Failover/persistence можно запускать прямо с хоста: make test-failover ACTION_SCRIPT=scripts/stop-one.sh, make test-persistence ACTION_SCRIPT=scripts/restart.sh. Rolling update: APP_VERSION=v3 sh scripts/rolling-update.sh.

3.9 Частые ошибки

Ошибка Причина Что сделать
Python make: *** [Makefile:13: check] Error 9009 (то же для validate, test) в Windows нет команды python3; не задан $env:PYTHON $env:PYTHON = ".venv/Scripts/python.exe" (раздел 3.3)
UnicodeDecodeError: 'charmap' codec … Python на Windows читает файлы в cp1251 $env:PYTHONUTF8 = "1"
FAIL: GET /health/live: connection/TLS failure (TimeoutError) тест идёт на 8080, а LB на другом порту (или стенд не запущен) $env:BASE_URL = "http://localhost:8081" (порт из LB_PORT); docker compose ps
Failed building wheel for pydantic-core / asyncpg venv на Python 3.14 пересоздать: @py -3.11 -m venv .venv
secret ... file not found при up не созданы секреты sh scripts/init-secrets.sh
failover-тест на Windows с хоста не запускает .sh Windows не исполняет .sh запускать через tester (раздел 3.4)

Переменные .env.example → реальная конфигурация:

.env.example Где используется
LB_PORT публичный порт HAProxy на хосте (по умолчанию 8080)
APP_VERSION тег образа api/migrate (по умолчанию dev)
API_REPLICAS deploy.replicas сервиса api (по умолчанию 2)
SESSION_TTL_SECONDS api (по умолчанию 3600)
IDEMPOTENCY_TTL_SECONDS api (86400 = 24 ч)
APP_HOST, APP_PORT заданы в compose.yaml (0.0.0.0:8080 внутри контейнера)
DATABASE_URL_FILE /run/secrets/database_url у api и migrate
SESSION_STORE valkey: сессии в PostgreSQL, cache-aside в Valkey (как в lab2)
CACHE_URL_FILE /run/secrets/cache_url у api
APP_ENV не используется приложением

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

client ──HTTP:8080──► HAProxy (lb) ──round-robin, проверка /health/ready раз в 1 s──► api-1 ─┐
                         │  DNS Docker 127.0.0.11: имя "api" → IP всех реплик            api-2 ─┤
                         └─ X-Request-Id, повтор на другую реплику при отказе             ...   │
                                                                                                ▼
                                                 сеть backend (internal): PostgreSQL (источник истины)
                                                                          Valkey (кэш сессий)

Источник истины — PostgreSQL: пользователи, чаты, участники, сообщения, сессии (хеш токена), ключи идемпотентности. Valkey хранит только копию «хеш токена → пользователь» с TTL ≤ 60 s. Logout на одной реплике пишет в общий Valkey отметку revoked (tombstone), её сразу видят все реплики. Поэтому повторный вход при смене реплики не нужен: в failover-тесте 40 запросов /users/me одним токеном обслужили 2 разные реплики.

Как работает идемпотентность. Таблица idempotency_keys: первичный ключ (user_id, chat_id, method, key), request_hash = SHA-256 тела запроса, message_id. Всё делается в одной транзакции:

  1. INSERT … ON CONFLICT DO UPDATE … WHERE created_at < now() - TTL RETURNING 1 — «занять» ключ. Если тот же ключ в этот момент занимает незавершённая транзакция на другой реплике, PostgreSQL заставляет вторую транзакцию ждать на уникальном индексе. Так одновременные повторы выстраиваются в очередь в самой БД, без блокировок в памяти API.
  2. Ключ занят нами → INSERT сообщения, UPDATE ключа ссылкой на сообщение, COMMIT. Если что-то упало до COMMIT, откатываются обе записи: ни сообщения, ни ключа нет, и повтор выполнится заново.
  3. Ключ уже был сохранён раньше → если хеш тела совпадает, возвращается 201 с тем же сообщением и заголовком Idempotent-Replayed: true; если тело другое — 409. Ключ старше 24 ч можно использовать заново.

До всего этого повтор проходит проверку токена и членства в чате (посторонний получит 404). Область действия ключа: пользователь + метод + чат + ключ — тот же ключ у другого пользователя или в другом чате создаёт новое сообщение (проверено тестом).

Миграции. Сервис migrate стартует после того, как БД стала healthy, а API — только после того, как migrate успешно завершился (depends_on: service_completed_successfully). Повторный запуск печатает SKIP. Миграция 003 только добавляет таблицу, поэтому её можно применить, пока работает старая версия API. Правило на будущее: удалять/переименовывать колонки — отдельным релизом, когда ни одна реплика их уже не использует (expand → deploy → contract). Автоматической проверки совместимости нет — это ограничение.

Транзакционные границы: создание чата с участниками — одна транзакция (из lab2); сообщение + ключ идемпотентности — одна транзакция; отзыв сессии — UPDATE в PostgreSQL, затем tombstone в Valkey.

5. Health, timeouts и обнаружение отказа (уровень 4)

Параметр Значение Где
/health/live 200, только «процесс жив» app/main.py
/health/ready 200, если SELECT 1 в PostgreSQL успешен и нет drain; иначе 503. Valkey не критичен: без него запросы идут в PostgreSQL app/main.py
Активная проверка LB inter 1s, fall 2, rise 2, timeout check 1s (раз в секунду; 2 неудачи подряд → DOWN; 2 успеха → UP) infra/haproxy/haproxy.cfg
Пассивная проверка LB observe layer4 error-limit 1 on-error mark-down: первая же ошибка соединения на реальном запросе сразу переводит сервер в DOWN там же
DNS-обновление списка реплик hold valid 2s (резолвер Docker 127.0.0.11) там же
Таймауты LB connect 1 s, server 10 s, http-request 10 s, keep-alive 10 s, client 30 s там же
Повторы в LB retries 2, option redispatch 1, retry-on conn-failure empty-response 503. Повтор уже отправленного запроса запрещён для POST (кроме POST сообщения с Idempotency-Key) и для DELETE там же
Приложение statement_timeout 5 s, ожидание соединения из пула 3 s, connect 3 s; uvicorn keep-alive 30 s (больше, чем 10 s у LB — соединение первым закрывает LB) compose.yaml, app/server.py
SIGTERM drain 3 s (readiness 503, Connection: close), затем закрытие порта и ожидание текущих запросов ≤ 8 s; stop_grace_period: 15s > 3 + 8 app/server.py, compose.yaml
Docker healthcheck API каждые 2 s, 2 неудачи compose.yaml

Как таймауты согласованы между собой: timeout server LB (10 s) больше, чем БД может держать запрос (5 s statement + 3 s ожидание пула), поэтому LB не обрывает запрос, который приложение ещё может успешно завершить. Drain (3 s) больше, чем время, за которое LB замечает 503 (≈ 2–3 s), поэтому к моменту закрытия порта новые запросы на реплику уже не идут.

Максимальное время обнаружения отказа (по конфигурации):

  • процесс упал (connection refused/reset) — на первом же реальном запросе (observe layer4), сам запрос тут же повторяется на другой реплике; если трафика нет — активная проверка, ≤ inter × fall = 2 s;
  • процесс жив, но не готов (нет БД, идёт drain) — ≤ inter × fall + timeout check ≈ 3 s;
  • процесс завис (не отвечает вовсе) — ≤ 2 × (1 s интервал + 1 s таймаут проверки) ≈ 4 s; запросы, уже отправленные на зависшую реплику, ждут до timeout server = 10 s.

Что видно при docker stop реплики: в логе HAProxy Server api/apiN is DOWN, reason: Layer7 wrong status, code: 503, затем в логе API drain finished: closing listener, контейнер завершается с Exited (0). Сам docker stop занимает ≈ 4 s (окно действия 4.13 и 4.04 s в evidence/failover-stop-*.json). При SIGKILL (kill-one.sh) код выхода 137.

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

Прогоны с измерениями — 2026-10-13, 14:49–14:58 UTC, на стенде из раздела 7. Повторная проверка команд 2026-10-20: make check/validate/test — PASS; make test-failover — PASS (observed_instances_before: 2, failed_attempts: 0, first_recovery_seconds: 4.262, у остановленного контейнера Exited (0)); make test-persistence — PASS; идемпотентность — PASS.

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test (хост → LB) PASS: lab3 public API scenario evidence/public-tests.txt
Структура контракта make check, make validate PASS evidence/public-tests.txt
≥2 реплики, одна точка входа, общая БД и сессии docker compose ps; 4 запроса подряд через LB; 40× /users/me одним токеном в failover-тесте 2 контейнера api; X-Instance-Id чередуется fcae2c6047af / 1ff54c0efa0c; observed_instances_before: 2, без повторного входа evidence/public-tests.txt
Остановка любой одной реплики, восстановление ≤10 s make test-failover ACTION_SCRIPT=scripts/stop-one.sh дважды — по разу для каждой реплики (в tester) оба PASS; failed_attempts: 0; first_recovery_seconds 4.4 и 4.52; в docker ps -a Exited (0) сначала у 1ff54c0efa0c, потом у fcae2c6047af — остановлен реальный контейнер evidence/public-tests.txt
Повтор с тем же ключом без дублей, в т.ч. во время отказа resilience.py повторяет неопределённый POST тем же ключом; smoke: повтор = то же сообщение, другое тело = 409 PASS, дублей нет evidence/public-tests.txt
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS, прежний токен действует; StartedAt у db, valkey, обеих api и lb — после запуска hook (14:50:49–14:51:02), volume messenger-lab3_postgres_data на месте evidence/persistence.txt
4: health/readiness/timeouts/SIGTERM согласованы, LB исключает backend конфигурация + docker stop реплики раздел 5; реплика перестаёт получать запросы через 0.87–0.99 s после начала docker stop; выход с кодом 0 раздел 5, evidence/failover-stop-*.json
4: поочерёдная остановка каждой реплики под нагрузкой: RPS, ошибки, время восстановления student-tests/run-failover-series.sh (stop и kill для каждой реплики, с восстановлением предыдущей) таблица в разделе 7; 1 ошибка на 4 прогона, потерь и дублей 0 evidence/failover-*.json, evidence/failover-series.txt
4: параллельные запросы с одним ключом student-tests/idempotency_concurrency.py (10 раундов × 16 одновременных POST с одним ключом) в каждом раунде 1 сообщение и 15 ответов-повторов; все 10 раундов прошли через 2 реплики; другое тело → 409; ключ не мешает другому пользователю/чату evidence/idempotency-concurrency.json
4: CPU/RAM-лимиты, нет портов API наружу, нет container_name, секреты только где нужны compose.yaml лимиты у всех сервисов; у api нет ports; db/valkey в internal-сети; у LB нет секретов (таблица в разделе 3) compose.yaml
4: rolling update под нагрузкой, однократные совместимые миграции APP_VERSION=v3 sh scripts/rolling-update.sh + параллельно failover_load.py (70 s, 4 потока) обе реплики v2 заменены на v3 (новые a9d3dc77f288, ea0e32824716); 4 826 подтверждённых записей, 0 ошибок, максимальная пауза между записями 0.054 s; миграции один раз, все SKIP evidence/rolling-update.txt, evidence/rolling-update-load.json
Нагрузка (справочно) tests/load.py --duration 30 --concurrency 4, 4 прогона 142–154 успешных RPS (среднее ≈ 148), 0 ошибок, p50 ≈ 15 ms, p95 76–86 ms, p99 98–138 ms evidence/load*.json, evidence/load-docker-stats.txt

Почему X-Instance-Id — не единственное доказательство: заголовок пишет само приложение. Поэтому после каждого отказа сохранён вывод docker ps -a: видно, что Exited именно тот контейнер, чей ID был в TARGET_INSTANCE_ID, а остальные сервисы продолжают работать.

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

Стенд. Docker Desktop 29.3.0 (WSL2), хост 14 CPU / 7.4 GiB RAM. Лимиты: каждая api — 0.5 CPU / 256 MiB, db — 1 CPU / 512 MiB, valkey — 0.25 CPU / 128 MiB, lb — 0.5 CPU / 128 MiB. Генератор нагрузки — в контейнере tester в той же Docker-сети. Данные: синтетические, каждый прогон создаёт своих пользователей и чат.

Профиль нагрузки (student-tests/failover_load.py): закрытый цикл, 4 потока, 30 s, без прогрева; 50 % — POST сообщения, 50 % — GET истории (limit 20); таймаут клиента 3 s. Клиент ведёт себя как настоящий: если результат неизвестен, повторяет POST с тем же ключом и текстом. Через 8 s запускается action-скрипт против выбранной реплики; после прогона она возвращается (start-api.sh), и следующий прогон бьёт по другой. В конце вся история чата читается заново и проверяется: каждое подтверждённое сообщение на месте, одинаковых текстов нет.

Гипотеза. При docker stop (SIGTERM) клиенты не увидят ошибок: реплика сначала уходит из пула, потом закрывается. При SIGKILL возможны единичные ошибки: запросы, которые были внутри убитого процесса, оборвутся; большую часть из них HAProxy повторит на другой реплике. После отказа пропускная способность упадёт, потому что API упирается в CPU-лимит реплики.

RPS ниже — все успешные запросы (чтение + запись) в секунду. «Во время» — окно, пока выполняется action-скрипт (≈ 4 s для stop, < 1 s для kill).

Воздействие Что ожидаем Что наблюдали: успешные RPS до → во время → после; p95 до → после Восстановление / потеря данных
stop-one реплика 1 (SIGTERM) 0 ошибок 130.6 → 79.1 → 93.5; p95 86 → 99 ms; ошибок 0 реплика перестала получать запросы через 0.99 s; макс. пауза между записями 0.40 s; 1 525 записей, потерь и дублей 0; Exited (0)
stop-one реплика 2 (SIGTERM) 0 ошибок 149.2 → 108.0 → 87.9; p95 81 → 100 ms; ошибок 0 0.87 s; пауза 0.39 s; 1 606 записей, потерь 0; Exited (0)
kill-one реплика 1 (SIGKILL) единичные ошибки 106.1 → 44.3 → 89.4; p95 99 → 100 ms; ошибок 0 0.06 s; пауза 0.19 s; 1 398 записей, потерь 0; Exited (137)
kill-one реплика 2 (SIGKILL) единичные ошибки 118.8 → 23.8 → 74.2; p95 94 → 104 ms; 1 ошибка (через 0.13 s после kill) 0.11 s; пауза 0.29 s; 1 273 записи, потерь и дублей 0; Exited (137)
Rolling update api ×2 → v3 0 ошибок 137.8 RPS в среднем за 70 s, ошибок 0; по секундам не ниже 52 успешных запросов макс. пауза между записями 0.054 s; 4 826 записей, потерь и дублей 0
Restart всего стенда данные и токен сохраняются make test-persistence PASS на время перезапуска сервис недоступен (ожидаемо: останавливаются и LB, и БД); БД поднялась в 14:50:49, LB — в 14:51:02 (≈ 13 s)

Реплики: 1 = fcae2c6047af, 2 = 1ff54c0efa0c.

Выводы.

  1. Graceful stop работает: 0 ошибок в обоих прогонах. Реплика ещё ≈ 1 s обслуживает запросы во время drain, потом HAProxy убирает её из пула.
  2. Гипотеза про SIGKILL подтвердилась: в одном прогоне 0 ошибок, в другом 1 ошибка из ~2 500 запросов. Почти все оборванные запросы HAProxy сам повторил на другой реплике (retry-on conn-failure empty-response). Единственную ошибку клиент повторил с тем же ключом — сообщение не потерялось и не задвоилось. Повторять в LB можно только потому, что GET безопасен, а POST сообщения защищён Idempotency-Key. Для остальных POST повтор в LB отключён.
  3. С одной репликой пропускная способность падает на ~30–40 % (с ~106–149 до ~74–94 RPS). docker stats под нагрузкой: обе api ≈ 49 % CPU при лимите 0.5 CPU, то есть упираются в свой лимит; db ≈ 34 % от 1 CPU, lb ≈ 22 %. Узкое место — CPU API, а не БД. Падение меньше двукратного, потому что часть времени запроса уходит на сеть, БД и сам генератор нагрузки на том же хосте.
  4. Rolling update прошёл без ошибок: новая реплика добавляется и проходит проверки до того, как останавливается старая, поэтому в пуле всегда минимум 2 рабочие реплики.

Ограничения измерений. Закрытый цикл (coordinated omission: пока клиент ждёт медленный ответ, он не шлёт новые, поэтому задержки занижены). Каждый сценарий отказа — один прогон по 30 s без повторов. Генератор нагрузки на том же хосте и делит с ним CPU. RPS «во время» посчитан по окну < 5 s и шумный. first_recovery_seconds публичного теста считается от начала hook до первой записи после его окончания, а сам docker stop с drain длится ≈ 4 s — реальный перерыв в записи намного меньше (макс. пауза 0.39–0.40 s).

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

  • Выдерживается отказ одной API-реплики (процесса/контейнера). Не выдерживаются: отказ PostgreSQL (один экземпляр без реплики), отказ HAProxy (единственная точка входа) и потеря Docker-хоста — всё работает на одном хосте. Отказ Valkey выдерживается: API переходит на PostgreSQL (проверялось в lab2).
  • Кэш сессий очищается (FLUSHDB) при старте каждого процесса API — решение из lab2 против потерянной инвалидации. С несколькими репликами каждый рестарт/rolling update сбрасывает общий кэш: на корректность не влияет, но ненадолго увеличивает нагрузку на PostgreSQL.
  • Время сообщения — now() начала транзакции PostgreSQL (одни часы для всех реплик). Транзакции могут фиксироваться не в порядке created_at, поэтому читатель, листающий историю во время конкурентной записи, может не увидеть сообщение, вставленное «позади» курсора. При чтении уже неизменной истории пропусков и повторов нет.
  • Старые ключи идемпотентности автоматически не удаляются: через 24 ч ключ переиспользуется, индекс по created_at подготовлен для будущей периодической очистки.
  • X-Instance-Id раскрывает hostname контейнера (короткий Docker ID) — по нему stop-one.sh находит контейнер. В lab7 его стоит заменить случайным псевдонимом.
  • rolling-update.sh использует docker compose --scale, поэтому номера контейнеров растут (api-5, api-6…). Автоматического отката нет: при ошибке скрипт останавливается, старые реплики продолжают работать.
  • Контейнер tester монтирует docker.sock — это полный доступ к Docker-хосту; допустимо только на учебном стенде.
  • Тесты lab2 (level4.py, db_checks.py) не перенесены: они рассчитаны на топологию lab2 (API напрямую на :8080, отдельный api_short_ttl на :8081).