Files
mtusi2026lab3/REPORT.md
T

103 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.
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка: **4** (трек 5 не заявлен)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, argon2-cffi, Nginx, PostgreSQL 16; документация Docker Compose и Nginx; помощь ИИ при генерации кода и текста отчёта.
## Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2.20+, `curl`, `make`, Python 3.9+ (для публичных тестов).
Версии образов закреплены: `postgres:16.4-alpine`, `nginx:1.27.3-alpine`, `python:3.12-slim` (базовый образ приложения).
```sh
cp .env.example .env
# отредактируйте .env: задайте POSTGRES_PASSWORD (не коммитить!)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождитесь готовности через LB:
until curl -fsS http://localhost:8080/health/ready >/dev/null; do sleep 1; done
make test BASE_URL=http://localhost:8080
```
Миграции выполняются one-shot сервисом `migrate` (Alembic `upgrade head`) до старта API; API ждёт `service_completed_successfully`. Повторный `up` безопасен: Alembic идемпотентен.
Безопасная остановка (сохраняет данные):
```sh
docker compose --env-file .env stop
```
Намеренное удаление учебных данных (необратимо):
```sh
docker compose --env-file .env down -v
```
## Архитектура и решения
```
Клиент → Nginx (lb:8080) → api-1 / api-2 (FastAPI, uvicorn) → PostgreSQL 16
```
- **Источник истины:** PostgreSQL. Пользователи, сессии, чаты, участники, сообщения и ключи идемпотентности хранятся в одной БД. Локального состояния в API нет — реплики взаимозаменяемы.
- **Сессии:** таблица `sessions` (SHA-256 от токена, `expires_at`). TTL задаётся `SESSION_TTL_SECONDS` (по умолчанию 3600). Переживают рестарт API и БД.
- **Идемпотентность:** таблица `idempotency_keys` с PK `(user_id, method, path, key)` и `body_hash`. Создание сообщения и запись ключа — в одной транзакции. Конкурентный повтор через разные реплики разрешается уникальным PK: проигравший получает `IntegrityError`, откатывается и читает уже сохранённый результат. Другой body при том же ключе → 409.
- **X-Instance-Id:** задаётся через env `INSTANCE_ID` (`api-1`/`api-2`), стабилен в пределах жизни процесса.
- **X-Request-Id:** генерируется middleware, если клиент не передал; возвращается во всех ответах, включая ошибки.
- **LB:** Nginx `upstream` с двумя явными backend-серверами, `max_fails=2 fail_timeout=5s`, `proxy_next_upstream error timeout http_502 http_503 http_504`, `proxy_connect_timeout 2s`. Обнаружение отказа ≤ 10 с.
- **Graceful shutdown:** uvicorn по SIGTERM перестаёт принимать новые соединения и завершает текущие; `stop_grace_period: 15s`. Nginx перенаправляет запросы на живую реплику.
- **Миграции:** one-shot сервис `migrate` (Alembic), запускается до API. Совместимы с работающей версией (только additive).
- **Лимиты:** API — 0.5 CPU / 256 MiB, PostgreSQL — 1 CPU / 512 MiB, Nginx — 0.5 CPU / 128 MiB.
- **Порты:** наружу публикуется только `lb:8080`. Порты API не публикуются.
Соответствие `.env.example`:
| Переменная | Где используется |
| --- | --- |
| `POSTGRES_PASSWORD` | compose.yaml (postgres, migrate, api-*) |
| `SESSION_TTL_SECONDS` | app/config.py |
| `IDEMPOTENCY_TTL_SECONDS` | app/config.py (зарезервировано для очистки) |
| `APP_HOST`, `APP_PORT` | app/config.py |
| `DATABASE_URL_FILE` | не используется в текущей реализации (см. ограничения) |
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/smoke.txt` |
| ≥2 API-реплики, одна точка входа | `for i in 1 2 3 4; do curl -sI http://localhost:8080/health/live \| grep X-Instance-Id; done` | чередуются `api-1` и `api-2` | `evidence/instances.txt` |
| Разные запросы одного пользователя на разных репликах | `make test` + `X-Instance-Id` в ответах | smoke проходит, `X-Instance-Id` меняется | `evidence/smoke.txt` |
| Остановка одной реплики, продолжение работы | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `PASS: failover preserved confirmed data` | `evidence/failover.txt` |
| Идемпотентность (в т.ч. конкурентная) | `make test` (LAB≥3) + параллельный повтор | повтор возвращает тот же Message, дублей нет | `evidence/smoke.txt` |
| Persistence (рестарт с сохранением volumes) | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data` | `evidence/persistence.txt` |
| Health/readiness, SIGTERM, LB исключает backend | `docker compose stop api-1` + `curl /health/ready` | 200 через api-2, api-1 исключён из upstream | `evidence/health.txt` |
| Последовательная остановка каждой реплики под нагрузкой | `make load` + `scripts/stop-one.sh` для api-1, затем api-2 | RPS/ошибки/время восстановления | `evidence/load-*.json` |
| CPU/RAM-лимиты, API не публикует порты | `docker compose config` | `deploy.resources.limits` заданы, у api-* нет `ports:` | `evidence/compose-config.txt` |
| Rolling update под нагрузкой | `docker compose up -d --no-deps api-1` при работающем `make load` | ошибок нет, RPS не падает до нуля | `evidence/rolling.txt` |
| Миграции однократно | `docker compose logs migrate` | один прогон `upgrade head`, повторный `up` не падает | `evidence/migrate.txt` |
## Эксперименты и отказы
**Гипотеза:** при остановке одной API-реплики Nginx исключает её из upstream за ≤ 10 с, а вторая реплика продолжает обслуживать чтение и запись без потери подтверждённых сообщений и без дублей при повторе с тем же `Idempotency-Key`.
**Стенд:** локальный Docker Desktop, 4 CPU / 8 GiB. Лимиты: API 0.5 CPU / 256 MiB × 2, PostgreSQL 1 CPU / 512 MiB, Nginx 0.5 CPU / 128 MiB. Версии: `postgres:16.4-alpine`, `nginx:1.27.3-alpine`, `python:3.12-slim`.
**Профиль нагрузки:** `make load` — closed-loop, 4 потока, 30 с, POST сообщений. Ограничения: клиент на Python, coordinated omission, latency только по успешным запросам.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `scripts/stop-one.sh` для `api-1` | Nginx исключает api-1, api-2 продолжает | ошибки в первые ~5 с, затем 200; `X-Instance-Id` = `api-2` | ≤ 10 с; потерь нет |
| `scripts/stop-one.sh` для `api-2` (после восстановления api-1) | симметрично | симметрично | ≤ 10 с; потерь нет |
| `scripts/restart.sh` (postgres + api-*) | данные и сессии сохранены | smoke с прежним токеном проходит | ~15 с; потерь нет |
| Rolling update `api-1` под нагрузкой | без 5xx | кратковременный рост latency, 5xx нет | ~5 с |
## Ограничения и следующие шаги
- **Выдерживается:** отказ одной API-реплики (процесса/контейнера), рестарт API и PostgreSQL с сохранением volumes.
- **Не выдерживается:** отказ узла (single-host Compose), отказ PostgreSQL (SPOF), отказ Nginx (SPOF). Для трека 2 потребовался бы Swarm/несколько узлов и репликация БД.
- **Упрощения:** `DATABASE_URL_FILE` из `.env.example` не используется — пароль передаётся через `POSTGRES_PASSWORD` в env (для локального синтетического стенда допустимо; для production нужен Docker secret). Очистка `idempotency_keys` по TTL не реализована (запись остаётся, но контракт требует хранения ≥ 24 ч — выполнено). Вложения (lab4+) не реализованы — целевая оценка 4 в рамках lab3.
- **Подтверждено:** failover одной реплики, persistence, идемпотентность (включая конкурентный повтор), rolling update без 5xx.
- **Гипотеза (не проверено):** поведение при отказе PostgreSQL и при горизонтальном масштабировании на 4+ реплик.