# Отчёт — лабораторная 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: ```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: ```powershell python tests/resilience.py --mode persistence --action-script scripts/restart.cmd ``` На Linux: `chmod +x scripts/*.sh`, затем `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. ## Архитектура ```text Client localhost:8080 -> HAProxy roundrobin + readiness check (1 s interval, fall=2) | | api1 api2 \ / PostgreSQL (users, chats, messages, idempotency receipts) Redis AOF (session: => 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-испытание не проводилось.