Files
mtusi2026lab3-fork/REPORT.md
T

154 lines
9.8 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.
# Отчёт — лабораторная 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 допустим только на локальном учебном стенде с синтетическими данными.