Files
mtusi2026lab3/REPORT.md
T

16 KiB
Raw Blame History

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

  • Автор / группа: Авзалов Артур Марсович, БПИ2301
  • Целевая оценка: 4; трек 5 не заявлен
  • Статус: локальная реализация проверена на двух Windows-компьютерах с Docker Desktop 06.11.2026; публичный API, persistence, идемпотентность, остановка обеих реплик и поочерёдное пересоздание под нагрузкой проверены.
  • Инструменты: Python 3.12, FastAPI/Pydantic, PostgreSQL 16, psycopg3 pool, Redis 7.4 с AOF, HAProxy 3.1, Docker Compose.
  • Помощь ИИ: ChatGPT использовался для генерации кода, SQL-миграций, конфигурации инфраструктуры, тестов и пояснений. Результаты ниже получены на локальном стенде и зафиксированы по фактическому выводу команд.

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

Нужны Docker Desktop (Compose v2), Python 3.9+ и make (или запуск тестов напрямую). PowerShell:

Copy-Item .env.example .env
# В .env заменить POSTGRES_PASSWORD на свой локальный случайный ASCII-пароль без URI-спецсимволов.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
make check PYTHON=python
make test PYTHON=python
python tests/idempotency_parallel.py

Все API-запросы идут только через http://localhost:8080 (HAProxy). PostgreSQL, Redis и API-реплики не публикуют портов на хост. Не коммитить .env и результаты с секретами. Безопасная остановка: docker compose --env-file .env down; без -v. Удаление учебных данных только намеренно: down -v.

Запуск миграций: одноразовый сервис migrate выполняется до старта API; версионные скрипты db/migrations/001_initial.sql и 002_idempotency.sql. Отдельная повторная проверка: docker compose --env-file .env run --rm migrate.

Проба сохранности на Windows:

python tests/resilience.py --mode persistence --action-script scripts/restart.cmd

