# Отчёт — лабораторная 3 - Автор, группа: Гадяцкий Л. Е., БПИ2302 - Целевая оценка: 3 - Commit/PR: solution/BPI2302-Gadiatskiy - Использованные источники и библиотеки: - контракт и семантика: `contracts/openapi.json`, `contracts/README.md`, `README.md`, `COURSE.md` - перенос из lab2: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, формат ошибок - runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0 - PostgreSQL: `postgres:16-alpine`; LB: `nginx:1.27-alpine` - Помощь ИИ использована при переносе lab2, частично при настройке Compose+Nginx и при написании отчёта. Результаты подтверждаются сохранёнными запусками. ## Запуск из чистого clone **Prerequisites:** Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (`make check` / `make test` / `tests/resilience.py`). Runtime приложения — внутри образа. **Версии:** - API: базовый образ `python:3.12.8-slim-bookworm` → локальный `mtusi-messenger:lab3` - PostgreSQL: `postgres:16-alpine` - Nginx: `nginx:1.27-alpine` - зависимости: `requirements.txt` **Конфигурация:** секретов в Git нет. Локальный `.env` создаётся из примера и не коммитится: ```sh cp .env.example .env ``` Соответствие `.env.example`: - `APP_HOST` / `APP_PORT` — bind uvicorn внутри контейнеров API - `HOST_PORT` — порт LB на host (по умолчанию 8080; если занят — например 8081) - `APP_ENV` — среда запуска (`lab`) - `SESSION_TTL_SECONDS` — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300) - `SESSION_STORE=postgres` — сессии в PostgreSQL (общие для всех реплик) - `DATABASE_URL` — строка подключения API/migrate к PostgreSQL в compose-сети (приложение также поддерживает `DATABASE_URL_FILE`) - `IDEMPOTENCY_TTL_SECONDS` — срок хранения идемпотентных записей (по умолчанию 86400) - `API_REPLICAS=2` — в `compose.yaml` зафиксированы сервисы `api1` и `api2` Учебные credentials compose (`messenger` / `messenger`) только для локального синтетического стенда. **Сборка и запуск:** ```sh docker compose --env-file .env up -d --build ``` Миграции `migrations/*.sql` применяет one-shot сервис `migrate` до старта `api1`/`api2` (учёт в `schema_migrations`). Реплики API миграции при старте не выполняют. Готовность через LB (подставьте свой `HOST_PORT`): ```sh curl -i http://127.0.0.1:8080/health/ready ``` Ожидается HTTP 200, тело `{"status":"ok"}`, заголовки `X-Request-Id` и `X-Instance-Id` (`api1` или `api2`). **Публичный smoke** (при уже запущенном стенде): ```sh python tests/smoke.py --base-url http://127.0.0.1:8080 # или: make test BASE_URL=http://127.0.0.1:8080 ``` **Проверка сохранности:** ```sh # Unix: chmod +x scripts/restart.sh python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080 # Windows: python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080 ``` Hook выполняет `docker compose --env-file .env restart` для `postgres`, `api1`, `api2`, `lb` **без** удаления volumes (`down -v` не используется). **Проверка отказа одной API-реплики:** ```sh # Unix: chmod +x scripts/stop-one.sh python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080 # Windows: python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080 ``` `TARGET_INSTANCE_ID` = `X-Instance-Id` (`api1`/`api2`); hook делает `docker compose stop` только этой реплики и оставляет её остановленной. После теста: `docker compose --env-file .env start api1` (или `api2`). Для защиты повторить на второй реплике после восстановления первой. Локальная проверка автора выполнялась на `HOST_PORT=8082` (host-порты 8080/8081 были заняты другими контейнерами). **Остановка:** ```sh docker compose --env-file .env down ``` Намеренное удаление учебных данных (volumes): ```sh docker compose --env-file .env down -v ``` ## Архитектура и решения ``` HTTP-клиент → lb (Nginx) → api1 / api2 (uvicorn + FastAPI) → PostgreSQL users, chats, chat_members, messages, sessions, idempotency_records ``` - Источник истины — PostgreSQL. Локального состояния, от которого зависит корректность, в API нет. - Сессии в PostgreSQL: один Bearer работает через любую реплику без sticky sessions. - `X-Instance-Id` стабилен на жизнь процесса (`INSTANCE_ID` сервиса). - `Idempotency-Key` обязателен на `POST .../messages`; область: пользователь + метод + путь + ключ; запись результата атомарна с сообщением; другой body при том же ключе → 409; TTL 24ч. - ORM-модели: `src/messenger/tables.py`. Доступ к данным: `src/messenger/store.py`. - Миграции: SQL в `migrations/` + one-shot `migrate`; Alembic не используется. - Порты API наружу не публикуются; публичная точка входа — LB (`infra/nginx.conf`: `least_conn`, `max_fails=1`, `proxy_next_upstream`). - Compose: `lb` + `api1` + `api2` + `postgres` + `migrate`, volume `pgdata`; `.env` в Git не коммитится. Перенесено из lab2: auth Basic→Bearer, Argon2id, чаты/сообщения, keyset-пагинация, формат ошибок. Добавлено в lab3: Nginx LB, две реплики API, `X-Instance-Id`, общая идемпотентность, отдельный migrate, `scripts/stop-one`. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Публичный smoke (lab2 + Idempotency-Key / X-Instance-Id) | `python tests/smoke.py --base-url http://127.0.0.1:8082` | `PASS: lab3 public API scenario...` | `evidence/smoke.txt` | | Стенд: ≥2 API, один LB, общая БД и сессии | `docker compose --env-file .env ps` | `lb`, `api1`, `api2`, `postgres`; migrate Exited 0 | `evidence/compose-ps.txt` | | Разные реплики через LB с одной сессией | серия запросов через LB | `api1` и `api2` | `evidence/instances.txt` | | Persistence: рестарт без удаления volumes, прежний токен | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8082` | `PASS: persistence preserved...` | `evidence/restart.txt` | | Failover: остановка одной API-реплики | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8082` | 2 instance до отказа; first_recovery ≈2.75 с; без дублей | `evidence/failover.txt` | | Идемпотентность POST сообщений | smoke replay + failover retries | тот же ключ → то же Message; другой body → 409 | `evidence/smoke.txt`, `evidence/failover.txt` | ## Эксперименты и отказы Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены сохранность и отказ API-реплики: | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | `docker compose --env-file .env restart` (postgres+api1+api2+lb), volumes сохранены | `/health/ready` ok; прежний Bearer читает те же данные; сессия действует | persistence PASS | в бюджете теста (hook ≤90 с, ready ≤90 с); потери данных нет | | `docker compose stop` одной API-реплики | LB обслуживает живую; записи ≤10 с; без дублей по retry | failover PASS; `first_recovery_seconds≈2.75` | подтверждённые сообщения на месте | Аппаратный профиль: локальный Docker Desktop на Windows; 2 API + Nginx + PostgreSQL без CPU/RAM limits. ## Ограничения и следующие шаги - Redis/Valkey, CPU/RAM limits, rolling update под нагрузкой и трек 5 не выполнялись. - Единственный PostgreSQL и единственный Nginx — SPOF; отказ host/узла не выдерживается. - Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.