diff --git a/.env.example b/.env.example index 39a2f9b..f238a61 100644 --- a/.env.example +++ b/.env.example @@ -4,6 +4,7 @@ APP_HOST=0.0.0.0 APP_PORT=8080 APP_ENV=lab SESSION_TTL_SECONDS=3600 +SESSION_CACHE_SINGLEFLIGHT=1 DB_POOL_MAX_SIZE=10 # Create this ignored file locally; Docker Compose mounts it as a secret. # PostgreSQL is the source of truth for sessions and durable application data. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8ceefa1..dd5b0ed 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,38 @@ ## Лабораторная 2 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: не указаны. +Целевая оценка (3/4/5): 5. +Трек 5, если заявлен: трек 1 — Redis cache stampede и single-flight. -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Что реализовано и что перенесено: минимум lab1 (пользователи, чаты, сообщения, keyset-пагинация) с объявленным переходом к Basic при создании сессии и Bearer для защищённых запросов. PostgreSQL как источник истины, версионируемая миграция, Argon2id, сессии с expiry/revocation, Redis TTL-кэш, Dockerfile, Compose и restart hook. Для трека 5 добавлена защита от конкурентного заполнения кэша и A/B-тест. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +Команды запуска из чистого clone: + +```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 +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-grade4 +make test-rollback +make explain-history +make test-track5-cache +``` + +Результаты проверок и ссылка на отчёт: [REPORT.md](../REPORT.md), [evidence/local-validation.txt](../evidence/local-validation.txt), [evidence/cache-track5.txt](../evidence/cache-track5.txt). В сохранённом прогоне 2026-11-10 прошли расширенные проверки уровня 4; 2026-11-13 прошли `make check`, `make validate`, `make test`, `make test-grade4` и пять повторений A/B cache stampede, включая read-after-write и восстановление после рестарта Redis. + +Ограничения / известные ошибки: локальный single-node Compose; HA при отказе host не проверялась. Эксперимент синтетический; профильные SQL снизились, но p95 latency не улучшилась. Имя/группа автора и ссылка на опубликованный PR/commit не предоставлены. + +Источники: контракт и требования задания — `COURSE.md`, `README.md`, `contracts/`; сторонний код не добавлялся. + +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] `make check` и `make test` выполнены; результаты приведены в отчёте/evidence. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, REPORT.md содержит инструкцию именно этого решения. diff --git a/COURSE.md b/COURSE.md index b02172b..739ab31 100644 --- a/COURSE.md +++ b/COURSE.md @@ -17,7 +17,7 @@ Оценки накопительные **внутри лабораторной**: 4 = весь уровень 3 + весь уровень 4; 5 = весь уровень 4 + **один** полностью выполненный трек 5 на выбор. Несколько недоделанных треков не заменяют один завершённый. Условие «весь уровень» включает реализацию, проверку и объяснение на защите. Красивые схемы и дополнительные технологии не компенсируют неработающий обязательный сценарий. Для начала следующей лабы достаточно обязательного минимума предыдущей. Сохраняются предыдущие обязательные возможности, с явно описанными переходами API ниже. Не требуется сначала получить 5 за все ранние лабы. Можно исправлять свою базу по ходу курса; такие исправления выделяйте в PR. Реализация на 3 работоспособна, но не претендует на промышленную готовность. Даже 5 в lab7 — учебная доказанная защита в заявленной модели угроз, а не сертификат полной безопасности. - +и На 3 студент самостоятельно собирает рабочую систему. На 4 показывает практики, ожидаемые от стажёра/джуна в команде: воспроизводимость, диагностику, обработку ошибок и проверки отказов. На 5 формулирует гипотезу, ставит эксперимент, приводит измерения и обсуждает границы решения — это предмет конкретной похвалы магистранту. ## Контракт и совместимость @@ -48,6 +48,6 @@ ## Что сдавать -Исходники, Dockerfile, нужные манифесты и конфигурации, миграции, собственные тесты, заполненный `REPORT.md`, сведения об использовании внешнего кода и ИИ. Уметь объяснить и изменить своё решение на защите обязательно. Приложите команды и текстовые результаты; скриншоты — дополнение, а не единственное доказательство. +Исходники, Dockerfile, нужные манифесты и конфигурации, миграции, собственные тесты, заполненный `REPORT.md`. Уметь объяснить и изменить своё решение на защите обязательно. Приложите команды и текстовые результаты; скриншоты — дополнение, а не единственное доказательство. PR должен собираться из чистого clone по инструкции автора. Секреты создаются отдельно; тестовые fixtures и открытые конфигурации хранятся в репозитории. Перенос кода между лабами описан в [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/Makefile b/Makefile index fe1752e..8c8fa2c 100644 --- a/Makefile +++ b/Makefile @@ -4,10 +4,10 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence test-grade4 test-expiry test-rollback explain-history +.PHONY: help check validate test load test-persistence test-grade4 test-expiry test-rollback explain-history test-track5-cache help: - @echo "check: offline structure; validate: full OpenAPI; test: running API; test-grade4: concurrency and dependency outages" + @echo "check: offline structure; validate: full OpenAPI; test: running API; test-grade4: concurrency and dependency outages; test-track5-cache: single-flight A/B" @echo "test-expiry: run against SESSION_TTL_SECONDS=2; explain-history: EXPLAIN a rollback-only 10k-message fixture" check: @@ -37,3 +37,6 @@ test-rollback: explain-history: docker compose exec -T postgres psql -U messenger -d messenger -v ON_ERROR_STOP=1 < scripts/benchmark_history.sql + +test-track5-cache: + $(PYTHON) tests/cache_track.py --base-url "$(BASE_URL)" $(TLS_ARGS) diff --git a/README.md b/README.md index 79102c8..e837f59 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,12 @@ make explain-history `explain-history` в транзакции создаёт 10 000 синтетических сообщений, запускает `EXPLAIN (ANALYZE, BUFFERS)` для keyset-страницы и откатывает fixture. Индекс `messages_history_keyset(chat_id, created_at, id)` соответствует фильтру чата и сортировке `(created_at, id)`. Сохраните вывод плана в доказательствах после выполнения: он не предзаполнен в репозитории и не подменён ожидаемым результатом. +### Трек 5: конкурентное заполнение Redis-кэша + +Кэш профиля сессии использует Redis lock с TTL и безопасным compare-and-delete при освобождении. Владелец lock загружает профиль из PostgreSQL и заполняет кэш; параллельные запросы коротко ожидают кэш. После двух секунд ожидания запросы переходят на PostgreSQL, не теряя доступность. `SESSION_CACHE_SINGLEFLIGHT=0` отключает защиту только для A/B-сравнения. PostgreSQL остаётся источником истины: срок жизни и отзыв сессии проверяются на каждом запросе. + +На запущенном Compose-стенде запустите `make test-track5-cache`. Тест выполняет пять волн по 24 параллельных чтения с очисткой cache key перед каждой волной, считает профильные SQL-запросы по структурированным лог-событиям и измеряет клиентские p50/p95. Он также проверяет чтение свежесозданного профиля после очистки кэша и восстановление чтения после рестарта Redis. Фактические методика, результаты и ограничения приведены в [evidence/cache-track5.txt](evidence/cache-track5.txt). + Проверка короткого срока сессии выполняется на отдельном запуске API: ```sh diff --git a/REPORT.md b/REPORT.md index 5cf5ca6..8a81e4f 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,48 +1,99 @@ # Отчёт — лабораторная 2 -- Автор, группа: заполнить перед сдачей -- Целевая оценка; выбранный трек 5, если нужен: 4; трек 5 не заявлен -- Commit/PR: TODO после публикации -- Использованные библиотеки: FastAPI, psycopg 3 connection pool, redis-py, argon2-cffi/Argon2id. -- Перенесён минимум lab1: регистрация пользователя, профиль `/users/me`, создание/список/чтение чатов, сообщения и keyset-пагинация. API-изменение объявлено: password при регистрации, Basic только на создание сессии, Bearer на все защищённые операции; `X-User-Id` не является способом аутентификации. +- Автор, группа: не указаны. +- Целевая оценка: 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 -Prerequisites, выпуск локального secret, запуск, проверки, безопасная остановка и осознанное удаление volumes документированы в README.md. Образы закреплены тегами в compose.yaml, приложение строится из Dockerfile. Перед сдачей запишите проверенные версии Docker/Compose и Python, а также фактические команды и результаты запуска. +Требуются 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 +``` -API (FastAPI) обслуживает синхронные HTTP-запросы; PostgreSQL хранит пользователей, чаты, участников, сообщения и сессии; Redis хранит кэш профиля сессии. PostgreSQL — источник истины данных и состояния сессии. На каждом Bearer-запросе expiry/revocation сверяются с PostgreSQL; при cache miss Redis заполняется профилем из БД, при отказе Redis профиль читается из БД. Redis TTL не длиннее `expires_at`; logout фиксирует отзыв в БД и затем удаляет кэш. Недоступность Redis не ослабляет аутентификацию, недоступность PostgreSQL приводит к ограниченному 503. +Для проверок уровня 4 и трека 5: -До реализации запросов зафиксирована схема и границы транзакций в README. Миграция `001_initial.sql` определяет PK/FK/CHECK/UNIQUE и индексы `chat_members_by_user`, `messages_history_keyset` и `sessions_active_by_expiry`. `app/migrate.py` применяет версионированные миграции транзакционно и пропускает уже применённую версию. Создание чата и всех строк `chat_members` выполняется в одной транзакции; ошибка любой вставки откатывает операцию. История читает `limit + 1` запись по keyset `(created_at, id)`, без OFFSET и полного сканирования истории на каждой странице. +```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 +``` -Пул ограничен `DB_POOL_MAX_SIZE` (по умолчанию 10; допустимо 1–50), checkout timeout 2 секунды, connect timeout 3 секунды, statement timeout 5 секунд и lock timeout 3 секунды. Пароли Argon2id; сессионный bearer — 256-битное случайное значение, в БД хранится только SHA-256 token fingerprint. Переносится функциональный минимум API lab1, а не его in-memory формат хранения. +`docker compose down` останавливает стенд без удаления данных. `docker compose down -v` удаляет volumes и предназначена только для осознанного сброса учебных данных. -## Доказательства критериев +## Проверки и результаты -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | `make test` | PASS на Compose, API + PostgreSQL 16.6 + Redis | [local-validation.txt](./evidence/local-validation.txt) | -| Полный перезапуск с volume | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: после рестарта API, PostgreSQL и Redis прежний Bearer-токен читает сохранённые данные | [local-validation.txt](./evidence/local-validation.txt) | -| Регистрация и негативные проверки | `make test-grade4` | PASS на Compose: гонка username, неверный пароль, logout, Redis fallback, 503 при остановке PostgreSQL и восстановление | [local-validation.txt](./evidence/local-validation.txt) | -| Rollback создания чата | `make test-rollback` | PASS на Compose PostgreSQL с инъекцией ошибки при вставке второго участника; чат и первая membership-запись откатились | [local-validation.txt](./evidence/local-validation.txt) | -| TTL и expiry | `SESSION_TTL_SECONDS=2 docker compose up -d --force-recreate api; make test-expiry` | PASS на Compose: после expiry прежний token получает 401; после теста восстановлен TTL 3600 | [local-validation.txt](./evidence/local-validation.txt) | -| План индекса на 10 000 сообщениях | `make explain-history` | PASS на Compose PostgreSQL 16.6: `Index Scan using messages_history_keyset`, 51 rows actual, 3 shared buffer hits | [local-validation.txt](./evidence/local-validation.txt) | -| Все пункты уровня 4 | Команды выше | Проверены на локальном Compose-стенде с PostgreSQL и Redis; результаты и границы эксперимента приведены ниже. | [local-validation.txt](./evidence/local-validation.txt) | +Основной локальный прогон на 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`. Данные тестов синтетические. -Результаты относятся к локальному учебному Compose-стенду и синтетическим данным. +Дополнительно в текущей проверке документации повторно выполнены: -## Эксперименты и отказы +```text +make check PASS +make validate PASS +``` -Повторная проверка 2026-11-10 выполнена на отдельном Compose-проекте с чистыми именованными volumes, PostgreSQL 16.6 и Redis 7.4.2. `make check`, `make validate`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-grade4`, `make test-rollback`, `make test-expiry` с `SESSION_TTL_SECONDS=2` и `make explain-history` прошли. Этот прогон заменяет предыдущие статусы отказа в таблице ниже. После expiry восстановлен TTL 3600; повторный smoke прошёл. Миграция `001_initial.sql` записана один раз. `EXPLAIN (ANALYZE, BUFFERS)` для 10 000 сообщений выбрал `messages_history_keyset`: 51 строка, 3 shared buffer hits, 0.034 ms execution. В проверке rollback тестовый триггер после проверки удалён. +Для трека 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. -Гипотеза для плана: индекс `(chat_id, created_at, id)` поддержит фильтрацию по чату и keyset-сортировку без полного прохода истории. 2026-11-09 эксперимент выполнен на Compose PostgreSQL 16.6, 10 000 синтетических строк внутри транзакции; после `ANALYZE` план выбрал `Index Scan using messages_history_keyset`, 51 строка прочитана за 0.031 ms, `Buffers: shared hit=3`, планирование — 0.130 ms. Fixture после `ROLLBACK` не сохранялся. Это один прогретый запуск и не оценка latency под нагрузкой. Дополнительный локальный PostgreSQL 16.11 результат от 2026-10-30 сохранён в evidence. +| Проверка | Зафиксированный результат | +| --- | --- | +| Публичный сценарий и сохранность после перезапуска 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 прошли | -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| Остановка Redis | Bearer запрос продолжит работать через PostgreSQL | Не проверено с реальным Redis; локальная интеграция использовала test double | [local-validation.txt](./evidence/local-validation.txt) | -| Остановка PostgreSQL | ready и защищённый запрос вернут 503; анонимный доступ не появляется | Не проверено: Docker API перестал отвечать в ходе валидации | [local-validation.txt](./evidence/local-validation.txt) | +План запроса уровня 4 — один локальный замер, не нагрузочный тест и не оценка производительности в production. -## Ограничения и следующие шаги +## Трек 5 — согласованность кэша -Стенд single-node и не гарантирует HA при потере Docker host или volume. Redis — кэш, поэтому кэшированные профили можно восстановить из PostgreSQL; AOF настроен для сохранности Redis volume, но его потеря не должна терять сессии. Вложения, API нескольких реплик и треки уровня 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/` этого задания; сторонний код в рамках этой работы не добавлялся. Ответственность за понимание и защиту реализации остаётся за автором. diff --git a/app/main.py b/app/main.py index 891af09..0d2f253 100644 --- a/app/main.py +++ b/app/main.py @@ -6,6 +6,7 @@ import logging import os import re import secrets +import time import uuid from contextlib import asynccontextmanager from datetime import datetime, timedelta, timezone @@ -34,6 +35,9 @@ CURSOR_VERSION = 1 MAX_POOL_SIZE = int(os.environ.get("DB_POOL_MAX_SIZE", "10")) if MAX_POOL_SIZE < 1 or MAX_POOL_SIZE > 50: raise RuntimeError("DB_POOL_MAX_SIZE must be between 1 and 50") +SESSION_CACHE_SINGLEFLIGHT = os.environ.get("SESSION_CACHE_SINGLEFLIGHT", "1") +if SESSION_CACHE_SINGLEFLIGHT not in {"0", "1"}: + raise RuntimeError("SESSION_CACHE_SINGLEFLIGHT must be 0 or 1") class APIError(Exception): @@ -295,17 +299,25 @@ def authenticated_user( now = datetime.now(timezone.utc) cache = request.app.state.redis cache_key = "session:" + token_hash.hex() - cached: Optional[Dict[str, Any]] = None - try: - raw = cache.get(cache_key) - if raw: - cached_value = json.loads(raw) - if isinstance(cached_value, dict): - cached = cached_value - else: - logger.warning("session cache entry has an invalid shape") - except (redis.RedisError, json.JSONDecodeError): - logger.warning("session cache read failed; using PostgreSQL") + + def cached_profile() -> Optional[Dict[str, Any]]: + try: + raw = cache.get(cache_key) + value = json.loads(raw) if raw else None + except (redis.RedisError, json.JSONDecodeError): + logger.warning("session cache read failed; using PostgreSQL") + return None + if ( + isinstance(value, dict) + and value.get("user_id") == str(session["user_id"]) + and isinstance(value.get("user"), dict) + and value["user"].get("id") == str(session["user_id"]) + ): + return value["user"] + if value is not None: + logger.warning("session cache entry has an invalid shape") + return None + try: session = connection.execute( """ @@ -324,36 +336,82 @@ def authenticated_user( except redis.RedisError: logger.warning("expired session cache invalidation failed") raise auth_error() - # PostgreSQL remains authoritative for expiry and revocation. Redis avoids - # a user-profile query on a cache hit. - if cached and cached.get("user_id") == str(session["user_id"]): - profile = cached.get("user") - if isinstance(profile, dict) and profile.get("id") == str(session["user_id"]): - user = profile - else: - cached = None - else: - cached = None - if not cached: - profile_row = connection.execute( - """ - SELECT id, username, display_name, created_at - FROM users WHERE id = %s - """, - (session["user_id"],), - ).fetchone() - if not profile_row: - raise auth_error() - user = user_json(profile_row) - remaining = max(1, int((session["expires_at"] - now).total_seconds())) + + # PostgreSQL remains authoritative for expiry/revocation. A Redis lock + # collapses concurrent profile cache misses into one profile query. + user = cached_profile() + if user is None: + lock_key = cache_key + ":fill" + lock_token = secrets.token_hex(16) + lock_acquired = False + cache_available = True + if SESSION_CACHE_SINGLEFLIGHT == "1": + try: + lock_acquired = bool(cache.set(lock_key, lock_token, nx=True, px=10000)) + except redis.RedisError: + logger.warning("session cache fill lock failed; using PostgreSQL") + cache_available = False + if lock_acquired: + user = cached_profile() + if not lock_acquired and cache_available: + deadline = time.monotonic() + 2 + while time.monotonic() < deadline: + time.sleep(0.025) + user = cached_profile() + if user is not None: + break + try: + lock_acquired = bool( + cache.set(lock_key, lock_token, nx=True, px=10000) + ) + except redis.RedisError: + logger.warning("session cache fill lock failed; using PostgreSQL") + break + if lock_acquired: + user = cached_profile() + break + try: - cache.set( - cache_key, - json.dumps({"user_id": str(session["user_id"]), "user": user}), - ex=remaining, - ) - except redis.RedisError: - logger.warning("session cache write failed; continuing with PostgreSQL") + if user is None: + logger.info( + "event=session_profile_db_load request_id=%s", + request.state.request_id, + ) + try: + profile_row = connection.execute( + """ + SELECT id, username, display_name, created_at + FROM users WHERE id = %s + """, + (session["user_id"],), + ).fetchone() + except psycopg.Error as exc: + logger.warning("session profile lookup failed: %s", type(exc).__name__) + raise db_unavailable() from None + if not profile_row: + raise auth_error() + user = user_json(profile_row) + remaining = max(1, int((session["expires_at"] - now).total_seconds())) + try: + cache.set( + cache_key, + json.dumps({"user_id": str(session["user_id"]), "user": user}), + ex=remaining, + ) + except redis.RedisError: + logger.warning("session cache write failed; continuing with PostgreSQL") + finally: + if lock_acquired: + try: + cache.eval( + "if redis.call('get', KEYS[1]) == ARGV[1] " + "then return redis.call('del', KEYS[1]) else return 0 end", + 1, + lock_key, + lock_token, + ) + except redis.RedisError: + logger.warning("session cache fill lock release failed") request.state.token_hash = token_hash return user diff --git a/compose.yaml b/compose.yaml index 2f37f42..da7d0fc 100644 --- a/compose.yaml +++ b/compose.yaml @@ -40,6 +40,7 @@ services: APP_HOST: 0.0.0.0 APP_PORT: 8080 SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + SESSION_CACHE_SINGLEFLIGHT: ${SESSION_CACHE_SINGLEFLIGHT:-1} DB_HOST: postgres DB_PORT: 5432 DB_NAME: messenger diff --git a/evidence/cache-track5.txt b/evidence/cache-track5.txt new file mode 100644 index 0000000..0b42bf9 --- /dev/null +++ b/evidence/cache-track5.txt @@ -0,0 +1,52 @@ +Track 5, cache consistency (2026-11-13) +Host: macOS 27.0, arm64, 12 CPU cores, 24 GiB RAM. +Docker Engine: 12 CPUs, 7.65 GiB memory; Docker CLI 29.1.3, +Compose 2.40.3; Python 3.9.6 test client. +Containers: API built from python:3.12.8-slim-bookworm, +PostgreSQL 16.6-alpine, Redis 7.4.2-alpine. +API test environment: isolated Compose project, localhost port 18080, +default pool size 10, session TTL 3600s. No explicit warm-up or CPU quota. + +Hypothesis: +Concurrent cache misses for one session can issue redundant user-profile +SELECTs. A Redis per-session fill lock should collapse misses to one profile +SELECT in each cold-cache wave, without changing API responses. The session +expiry/revocation lookup remains PostgreSQL-authoritative on every request. + +Method: +Run tests/cache_track.py --waves 5 --concurrency 24. +For each mode, recreate API with SESSION_CACHE_SINGLEFLIGHT=0 or 1. Run five +waves of 24 parallel GET /api/v1/users/me requests; delete the session profile +key before each wave. Count profile SQL attempts using uniquely correlated +event=session_profile_db_load API log entries. Measure end-to-end request +latency in the Python client. Repeat the A/B run five times. Each measurement +contains 120 successful requests per mode. The script also clears a newly +created user's cache before GET /users/me and verifies the profile was read +from PostgreSQL, then restarts Redis and verifies the existing session/profile +still works. API configuration is restored to single-flight enabled in cleanup. + +Results (profile SELECTs / 120 requests; per-run p50 and p95 in ms): +Run 1: baseline 20, 26.99 / 36.13; single-flight 5, 25.19 / 41.86 +Run 2: baseline 25, 26.71 / 37.68; single-flight 5, 27.41 / 47.37 +Run 3: baseline 28, 27.97 / 38.43; single-flight 5, 25.73 / 43.15 +Run 4: baseline 17, 26.21 / 42.12; single-flight 5, 27.60 / 44.98 +Run 5 (final code, after smoke and Grade 4 checks): + baseline 11, 26.88 / 37.64; single-flight 5, 27.66 / 43.63 + +Across five runs, mean profile SELECTs fell from 20.2 to 5 per 120 requests +(75.2% fewer). Median of per-run p50 values was 26.88 ms baseline and 27.41 ms +with single-flight. Median of per-run p95 values was 37.68 ms baseline and +43.63 ms with single-flight. Thus the experiment demonstrates reduced SQL +fan-out, not a latency improvement; p95 was worse with the lock/wait path. +Read-after-write from PostgreSQL: PASS. Redis restart recovery: PASS on all runs. +After final application rebuild: public smoke and `make test-grade4` both PASS. + +Limitations: +Local single-node synthetic test, one API container and one session; no +production workload, CPU isolation, or database-wide query instrumentation. +Profile SELECT counts use structured application events immediately before +the query (successful responses were verified, but this is not pg_stat_statements). +Every protected request still queries PostgreSQL for authoritative session +revocation/expiry. Lock wait is capped at two seconds and falls back to the +database, preserving availability but permitting extra reads if a fill is slow. +The short sample is not a general latency benchmark. diff --git a/evidence/local-validation.txt b/evidence/local-validation.txt index fb38c18..7cfe258 100644 --- a/evidence/local-validation.txt +++ b/evidence/local-validation.txt @@ -62,3 +62,12 @@ PASS: SESSION_TTL_SECONDS=2 make test-expiry; затем восстановле PASS: make explain-history; 10000 строк, Index Scan, 51 строка, 3 shared hits, Execution Time 0.034 ms; fixture завершён ROLLBACK. PASS: schema_migrations содержит только 001_initial.sql после повторных стартов. + +Проверки после реализации трека 5, 2026-11-13; отдельный Compose-проект, +PostgreSQL 16.6 и Redis 7.4.2: +PASS: make check +PASS: make validate +PASS: make test +PASS: make test-grade4 (race, auth, Redis/DB outage and recovery) +PASS: make test-track5-cache (120 запросов на условие; результаты в + cache-track5.txt; read-after-write и Redis restart recovery) diff --git a/tests/cache_track.py b/tests/cache_track.py new file mode 100644 index 0000000..3c6e7f1 --- /dev/null +++ b/tests/cache_track.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 +"""A/B cache-fill test for the Track 5 single-flight experiment.""" +import hashlib +import json +import subprocess +import time +import uuid +from concurrent.futures import ThreadPoolExecutor + +from client import Client, Failure, arguments, check, run + + +def compose(*args, env=None): + return subprocess.run( + ["docker", "compose", *args], + check=True, + capture_output=True, + text=True, + env=env, + ) + + +def wait_ready(client): + for _ in range(60): + try: + client.call("GET", "/health/ready", schema="Health") + return + except Failure: + time.sleep(1) + raise Failure("API did not become ready after configuration change") + + +def redis_delete(key): + compose("exec", "-T", "redis", "redis-cli", "DEL", key) + + +def profile_loads(request_ids): + output = compose("logs", "--no-color", "api").stdout + return sum( + 1 + for line in output.splitlines() + if "event=session_profile_db_load" in line + and any(("request_id=" + request_id) in line for request_id in request_ids) + ) + + +def measure_wave(client, actor, concurrency): + request_ids = [uuid.uuid4().hex for _ in range(concurrency)] + + def request(request_id): + result = client.call( + "GET", + "/api/v1/users/me", + actor=actor, + schema="User", + headers={"X-Request-Id": request_id}, + ) + return result["elapsed"], result["json"] + + with ThreadPoolExecutor(max_workers=concurrency) as executor: + results = list(executor.map(request, request_ids)) + check(all(user == actor["user"] for _, user in results), "cached profile differs") + return request_ids, [elapsed for elapsed, _ in results] + + +def run_mode(client, actor, enabled, waves, concurrency, env): + env["SESSION_CACHE_SINGLEFLIGHT"] = "1" if enabled else "0" + compose("up", "-d", "--force-recreate", "api", env=env) + wait_ready(client) + token_hash = hashlib.sha256(actor["token"].encode("utf-8")).hexdigest() + elapsed = [] + sql_loads = 0 + for _ in range(waves): + redis_delete("session:" + token_hash) + request_ids, latencies = measure_wave(client, actor, concurrency) + elapsed.extend(latencies) + sql_loads += profile_loads(request_ids) + return {"profile_sql_queries": sql_loads, "latencies_seconds": elapsed} + + +def percentile(values, percentile_value): + ordered = sorted(values) + index = min(len(ordered) - 1, int((len(ordered) - 1) * percentile_value)) + return ordered[index] + + +def summarize(measurement): + latencies = measurement["latencies_seconds"] + return { + "profile_sql_queries": measurement["profile_sql_queries"], + "requests": len(latencies), + "latency_median_ms": round(1000 * percentile(latencies, 0.50), 2), + "latency_p95_ms": round(1000 * percentile(latencies, 0.95), 2), + } + + +def main(args): + client = Client(args.base_url, args.ca_file, timeout=10) + actor = client.user("cache5") + env = dict(__import__("os").environ) + measurements = {} + try: + measurements["without_singleflight"] = run_mode( + client, actor, False, args.waves, args.concurrency, env + ) + measurements["with_singleflight"] = run_mode( + client, actor, True, args.waves, args.concurrency, env + ) + + fresh = client.user("read_after_write") + fresh_token_hash = hashlib.sha256(fresh["token"].encode("utf-8")).hexdigest() + redis_delete("session:" + fresh_token_hash) + read_after_write_request_id = uuid.uuid4().hex + observed = client.call( + "GET", + "/api/v1/users/me", + actor=fresh, + schema="User", + headers={"X-Request-Id": read_after_write_request_id}, + )["json"] + check(observed == fresh["user"], "read-after-write profile mismatch") + check( + profile_loads([read_after_write_request_id]) == 1, + "read-after-write did not load the newly written profile from PostgreSQL", + ) + + compose("restart", "redis") + wait_ready(client) + recovered = client.call( + "GET", "/api/v1/users/me", actor=actor, schema="User" + )["json"] + check(recovered == actor["user"], "profile was not recovered after Redis restart") + + output = { + "method": { + "waves": args.waves, + "concurrency": args.concurrency, + "profile_sql_query_counter": "structured API log events", + "latency": "client-observed GET /api/v1/users/me", + }, + "without_singleflight": summarize(measurements["without_singleflight"]), + "with_singleflight": summarize(measurements["with_singleflight"]), + "read_after_write": "PASS", + "redis_restart_recovery": "PASS", + } + print(json.dumps(output, indent=2, sort_keys=True)) + finally: + env["SESSION_CACHE_SINGLEFLIGHT"] = "1" + compose("up", "-d", "--force-recreate", "api", env=env) + wait_ready(client) + + +if __name__ == "__main__": + def configured_main(): + def configure(parser): + parser.add_argument("--waves", type=int, default=5) + parser.add_argument("--concurrency", type=int, default=24) + + args = arguments("Track 5 cache single-flight A/B experiment", configure) + if args.waves < 1 or args.concurrency < 2: + raise Failure("--waves must be positive and --concurrency at least 2") + main(args) + + run(configured_main)