forked from mtusi2026/mtusi2026lab2
100 lines
12 KiB
Markdown
100 lines
12 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: не указаны.
|
||
- Целевая оценка: 5.
|
||
- Трек 5: трек 1 — согласованность Redis-кэша при конкурентном заполнении (single-flight).
|
||
- Commit/PR: заполнить после публикации.
|
||
- Стек: Python 3.12.8 в Docker-образе; FastAPI, psycopg 3 connection pool, redis-py, argon2-cffi/Argon2id; PostgreSQL 16.6 и Redis 7.4.2.
|
||
|
||
## Реализовано
|
||
|
||
Перенесён функциональный минимум lab1: регистрация и профиль пользователя, создание/список/чтение чатов, сообщения и keyset-пагинация. Переход аутентификации соответствует COURSE.md: регистрация требует пароль, Basic используется только для создания сессии, защищённые запросы используют Bearer, `X-User-Id` не задаёт личность пользователя.
|
||
|
||
PostgreSQL является источником истины для пользователей, чатов, участников, сообщений и сессий. Пароли хранятся как Argon2id-хеши; в базе хранится SHA-256 отпечаток случайного Bearer-токена. Redis используется как TTL-кэш профиля сессии, но expiry и отзыв проверяются по PostgreSQL на каждом запросе. При отказе Redis используется PostgreSQL; отказ PostgreSQL приводит к ограниченному 503.
|
||
|
||
Миграция `app/migrations/001_initial.sql` задаёт таблицы, ключи, ограничения и индексы. `app/migrate.py` применяет версии в транзакции и не применяет повторно уже записанные версии. Создание чата с участниками атомарно. История сообщений запрашивается keyset-страницами по `(created_at, id)`. Пул подключений и сетевые/SQL-таймауты ограничены.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker Compose v2 и OpenSSL. Из корня репозитория:
|
||
|
||
```sh
|
||
umask 077
|
||
mkdir -p secrets
|
||
openssl rand -hex 32 > secrets/database_password
|
||
chmod 600 secrets/database_password
|
||
docker compose config --quiet
|
||
docker compose up -d --build
|
||
curl --fail http://localhost:8080/health/ready
|
||
make check
|
||
make test
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
Для проверок уровня 4 и трека 5:
|
||
|
||
```sh
|
||
make test-grade4
|
||
make test-rollback
|
||
make explain-history
|
||
SESSION_TTL_SECONDS=2 docker compose up -d --force-recreate api
|
||
make test-expiry
|
||
SESSION_TTL_SECONDS=3600 docker compose up -d --force-recreate api
|
||
make test-track5-cache
|
||
```
|
||
|
||
`docker compose down` останавливает стенд без удаления данных. `docker compose down -v` удаляет volumes и предназначена только для осознанного сброса учебных данных.
|
||
|
||
## Проверки и результаты
|
||
|
||
Основной локальный прогон на Compose зафиксирован в [evidence/local-validation.txt](./evidence/local-validation.txt): 2026-11-10 прошли `make check`, `make validate`, `make test`, полный перезапуск через `scripts/restart.sh`, проверки уровня 4, rollback, короткий TTL и `make explain-history`. Данные тестов синтетические.
|
||
|
||
Дополнительно в текущей проверке документации повторно выполнены:
|
||
|
||
```text
|
||
make check PASS
|
||
make validate PASS
|
||
```
|
||
|
||
Для трека 5 на отдельном Compose-проекте выполнен A/B-эксперимент с реальными PostgreSQL и Redis. `make check`, `make validate`, `make test`, `make test-grade4`, `make test-track5-cache`, проверка синтаксиса теста и `git diff --check` прошли. Прежние результаты расширенных проверок уровня 4 ниже относятся к зафиксированному прогону 2026-11-10.
|
||
|
||
| Проверка | Зафиксированный результат |
|
||
| --- | --- |
|
||
| Публичный сценарий и сохранность после перезапуска API/хранилищ | PASS; данные и действующий токен доступны после restart hook без удаления volumes |
|
||
| Неверный пароль, logout, конкурентная регистрация | PASS |
|
||
| Отказ Redis / PostgreSQL | PASS; при Redis fallback на PostgreSQL, при отказе PostgreSQL ограниченный 503, после восстановления сервис работает |
|
||
| Короткий срок жизни сессии | PASS с `SESSION_TTL_SECONDS=2`; просроченный токен получает 401 |
|
||
| Атомарность создания чата | PASS; внедрённая ошибка при добавлении участника не оставила частичный чат |
|
||
| План истории на 10 000 синтетических сообщениях | `Index Scan using messages_history_keyset`, 51 строка, 3 shared buffer hits, 0.034 ms execution; fixture откатан |
|
||
| Трек 5, Redis cache stampede | 5 повторений A/B, по 120 параллельных чтений на режим; PostgreSQL profile SELECT снизились с 11–28 до 5 на прогон. Read-after-write и чтение после рестарта Redis прошли |
|
||
|
||
План запроса уровня 4 — один локальный замер, не нагрузочный тест и не оценка производительности в production.
|
||
|
||
## Трек 5 — согласованность кэша
|
||
|
||
**Гипотеза.** При одновременном cache miss нескольких запросов одной сессии выполняются повторные запросы профиля к PostgreSQL. Redis lock на заполнение кэша должен свести эти профильные SELECT к одному на волну, не меняя ответы API. PostgreSQL остаётся источником истины для expiry/revocation и проверяется на каждом защищённом запросе.
|
||
|
||
**Защита.** При промахе кэша один запрос получает per-session Redis lock с TTL 10 секунд, читает профиль из БД и заполняет кэш. Остальные ждут появления значения не более двух секунд и затем, если кэш не появился, безопасно переходят на PostgreSQL. Lock освобождается compare-and-delete Lua-скриптом, чтобы не удалить lock другого владельца после истечения TTL. Redis недоступен — запрос продолжает работать через PostgreSQL. Переключатель `SESSION_CACHE_SINGLEFLIGHT=0` используется только как baseline эксперимента.
|
||
|
||
**Методика.** `make test-track5-cache` запускает A/B-проверку на уже поднятом Compose-стенде. Для каждого режима API пересоздаётся с включённым/выключенным single-flight. В каждой из пяти волн удаляется профильный cache key, затем 24 потока одновременно вызывают `GET /api/v1/users/me` с одной сессией. A/B-условия повторены пять раз, по 120 запросов на прогон и режим. Число профильных SQL определяется по структурированным событиям `session_profile_db_load`, связанным с уникальными `X-Request-Id`; latency p50/p95 измеряет тестовый клиент. Дополнительно тест удаляет кэш только что созданного пользователя и проверяет чтение профиля из PostgreSQL (read-after-write), перезапускает Redis и проверяет повторное чтение с существующей сессией.
|
||
|
||
Стенд: macOS 27.0 arm64, Docker Engine с 12 CPU и 7.65 GiB памяти, Docker CLI 29.1.3, Compose 2.40.3; API на `python:3.12.8-slim-bookworm`, PostgreSQL 16.6-alpine, Redis 7.4.2-alpine. Отдельный проект и порт 18080; пул БД 10, TTL сессии 3600 секунд; явные CPU quota и прогрев не задавались.
|
||
|
||
| Прогон | Baseline: профильные SELECT / p50 / p95 | Single-flight: профильные SELECT / p50 / p95 |
|
||
| --- | --- | --- |
|
||
| 1 | 20 / 26.99 ms / 36.13 ms | 5 / 25.19 ms / 41.86 ms |
|
||
| 2 | 25 / 26.71 ms / 37.68 ms | 5 / 27.41 ms / 47.37 ms |
|
||
| 3 | 28 / 27.97 ms / 38.43 ms | 5 / 25.73 ms / 43.15 ms |
|
||
| 4 | 17 / 26.21 ms / 42.12 ms | 5 / 27.60 ms / 44.98 ms |
|
||
| 5 | 11 / 26.88 ms / 37.64 ms | 5 / 27.66 ms / 43.63 ms |
|
||
|
||
В среднем профильные запросы снизились с 20.2 до 5 на 120 вызовов (на 75.2%). Медиана пяти p50 составила 26.88 ms baseline и 27.41 ms с защитой; медиана p95 — 37.68 ms и 43.63 ms соответственно. Эксперимент подтверждает сокращение SQL fan-out, но не ускорение ответа: p95 с lock/wait в этих измерениях выше. Read-after-write через PostgreSQL: PASS. Доступ к профилю и авторизация после каждого из пяти рестартов Redis: PASS. Полные методика, окружение и ограничения сохранены в [evidence/cache-track5.txt](./evidence/cache-track5.txt).
|
||
|
||
## Ограничения
|
||
|
||
Стенд single-node и не проверяет отказ Docker-host, HA базы данных или Redis. Измерение синтетическое, с одним API и одной сессией; лог-счётчик фиксирует попытку профильного SELECT непосредственно перед SQL, а не серверную статистику `pg_stat_statements`. Каждый защищённый запрос по-прежнему выполняет запрос проверки сессии в PostgreSQL. Ограничение ожидания lock может допустить несколько fallback SQL-запросов при медленном заполнении; это сознательный компромисс доступности. Latency на коротких сериях чувствительна к шуму стенда, и p95 не улучшилась. Для публикации PR необходимо вписать имя/группу автора и ссылку на PR/commit.
|
||
|
||
## Источники
|
||
|
||
Нормативные требования и API-контракт взяты из `COURSE.md`, `README.md` и файлов `contracts/` этого задания; сторонний код в рамках этой работы не добавлялся. Ответственность за понимание и защиту реализации остаётся за автором.
|