[+] add project

This commit is contained in:
2026-11-13 21:16:52 +03:00
parent 982fe0e6d2
commit 802f1a4321
11 changed files with 453 additions and 88 deletions
+1
View File
@@ -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.
+34 -14
View File
@@ -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 содержит инструкцию именно этого решения.
+2 -2
View File
@@ -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).
+5 -2
View File
@@ -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)
+6
View File
@@ -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
+81 -30
View File
@@ -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/` этого задания; сторонний код в рамках этой работы не добавлялся. Ответственность за понимание и защиту реализации остаётся за автором.
+98 -40
View File
@@ -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
+1
View File
@@ -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
+52
View File
@@ -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.
+9
View File
@@ -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)
+164
View File
@@ -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)