Files
mtusi2026lab2/openspec/changes/membership-cache/proposal.md
T
ricoromaandClaude Opus 5.5 cae4b09147 feat: cache chat cards in Valkey
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>
2026-10-01 21:17:55 +03:00

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/.