forked from mtusi2026/mtusi2026lab2
[+] add project
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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 содержит инструкцию именно этого решения.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user