diff --git a/REPORT.md b/REPORT.md index c2679005..f1129306 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,125 @@ -# Отчёт — лабораторная 3 +# Отчёт — лабораторная 2 +**Автор, группа:** Кашкарова Арина, БПИ2302 +**Целевая оценка:** 3 +**Commit/PR:** TODO +**Использованные источники, библиотеки и помощь ИИ:** Python 3.11, FastAPI, Uvicorn, Pydantic, PostgreSQL 16.1, psycopg2-binary, bcrypt, Docker, Docker Compose. ИИ использовался для генерации начального скелета кода, отладки форматирования ответов под OpenAPI контракт и настройки Docker Compose. -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO ## Запуск из чистого clone +**Prerequisites:** Python 3.9+, Docker, Docker Compose, Git. -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +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 + ``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Схема процессов и хранилищ +Клиент → 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 | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный 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 | — | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Отказ одной 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) проходят успешно -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Ограничения: +- Стенд использует один Docker-host, поэтому отказ самого хоста или PostgreSQL не покрывается (нет репликации БД). Для оценки 3 это не требуется. +- Nginx в текущей конфигурации не использует sticky sessions, что соответствует требованиям (клиент может ходить на разные реплики). diff --git a/screenshots/lab3_failover_pass.png b/screenshots/lab3_failover_pass.png new file mode 100644 index 00000000..ab235c70 Binary files /dev/null and b/screenshots/lab3_failover_pass.png differ diff --git a/screenshots/lab3_instances.png b/screenshots/lab3_instances.png new file mode 100644 index 00000000..2865fbb5 Binary files /dev/null and b/screenshots/lab3_instances.png differ diff --git a/screenshots/lab3_persistence_pass.png b/screenshots/lab3_persistence_pass.png new file mode 100644 index 00000000..cf109986 Binary files /dev/null and b/screenshots/lab3_persistence_pass.png differ diff --git a/screenshots/lab3_smoke_pass.png b/screenshots/lab3_smoke_pass.png new file mode 100644 index 00000000..e5dcac12 Binary files /dev/null and b/screenshots/lab3_smoke_pass.png differ