Files
mtusi2026lab3/REPORT.md
T

126 lines
10 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.
# Отчёт — лабораторная 2
**Автор, группа:** Кашкарова Арина, БПИ2302
**Целевая оценка:** 3
**Commit/PR:** TODO
**Использованные источники, библиотеки и помощь ИИ:** Python 3.11, FastAPI, Uvicorn, Pydantic, PostgreSQL 16.1, psycopg2-binary, bcrypt, Docker, Docker Compose. ИИ использовался для генерации начального скелета кода, отладки форматирования ответов под OpenAPI контракт и настройки Docker Compose.
## Запуск из чистого clone
**Prerequisites:** Python 3.9+, Docker, Docker Compose, Git.
1. **Клонирование и подготовка окружения:**
```bash
git clone https://gitea.privcloud.tech/ari_kash/mtusi2026lab2.git
cd mtusi2026lab3
python3 -m venv .venv
source .venv/Scripts/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
2. Создание .env:
```bash
cp .env.example .env
```
3. Сборка и запуск стенда (API x2 + PostgreSQL + Nginx):
```bash
docker compose up -d --build
```
4. Ожидание готовности и проверка:
```bash
curl http://localhost:8080/health/ready
```
5. Запуск тестов:
```bash
export PYTHONUTF8=1
# Smoke test (базовый сценарий API)
python tests/smoke.py --base-url "http://localhost:8080"
# Test persistence (проверка сохранности данных после рестарта)
python tests/resilience.py --mode persistence --action-script "scripts/restart.bat" --base-url "http://localhost:8080"
# Test failover (проверка отказоустойчивости при падении одной реплики)
python tests/resilience.py --mode failover --action-script "scripts/stop-one.bat" --base-url "http://localhost:8080"
```
6. Безопасная остановка и удаление учебных данных:
```bash
# Остановка контейнеров (данные сохраняются в volume)
docker compose down
# Полное удаление включая volumes (сброс всех данных)
docker compose down -v
```
## Архитектура и решения
Схема процессов и хранилищ
Клиент → HTTP API (FastAPI) → PostgreSQL
↓
Сессии в PostgreSQL
Компоненты:
- Nginx 1.27: Единая точка входа (Load Balancer) на порту 8080. Настроен proxy_next_upstream и max_fails=2 fail_timeout=5s для быстрого исключения упавшей реплики.
- API-реплики (api-1, api-2): Два идентичных контейнера FastAPI + Uvicorn. Для различия в ответах отдают заголовок X-Instance-Id (генерируется из переменной окружения).
- PostgreSQL 16.4: Общий источник истины для всех данных, включая сессии и ключи идемпотентности.
- Named volume: pgdata:/var/lib/postgresql/data обеспечивает сохранность данных при перезапуске.
Таблицы базы данных
Схема включает 6 таблиц:
users, chats, chat_members, messages, sessions (из lab2).
idempotency_keys (новая) — хранит user_id, method, path, key, request_hash, status_code, response_body. Первичный ключ (user_id, method, path, key) защищает от одновременных дублей.
Миграции: Файлы src/migrations/001_initial.sql и src/migrations/002_idempotency.sql запускаются idempotently при старте приложения.
Идемпотентность (Lab 3):
- На POST /api/v1/chats/{chat_id}/messages теперь обязателен заголовок Idempotency-Key.
- При получении запроса API вычисляет SHA-256 хеш тела и ищет ключ в БД. Если находит и хеш совпадает — возвращает сохраненный ответ (201). Если хеш другой — возвращает 409 Conflict.
- Если ключа нет, сообщение создается атомарно вместе с записью в idempotency_keys в одной транзакции.
Балансировка и отказоустойчивость:
- Балансировщик Nginx распределяет запросы между api-1 и api-2 по алгоритму Round Robin.
- Публикация портов API наружу убрана (в compose.yaml нет ports у api-сервисов). Доступ только через Nginx (порт 8080).
- Healthcheck базы данных гарантирует, что API не начнут прием трафика, пока PostgreSQL не будет готов.
Соответствие .env.example
- POSTGRES_PASSWORD=messenger_pass — используется для подключения к БД.
- SESSION_TTL_SECONDS=3600 — читается в auth.py.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | python tests/smoke.py --base-url "http://localhost:8080" | PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.3 | screenshots/lab3_smoke_pass.png |
| Persistence test | python tests/resilience.py --mode persistence --action-script "scripts/restart.bat" --base-url "http://localhost:8080" | Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. | screenshots/lab3_persistence_pass.png |
| Failover test | python tests/resilience.py --mode failover --action-script "scripts/stop-one.bat" --base-url "http://localhost:8080" | Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 79, "failed_attempts": 2, "first_recovery_seconds": 2.812}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. | screenshots/lab3_failover_pass.png |
| Две реплики через LB | curl -i -H "Connection: close" http://localhost:8080/health/live | В ответах поочередно появляются заголовки X-Instance-Id: api-1 и X-Instance-Id: api-2 | screenshots/lab3_instances.png |
| Конкурентная идемпотентность | Отправка 10 параллельных POST с одинаковым Idempotency-Key | В БД создается только 1 сообщение, остальные получают 201 с тем же id | — |
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Отказ одной API-реплики (scripts/stop-one.bat) | Nginx исключает упавший узел, запросы продолжают обрабатываться оставшейся репликой. Сессия не теряется. | Тест прошел успешно. Из 82 попыток записи 80 успешны, 2 упали во время переключения. Система восстановилась. | 2.812 секунды до полного восстановления (Nginx перестал слать запросы на упавший контейнер). Данные не потеряны. |
| Перезапуск всего стенда (scripts/restart.bat) | Реплики и БД перезапускаются. Токен сессии остается валидным, данные не теряются благодаря volume. | После рестарта тот же Bearer-токен позволяет читать данные. Persistence-тест вернул PASS. | ~5-7 секунд на старт PostgreSQL + API. Данные сохранены. |
| Остановка PostgreSQL | API должен вернуть 503 Service Unavailable на /health/ready. | Проверено вручную: при падении БД балансировщик отсекает реплики. | Мгновенно после потери соединения. |
## Ограничения и следующие шаги
Что реализовано и работает:
✅ Стенд из двух API-реплик за балансировщиком Nginx
✅ Общая база данных PostgreSQL (сессии и идемпотентность не теряются при рестарте)
✅ Сервер генерирует заголовки X-Request-Id и X-Instance-Id во всех ответах
✅ Обязательный заголовок Idempotency-Key при отправке сообщений предотвращает создание дублей
✅ Остановка любой одной реплики не приводит к потере данных и не ломает сессию
✅ Все публичные тесты (make test, persistence, failover) проходят успешно
Ограничения:
- Стенд использует один Docker-host, поэтому отказ самого хоста или PostgreSQL не покрывается (нет репликации БД). Для оценки 3 это не требуется.
- Nginx в текущей конфигурации не использует sticky sessions, что соответствует требованиям (клиент может ходить на разные реплики).