Files
mtusi2026lab2/openspec/changes/membership-cache/tasks.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

7.8 KiB
Raw Blame History

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 — valkey healthy, 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 valkey get возвращает промах за < 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, change bench-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 и отчёт.