Files
mtusi2026lab3/REPORT.md
drunkdiente 3aba500a0e Реализовать стенд лабораторной 3: две API-реплики и балансировка
FastAPI + PostgreSQL как единый источник истины: пользователи, Basic/Bearer-сессии, чаты, сообщения. Сессии и идемпотентные ключи хранятся в БД, поэтому реплики взаимозаменяемы. Общая идемпотентность POST сообщения по Idempotency-Key, включая конкурентный повтор через разные реплики. compose.yaml: postgres, one-shot migrate, api1, api2 и nginx как единственная публичная точка входа. Добавлены scripts/stop-one.sh и scripts/restart.sh, student-tests, evidence и заполненный REPORT.md.
2026-11-07 16:04:29 +03:00

140 lines
19 KiB
Markdown
Raw Permalink 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 (заполнить перед PR)
- Целевая оценка: **3 — работающий минимум**. Уровень 4 и трек 5 не заявлены.
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: `contracts/openapi.json`, `contracts/README.md`, `README.md`, публичные тесты `tests/`; FastAPI 0.115.0, uvicorn 0.30.6, psycopg 3.2.3, psycopg-pool 3.3.3, PostgreSQL 16.4, Nginx 1.26.2. Реализация и текст отчёта подготовлены с помощью ИИ-ассистента Koda; все приведённые проверки выполнены и воспроизведены локально.
## Запуск из чистого clone
Проверено на: Windows 11 Pro 22621 x64, AMD Ryzen 7 7700 (8 ядер / 16 потоков), 32 GB RAM, Docker Engine 29.4.3, Docker Compose v5.1.3 (Linux containers), Python 3.10.11 для публичных тестов. Дата прогонов: 2026-11-07.
Версии зафиксированы: `python:3.12.6-slim-bookworm`, `postgres:16.4-alpine`, `nginx:1.26.2-alpine`; Python-зависимости — в `requirements.txt`.
```sh
# 1. Локальная конфигурация (значения в примере синтетические, .env не коммитится)
cp .env.example .env
# 2. Проверка и сборка/запуск всего стенда
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# 3. Ожидание готовности (миграции выполняются автоматически отдельным сервисом)
curl -fsS http://localhost:8080/health/ready
# 4. Проверки
make check
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# 5. Восстановление остановленной в failover реплики (api1 или api2)
docker compose --env-file .env start api1
docker compose --env-file .env restart lb
# 6. Штатная остановка без удаления данных
docker compose --env-file .env down
# 7. Намеренное удаление учебных данных и volumes (необратимо)
docker compose --env-file .env down -v
```
На Windows-хосте `make` не установлен, поэтому вместо целей Makefile выполнены те же команды напрямую: `python scripts/check_contract.py`, `python tests/smoke.py --base-url http://localhost:8080`, `python tests/resilience.py --mode persistence|failover --action-script ...`. Скрипты `restart.sh`/`stop-one.sh` — POSIX shell, поэтому resilience-тесты запускались в Linux-контейнере `docker:27-cli` с смонтированным репозиторием и Docker-сокетом:
```sh
docker run --rm --network mtusi-lab3_appnet \
-v "<repo>:/repo" -v /var/run/docker.sock:/var/run/docker.sock \
-w /repo -e PYTHONUTF8=1 docker:27-cli \
sh -lc "apk add --no-cache python3 >/dev/null && \
python3 tests/resilience.py --mode failover \
--action-script scripts/stop-one.sh --base-url http://lb:8080"
```
На Linux/macOS те же проверки запускаются обычными командами Makefile из блока выше.
## Архитектура и решения
```text
клиент
|
v
lb (nginx :8080) — единственный опубликованный порт
| round-robin, passive health, retry на вторую реплику
+--> api1 (uvicorn :8080, INSTANCE_ID=api-1) --+
+--> api2 (uvicorn :8080, INSTANCE_ID=api-2) --+
v
postgres:16.4 (volume pgdata)
users, chats, chat_members, messages,
sessions, idempotency_keys
```
- **Источник истины — PostgreSQL.** В API нет локальных сессий, сообщений или идемпотентных ключей. Единственное локальное состояние процесса — стабильный `X-Instance-Id` (`api-1`/`api-2`) из переменной окружения.
- **Реплики взаимозаменяемы.** `api1` и `api2` собираются из одного Dockerfile и образа, не публикуют порты наружу, имеют одинаковый `DATABASE_URL`. Клиент ходит только через `lb`.
- **Балансировщик.** Nginx upstream `api1:8080`, `api2:8080`, `max_fails=1 fail_timeout=5s`, `proxy_connect_timeout 1s`, `proxy_read_timeout 10s`. `proxy_next_upstream ... non_idempotent` повторяет POST на второй реплике; это безопасно, потому что создание сообщения идемпотентно по `Idempotency-Key`.
- **Миграции отдельно.** Сервис `migrate` запускается один раз, ждёт готовности PostgreSQL, берёт advisory lock, применяет идемпотентный `migrations/001_init.sql` и завершается с кодом 0. Реплики стартуют только после `service_completed_successfully`, поэтому гонки DDL между ними нет.
- **Graceful shutdown.** Uvicorn — PID 1, получает SIGTERM, перестаёт принимать соединения и до 5 с завершает текущие запросы (`--timeout-graceful-shutdown 5`), `stop_grace_period: 10s`. Nginx в это время повторяет запрос на живую реплику.
- **Сессии.** Basic используется только в `POST /api/v1/auth/sessions`. Токен — `secrets.token_urlsafe(48)` (384 бита), в БД хранится только SHA-256 токена и `expires_at`; TTL из `SESSION_TTL_SECONDS` (по умолчанию 3600). Перезапуск не продлевает TTL.
- **Пароли.** `hashlib.scrypt` (N=2^14, r=8, p=1, 32-байтовый digest, случайная соль), не SHA-256 и не plaintext.
- **Транзакционные границы.** Регистрация — один INSERT с уникальным `username`. Создание чата — чат и все `chat_members` в одной транзакции после проверки существования участников. Отправка сообщения — проверка членства, вставка/чтение `idempotency_keys`, вставка `messages` и запись сохранённого ответа в одной транзакции.
- **Идемпотентность.** Первичный ключ `(user_id, method, path, key)`; `INSERT ... ON CONFLICT DO NOTHING` определяет владельца, конкурентный запрос ждёт завершения транзакции владельца и читает сохранённый ответ. Хранится канонический хеш тела: другой JSON при том же ключе — `409`, тот же JSON — исходный `201` и то же сообщение. Срок хранения — `IDEMPOTENCY_TTL_SECONDS` (24 ч).
- **История.** Keyset-пагинация по `(created_at, id)` по возрастанию, `limit` 1–100 (по умолчанию 50), непрозрачный base64-cursor со scope. Cursor от другого чата/коллекции — `400`; последний элемент страницы не повторяется; `next_cursor=null`, если следующей записи нет.
- **Ошибки.** Единый конверт `{"error":{"code","message","request_id"}}`, `X-Request-Id` совпадает с телом, `X-Instance-Id` добавляется middleware ко всем ответам API, включая ошибки и health.
- **Перенос из lab2.** В этом репозитории нет кода lab2, поэтому обязательные возможности lab2 (PostgreSQL, регистрация с паролем, Basic → Bearer-сессия, миграции, сохранность) реализованы здесь же. In-memory fallback отсутствует.
Соответствие `.env.example` реальной конфигурации:
| Переменная | Где используется | Смысл |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT`, `APP_ENV` | compose | информационные параметры стенда |
| `SESSION_TTL_SECONDS` | API | TTL сессии, по умолчанию 3600 |
| `IDEMPOTENCY_TTL_SECONDS` | API | срок хранения результата, по умолчанию 86400 |
| `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` | compose → `DATABASE_URL` | общая БД; пароль в примере синтетический |
| `DATABASE_URL` / `DATABASE_URL_FILE` | API, migrate | альтернативные способы передать строку подключения |
| `API_REPLICAS` | документация | фактическое число реплик задано сервисами `api1`/`api2` |
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Офлайн-структура и контракт | `python scripts/check_contract.py` (эквивалент `make check`) | `PASS: offline skeleton structure...` | `evidence/check.txt` |
| Compose-стенд описан и валиден | `docker compose --env-file .env config --quiet` | код 0, ошибок нет | вывод в отчёте, `compose.yaml` |
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` (эквивалент `make test`) | `PASS: lab3 public API scenario` | `evidence/smoke-final.txt`, `evidence/smoke.txt` |
| ≥2 API-реплики, одна точка входа, общая БД | `docker compose ps`; 10 запросов `/health/live` | `api1`/`api2` healthy; опубликован только `lb` 8080; `postgres` healthy | `evidence/instances.txt`, `evidence/final-ps.txt` |
| Одна сессия обслуживается разными репликами без повторного входа | `python student-tests/session_across_replicas.py` | 12 запросов с одним Bearer: `api-1, api-2, api-1, api-2, ...` | `evidence/session-across-replicas.txt` |
| Остановка одной реплики: чтение/запись продолжаются | failover-тест, цель `api-1` | 85 успешных записей, 0 ошибок, первое восстановление 0.558 с (в повторных прогонах 0.65–1.43 с); `api1` — `Exited (0)`, `api2` работает | `evidence/failover-final.txt`, `evidence/failover-final-ps.txt` |
| Остановка второй реплики | failover-тест, цель `api-2` | 90 успешных записей, 0 ошибок, восстановление 0.546 с; `api2` — `Exited (0)`, `api1` работает | `evidence/failover-final-2.txt`, `evidence/failover-final-2-ps.txt` |
| Подтверждённые сообщения доступны после отказа, дублей нет | тот же failover-тест | тест читает всю историю, проверяет исходное сообщение, все подтверждённые записи и уникальность текстов | `evidence/failover-final.txt` |
| Последовательный повтор `Idempotency-Key` | публичный smoke | повтор возвращает то же сообщение; другой body — `409`; без ключа — `400` | `evidence/smoke-final.txt` |
| Конкурентный повтор через разные реплики | `python student-tests/concurrent_idempotency.py` | 40 одновременных POST с одним ключом: реплики `api-1` и `api-2`, ровно 1 сообщение, другой body — `409` | `evidence/concurrent-idempotency.txt` |
| Сохранность данных и сессии после перезапуска | persistence-тест + `scripts/restart.sh` | `PASS`; прежний токен и данные доступны без повторного входа; в БД после всех прогонов 40 пользователей, 13 чатов, 4171 сообщение, 37 сессий | `evidence/persistence-final.txt`, `evidence/db-counts.txt` |
| Hook действительно перезапустил хранилища | `docker inspect` до/после `scripts/restart.sh` | у `postgres`, `api1`, `api2`, `lb` изменился `State.StartedAt` | `evidence/restart-scope.txt` |
| Health/readiness | `curl /health/ready` | `{"status":"ok"}`; readiness проверяет `SELECT 1` к PostgreSQL | `evidence/instances.txt` |
| Миграции не гоняются репликами | `docker compose ps -a` | `migrate` завершился `Exited (0)` до старта API | `evidence/failover-final-ps.txt` |
| Версии образов/зависимостей зафиксированы | `Dockerfile`, `compose.yaml`, `requirements.txt` | явные теги/пины, без `latest` | файлы репозитория |
| Нагрузочный профиль (дополнительно) | `python tests/load.py --duration 15 --concurrency 4` | 3722 успешных запроса, 0 ошибок, 247.6 RPS, p50/p95/p99 = 16/32/46 мс | `evidence/load.txt`, `evidence/load.json` |
## Эксперименты и отказы
Условия: один Docker-host, сервисные лимиты `api` 1 CPU / 256 MB, `postgres` 1 CPU / 512 MB, `lb` 0.5 CPU / 128 MB. Все запросы идут через `http://localhost:8080` (nginx). Данные синтетические.
| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `stop api1` во время 15-секундной серии POST | Записи продолжаются через `api2`, подтверждённые сообщения не теряются | 85 успешных записей, 0 неудачных попыток; `api1` остановлен (`Exited (0)`), `api2` healthy | первое восстановление 0.558 с; потерь и дублей нет |
| `stop api2` во время такой же серии | То же через `api1` | 90 успешных записей, 0 неудачных; `api2` остановлен, `api1` healthy | 0.546 с; потерь и дублей нет |
| 40 одновременных POST с одним `Idempotency-Key` | Ровно одно сообщение, одинаковые ответы | Оба экземпляра обслужили запросы, все ответы совпали, в истории 1 копия; другой body — `409` | потерь нет |
| `scripts/restart.sh`: рестарт PostgreSQL, api1, api2, lb | Данные, сессии и схема сохраняются | Persistence-тест `PASS`; у всех четырёх контейнеров новый `StartedAt` | сессия и сообщения доступны без повторного входа |
| Пересборка образа и `up -d --build` | Сессии/сообщения не зависят от жизни процесса | Smoke после пересборки `PASS`; в PostgreSQL сохранились 40 пользователей, 13 чатов, 4171 сообщение и 37 сессий | потерь нет |
Нагрузочный прогон: 15 с, concurrency 4, closed-loop генератор `tests/load.py` без автоматических retry. Получено 3722 успешных POST, 0 ошибок, 247.6 успешных RPS, p50 16 мс, p95 32 мс, p99 46 мс. Это throughput HTTP-подтверждений через LB, а не точный счётчик COMMIT; генератор ограничен клиентом, страдает coordinated omission, а latency посчитана только по успешным запросам. CPU/RAM контейнеров в этом прогоне не сэмплировались, поэтому цифры не заявляются как saturation point.
## Ограничения и следующие шаги
- Стенд работает на одном Docker-host. Потеря узла, а также отказ единственных PostgreSQL и nginx не выдерживаются: они остаются SPOF. Проверен только отказ одного API-процесса.
- Nginx разрешает имена `api1`/`api2` при старте. После восстановления остановленной реплики надёжный способ вернуть её в балансировку — `docker compose start apiN` и `docker compose restart lb`; в проверенных прогонах Docker переиспользовал IP, но на это не следует опираться. Следующий шаг — динамический resolver/`resolve` в upstream.
- После восстановления реплика возвращается в балансировку не мгновенно: если первый запрос к ней попал в момент старта, nginx держит её вне пула до `fail_timeout=5s`. Это наблюдалось один раз сразу после `restart lb`; в рабочий период оба экземпляра получают запросы. Поэтому `student-tests/session_across_replicas.py` сначала ждёт появления обоих экземпляров, а затем проверяет одну сессию.
- Сессии и идемпотентные ключи хранятся в PostgreSQL; Redis/Valkey не используется. Это соответствует контракту lab3, но увеличивает нагрузку на БД.
- Просроченные идемпотентные ключи удаляются лениво — при повторном использовании ключа; фоновой очистки нет.
- Не реализованы TLS, rate limiting, вложения, фоновая обработка, телеметрия — это следующие лабораторные, для оценки 3 они не требуются.
- Уровень 4 (поочерёдная остановка всех реплик с метриками RPS/ошибок, rolling update под нагрузкой, CPU/RAM-лимиты как проверяемый критерий) и трек 5 не заявляются. Лимиты ресурсов в compose заданы, но измерение saturation и сравнение 1/2/4 реплик не проводилось.
- На Windows-хосте отсутствует `make`, поэтому публичные цели запускались эквивалентными командами; на Linux/macOS команды Makefile применимы без изменений.