Files

113 lines
16 KiB
Markdown
Raw Permalink 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
- **Автор / группа:** Авзалов Артур Марсович, БПИ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:<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-испытание не проводилось.