Files
mtusi2026lab3/REPORT.md
T

163 lines
26 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-реплики
Автор: **Дугина Александра, БПИ2301**. Целевая оценка: **4**.
## Запуск из чистого clone
Нужны Docker Desktop с Compose v2, Python 3.11+ и make. На использованном Mac Python хоста — 3.13, контейнера — 3.11.16.
Все команды выполняются из **mtusi2026lab3**.
```sh
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
scripts/up.sh
export BASE_URL="http://localhost:$(sed -n 's/^PUBLIC_PORT=//p' .env)"
curl -i "$BASE_URL/health/ready"
make check
make validate PYTHON=.venv/bin/python
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
scripts/restore.sh
python3 scripts/wait-ready.py
```
`scripts/up.sh` вызывает bootstrap, `docker compose --env-file .env config --quiet`, сборку и запуск, ожидает две реплики через LB.
`bootstrap.py` создаёт случайный пароль PostgreSQL, DSN в `secrets/` и `.env`, выбирает свободный порт 8080–8099 только при отсутствии `.env`. Существующие настройки не заменяет. В текущем запуске выбран **127.0.0.1:8080**. При уже созданном `.env` и занятом порте меняют только PUBLIC_PORT своей lab3. Чужие контейнеры не останавливаются.
`secrets/`, `.env` игнорируются Git; локальные файлы создаются с umask 077. Compose secrets монтирует их только в нужные контейнеры. Redis доступен исключительно во внутренней сети и не содержит токены в открытом виде.
`scripts/compose.sh` фиксирует каталог проекта и `.env`, на macOS добавляет Docker credential helper в PATH.
Swagger UI: `http://localhost:8080/docs`; `/openapi.json` отдаёт обязательный контракт без изменения исходного файла.
Безопасная остановка: `scripts/compose.sh stop`. Повторный запуск: `scripts/up.sh`.
`restart.sh` перезапускает API, PostgreSQL, Redis и LB, не удаляет контейнеры/volumes и не меняет секреты.
Данные живут в `mtusi2026lab3_postgres_data` и `mtusi2026lab3_redis_data`; сеть — `mtusi2026lab3_default`.
Удаление учебных данных — отдельная намеренная административная операция, при выполнении работы не применялась. Обычные start/restart/down без удаления volumes данные не очищают.
## Архитектура и версии
```text
клиент → 127.0.0.1:8080 → HAProxy → api × 2 (Uvicorn/FastAPI)
├── PostgreSQL: данные, сессии, идемпотентность
└── Redis: общий кэш профилей сессий
```
| Компонент | Версия | CPU | RAM |
|---|---|---:|---:|
| API, каждая реплика | Python 3.11.16 slim-bookworm, FastAPI 0.115.12, Uvicorn 0.34.2 | 0,75 | 384 MiB |
| Мигратор | тот же образ приложения, отдельный one-shot процесс | 0,5 | 256 MiB |
| PostgreSQL | 16.8-bookworm | 1 | 512 MiB |
| Redis | 7.4.2-alpine | 0,25 | 128 MiB |
| HAProxy | 3.0.9-alpine | 0,5 | 128 MiB |
Остальные зависимости закреплены в `requirements.txt`: psycopg 3.2.6, psycopg-pool 3.2.6, redis-py 5.2.1, Argon2-cffi 23.1.0, Pydantic 2.11.4. Образы поддерживают ARM64. Docker Engine 28.0.1, Compose 2.33.1-desktop.1.
Хост: MacBookPro18,3, Apple M1 Pro ARM64, 8 CPU, 16 GiB RAM; Docker VM имеет 8 CPU и 8 218 316 800 байт RAM. Полные условия — `evidence/environment.txt`.
Перенесены собственные `src/`, SQL начальной схемы, зависимости, Dockerfile и тест авторизации из lab2 (`bd34c1050a61d92faa30468eace4e4dadea306c3`, та же рабочая ветка). Lab2 читалась, её файлы и данные не изменялись. Контракты, публичные тесты и исходный README lab3 сохранены. Добавлены балансировка, заголовок процесса, отдельный мигратор, общая идемпотентность, эксплуатационные скрипты, эксперименты. API — один Compose-service с `deploy.replicas: 2`, без `container_name`, без опубликованных портов. Публичен только LB на loopback.
HAProxy выбран за активные HTTP readiness-проверки и штатный Docker DNS resolver/server-template; это позволяет масштабировать один сервис без перечня двух фиксированных имён. Round robin распределяет HTTP-запросы без cookie/sticky session. В конфигурации десять слотов backend (поддерживаемый предел данного учебного конфига). Незаполненные слоты переходят в DNS maintenance. Логи ошибок, переходы UP/DOWN и HTTP-статусы пишутся в stdout контейнера.
## Состояние, контракт и идемпотентность
PostgreSQL — источник истины для пользователей, membership, чатов, сообщений и сессий. Пароли — Argon2id: time_cost=3, memory_cost=65536 KiB, parallelism=4. Basic используется только для выдачи случайного токена с 256 битами энтропии. В БД хранится SHA-256 токена и expiry; TTL по умолчанию 3600 секунд, рестарт его не продлевает. На каждом защищённом запросе БД проверяет expiry/revoked_at. Redis кэширует профиль пользователя по хешу токена, но не заменяет проверку сессии: отказ Redis допускает чтение профиля из PostgreSQL. Сессионное состояние не локально. Logout отзывает сессию в PostgreSQL и удаляет кэш. Redis использует AOF с appendfsync always и отдельный volume.
Доступ к чату проверяется перед операцией; посторонний получает 404. Ошибки соответствуют контракту, request_id в JSON совпадает с X-Request-Id. Каждый созданный API ответ, включая ошибки/health/204, получает X-Instance-Id (случайный UUID при импорте приложения) и X-Request-Id. ID стабилен в жизни одного Uvicorn-процесса, после рестарта меняется. LB-ошибки соединения могут не иметь этих заголовков.
Пагинация keyset по `(created_at, id)`, limit 1–100; cursor содержит область user/chat и ID последней записи, проверяется принадлежность. История читается непосредственно из PostgreSQL без устаревающего кэша. При конкурентных вставках между страницами нет snapshot: поздний COMMIT с более ранним created_at может оказаться позади уже выданного cursor. Для неизменной истории обход без повторов; это соответствует контракту. Вложения не добавлены: CreateMessage lab3 принимает только text.
`Idempotency-Key` обязателен, ASCII `[A-Za-z0-9._:-]{1,128}`. Таблица `message_requests` имеет PK `(chat_id, sender_id, key)`; HTTP-метод и тип пути фиксированы единственным POST сообщений. Записи не удаляются: защита дольше 24 часов (плата — рост таблицы).
В одной транзакции выполняются:
1. INSERT запроса с ON CONFLICT DO NOTHING.
2. Победитель создаёт сообщение и связывает результат с ключом.
3. Конкурирующий INSERT ожидает завершения транзакции победителя. Следующий SELECT в READ COMMITTED видит готовое сообщение. Одинаковый text возвращает тот же объект и 201; отличный — 409.
COMMIT атомарен для сообщения и результата. При исключении обе записи откатываются; транзиентные ошибки не закрепляются. Другие пользователи/чаты имеют независимые ключи. Аутентификация и доступ проверяются заново до повтора. Участники неизменяемы в обязательном API. Синхронная транзакция отправки вынесена в thread pool, поэтому HTTP-запросы могут реально конкурировать и внутри одного процесса. Локального словаря ключей нет.
## Готовность, отказ и остановка
`/health/live` проверяет жизнь процесса. `/health/ready` выполняет SELECT 1 в обязательной PostgreSQL; Redis не критичен благодаря fallback. Если PostgreSQL недоступен — 503 в общем формате. В `evidence/readiness.json` зафиксирован реальный эксперимент: после stop PostgreSQL у обеих API live=200 и ready=503; после stop Redis ready=200 и профиль читается через fallback. Оба хранилища затем восстановлены. Пул: 1–10 соединений на API, ожидание до 5 с, connect_timeout 5 с, statement_timeout 5 с.
HAProxy проверяет каждую реплику раз в 1 с, при изменении состояния fastinter 500 мс, fall=2, rise=2, timeout check/connect=1 с. Для отказа соединения практический бюджет обнаружения порядка 2–4 с при свободном Docker-host; это расчёт по настройкам, не гарантия при остановке всей VM. Read timeout сервера 8 с, клиента 10 с. Docker-health API — каждые 2 с, timeout 3 с, retries 3, start_period 5 с; сам Docker-health не маршрутизирует запросы. Решение о маршрутизации принимает HAProxy.
Docker DNS `127.0.0.11:53`, hold valid/obsolete/NX=1 с, resolver retry/timeout=1 с обновляет server-template. Отдельный тест реально изменил IP работающей API-реплики и подтвердил её повторную доступность через LB (`dns-change.json`). Для занятия старого IP кратковременно запускалась третья настоящая API-реплика; после теста она удалена без удаления данных. Проверка включает Docker CLI и ожидание, поэтому её 9,420 с — не чистый DNS latency.
PID 1 — Uvicorn, STOPSIGNAL SIGTERM. При сигнале сервер закрывает listener, ждёт активные запросы до 4 с; shutdown hook закрывает пул. Compose даёт 6 с до SIGKILL. После закрытия listener HAProxy исключает backend активными проверками. Полного drain перед остановкой нет: краткие ошибки допустимы и измерены. LB не делает автоматический replay POST (`retries 0`): неопределённую запись повторяет клиент с тем же ключом. `stop-one.sh` опрашивает прямой health внутри только API-контейнеров, точно сопоставляет TARGET_INSTANCE_ID и останавливает найденный контейнер; остальные компоненты не трогает. Восстановление — `scripts/restore.sh`, затем ожидание двух ID.
## Миграции и rolling update
Миграции не запускаются из API/startup и не подключены к docker-entrypoint PostgreSQL. Сервис migrate ждёт healthy PostgreSQL; API ждут `service_completed_successfully`. SQL-файлы применяются в одной транзакции под `pg_advisory_xact_lock(310026)` и записываются в `schema_migrations`. Это также сериализует случайный повторный запуск runner. Времена применения двух миграций зафиксированы; явный повтор runner вывел Already applied, таблица до/после совпала. Восстановление API не запускает зависимости. Мигратор может вызываться повторно при полном `up`, но **каждая версия схемы применяется ровно один раз**, а не каждым API.
002 — добавление таблицы без изменения старых колонок, совместимо с работающей API lab2. При демонстрационном обновлении схема не менялась; версии образов старого/нового API записаны в JSON. Для будущих несовместимых миграций этот скрипт не гарантирует rolling: нужен expand/contract, обратная совместимость либо согласованное окно обслуживания. Автоматического rollback схемы нет.
```sh
scripts/compose.sh build api
# При НОВЫХ совместимых миграциях отдельно, до замены API:
scripts/compose.sh run --rm --no-deps migrate
scripts/rolling-update.sh
# Или эксперимент сразу с 4 writers и проверкой подтверждений:
python3 student-tests/scenarios.py rolling --output evidence/rolling-update-new.json
```
Алгоритм: сохранить два исходных контейнера; проверить survivor; остановить/удалить только первый API; `up --no-deps --no-recreate --scale api=2 api` создаёт недостающий контейнер новым образом, не пересоздаёт survivor; дождаться readiness нового и наблюдения обоих ID через LB; затем заменить второй исходный. При ошибке готовности дальнейшая замена прекращается. Номера Compose-контейнеров могут увеличиваться; скрипты не зависят от суффиксов 1/2. Это поочерёдная замена Compose на одном host, не встроенный rolling deploy оркестратора, не автоматический rollback и не нулевые ошибки.
## Команды и результаты испытаний
```sh
python3 student-tests/check_auth.py
python3 student-tests/scenarios.py idempotency --output evidence/idempotency.json
python3 student-tests/scenarios.py failover --target-index 0 --duration 15 --output evidence/failover-replica-1.json
python3 student-tests/scenarios.py failover --target-index 1 --duration 15 --output evidence/failover-replica-2.json
python3 student-tests/baseline.py
python3 student-tests/scenarios.py rolling --output evidence/rolling-update.json
python3 student-tests/scenarios.py rolling --output evidence/rolling-continuity.json
python3 student-tests/dns.py
python3 student-tests/readiness.py
# Полный повтор (заменяет соответствующие evidence новыми результатами):
scripts/verify.sh
```
Публичные make check, validate, test, test-persistence и test-failover прошли. У persistence сняты sanitized StartedAt/ID всех контейнеров до/после, включая оба хранилища; токен сохранился. Собственный тест: 24 параллельных одинаковых POST обслужены обеими репликами, один Message и одна копия в истории; повтор с другим body — 409, чужой чат — 404, отозванный токен — 401, независимые user/chat scope, отсутствующий/неверный ключ — 400. Старение тестовых ключей до 25 часов не отменило повтор. Общая сессия и чтение подтверждённого сообщения наблюдались на обеих репликах.
| Эксперимент (4 writers) | Duration, с | Успешные / ошибки | Ошибки, % | Successful RPS | p50/p95/p99, мс | Восстановление, с | Потеря подтверждённых |
|---|---:|---:|---:|---:|---|---:|---:|
| Baseline, public load.py, 30 с | 30,077 | 11112 / 0 | 0 | 369,451 | 9,070 / 15,647 / 63,266 | — | не оценивается этим генератором |
| Отказ первой | 16,683 | 4803 / 366 | 7,0807 | 287,901 | 9,761 / 25,936 / 69,031 | 3,277 | 0 из 4804 |
| Отказ второй после восстановления первой | 16,741 | 4282 / 322 | 6,9939 | 255,782 | 11,185 / 28,477 / 69,385 | 2,879 | 0 из 4283 |
| Rolling новым образом | 19,218 | 4768 / 453 | 8,6765 | 248,103 | 9,335 / 51,021 / 80,478 | см. ниже | 0 из 4769 |
| Дополнительный rolling, тот же образ | 20,325 | 5064 / 270 | 5,0619 | 249,150 | 11,866 / 36,704 / 71,268 | см. ниже | 0 из 5065 |
В первом эксперименте остановлен container `7d2957677a35…`, alias `d2f38075-ad18-4b40-b025-0b6b75b5deec`; во втором — **другой исходный контейнер** `cdc714ebeb09…`, alias `0fa5e6d8-e471-4f44-992c-42c530dceb1f`. JSON хранит полные IDs и факт Running=false после hook. Первый восстановлен до второго эксперимента; после обоих снова наблюдались две реплики. Чтение полной истории выполнялось при остановленной реплике прежней сессией; подтверждены запись и доступность всех подтверждений.
Время восстановления измерено от начала action до завершения первого успешного POST, начатого **после возврата** action. Это консервативная оценка с затратами Docker CLI, обе менее 10 с. Длительность собственных сценариев включает завершение worker/сборщика ресурсов, поэтому больше запрошенного 15-секундного интервала. Успешные RPS посчитаны по этому полному интервалу. Между экспериментами данные не очищались.
Rolling новым образом: обе замены заняли 3,447 и 6,235 с; весь action (с подготовкой) 12,639 с. Поле first_success_after_action=12,666 с означает первый POST **после завершения двух замен**, а не 12-секундный простой! Дополнительный эксперимент специально измерил непрерывность: **3424 успешных запроса начаты во время action**, максимальный промежуток между успешными завершениями **1,000 с**; прежняя сессия и все 5065 подтверждений сохранены. Версии образов первого rolling действительно отличаются, повторный rolling проверяет замену контейнеров тем же образом.
Методика: synthetic POST text, closed loop, уникальные ключи, 4 потока, без прозрачного retry в измерении throughput. Для отказов 2 с до воздействия, далее нагрузка до ~15 с. Все тестовые объекты синтетические. На baseline уже были данные предшествующих проверок, размер БД в конце — `dataset.txt`. CPU/RAM сняты параллельно, интервалы нерегулярны (docker stats и Docker CLI добавляют задержку); peaks — максимум **из выборок**, не абсолютный пик. Baseline дал 9 выборок; API суммарно до 120,70% CPU / 118,69 MiB, PostgreSQL 41,47% / 53,01 MiB, HAProxy 17,39% / 13,63 MiB, Redis 4,16% / 9,33 MiB. CPU 100% означает одно ядро; API в таблице суммируются. Детали остальных экспериментов — `resources-summary.json`, raw samples — в JSON экспериментов.
Это единичные небольшие генераторы на одном ноутбуке: coordinated omission, overhead Python/клиента, latency только успешных ответов, нет определения saturation point. Предельная производительность и SLA production не заявляются. Baseline выполнялся до финального изменения Swagger; путь сообщений и транзакций тот же. Краткие 503/обрывы при остановке не скрыты; нужны retry клиента с тем же ключом и более аккуратный drain для уменьшения ошибок.
## Соответствие всем критериям уровней 3 и 4
| Уровень / требование | Проверка / реализация | Фактическое доказательство |
|---|---|---|
| 3: воспроизводимый Compose, 2+ настоящих API | up.sh, capture-state.py, CPU/port metadata | containers.json, containers.txt |
| 3: одна публичная точка, общие БД/сессии | compose.yaml, public smoke и persistence | smoke.txt, persistence.txt |
| 3: одна сессия на разных репликах | scenarios.py idempotency, me и история на двух ID | idempotency.json |
| 3: X-Instance-Id реального процесса | опрос внутри контейнера, сопоставление hook | failover-replica-1.json, failover-replica-2.json |
| 3: новые чтения/записи ≤10 с после отказа любой одной | последовательный отказ каждой, полная история до restore | оба failover-replica JSON: 3,277 / 2,879 с |
| 3: подтверждённые сообщения не потеряны | сравнение всех объектов в полной истории | оба failover-replica JSON, lost_confirmed=0 |
| 3: общая идемпотентность, включая concurrent/replay | PostgreSQL транзакция, PK; 24 запроса на обе реплики | idempotency.json |
| 3: make test | публичный контрактный сценарий | smoke.txt |
| 3: persistence и failover tests | make test-persistence, make test-failover | persistence.txt, failover-public.txt |
| 4: health/readiness, timeout, SIGTERM, исключение backend | Dockerfile, HAProxy checks, настоящие stop | оба failover JSON; lb-events.txt |
| 4: восстановление / DNS backend | restore.sh; реальная смена IP | dns-change.json, instances_after_restore в failover JSON |
| 4: отказ каждой реплики, RPS/errors/recovery | scenarios.py failover с индексами 0/1 | оба failover-replica JSON и TXT |
| 4: CPU/RAM limits, нет обхода LB и container_name | Compose + sanitized inspect | containers.json, resources-summary.json |
| 4: корректное общее состояние/секреты | PostgreSQL authority, Redis AOF, secrets mounts | persistence.txt, idempotency.json, compose.yaml |
| 4: rolling под нагрузкой, рабочий survivor | rolling-update.py, 4 writers, проверка данных | rolling-update.json, rolling-continuity.json |
| 4: согласованные однократные миграции / совместимость | one-shot migrate, advisory lock, version table | migrations-initial.txt, migrations-rerun.txt, migrations-before.txt, migrations-after.txt |
| Подготовка: структура/полная схема OpenAPI | make check / make validate | check.txt, validate.txt |
Все пути доказательств в таблице относительны `evidence/`. HTTP-тесты не заменяют анализа конфигурации миграций/лимитов: оба вида доказательств приведены вместе.