На Linux: chmod +x scripts/*.sh, затем make test-persistence ACTION_SCRIPT=scripts/restart.sh.

Архитектура

Client localhost:8080 -> HAProxy roundrobin + readiness check (1 s interval, fall=2)
                              |                         |
                            api1                      api2
                              \                         /
                               PostgreSQL (users, chats, messages, idempotency receipts)
                               Redis AOF (session:<SHA256(bearer)> => user UUID, EX TTL)

Между API-репликами нет общих файлов и локального авторизационного состояния. API_INSTANCE_ID назначается для каждой реплики, отражается в X-Instance-Id, а X-Request-Id генерируется для каждого запроса. Basic используется только на login; пользователь и членство проверяются через Bearer + Redis + PostgreSQL. Argon2id применяется для паролей.

Тексты сообщений, названия чатов и display names — UTF-8 в PostgreSQL bytea, чтобы API поддерживал U+0000, запрещённый в PostgreSQL text/varchar. Транзакция защищает создание чата и участников. Пагинация истории — keyset по (created_at, id), индекс (chat_id, created_at, id).

Идемпотентность POST сообщений

Ключ (actor_id, chat_id, method, Idempotency-Key) уникален в PostgreSQL. Body fingerprint — SHA-256 канонического JSON с полем text; lab3 ещё не содержит вложений. В транзакции после проверки доступа вызывается pg_advisory_xact_lock(hashtextextended(scope, 0)), затем либо читается результат предыдущего сообщения, либо атомарно вставляются сообщение и receipt. Повтор возвращает тот же 201 Message, другое тело с тем же ключом — 409. Блокировка работает между процессами и освобождается с завершением транзакции.

Результаты сохраняются бессрочно: требование не менее 24 часов выполняется, но БД будет расти; политику очистки следует добавить при длительной эксплуатации. Внешний отказ после COMMIT безопасен: повтор возвращает исходное сообщение. Нет автоматических повторов POST на уровне HAProxy.

Отказы и ограничения

Остановка одной API-реплики переносится на другую. HAProxy проверяет GET /health/ready с интервалом 1 с и fall=2; в двух прогонах с остановкой api1 восстановление записи заняло 6.281 и 8.282 с. При повторной автоматической проверке на втором компьютере восстановление заняло 8.328 с; имя остановленной реплики в сохранённом выводе не указано. Все три значения меньше 10 с. При ручной остановке api2 на первом компьютере LB вернул 200 от api1; на втором компьютере первый запрос к LB получил переходный 503, после чего публичный smoke успешно прошёл через оставшуюся реплику. Мгновенное переключение или точное время восстановления для api2 не заявляются. Graceful shutdown Uvicorn ограничен 8 с, Docker stop grace period 12 с. HAProxy использует Docker DNS резолвер для смены адреса пересозданной реплики. На каждом API контейнере CPU limit 0.75 и RAM limit 384 MiB, LB 0.5/128 MiB, PG 1.0/512 MiB, Redis 0.5/256 MiB.

Остановка PostgreSQL или Redis делает обязательные операции недоступными (503); /health/live не зависит от внешних сервисов, /health/ready проверяет оба. Хранилища не реплицированы. Потеря узла Docker, LB, диска или volumes не покрыта. HTTP Basic/Bearer в локальном стенде допускается только на loopback; для удалённого доступа требуется TLS.

Миграции вынесены в отдельный one-shot сервис и координируются PG advisory lock. Текущие миграции предназначены для чистого стенда Lab3; автоматический импорт уже существующей чужой схемы/volume Lab2 не заявлен. Rolling update рассчитан на совместимость неизменной текущей схемы с обеими API-репликами; миграции с несовместимыми ALTER TABLE потребуют расширения стратегии.

Фактические проверки (Windows PowerShell + Docker Desktop, 06.11.2026)

Критерий Команда / способ Наблюдение
Подъём стенда docker compose --env-file .env up -d --build, docker compose --env-file .env ps PASS: api1, api2, lb, postgres, redis — healthy; наружу опубликован только LB на 127.0.0.1:8080
Проверка структуры make check PYTHON=python PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
Публичный API make test PYTHON=python PASS: lab3 public API scenario; также PASS после rolling update и при остановленной api2 на обоих компьютерах
Конкурентная идемпотентность python tests/idempotency_parallel.py PASS: две реплики, одно сообщение, повтор 201, изменённое тело 409
Persistence python tests/resilience.py --mode persistence --action-script scripts/restart.cmd PASS: подтверждённые данные и прежняя сессия сохранились после restart; тест требует дополнительно показать scope hook
Автоматический failover python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd PASS трижды (6.281, 8.282 и 8.328 с); на первом компьютере после тестов в docker compose ps отсутствовала api1, api2 оставалась healthy. На втором выбор остановленной реплики в логе не зафиксирован
Отказ api2 docker compose --env-file .env stop --timeout 1 api2 + curl.exe -i http://localhost:8080/health/ready + make test PYTHON=python PASS для функциональной доступности: на первом ПК 200 OK, X-Instance-Id: api1 и smoke PASS. На втором ПК первый curl вернул от HAProxy 503 No server is available, но следующий smoke PASS при остановленной api2. Срок восстановления именно для api2 не замерен
Повторное применение миграций на втором ПК docker compose --env-file .env run --rm migrate PASS: Migrations up to date
Возврат обеих реплик docker compose --env-file .env up -d --no-deps --wait api1 api2 PASS: обе реплики healthy
Rolling update под нагрузкой Фоновый 90-секундный tests/load.py + поочерёдное --force-recreate --wait api1, затем api2 PASS: нагрузка была Running до замены; обе реплики вернулись в healthy; первый ПК — 171 успешная запись, 0 ошибок; второй ПК — 168 успешных записей, 0 ошибок; оба раза job Completed

Linux persistence отдельно не прогонялся. Локальный дополнительный unit-тест tests/own_unit.py не заявляется как выполненный; публичный smoke, check и конкурентная идемпотентность проверены.

Измерения нагрузки

Сценарий Успешные запросы Ошибки RPS p50 p95 p99
Базовая нагрузка, concurrency=4, 30 с 60 0 1.863 2063 мс 2344 мс 2703 мс
90 с без подтверждённого перекрытия с update 176 0 1.914 2063 мс 2203 мс 2469 мс
Rolling update под нагрузкой, первый ПК, concurrency=4, 90 с 171 0 1.838 2063 мс 2828 мс 4047 мс
Базовая нагрузка, второй ПК, concurrency=4, 30 с 60 0 1.882 2093 мс 2125 мс 2329 мс
Rolling update, второй ПК, concurrency=4, 90 с 168 0 1.861 2094 мс 2156 мс 6172 мс

Rolling update запускался в PowerShell Start-Job; после 15 секунд тест был Running, затем по очереди выполнялось пересоздание реплик. На первом ПК api1 восстановилась за 7.6 с, api2 за 6.9 с; на втором — за 7.1 с и 7.5 с соответственно. Wait-Job оба раза вернул JSON с нулём ошибок и состоянием Completed. Эти результаты подтверждают замену контейнеров под нагрузкой, но не являются тестом обновления на новую версию кода или несовместимой схемы БД.

Фактические значения failover в автоматических прогонах:

Остановленная реплика Успешные записи Неуспешные попытки Первое восстановление записи
api1, прогон 1 8 0 6.281 с
api1, прогон 2 6 1 8.282 с
выбранная тестом реплика, второй ПК 6 1 8.328 с
api2, ручной сценарий (первый ПК) Smoke: PASS Не измерено Проверка readiness дала HTTP 200, время failover не измерялось
api2, ручной сценарий (второй ПК) Smoke: PASS Первый curl: 503 После 503 smoke прошёл; время восстановления не измерялось

На первом ПК остановку именно api2 подтвердил docker compose ps, а обработчик ответа имел X-Instance-Id: api1. На втором ПК остановка api2 подтверждена выводом docker compose stop, первый readiness-запрос вернул 503 от HAProxy, последующий smoke прошёл. Ручной сценарий не даёт количественной оценки RPS или задержки восстановления для api2.

tests/load.py использует closed-loop нагрузку без автоматических повторов: измерение включает клиентские задержки и может страдать coordinated omission. p50/p95/p99 относятся только к успешным HTTP-ответам. На обоих компьютерах медиана осталась около 2.1 с; это делает нехватку RAM первого ПК менее убедительной единственной причиной. Задержку не профилировали, узкое место не установлено.

Ограничения результатов

  • PostgreSQL, Redis и балансировщик представлены одним экземпляром; отказ всего хоста и потеря volumes не покрываются.
  • При остановке api2 проверены работоспособность и публичный smoke, но отдельное инструментальное время восстановления и RPS этой реплики не фиксировались. На втором ПК первый readiness после остановки вернул 503, поэтому непрерывную безошибочную доступность в этом сценарии не заявляем.
  • Приведены результаты двух Windows-хостов при конкретном closed-loop профиле нагрузки; Linux-испытание не проводилось.