Files
mtusi2026lab6-fork/docs/lab3/REPORT.md
T

232 lines
40 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
- Автор, группа: Попов Константин Дмитриевич, группа БВТ2303
- Целевая оценка: **4**; трек 5 не заявляется
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, psycopg 3.2.3 + psycopg-pool 3.2.4, redis-py 5.2.1, argon2-cffi 23.1.0; PostgreSQL 16, Redis 7, HAProxy 2.8 LTS. Документация: Docker Compose (services, deploy, depends_on, healthcheck), HAProxy 2.8 Configuration Manual (server-template, resolvers, http-check, retries/redispatch, http-error), PostgreSQL (INSERT … ON CONFLICT, deferrable constraints, advisory locks), Uvicorn (graceful shutdown). Помощь ИИ (Claude) использовалась при проектировании схемы идемпотентности и drain-фазы, написании скриптов стенда, тестов и формулировке отчёта; решения проверены тестами, приведёнными ниже.
## Запуск из чистого clone
**Версии.** API: сборка из `Dockerfile` на `python:3.12.7-slim-bookworm`; `postgres:16.4-alpine`; `redis:7.4.1-alpine`; `haproxy:2.8.30-alpine`. Зависимости Python закреплены в `requirements.txt`. Нужны Docker Desktop / Docker Engine с Compose v2 и Python 3.9+ на хосте (тесты и `scripts/ops.py` — только стандартная библиотека). Вариант оркестрации — **Compose + HAProxy** (Swarm не используется).
```powershell
$env:PYTHONUTF8 = "1"
# 1. Локальные секреты (один раз; каталог secrets/ в .gitignore, значения не печатаются) и .env
python scripts/init_secrets.py
copy .env.example .env # Linux/macOS: cp .env.example .env
# 2. Проверка, сборка и запуск: postgres+redis -> migrate (однократно) -> api x2 -> lb
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# 3. Ожидание готовности: 2 реплики healthy, обе UP в HAProxy, /health/ready через LB = 200
python scripts/ops.py wait
python scripts/ops.py ps # X-Instance-Id <-> контейнер <-> статус в LB
```
Время прогрева: первая сборка образа 1–2 мин; дальше стенд готов примерно через 20–30 с (healthcheck PostgreSQL, миграции, `start_period` API, `rise 2` в HAProxy).
```powershell
# Публичные проверки (Linux/macOS: make check / make test / make test-persistence ... )
python scripts/check_contract.py
python tests/smoke.py --base-url http://localhost:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd # Linux/macOS: scripts/restart.sh
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd # Linux/macOS: scripts/stop-one.sh
python scripts/ops.py restore # вернуть остановленную реплику; затем повторить failover для другой
# Собственные проверки уровня 4
python student-tests/run_all.py --base-url http://localhost:8080 # API, auth, идемпотентность через реплики, race
python scripts/ops.py in-network storage # тесты с прямым доступом к БД (внутри compose-сети)
python scripts/ops.py in-network expiry # истечение сессии (api-short-ttl, TTL 2 с)
python student-tests/failover_series.py --output evidence/failover_series.json # каждая реплика по очереди, SIGTERM
python student-tests/failover_series.py --mode kill --output evidence/failover_series_kill.json # то же, SIGKILL
python student-tests/rolling_update_load.py --output evidence/rolling_update.json # rolling update под нагрузкой
python tests/load.py --duration 30 --concurrency 8 --output evidence/load.json
# Всё перечисленное одной командой с записью результатов в evidence/ (~8–10 мин):
python scripts/collect_evidence.py
```
**Rolling update.** Задать новый тег `APP_VERSION` (например, `lab3.1`) в `.env` или в окружении и выполнить `python scripts/ops.py rolling-update`: сборка образа, однократные миграции (`docker compose run --rm migrate`), затем для каждой старой реплики: +1 новая → healthy и UP в HAProxy → graceful stop старой → удаление.
**Остановка.** Безопасная, данные сохраняются: `docker compose --env-file .env --profile ttl down` (volume `pgdata` остаётся). Намеренное удаление всех учебных данных — только вручную: `docker compose --env-file .env --profile ttl down -v`. Hooks и тесты никогда не удаляют volumes.
**Действия оператора:** создать секреты до первого запуска; пароль PostgreSQL задаётся только при инициализации пустого volume, поэтому `init_secrets.py` не перезаписывает существующие файлы. После `stop-one`/тестов отказа вернуть реплику `python scripts/ops.py restore`.
## Архитектура и решения
```
127.0.0.1:8080 (единственная публичная точка входа API)
Клиент ──HTTP──► lb: HAProxy 2.8 ── roundrobin, активные проверки GET /health/ready
│ 127.0.0.1:8404 — страница состояния (UP/DOWN реплик), только чтение
│ обнаружение реплик: Docker DNS имени `api` -> server-template api1..api6
▼
┌───────── api (deploy.replicas = 2, без ports, без container_name) ─────────┐
│ api-1: X-Instance-Id = hostname = короткий ID контейнера 0.5 CPU / 256M │
│ api-2: ... 0.5 CPU / 256M │
└──────┬──────────────────────────────────────────────────────────┬──────────┘
▼ ▼
postgres 16 (1 CPU / 512M, volume pgdata) redis 7 (0.25 CPU / 96M)
источник истины: users, chats, messages, общий кэш проверок токена,
sessions, idempotency_keys, schema_migrations без persistence
▲
migrate (one-shot): python -m src.migrate — до старта реплик, один раз
```
Порядок старта задаётся `depends_on`: `postgres`, `redis` (healthy) → `migrate` (`service_completed_successfully`) → `api` (healthy) → `lb`. API-реплики не публикуют порты: `expose: 8080` только внутри сети `backend`. Наружу (на 127.0.0.1) опубликован только `lb`.
### Почему HAProxy, а не Nginx
В open-source Nginx нет активных health checks: он узнаёт об отказе только по ошибкам живых запросов (`max_fails`). HAProxy сам опрашивает `/health/ready` с заданным периодом. Поэтому время обнаружения отказа можно указать числом, а фаза осушения при SIGTERM действительно выводит реплику из ротации до остановки. `server-template` + `resolvers` синхронизируют список реплик с DNS-записями сервиса `api` каждые 2 с. Масштабирование и rolling update поэтому не требуют перезапуска или перечитывания конфига LB. Sticky sessions не используются (`balance roundrobin`, без cookie).
### Что перенесено из lab2 и что изменено
Перенесены без изменения семантики: модели и валидация, формат ошибок, keyset-пагинация, Argon2id, Basic → Bearer, сессии в PostgreSQL + кэш в Redis с надёжной инвалидацией (`session_cache_invalidations`), собственные тесты lab2. Схема lab2 уже рассчитана на несколько реплик: сессии лежат в общей БД, кэш — в общем Redis, а долг инвалидации перечитывается всеми репликами не реже раза в секунду.
Изменено в lab3:
1. **Переход 2 → 3 по контракту:** `X-Instance-Id` во всех ответах API, включая ошибки и health (middleware + `error_response`). Обязательный `Idempotency-Key` для `POST /chats/{id}/messages`.
2. **Общая идемпотентность** — таблица `idempotency_keys` (миграция `003`), подробности ниже.
3. **Миграции вынесены из реплик** в one-shot сервис `migrate` (`RUN_MIGRATIONS_ON_START=false`). Реплика готова только когда в `schema_migrations` есть последняя версия, которую знает её образ.
4. **Graceful shutdown с осушением** (`src/server.py`): по SIGTERM реплика сразу отвечает 503 на readiness, но ещё 3 с обслуживает запросы, затем штатно останавливается.
5. **Лимит одновременных хешей Argon2id** (`PASSWORD_HASH_CONCURRENCY=4`). У реплики лимит 256M, а threadpool FastAPI — до 40 потоков; без лимита всплеск входов мог бы занять 40 × 19 MiB и привести к OOM-kill.
6. **Readiness** использует отдельный короткий таймаут БД (`READY_DB_TIMEOUT_SECONDS=1`) меньше `timeout check` HAProxy.
7. Тесты lab2 адаптированы к переходу: при отправке сообщения добавляется `Idempotency-Key`, имя проекта сменилось на `messenger-lab3`. Тест истечения сессии и тесты хранилища теперь идут внутри compose-сети, без публикации портов в обход LB.
### Идемпотентность отправки сообщения (`src/storage.py`, `migrations/003_idempotency_keys.sql`)
- Ключ: `PRIMARY KEY (user_id, method, chat_id, idem_key)` — ровно область из контракта «пользователь + метод + путь чата + ключ». В строке хранятся SHA-256 канонического JSON тела (`sort_keys`, без пробелов: порядок ключей и форматирование не важны), `message_id`, `expires_at = now + IDEMPOTENCY_TTL_SECONDS (86400)`.
- **Одна транзакция READ COMMITTED:**
1. `INSERT INTO idempotency_keys … ON CONFLICT DO UPDATE … WHERE expires_at <= now() RETURNING`. Конкурентная транзакция с тем же ключом **ждёт на уникальном индексе**, пока первая не сделает COMMIT/ROLLBACK. Это и даёт «ровно одно сообщение» при одновременных повторах через разные реплики: арбитр — PostgreSQL, а не память процесса.
2. Ключ наш → `INSERT messages … WHERE EXISTS (членство)` с заранее выбранным id. FK `message_id → messages` объявлен `DEFERRABLE INITIALLY DEFERRED` и проверяется при COMMIT, поэтому `message_id NOT NULL` с первого шага.
3. Ключ уже подтверждён → снова проверяется членство (и сессия — dependency `current_user`). Hash совпал → 201 и то же сообщение (+ информационный заголовок `Idempotency-Replayed: true`); не совпал → 409.
- Любая ошибка или обрыв до COMMIT откатывает и ключ, и сообщение: транзиентный 5xx не фиксируется. 404 и 400 ключ не «сжигают». Истёкший, но ещё не удалённый ключ можно занять заново. Фоновая очистка раз в 5 мин удаляет истёкшие ключи пачками под `pg_try_advisory_xact_lock`, то есть одной репликой за раз.
- Порядок проверок: аутентификация → ключ (нет/неверный → 400) → тело → доступ к чату (404).
### Readiness, таймауты и остановка — согласованные значения
| Параметр | Значение | Почему |
| --- | --- | --- |
| HAProxy `inter` / `fastinter` / `fall` / `rise` | 1 с / 0.5 с / 2 / 2 | DOWN после 2 неудачных проверок подряд, вторая — через 0.5 с |
| HAProxy `timeout check` | 1.5 с | больше `READY_DB_TIMEOUT_SECONDS` = 1 с |
| HAProxy `timeout connect`, `retries`, `option redispatch 1` | 1 с, 2, да | несостоявшееся соединение повторяется на другой реплике; запрос ещё не отправлен — безопасно и для POST |
| HAProxy `timeout server` | 10 с | > максимум запроса API: пул 3 с + `statement_timeout` 5 с |
| `resolvers` hold valid/obsolete | 2 с / 2 с | новые/исчезнувшие контейнеры попадают в LB за ≤ ~2–3 с |
| API `DRAIN_SECONDS` | 3 с | > худшее обнаружение DOWN при ответах 503 (≈ 1 + 0.5 с + задержка проверок) |
| API `GRACEFUL_TIMEOUT_SECONDS` | 10 с | дождаться запросов в обработке (≤ 8 с) |
| compose `stop_grace_period` (api) | 20 с | > 3 + 10 — SIGKILL не прилетает во время graceful stop |
| Docker healthcheck api | 3 с / timeout 2 с / retries 2 / start_period 20 с | для `depends_on` и `ops.py` (rolling update ждёт healthy) |
| Uvicorn keep-alive | 30 с | дольше, чем LB держит простаивающие соединения к серверу |
**Максимальное время обнаружения отказа балансировщиком:** graceful stop (сразу 503) и падение процесса (соединение отклонено) — до ≈ 1.5–2 с; зависшая реплика без ответа — до 1 + 1.5 + 0.5 + 1.5 = **4.5 с**. Пока реплика не помечена DOWN, запрос к ней, не сумевший соединиться за 1 с, уходит на другую. **Измерено** (`evidence/failover_series*.json`, `evidence/shutdown_timeline.txt`): DOWN через 0.96–1.41 с после SIGTERM и через 1.10–1.28 с после SIGKILL.
**Временная шкала graceful stop** (`evidence/shutdown_timeline.txt`): SIGTERM → +0.01 с readiness 503 → +1.30 с HAProxy DOWN (новые запросы больше не приходят) → +3.02 с закрыт listening-сокет → +3.12 с процесс завершён. LB выводит реплику из ротации на ~1.7 с раньше, чем она перестаёт принимать соединения, поэтому graceful stop не даёт ошибок клиенту.
**Критичные зависимости readiness:** PostgreSQL (и наличие мигрированной схемы). Redis не критичен — это кэш с обходом (circuit breaker 5 с), как в lab2. Если ни одна реплика не готова, LB сам отвечает `503` в общем JSON-формате ошибок с тем же `X-Request-Id` (`http-error`, `evidence/lb_errors.txt`). `X-Instance-Id` в таком ответе нет — контракт это допускает.
### Миграции и совместимость с работающей версией
- `migrate` выполняется **один раз** до старта реплик. Повтор — no-op (`schema_migrations`); две одновременные копии сериализуются `pg_advisory_lock` (`evidence/migrations.txt`: копия B применила 3 миграции, копия A — `nothing applied`). Реплики миграции не запускают и не готовы, пока схема не мигрирована: на пустой БД readiness = 503 `Database schema is not migrated`, после `migrate` — 200 без рестарта.
- Rolling update применяет миграции **до** замены реплик, поэтому допускаются только **расширяющие** (expand) миграции, совместимые со старой версией. `003` только добавляет таблицу. Проверено: код lab2 (старая версия) проходит smoke lab2 на схеме lab3 одновременно с репликами lab3 (`evidence/migrations.txt`).
- Ограничение: смешанный парк «lab2 + lab3» во время обновления формально совместим по схеме, но реплики lab2 не требуют и не записывают `Idempotency-Key`. Поэтому гарантия идемпотентности действует только когда все реплики уже lab3. Удаляющие/переименовывающие миграции нужно делить на expand → переключение кода → contract отдельным релизом.
### Соответствие `.env.example` и реальной конфигурации
| Переменная | Где используется |
| --- | --- |
| `APP_HOST`, `APP_PORT` | внутри контейнера Uvicorn слушает `0.0.0.0:8080`; `APP_PORT` — публикуемый порт LB `127.0.0.1:${APP_PORT}` |
| `LB_STATS_PORT` | страница состояния HAProxy `127.0.0.1:8404` (`ops.py`, тесты отказов) |
| `APP_ENV`, `APP_VERSION` | `APP_VERSION` — тег образа `messenger-api:${APP_VERSION}` (rolling update) и строка в логе старта |
| `SESSION_TTL_SECONDS`, `SHORT_SESSION_TTL_SECONDS` | TTL сессий; второй — для `api-short-ttl` (профиль `ttl`) |
| `DATABASE_URL_FILE`, `CACHE_URL_FILE` | Compose secrets `/run/secrets/database_url`, `/run/secrets/cache_url` |
| `SESSION_STORE` | `postgres` — источник истины сессий; Redis — общий кэш |
| `SESSION_CACHE_TTL_SECONDS` | TTL записи кэша и «надгробия» logout |
| `API_REPLICAS` | `deploy.replicas` сервиса `api` (2); ожидаемое число реплик в `ops.py` |
| `IDEMPOTENCY_TTL_SECONDS` | срок хранения результата ключа (≥ 86400, иначе API не стартует) |
| `DB_POOL_*`, `DB_*_TIMEOUT*` | пул (1..10 на реплику), ожидание соединения 3 с, connect 3 с, statement 5 с |
| `CACHE_TIMEOUT_SECONDS`, `CACHE_RETRY_AFTER_SECONDS` | таймаут Redis 250 мс и обход кэша на 5 с после ошибки |
| `READY_DB_TIMEOUT_SECONDS`, `DRAIN_SECONDS`, `GRACEFUL_TIMEOUT_SECONDS`, `KEEP_ALIVE_SECONDS` | readiness и остановка — таблица выше |
| `PASSWORD_HASH_CONCURRENCY` | одновременных хешей Argon2id на реплику |
`max_connections=100` у PostgreSQL ≥ (2 реплики + 1 во время rolling update) × 10 + migrate + api-short-ttl + запас.
### Инфраструктура
| Роль | Service | Версия | Health/readiness | Volume | Сеть/порт | Credentials | Лимиты |
| --- | --- | --- | --- | --- | --- | --- | --- |
| load_balancer | `lb` | `haproxy:2.8.30-alpine` | `wget /lb-health` (monitor-uri) | — (конфиг ro bind) | `backend`; **127.0.0.1:8080**, 127.0.0.1:8404 | — | 0.5 CPU / 128M |
| api × 2 | `api` | сборка `Dockerfile`, `python:3.12.7-slim-bookworm` | `/health/ready` (БД + схема + не в drain) | нет, `read_only` + tmpfs `/tmp` | `backend`, `expose 8080` (наружу нет) | secrets `database_url`, `cache_url` | 0.5 CPU / 256M |
| миграции | `migrate` | тот же Dockerfile | one-shot, exit 0 | — | `backend` | secret `database_url` | 0.5 CPU / 256M |
| postgres | `postgres` | `postgres:16.4-alpine` | `pg_isready` | `pgdata` | `backend`, наружу нет | secret `postgres_password` | 1 CPU / 512M |
| redis | `redis` | `redis:7.4.1-alpine`, user `redis` | `redis-cli ping` | нет (кэш) | `backend`, наружу нет | secret `redis_password` | 0.25 CPU / 96M |
| тест TTL | `api-short-ttl` (профиль `ttl`) | образ api | `/health/ready` | — | `backend`, не в LB, портов нет | как api | 0.5 CPU / 256M |
`container_name` нигде не задан. Секреты общие только там, где нужны: пароль PostgreSQL есть только у `postgres`, пароль Redis — у `redis`, строки подключения — у `api`/`migrate`. Bootstrap: схема создаётся сервисом `migrate` на пустом volume; повтор безопасен. Hooks: `scripts/restart.sh|.cmd` → `ops.py restart` (stop lb+api → restart postgres+redis → start api → healthy → start lb); `scripts/stop-one.sh|.cmd` → `ops.py stop-one` (одна реплика по `TARGET_INSTANCE_ID`, остаётся остановленной). Каждое действие пишется в `evidence/ops.log`.
## Доказательства критериев
**Стенд, на котором сняты приложенные результаты.** Windows 10, Ryzen 5 7500f, 32 GB RAM. PostgreSQL 16, Redis 7 и HAProxy **2.8.30**, Docker Desktop. Код приложения, миграции и **тот же `infra/haproxy/haproxy.cfg`** использованы как есть. Только `server-template` + DNS заменены на 6 статических слотов, реплики запущены как `python -m src.server` (2 процесса), CPU/RAM-лимитов нет. Compose-файл проверен `docker compose config`, конфиг HAProxy — `haproxy -c` той же версии 2.8.30, что в образе. `scripts/ops.py` прогнан против заглушки `docker`.
### Уровень 3
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/smoke.txt` |
| Контракт | `make check`, `make validate`, `docker compose config --quiet`, `haproxy -c` | все PASS / valid | `evidence/check.txt` |
| Стенд в `compose.yaml`, ≥ 2 реплики, одна точка входа, общая БД и хранилище сессий | `compose.yaml`; `python scripts/ops.py ps` | `api` × 2 без `ports`; публикуется только `lb`; одна `postgres`, один `redis` | `compose.yaml`, `evidence/stand.txt` (после `collect_evidence.py`) |
| Разные запросы одного пользователя — разными репликами без повторного входа | 20 × `GET /users/me` с одним токеном через LB | чередование двух `X-Instance-Id`, все 200 | `evidence/instances.txt` |
| Остановка любой одной реплики: ≤ 10 с, чтение/запись продолжаются, подтверждённые доступны | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` × 2 (вторая реплика после восстановления первой) + SIGKILL | PASS ×3; `failed_attempts: 0`; запись не прерывалась (первая запись после возврата hook — 3.3 с = длительность graceful hook; при SIGKILL — 0.11 с); остановлены разные реплики | `evidence/failover.txt` |
| Какой процесс реально остановлен | журнал hook | `SIGTERM nat-api-4` в прогоне 1, `SIGTERM nat-api-3` в прогоне 2 (в compose — `evidence/ops.log`: имя контейнера, IP, состояние после) | `evidence/failover.txt` |
| Повтор POST с тем же ключом не создаёт дубль, в т.ч. конкурентно и при смене реплики | smoke; `test_idempotency.py` (24 параллельных POST, Barrier); failover-тест повторяет неопределённые POST тем же ключом | 24 × 201, один `id`, ответы через **обе** реплики, в истории 1 сообщение; дублей нет ни в одном сценарии отказа | `evidence/student-tests.txt`, `evidence/failover*.txt` |
| Persistence: рестарт стенда с volumes и тем же токеном | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; PID до/после: postgres 1469→2901, redis 1479→2911, api 2846→2917 и 2866→2925, HAProxy перезапущен | `evidence/persistence.txt` |
| Миграции отдельно и согласованно | сервис `migrate`; readiness проверяет схему | реплики не мигрируют; повтор no-op; гонка двух `migrate` безопасна | `evidence/migrations.txt` |
### Уровень 4
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Health/readiness, timeouts и SIGTERM согласованы; LB исключает недоступный backend; период проверок и макс. время обнаружения | `infra/haproxy/haproxy.cfg`, `src/server.py`; замер шкалы остановки | проверки каждые 1 с (0.5 с после первой неудачи), fall 2; обнаружение ≤ 1.5–2 с (503/RST), ≤ 4.5 с (зависание). Замер: 503 на readiness через 0.01 с, DOWN через 1.30 с, приём прекращён через 3.02 с | таблица выше, `evidence/shutdown_timeline.txt`, `evidence/lb_log_sample.txt` |
| Последовательно остановить каждую реплику (восстанавливая предыдущую); RPS, ошибки, время восстановления | `failover_series.py` (4 писателя + 2 читателя, timeout клиента 2 с) | **SIGTERM:** 0 ошибок; DOWN в LB через 1.41 / 0.96 с; RPS 407 → 324 (одна реплика) → 354 после restore; p95 30–31 мс; реплика снова в ротации через 3.0 / 2.6 с после restore. **SIGKILL:** 6 / 3 оборванных запроса (502) в окне ≤ 0.21 с после kill, все записи повторены тем же ключом без дублей; DOWN через 1.28 / 1.10 с | `evidence/failover_series.json`, `evidence/failover_series_kill.json`, `evidence/failover_series.txt` |
| Общая идемпотентность параллельными запросами с одним ключом | `test_idempotency.py`, `test_storage_idempotency.py` | 24 параллельных → 1 сообщение через 2 реплики; 12 разных тел с одним ключом → один победитель, остальные 409; 16 потоков на уровне хранилища → одна вставка; сбой после вставки ключа и сообщения → ни ключа, ни сообщения, повтор успешен | `evidence/student-tests.txt` |
| CPU/RAM-лимиты; API без портов в обход LB; секреты/хранилища общие только где нужно; нет `container_name` | `compose.yaml` | лимиты у всех сервисов (api 0.5 CPU / 256M); у `api` только `expose`; `container_name` отсутствует; RSS реплики под нагрузкой 132 MB < 256M | `compose.yaml`, `evidence/load.txt` |
| Rolling update под нагрузкой | `rolling_update_load.py` → `ops.py rolling-update` (на нативном стенде — тот же алгоритм) | замена 2 реплик за 11.8 с, **0 ошибок**, RPS 388 → 381 во время → 385 после, p95 31 → 34 мс; после — только новые реплики; 5709 подтверждённых сообщений на месте, дублей нет | `evidence/rolling_update.json`, `evidence/rolling_update.txt` |
| Миграции однократно и совместимы с работающей версией | сервис `migrate`; код lab2 на схеме lab3 | см. раздел «Миграции»; ограничение смешанного парка описано | `evidence/migrations.txt` |
| Возможности lab2 сохранены | `run_all.py` (47 тестов + race), `test_expiry` на экземпляре с TTL 2 с | все PASS (1 skip — expiry в общем прогоне, запускается отдельно и проходит) | `evidence/student-tests.txt` |
## Эксперименты и отказы
**Гипотеза.** Если всё состояние, от которого зависит корректность (данные, сессии, ключи идемпотентности), лежит в общем PostgreSQL, а LB активно проверяет готовность и реплика по SIGTERM сначала выходит из ротации, то: (1) graceful-остановка любой реплики и rolling update проходят без ошибок для клиента; (2) падение реплики даёт только кратковременные ошибки запросов, которые были в обработке, и клиент безопасно повторяет их с тем же ключом; (3) дублей и потерь подтверждённых сообщений нет. Подтверждено измерениями ниже.
**Методика.** Генератор `student-tests/loadgen.py`: 4 писателя (POST с `Idempotency-Key`; при обрыве, timeout или 5xx — повтор с тем же ключом и телом до 201) и 2 читателя (история, `/users/me`); timeout клиента 2 с; опрос страницы HAProxy каждые 100 мс. Каждый раунд: 5 с прогрева → действие → 15 с без реплики → restore → 3 с. После раунда — полный обход истории и сверка со всеми подтверждёнными ответами. Стенд — см. «Доказательства»: клиент на той же машине, без лимитов. Повторов для статистики нет: разброс RPS между раундами ±5–8 %.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| SIGTERM реплики 1 под нагрузкой | 0 ошибок, LB выводит до остановки | 0 ошибок; DOWN через 1.41 с; реплика отвечала ещё 1.34 с (до DOWN) | hook 3.3 с; RPS 407 → 324 → 354; возврат в ротацию 3.0 с после restore; потерь нет |
| SIGTERM реплики 2 | то же | 0 ошибок; DOWN через 0.96 с | hook 3.4 с; RPS 393 → 304 → 348; возврат 2.6 с; потерь нет |
| SIGKILL реплики 1 | ошибки только у запросов в обработке, повтор без дублей | 6 × 502 в окне 0.21 с, 4 повтора записи тем же ключом; DOWN через 1.28 с | новые запросы успешны сразу (redispatch); возврат 2.8 с; дублей нет |
| SIGKILL реплики 2 | то же | 3 × 502 в окне 0.14 с, 1 повтор записи; DOWN через 1.10 с | возврат 2.7 с; дублей нет |
| Публичный failover (×2 graceful, ×1 kill) | PASS, ≤ 10 с | PASS; 0 failed attempts | первая запись после hook: 3.3 с / 3.4 с / 0.11 с |
| Rolling update 2 реплик под нагрузкой | 0 ошибок, после — только новые | 0 ошибок; `[api1,api2] → [api1,api2,api3] → [api2,api3] → … → [api3,api4]` | 11.8 с; RPS не просел (388 / 381 / 385) |
| Рестарт API + PostgreSQL + Redis + LB | данные и сессия сохраняются | PASS, тот же токен | потерь нет |
| Все реплики недоступны | LB отвечает 503 в формате контракта | JSON 503 с `request_id` = `X-Request-Id` | — |
**Нагрузка** (`tests/load.py`, closed-loop POST, без retry): 30 с, concurrency 8 → 10 955 успешных, 0 ошибок, **364 RPS**, p50 19.9 мс, p95 42.8 мс, p99 53.4 мс (только успешные); набор данных — один чат, ~11 тыс. новых сообщений. RSS каждой реплики 132 MB, 14 потоков. Во время отказа одной реплики RPS падает примерно на 20 %: при 2 vCPU на машину одна реплика (один процесс Uvicorn) упирается в CPU. Это пропускная способность HTTP-подтверждений в данном профиле, а не максимум системы; с лимитами 0.5 CPU на реплику в Docker цифры будут ниже.
## Ограничения и следующие шаги
- **Отказы, которые выдерживаются:** остановка или падение любой одной API-реплики, rolling update реплик, рестарт всего стенда с volumes. **Не выдерживаются:** отказ `lb`, `postgres` (единственная копия, без репликации) и Docker-host — это SPOF. Отказ `redis` не влияет на корректность (обход кэша, как в lab2).
- При падении (SIGKILL) запросы, которые реплика обрабатывала в этот момент, завершаются ошибкой 502. LB не повторяет уже отправленные POST — по контракту это делает клиент с тем же `Idempotency-Key`. Для `POST /users` и `POST /chats` повтор после неопределённого результата может создать второй объект (контракт этого не запрещает и прозрачных повторов не требует).
- HAProxy держит до 6 слотов реплик (`server-template api 1-6`). Больше — поменять число в конфиге.
- Страница состояния HAProxy на 127.0.0.1:8404 без аутентификации, только чтение и только localhost.
- Приложенные результаты сняты на нативном эквиваленте стенда (см. «Доказательства»), без CPU/RAM-лимитов и без Docker DNS. Перед защитой их нужно повторить `python scripts/collect_evidence.py` на Docker; конкретные цифры на ноутбуке будут другими.
- Время обнаружения на Docker дополнительно включает DNS-синхронизацию (до ~2 с на появление новой реплики в LB). На отказ это не влияет: остановленную реплику исключают активные проверки раньше, чем DNS.
- Идемпотентность гарантирована, только когда все реплики — lab3 (см. «Миграции»).
- HTTP без TLS — допустимо только на локальном учебном стенде. Пароль Redis передаётся `redis-server` аргументом внутри контейнера (как в lab2).
## Вопросы защиты — кратко
- **Отказ процесса vs отказ узла.** Процесс (контейнер реплики) падает, остальные реплики на том же host живы, общие PostgreSQL/Redis/LB целы — это и проверяет лаба. При отказе узла пропадает всё, что на нём: здесь это весь стенд, включая LB и единственную БД. Защита от него — несколько host, репликация БД, LB с переносом адреса (трек 2 уровня 5, не заявлен).
- **Почему depends_on/healthcheck — не балансировщик.** `depends_on` управляет только порядком старта, а Docker healthcheck лишь меняет статус контейнера. Ни один из них не перенаправляет трафик и не выводит больную реплику из ротации. Это делает LB своими проверками (здесь — HAProxy `http-check` каждые 1 с).
- **Какие POST можно повторять после timeout.** Только те, что защищены ключом идемпотентности: здесь `POST /chats/{id}/messages` с тем же `Idempotency-Key` и тем же телом. Ключ защищает от дубля, если ответ потерялся после COMMIT: повтор вернёт исходное сообщение, а не создаст второе. `POST /users`, `POST /chats`, `POST /auth/sessions` после неопределённого результата повторять «вслепую» нельзя — создастся новый объект или новая сессия.
- **Сессии в локальной памяти при росте числа реплик.** Токен, выданный репликой A, неизвестен реплике B: каждый второй запрос получит 401, logout на одной реплике не отзовёт сессию на другой, рестарт реплики разлогинит её пользователей. «Чинить» это sticky sessions — значит терять сессии при отказе реплики. Поэтому сессии лежат в общем PostgreSQL (кэш — общий Redis), а ключи идемпотентности — в общей БД.