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

437 lines
65 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.
# Отчёт — лабораторная 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
```powershell
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 для проверок
```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
```powershell
# Публичные проверки с хоста
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
```powershell
# Идемпотентность: 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:
```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 Наблюдение и логи
```powershell
# Состояние реплик в 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 Остановка стенда
```powershell
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).