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>
7.8 KiB
7.8 KiB
Tasks
Как строить — design.md (дальше «решение N»), что должно получиться —
дельты в specs/. Перед первым файлом слоя прочитать его правило:
infra.md, repo-layer.md, service-layer.md, api-layer.md,
settings.md, docker.md, run-modes.md, logging.md,
student-tests.md. Evidence снимается с закоммиченного кода, коммит —
только после подтверждения пользователя (bench.md, «Измеренное
состояние — commit»).
1. Зависимость и настройки
- 1.1
uv add "redis>=8.1,<9"в основную группу с комментарием (клиент для Valkey). Проверка:uv lock --check;uv run python -c "import redis; print(redis.__version__)"— 8.1.x. - 1.2 Секция
Cacheвsrc/config/settings.py(решение 6):host,port,password(SecretStr),timeout_seconds,retry_after_seconds,chat_ttl_seconds,max_connections; значения по умолчанию — для консоли..env.example:VALKEY_*и мостыCACHE__*;make env_setupподставляет случайныйVALKEY_PASSWORDв новый.env;config_example.tomlи рабочийconfig.toml—[cache]; строки Valkey — в рабочий.env(только их, пароль не читать). Проверка:settings.cacheв консоли —127.0.0.1:<VALKEY_OUT_PORT>;make env_setupв пустом каталоге даёт непустыеPOSTGRES_PASSWORDиVALKEY_PASSWORD.
2. Стенд
- 2.1
infra/valkey/valkey.confи сервисvalkeyвdocker-compose.ymlпо решению 3: пин тега и digest, порт изVALKEY_PORT, публикация127.0.0.1:${VALKEY_OUT_PORT}, алиас, пароль из переменной контейнера, healthcheck сVALKEYCLI_AUTH;CACHE__*вx-app-env;apiждётvalkey: service_healthy. Проверка:docker compose --env-file .env config --quiet;make run_docker—valkeyhealthy,CONFIG GET maxmemory-policy—allkeys-lru,CONFIG GET save— пусто;docker port— только127.0.0.1; без пароляPINGотвечаетNOAUTH. - 2.2
Makefile:start_cache,stop_cache,run_dev: upgrade start_cache,test_isolated: env_setup start_db start_cache;scripts/restart.sh— Valkey вместе с Postgres (решение 6). Проверка:make -nдля целей;scripts/restart.sh— уpostgres,valkeyиapiновыйStartedAt, укладывается в 90 с.
3. Код
- 3.1
src/infra/cache/: фабрика клиента без повторов, обёрткаCacheс пропуском после отказа и журналом, глобал вinstance.py(решения 4, 5). Проверка: разовым скриптом против Valkey стендаset/getработают; приdocker compose stop valkeygetвозвращает промах за < 50 мс, приpause— за ≈ 0,2 с, следующий вызов в пределах 5 с — сразу, без обращения к Valkey; в журнале одинwarningна отказ иinfoпосле возврата; пароля в журнале нет. - 3.2
src/core/repos/chat_cache.py: ключ с именем базы иv1, JSON ↔ChatFullDTO(решение 1). Проверка: карточка после записи и чтения равна исходной, включая порядокmember_idsи микросекундыcreated_at. - 3.3
ChatServiceиMessageServiceс кэшем вторым параметром: cache-aside вget_chat_for_member, запись после commit вcreate_chat, без отрицательных записей (решение 2); фабрики вdependencies.py,acloseв lifespan. Проверка:make lint;make testиmake student_testпротив консольного сервиса —PASSи все тесты;idx_scanтаблицыchatsрастёт на 1 за 10 чтений одного чата.
4. Тесты
- 4.1 Тесты сценариев
chat-cache, видимых по HTTP: «Повторное чтение чата», «Проверка членства по карточке», «Сообщение видно сразу», «Новый чат в списке». Проверка: тесты проходят против консольного сервиса. - 4.2
/opsx:syncи в том же шагеspec_coverage.py:chat-cache— в список отслеживаемых capability; исключения со ссылкой на evidence иfailure-checksдля «Чтение из кэша», «Срок записи», «Valkey остановлен», «Valkey завис», «Valkey вернулся», «Очистка кэша», «Временная база» (chat-cache) и «Кэш недоступен» (health). Проверка:make student_test— все прошли, в том числеtest_coverage.py;openspec validate --specsбез ошибок.
5. Инструменты и документы
- 5.1 Правила:
infra.md(клиент Valkey без повторов, обход,instance.py),docker.md(сервис Valkey, пароль, без volume),run-modes.md(start_cache,run_dev,test_isolated),settings.md([cache],VALKEY_*),service-layer.md(кэш — второй параметр, запись после commit);AGENTS.md— команды, карта кода, «Переходное состояние»; скилл:driver.py startподнимает Valkey,SKILL.md. Проверка:grep -rn "Redis/Valkey ещё нет\|start_redis" AGENTS.md .claude— пусто («решает design change» вbench.md— проinproc.py, changebench-postgres). - 5.2 Финальная проверка кода:
make lint,make check,openspec validate membership-cache --strict,make test_isolated— код 0,python3 .claude/skills/run-mtusi-messenger/driver.py all— код 0. Затем показать изменения, предложить сообщение и после подтверждения закоммитить.
6. Evidence и отчёт
- 6.1 Evidence по таблице решения 7 с закоммиченного кода. Проверка: в каждом файле дата, commit, стенд; паролей и токенов в файлах нет.
- 6.2
REPORT.md: роль Valkey (кэш карточки чата), источник истины, срок, вытеснение и отсутствие инвалидации, поведение при отказе, flush и рестарте; таблица роль → сервис → версия/digest → healthcheck → volume → порт → credentials для api, postgres, valkey (infra/README.md);CACHE_URL_FILEв таблице соответствия; строка уровня «4» про Redis/Valkey и отказ кэша со ссылками на evidence; шаг про строки Valkey в существующем.env. Проверка: у каждой строки таблицы доказательств есть команда, наблюдение и файл. - 6.3
make lint,make check,openspec validate membership-cache --strict,graphify update .; показать изменения и после подтверждения закоммитить evidence и отчёт.