Files
mtusi2026lab3/REPORT.md
T
ejur22 c60c78b51e Исправить обход отзыва сессии при сбое Valkey
resolve() больше не доверяет кэшу: валидность сессии всегда проверяется в PostgreSQL, поэтому неудавшаяся инвалидация при недоступном Valkey не воскрешает отозванный токен. Valkey остаётся read-through кэшем неизменяемого профиля. Добавлены scripts/check-revocation.py и student-tests/test_session_revocation.py.
2026-10-23 19:46:34 +03:00

131 lines
18 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
- Автор, группа: Журавский, БВТ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, поэтому ошибок нет.