Files
mtusi2026lab2/openspec/changes/membership-cache/tasks.md
T
ricoromaandClaude Opus 5.5 287a61c704 docs: re-shoot Valkey outage and restart evidence
Evidence from d7c9a59: Valkey stop adds 97 ms (one reconnect), pause
207 ms, 30 concurrent commands stay within 201 ms, and restarting Valkey
alone no longer switches the cache off. REPORT.md and the skill describe
the retry on a dropped connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 22:07:35 +03:00

9.5 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/: фабрика клиента без повторов (после verify — один повтор на обрыв, задача 7.1), обёртка 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 и все тесты; чтения таблицы chats (seq_scan + idx_scan: таблица мала, поиск по id — последовательным сканированием) растут на 1 за 50 чтений одного чата — evidence/cache/hits.md (первый замер по одному idx_scan был неверен: он поймал проверку внешнего ключа при создании чата).

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 и отчёт.

7. Правки по verify

  • 7.1 Клиент (решение 4): Retry из redis.asyncio.retry — один немедленный повтор только на ConnectionError; вся команда Cache — под asyncio.timeout([cache] timeout_seconds). Проверка: разовым скриптом против Valkey стенда — после restart valkey промах без warning, stop — < 50 мс, pause — ≈ 0,2 с, 30 одновременных команд при pause — не дольше 0,21 с; driver.py all — код 0.
  • 7.2 Документы под новое поведение: design (Context, решения 4–5, Risks), infra.md, AGENTS.md, комментарии [cache] timeout_seconds, REPORT.md. Проверка: grep -rn "без повторов" .claude AGENTS.md REPORT.md — нет утверждений, что повторов нет совсем.
  • 7.3 make lint, make test_isolated; после подтверждения — commit фикса. Затем с него переснять evidence/cache/outage.md и evidence/cache/flush-restart.md, обновить строки REPORT.md и после подтверждения закоммитить.