Valkey 9.1 in compose caches the immutable chat card (title, members,
created_at) used by GET /chats/{id} and by the membership check of the
message endpoints. Cache-aside with a write after commit, keys per
database, TTL plus allkeys-lru, persistence off. redis-py runs without
retries; on failure the cache is skipped for a few seconds and requests
go to PostgreSQL. Readiness does not depend on Valkey.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.2 KiB
Proposal
Why
Уровень «4» требует, чтобы Redis или Valkey «реально использовался для
сессий с TTL либо осмысленного кэша» с описанными источником истины,
политикой expiry и инвалидации. При его потере приложение должно
корректно обходить кэш и не пускать анонимного пользователя
(README.md). Сессии остаются в PostgreSQL ради мгновенного отзыва
(session-auth), поэтому Valkey получает роль кэша.
Кэшировать будем карточку чата: id, title, участников и
created_at. Её читают три самых частых запроса: GET /chats/{id},
POST …/messages (проверка членства) и GET …/messages. По контракту
она не меняется после создания, поэтому кэш не может вернуть устаревшее,
и инвалидация не нужна.
What Changes
- В стенде появляется Valkey 9.1: сервис compose с закреплённым тегом и
digest, healthcheck, конфигом из
infra/только на чтение, паролем из.envи публикацией только на127.0.0.1. Persistence выключен: кэш можно потерять без потери данных. - Карточка чата кэшируется по
id. Чтение идёт сначала из Valkey, при промахе — из PostgreSQL с записью в кэш. Новый чат кладётся в кэш после commit. Срок записи — настройка, вытеснение — LRU с лимитом памяти. Ключ включает имя базы, поэтомуmake test_isolatedне смешивает свои чаты с рабочими. - Историю сообщений, список чатов и сессии кэш не хранит: история и список меняются с каждой записью, а сессии должны отзываться мгновенно.
- Valkey недоступен или завис: запросы обслуживаются из PostgreSQL с
тем же ответом. Задержка ограничена коротким таймаутом, затем кэш
пропускается на несколько секунд, причина — в журнале. После возврата
Valkey кэш снова используется без рестарта API.
/health/readyот Valkey не зависит: он не критичен для обязательного пути. scripts/restart.shперезапускает и Valkey;make run_dev,make test_isolatedи драйвер скилла поднимают его вместе с Postgres. Новые целиstart_cacheиstop_cache.- BREAKING (для оператора): в существующий
.envнужно добавить строки Valkey из.env.example:make env_setupсуществующий.envне меняет. Для нового.envпароль Valkey генерируется сам.
Вне этого change: автоматические проверки недоступности Valkey и БД на
особом стенде (failure-checks), кэш списков и истории, трек 1 на «5»
(согласованность кэша под нагрузкой).
Capabilities
New Capabilities
chat-cache: кэш карточки чата в Valkey — что кэшируется, источник истины, срок и вытеснение, инвалидация (не нужна) и её граница, обход при недоступности, потеря и очистка кэша.
Modified Capabilities
container-run: Valkey в стенде compose, его порты из.env, публикация на127.0.0.1, перезапуск hook-ом.service-configuration: подключение к Valkey (адрес и пароль из.env, таймауты и срок записей изconfig.toml), консоль и docker без правки файлов.health: readiness не зависит от Valkey.student-tests: прогон на временной базе поднимает Valkey стенда;chat-cache— в списке спеков, чьи сценарии покрывают тесты (там же дописан пропущенныйsessions).
Impact
- Код: клиент Valkey в
src/infra/cache/(глобал процесса, таймауты, обход при отказе),src/core/repos/chat_cache.py(ключ и сериализация карточки),ChatServiceиMessageServiceс клиентом вторым параметром,src/api/dependencies.py,src/main.py(закрытие клиента),src/config/settings.py([cache]),src/utils/constants.py. - Зависимости:
redis(redis-py, асинхронный клиент; с Valkey совместим по протоколу);uv.lock. - Инфраструктура:
docker-compose.yml(сервисvalkey,x-app-env),infra/valkey/valkey.conf,.env.example(VALKEY_*и мосты),config_example.toml,Makefile(start_cache,stop_cache,run_dev,test_isolated,env_setup),scripts/restart.sh. - Тесты:
student-tests— сценарииchat-cache, видимые по HTTP; исключения для отказа и очистки Valkey со ссылками на evidence иfailure-checks. - Документы: правила (
infra.md,docker.md,run-modes.md,settings.md,service-layer.md),AGENTS.md, скиллrun-mtusi-messenger,REPORT.md(роль Valkey, таблица роль → сервис → версия → healthcheck → volume → порт → credentials, expiry и инвалидация, поведение при flush и рестарте),evidence/.