Files
mtusi2026lab2/REPORT.md
T
2026-11-13 21:16:52 +03:00

100 lines
12 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.
# Отчёт — лабораторная 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/` этого задания; сторонний код в рамках этой работы не добавлялся. Ответственность за понимание и защиту реализации остаётся за автором.