forked from mtusi2026/mtusi2026lab3
resolve() больше не доверяет кэшу: валидность сессии всегда проверяется в PostgreSQL, поэтому неудавшаяся инвалидация при недоступном Valkey не воскрешает отозванный токен. Valkey остаётся read-through кэшем неизменяемого профиля. Добавлены scripts/check-revocation.py и student-tests/test_session_revocation.py.
131 lines
18 KiB
Markdown
131 lines
18 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Журавский, БВТ2301
|
||
- Целевая оценка; выбранный трек 5, если нужен: **4** (уровень 3 + уровень 4); трек 5 не заявлен
|
||
- Commit/PR: TODO после публикации (ветка `solution/БВТ2301-Журавский`)
|
||
- Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.6, Pydantic 2.10.6, Uvicorn 0.34.0, psycopg 3.2.3 + psycopg-pool 3.2.4, argon2-cffi 23.1.0, redis-py 5.2.1 (клиент Valkey), nginx 1.27.4, PostgreSQL 16.6, Valkey 8.0.2, Docker Compose v2.27.1. Документация nginx (`upstream`, `resolve`, `proxy_next_upstream`), PostgreSQL (`pg_advisory_xact_lock`, `EXPLAIN`), RFC 7617. Помощь ИИ: генерация каркаса и текста отчёта, проверено запуском тестов.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
**Версии и prerequisites**
|
||
|
||
| Компонент | Версия / образ |
|
||
| --- | --- |
|
||
| Runtime | Python 3.11.9 |
|
||
| API-образ | `python:3.11.9-slim-bookworm`, свой `Dockerfile`, тег `messenger-api:lab3` |
|
||
| Балансировщик | `nginx:1.27.4-alpine` (встроенный Docker DNS `resolve`) |
|
||
| PostgreSQL | `postgres:16.6-bookworm` |
|
||
| Valkey | `valkey/valkey:8.0.2-alpine` |
|
||
| Docker / Compose | 26.1.4 / v2.27.1 |
|
||
| Python-зависимости | `requirements.txt` (пины: fastapi, pydantic, uvicorn, psycopg[binary], psycopg-pool, argon2-cffi, redis) |
|
||
| Стенд | Windows 10 Pro 10.0.19045, Ryzen 5 3600 (6C/12T), 15.9 GiB RAM; публичные хуки `restart.sh`/`stop-one.sh` выполняются в WSL Ubuntu (Python 3.12) |
|
||
|
||
Prerequisites: Docker с Linux-контейнерами и плагином Compose. Публичный smoke и `make check` работают везде; на «родном» Windows для `make check` нужен `PYTHONUTF8=1` (иначе Python читает UTF-8 JSON в кодировке cp1251). Хуки persistence/failover — POSIX-скрипты, их нужно запускать в WSL/Git Bash либо Linux-раннере.
|
||
|
||
**Создание локальных secrets (не коммитятся)**
|
||
|
||
```sh
|
||
sh scripts/gen-secrets.sh
|
||
# создаёт ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url
|
||
```
|
||
|
||
**Запуск, миграции, проверка, остановка**
|
||
|
||
```sh
|
||
docker compose --env-file .env config --quiet # 1. валидация конфигурации
|
||
docker compose --env-file .env up -d --build # 2. сборка и запуск lb + api x2 + postgres + valkey
|
||
docker compose ps # 3. все healthy, api портов наружу не публикует
|
||
|
||
# Миграции выполняет одноразовый сервис `migrate` до старта реплик (advisory-lock, идемпотентно):
|
||
docker compose exec -T api python -m src.migrate # -> "migrations up to date"
|
||
|
||
python tests/smoke.py --base-url http://localhost:8080 # 4. публичный smoke
|
||
.venv\Scripts\python -m pytest student-tests -v # свои тесты (36 passed)
|
||
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # выполнять в WSL/Linux
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # одна реплика остаётся остановленной
|
||
sh scripts/restore-api.sh # вернуть остановленную реплику
|
||
sh scripts/rolling-update.sh # поочерёдная замена под нагрузкой
|
||
python scripts/check-revocation.py # отзыв сессии при недоступном Valkey
|
||
|
||
# Безопасная остановка (данные сохраняются):
|
||
docker compose stop
|
||
# Намеренное удаление учебных данных (тома):
|
||
docker compose down -v
|
||
```
|
||
|
||
Оператору нужно: сгенерировать secrets, выполнить шаги 1–4. Обычная остановка/`down` (без `-v`) сохраняет данные PostgreSQL и Valkey; `down -v` удаляет их.
|
||
|
||
## Архитектура и решения
|
||
|
||
**Схема:** `клиент → nginx (LB, единственный публичный порт 127.0.0.1:8080) → api × 2 (FastAPI/Uvicorn) → PostgreSQL (источник истины) + Valkey (кэш сессий)`.
|
||
|
||
- **Единая точка входа.** Публикуется только `lb` (`127.0.0.1:8080`). Реплики `api` используют `expose: 8080` без `ports`, поэтому обойти балансировщик нельзя. Балансировка — nginx round-robin.
|
||
- **Динамический backend-list.** `upstream api_backend { zone …; server api:8080 resolve max_fails=1 fail_timeout=5s; }` + `resolver 127.0.0.11 valid=5s`. nginx перечитывает A-записи Docker DNS: добавление/остановка реплики подхватывается без reload; `proxy_next_upstream error timeout http_502/503/504` повторяет запрос на живой реплике. Максимальное время обнаружения отказа: пассивный `fail_timeout` 5 s + `valid` 5 s, замеренная первая успешная запись после старта хука — **< 1 с**.
|
||
- **X-Instance-Id.** `src/instance.py`: `INSTANCE_ID = $INSTANCE_ID` или hostname контейнера (= короткий container id). Ставится middleware на **каждый** ответ, включая ошибки и health; стабилен на время жизни процесса. Проверка в `evidence/lab3-instances.txt`: 12 запросов дают ровно два чередующихся id.
|
||
- **Общая идемпотентность.** Таблица `idempotency_keys` (PK `user_id, scope, key`, `scope = "POST /api/v1/chats/{id}/messages"`), `request_hash`, `status_code`, `response_body jsonb`, `expires_at`. `POST …/messages` требует `Idempotency-Key` `[A-Za-z0-9._:-]{1,128}` (нет/неверный — 400). Вставка сообщения и запись журнала — одна транзакция; `pg_advisory_xact_lock(hashtext(user|scope), hashtext(key))` сериализует одинаковые ключи между всеми репликами. Повтор возвращает тот же `201` и тот же Message; другой body — `409`. TTL — `IDEMPOTENCY_TTL_SECONDS` (default 86400).
|
||
- **Сессии общие, отзыв немедленный.** Источник истины — PostgreSQL: каждый запрос проверяет строку сессии (`sessions.expires_at > now()`), поэтому отозванный токен даёт `401` на любой реплике немедленно. Valkey — read-through кэш **неизменяемого профиля пользователя** (`user:{id}`, TTL 300 c), он никогда не используется для решения о доступе. Поэтому сбой инвалидации при лежащем Valkey не может «воскресить» отозванную сессию (регрессионная проверка — `scripts/check-revocation.py`). Sticky session не используются: пользователь свободно попадает на любую реплику без повторного входа.
|
||
- **Одноразовые миграции.** Отдельный сервис `migrate` (`python -m src.migrate`) под `pg_advisory_xact_lock`; реплики стартуют только после `service_completed_successfully`, гонки за схему нет.
|
||
- **Graceful shutdown.** `src/main.py` переопределяет `Server.handle_exit`: по SIGTERM/SIGINT выставляет флаг (`src/state.py`), `/health/ready` отвечает `503` (LB выводит реплику из ротации), затем Uvicorn доигрывает запросы (`timeout_graceful_shutdown=10`).
|
||
- **Ресурсы и секреты.** У всех сервисов заданы CPU/RAM-лимиты (`deploy.resources.limits`); секреты — файловые compose secrets/`*_FILE`, в образ и Git не попадают. `container_name` не задаётся, масштабирование одной Compose-service работает.
|
||
- **Надёжность БД.** Ограниченный пул (`DB_POOL_MAX`), `DB_POOL_TIMEOUT`, `statement_timeout`; все SQL параметризованы; индекс `messages(chat_id, created_at, id)` под keyset-пагинацию.
|
||
|
||
**Соответствие `.env.example`**
|
||
|
||
| Переменная | Роль в решении |
|
||
| --- | --- |
|
||
| `APP_HOST`, `APP_PORT` | адрес/порт Uvicorn; в compose `0.0.0.0:8080` |
|
||
| `APP_ENV`, `LOG_LEVEL` | метки логирования запуска |
|
||
| `SESSION_TTL_SECONDS` | срок жизни сессии (`sessions.expires_at`) и TTL кэша |
|
||
| `SESSION_STORE` | `valkey`/`redis` — включить кэш; `postgres` — без кэша |
|
||
| `IDEMPOTENCY_TTL_SECONDS` | срок хранения журнала идемпотентности (24 ч) |
|
||
| `DATABASE_URL_FILE`, `CACHE_URL_FILE` | файлы с DSN PostgreSQL и URL Valkey (compose secrets) |
|
||
| `API_REPLICAS` | число реплик `api` (`deploy.replicas`) |
|
||
| `PUBLISH_PORT` | публикуемый порт LB (по умолчанию 8080) |
|
||
| `DB_POOL_*`, `DB_STATEMENT_TIMEOUT_MS` | ограничения пула и таймауты |
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab3 public API scenario` | `evidence/lab3-smoke.txt` |
|
||
| Стенд: ≥2 реплики, LB, общая БД/сессии | `docker compose up -d --build`, `docker compose ps` | 2× `api` healthy, `lb` 127.0.0.1:8080, `postgres`, `valkey`; у `api` порты не публикуются | `evidence/lab3-compose-ps.txt` |
|
||
| Разные запросы одной сессии обслуживают разные реплики | 12× `GET /users/me` через LB | чередование `4141f552b001`/`5ac0582fa5e1` (2 реплики), один токен | `evidence/lab3-instances.txt` |
|
||
| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 122 успешных записи, 0 ошибок, восстановление **1.083 с**; `api-6 Exited` при живом `api-5` | `evidence/lab3-failover.txt` |
|
||
| Общая идемпотентность, в т.ч. конкурентная и через разные реплики | `test_idempotency.py` | повтор = тот же Message; другой body → 409; 8 параллельных запросов с одним ключом → ровно одно сообщение | `evidence/lab3-student-tests.txt` |
|
||
| Отзыв сессии не обходится при сбое Valkey | `python scripts/check-revocation.py` (pause Valkey → logout 204 → unpause → 6 c) | старый токен даёт `401` через 2 реплики и не может отправить сообщение | `evidence/lab3-revocation-fix.txt` |
|
||
| Деградация кэша без остановки API | pause Valkey, валидный `/users/me` | 5×`200`, `/health/ready` = `200` (кэш обойдён) | `evidence/lab3-valkey-degradation.txt` |
|
||
| Persistence: данные и сессия переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session` | `evidence/lab3-persistence.txt` |
|
||
| Миграции применяются однократно и повторно идемпотентно | `docker compose exec -T api python -m src.migrate` | `migrations up to date`; в `schema_migrations` 2 строки | `evidence/lab3-migrations.txt` |
|
||
| Уровень 4: health/readiness, SIGTERM, LB исключает backend | `scripts/stop-one.sh` + `/health/ready` | остановленная реплика исчезает из ответов; readiness→503 при SIGTERM; пассивные проверки nginx | `evidence/lab3-failover.txt` |
|
||
| Уровень 4: CPU/RAM-лимиты, порты API только через LB | `docker compose config`, `docker stats` | лимиты 0.75 CPU / 256M у api; `8080/tcp` без проброса | `evidence/lab3-stats.txt`, `evidence/lab3-compose-ps.txt` |
|
||
| Уровень 4: rolling update под нагрузкой | `scripts/rolling-update.sh` при непрерывном опросе LB | 400/400 запросов `200`, реплики заменены по одной | `evidence/lab3-rolling.txt` |
|
||
| Уровень 4: индекс под keyset-пагинацию (≥10 000 сообщений) | `EXPLAIN (ANALYZE, BUFFERS)` | `Bitmap Index Scan on messages_chat_created_id_idx`, 0.907 мс | `evidence/lab3-explain.txt` |
|
||
| Уровень 4: нагрузочные метрики | `tests/load.py` | 133 RPS, 0 ошибок, p50/p95/p99 = 47/141/203 мс | `evidence/lab3-load.txt` |
|
||
| Секреты вне Git | `.gitignore`, `secrets.example/`, `gen-secrets.sh` | `git status` без `.env`/`secrets/` | описание в PR |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Гипотеза: LB с динамическим backend-list маскирует отказ одной реплики, общая идемпотентность в PostgreSQL не даёт дублей при переключении реплик, а общий статус позволяет любой реплике обслуживать сессию. Методика: реальный compose-стенд, синтетические данные, хуки в WSL.
|
||
|
||
**Нагрузочный профиль:** closed-loop POST сообщений, 8 параллельных клиентов, 20 с, прогрева нет; конфигурация — один Docker-host (WSL2), api 0.75 CPU/256 MB ×2, postgres 1 CPU/512 MB.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка одной API-реплики (`stop-one.sh`, TARGET = обслужившая реплика) | записи/чтения продолжаются, без дублей, токен жив | 122 записи за 15 с, 0 ошибок, цель не в последних ответах; `api-6 Exited` | **1.083 с**; потерь нет |
|
||
| То же для второй реплики (после восстановления первой) | то же | ≈120–140 записей, 0 ошибок; `api-2 Exited` | **≈1 с**; потерь нет |
|
||
| `docker compose restart api lb postgres valkey` | данные и сессия сохранены | `PASS: persistence preserved……` | рестарт ≈ секунды; потерь нет |
|
||
| Rolling update (`rolling-update.sh`) под непрерывным опросом | замена реплик без недоступности | 400/400 `200` при поочерёдной замене | простоя нет |
|
||
| Valkey недоступен во время logout (`check-revocation.py`) | отзыв сессии не обходится, старый токен → 401 | pause → logout 204 → unpause → 6 c → 401 через обе реплики, POST отклонён | потерь нет; сессия отозвана в PostgreSQL |
|
||
| Нагрузка 133 RPS на 2 реплики | стабильная пропускная способность | 0 ошибок, p99 203 мс | n/a |
|
||
|
||
Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. `docker stats` показывает ~74 MB RSS на реплику при лимите 256 MB.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Выдерживается: отказ **процесса** одной API-реплики, рестарт API и хранилищ с volumes, потеря Valkey (кэш), конкурентные повторы с общим ключом, rolling-замена реплик под нагрузкой, некорректный ввод.
|
||
- **Не** выдерживается и не заявлено: отказ Docker-host, отказ единственного PostgreSQL и единственного LB, отказ узла БД. Multi-node/HA БД — это трек 5, он не выбран.
|
||
- Учебные упрощения: HTTP без TLS (локальный стенд lab1–6); `scripts/rolling-update.sh` — поочерёдная замена через `docker`+`compose`, эквивалент rolling update оркестратора, а не сам оркестратор; нет rate limiting.
|
||
- Подтверждено измерениями: смена обслуживающей реплики при отказе, конкуренто-безопасная идемпотентность, сохранность после рестарта, использование индекса (EXPLAIN), отсутствие публикации портов API.
|
||
- Возможное улучшение (гипотеза): при большем числе реплик и `proxy_next_upstream_tries` можно снизить долю ошибок при «жёстком» (без ожидания healthy) rolling-обновлении; в этой работе замена ожидает healthy, поэтому ошибок нет.
|