From cae4b09147866bfd7f7056acefdc98321f49a14f Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 1 Oct 2026 21:17:55 +0300 Subject: [PATCH] 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 --- .claude/rules/auth.md | 9 +- .claude/rules/docker.md | 52 +++-- .claude/rules/infra.md | 58 +++-- .claude/rules/repo-layer.md | 4 + .claude/rules/run-modes.md | 29 ++- .claude/rules/service-layer.md | 22 +- .claude/rules/settings.md | 34 ++- .claude/rules/student-tests.md | 11 +- .claude/skills/run-mtusi-messenger/SKILL.md | 61 +++-- .claude/skills/run-mtusi-messenger/driver.py | 14 +- .env.example | 20 +- AGENTS.md | 67 +++--- Makefile | 39 +++- config_example.toml | 12 + docker-compose.yml | 53 ++++- infra/valkey/valkey.conf | 15 ++ .../changes/membership-cache/.openspec.yaml | 2 + openspec/changes/membership-cache/design.md | 221 ++++++++++++++++++ openspec/changes/membership-cache/proposal.md | 87 +++++++ .../membership-cache/specs/chat-cache/spec.md | 119 ++++++++++ .../specs/container-run/spec.md | 102 ++++++++ .../membership-cache/specs/health/spec.md | 31 +++ .../specs/service-configuration/spec.md | 41 ++++ .../specs/student-tests/spec.md | 68 ++++++ openspec/changes/membership-cache/tasks.md | 110 +++++++++ openspec/specs/chat-cache/spec.md | 119 ++++++++++ openspec/specs/container-run/spec.md | 54 +++-- openspec/specs/health/spec.md | 9 +- openspec/specs/service-configuration/spec.md | 30 ++- openspec/specs/student-tests/spec.md | 30 +-- pyproject.toml | 2 + scripts/restart.sh | 17 +- src/api/dependencies.py | 11 +- src/config/settings.py | 23 ++ src/core/repos/chat_cache.py | 61 +++++ src/core/services/chat.py | 36 ++- src/core/services/message.py | 18 +- src/infra/cache/__init__.py | 6 + src/infra/cache/client.py | 113 +++++++++ src/infra/cache/instance.py | 13 ++ src/main.py | 10 +- src/utils/constants.py | 5 + student-tests/run_isolated.py | 6 +- student-tests/spec_coverage.py | 41 ++++ student-tests/test_chat_cache.py | 83 +++++++ uv.lock | 11 + 46 files changed, 1769 insertions(+), 210 deletions(-) create mode 100644 infra/valkey/valkey.conf create mode 100644 openspec/changes/membership-cache/.openspec.yaml create mode 100644 openspec/changes/membership-cache/design.md create mode 100644 openspec/changes/membership-cache/proposal.md create mode 100644 openspec/changes/membership-cache/specs/chat-cache/spec.md create mode 100644 openspec/changes/membership-cache/specs/container-run/spec.md create mode 100644 openspec/changes/membership-cache/specs/health/spec.md create mode 100644 openspec/changes/membership-cache/specs/service-configuration/spec.md create mode 100644 openspec/changes/membership-cache/specs/student-tests/spec.md create mode 100644 openspec/changes/membership-cache/tasks.md create mode 100644 openspec/specs/chat-cache/spec.md create mode 100644 src/core/repos/chat_cache.py create mode 100644 src/infra/cache/__init__.py create mode 100644 src/infra/cache/client.py create mode 100644 src/infra/cache/instance.py create mode 100644 student-tests/test_chat_cache.py diff --git a/.claude/rules/auth.md b/.claude/rules/auth.md index 9e674444..fdd83e1d 100644 --- a/.claude/rules/auth.md +++ b/.claude/rules/auth.md @@ -85,10 +85,11 @@ paths: Проверка токена — один `SELECT` по `token_hash` с `JOIN` на пользователя; `now` для `expires_at > now` передаёт сервис, срок сравнивается по часам приложения. -- Redis/Valkey сессии не хранит: он — кэш состава чатов - (`membership-cache`). Любое хранилище сессий обязано пережить рестарт, - соблюдать срок и отзыв, при недоступности отвечать 503 и никогда не - пропускать запрос как анонимный или доверенный. +- Valkey сессии не хранит: он — кэш карточек чатов (спек + `chat-cache`, change `membership-cache`). Любое хранилище сессий + обязано пережить рестарт, соблюдать срок и отзыв, при недоступности + отвечать 503 и никогда не пропускать запрос как анонимный или + доверенный. ## Текущий пользователь diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index f9a687ab..0068e7a4 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -140,8 +140,8 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t - С лабы 2 compose — основной запуск стенда: API без Postgres запросы не обслуживает. Проверка и запуск — по README: `docker compose --env-file .env config --quiet`, затем - `up -d --build`, ожидание `/health/ready`. Роли — api и postgres, на - «4» ещё Redis или Valkey (`contracts/infrastructure.json`). + `up -d --build`, ожидание `/health/ready`. Роли — api, postgres и + valkey (`contracts/infrastructure.json`: Redis или Valkey на «4»). `compose.example.yaml` — лишь список ролей, стенд — свой `docker-compose.yml` (compose находит его сам, как и `compose.yaml`). - Образы зависимостей закреплены так же, как базовый: тег с патч-версией @@ -161,27 +161,45 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t - Postgres наружу — только `127.0.0.1:${POSTGRES_OUT_PORT}`, для console-режима. Пароль — `POSTGRES_PASSWORD` в `.env`, в приложение мостом (`settings.md`). -- Redis или Valkey: те же пины, healthcheck и volume. Если это - единственное хранилище сессий, persistence включён (`appendonly yes` - или RDB с обоснованным интервалом): без него рестарт стирает сессии, - и `make test-persistence` падает. -- Конфигурации сервисов (`postgresql.conf`, `redis.conf`) — в `infra/`, - монтируются read-only (`infra/README.md`). В `REPORT.md` — таблица - роль → сервис → версия/digest → healthcheck → volume → порт → способ - передачи credentials. +- Valkey (сервис `valkey`, кэш карточек чатов): тот же пин тега с + патч-версией и digest индекса, `restart: unless-stopped`, healthcheck, + `api` ждёт `service_healthy`. Отличия от Postgres: + - volume нет: persistence выключен в `infra/valkey/valkey.conf` + (`save ""`, `appendonly no`), кэш после рестарта пуст, а данные — + в Postgres. Если бы в Valkey жили сессии, persistence был бы + обязателен: без него рестарт стёр бы их, и `make test-persistence` + упал бы; + - пароль — `VALKEY_PASSWORD` в `.env`, в контейнер — переменной + окружения. Сервер получает его в `command` через `sh -c` из + переменной контейнера (`--requirepass "$$VALKEY_PASSWORD"`), в + compose он не литерал. Запуск — `exec docker-entrypoint.sh + valkey-server ...`: с `sh` первым аргументом entrypoint образа не + сбрасывает root, а так сервер работает от пользователя `valkey`; + - healthcheck — `valkey-cli ping` с паролем из `VALKEYCLI_AUTH` + (без `-a` в команде): `PONG` только после AUTH, и проверка + ловит неверный пароль; + - порт сервера — `VALKEY_PORT` (`--port`), алиас в сети — + `VALKEY_HOST`, публикация — `127.0.0.1:${VALKEY_OUT_PORT}`, как у + Postgres. +- Конфигурации сервисов (`valkey.conf`, при необходимости + `postgresql.conf`) — в `infra/<сервис>/`, монтируются read-only + длинной записью с `create_host_path: false` (`infra/README.md`). В + `REPORT.md` — таблица роль → сервис → версия/digest → healthcheck → + volume → порт → способ передачи credentials. ## `scripts/restart.sh` Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), по образцу `scripts/restart.example.sh`. -- Перезапускает API и **все** используемые хранилища: Postgres и, если - есть, Redis или Valkey. Volumes, схему и данные сохраняет: без - `down -v`, `FLUSHALL`, повторного seed и изменения тестовых данных. -- Порядок: `stop api` → `restart postgres` → `up -d --wait postgres` - (тот же контейнер, ожидание healthcheck) → `start api`. `start api` - запускает и зависимость `migrate`: повторный прогон миграций — - no-op. +- Перезапускает API и **все** используемые хранилища: Postgres и + Valkey. Volumes, схему и данные сохраняет: без `down -v`, `FLUSHALL`, + повторного seed и изменения тестовых данных. Кэш Valkey после + рестарта пуст сам: persistence у него выключен. +- Порядок: `stop api` → `restart postgres valkey` → `up -d --wait + postgres valkey` (те же контейнеры, ожидание healthcheck) → + `start api`. `start api` запускает и зависимость `migrate`: повторный + прогон миграций — no-op. - `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`, `git update-index --chmod=+x`). Возвращает 0 только после действия, укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает. diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 3795e6c2..2c7442cf 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -6,17 +6,18 @@ paths: # Инфраструктура (`src/infra/`) Всё, что не содержит бизнес-логики и может смениться от лабы к лабе: -логгер, PostgreSQL (`db/`), с «4» — клиент Redis или Valkey, дальше — -S3, брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) -здесь нет: они в сервисах, атомарные операции — в repo. +логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), дальше — S3, брокер, +телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет: +они в сервисах, атомарные операции — в repo. -- Клиент хранилища (engine Postgres, с «4» клиент Redis/Valkey) — - глобал своего модуля (`db/session.py`): создаётся при импорте по +- Клиент хранилища (engine Postgres, кэш Valkey) — глобал своего модуля + (`db/session.py`, `cache/instance.py`): создаётся при импорте по `settings` (настройки читаются один раз на процесс), соединения - открывает лениво, при первом запросе. Модуль не импортирует пакет - `src/infra/<клиент>/` и модели, поэтому alembic и скрипты клиента не - создают. Закрытие (`engine.dispose()`) — в lifespan `src/main.py`. - Почему не `app.state` — design change `postgres-storage`, решение 5. + открывает лениво, при первом запросе. Пакет `src/infra/<клиент>/` этот + модуль не импортирует, модели тоже, поэтому alembic и скрипты клиента + не создают. Закрытие (`engine.dispose()`, `cache.aclose()`) — в + lifespan `src/main.py`. Почему не `app.state` — design change + `postgres-storage`, решение 5. - Глобал импортируют только `src/main.py` (закрытие) и `src/api/dependencies.py`; сервисы получают сессию или клиент через конструктор из зависимости и сами глобал не импортируют. Процессу со @@ -25,10 +26,12 @@ S3, брокер, телеметрия. Бизнес-правил (уникал `ping`; `session.py` — глобалы `engine` и `session_factory`; `errors.py` — `is_db_unavailable`; модели — `models/` (`migrations.md`). Драйвер — asyncpg. +- `cache/`: `client.py` — фабрика `create_cache` и обёртка `Cache`; + `instance.py` — глобал `cache`. Ключи и формат значений — в repo + (`src/core/repos/chat_cache.py`), не здесь. - Источник истины — PostgreSQL. SQLite, файлы и память процесса его не заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в - Postgres; исключение — сессии, если их хранилище выбрано в Redis или - Valkey (`auth.md`). + Postgres: сессии в Valkey не лежат (`auth.md`). - Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у подключения и запроса есть таймауты (`connect_timeout_seconds`, серверный `statement_timeout`, срок запроса `request_timeout_seconds`). @@ -45,21 +48,36 @@ S3, брокер, телеметрия. Бизнес-правил (уникал оказались бы текст сообщений, а с `session-auth` — хэши паролей и токенов (`logging.md`, «Чего в логах быть не должно»). - `/health/ready` проверяет критичные зависимости через infra: - `SELECT 1` в Postgres с коротким таймаутом, Redis или Valkey — если - без него не работает обязательный путь (хранилище сессий). - Недоступность — 503. Какие зависимости критичны, фиксируется в - `REPORT.md`. + `SELECT 1` в Postgres с коротким таймаутом. Valkey не проверяется: это + кэш, без него обязательный путь идёт в Postgres. Недоступность + критичной зависимости — 503. Какие зависимости критичны, фиксируется + в `REPORT.md`. - Потеря соединения и таймауты драйвера на бизнес-запросе — 503 `unavailable` без деталей (`api-contract.md`), не 500 и не обход аутентификации. Перевод — в `get_db_session`: `is_db_unavailable` решает, отказ ли это, сессия закрывается через `invalidate()`, в журнал — `warning`. Остальные `DBAPIError` (ограничения, синтаксис) — дефект, им положен 500. -- Redis или Valkey — одно из двух, на «4». Роль (сессии с TTL или - осмысленный кэш), источник истины, политика expiry и инвалидации — - в `REPORT.md`. Если это единственное хранилище сессий, нужен - persistence, который выдерживает рестарт (`docker.md`). При его - недоступности — 503 либо корректный обход кэша. +- Valkey (не Redis) — кэш карточки чата (спек `chat-cache`, design + change `membership-cache`). Роль, источник истины, срок, вытеснение и + отсутствие инвалидации — в `REPORT.md`. Клиент — redis-py + (`redis.asyncio`): + - **без повторов**: `retry=Retry(NoBackoff(), 0)`. По умолчанию + redis-py повторяет команду с backoff, и замороженный Valkey держал + запрос 6 с вместо таймаута 0,2 с; + - `BlockingConnectionPool` на `[cache] max_connections` с ожиданием не + дольше `timeout_seconds`: обычный пул при всплеске запросов сразу + бросает `MaxConnectionsError`, и здоровый Valkey считался бы + отказавшим; + - `socket_timeout` и `socket_connect_timeout` — `[cache] + timeout_seconds`. +- Отказ Valkey — промах, а не 503 и не 500: `Cache.get` / `Cache.set` + ловят `RedisError` и `OSError`, отдают `None` / `False`, и запрос идёт в + Postgres. После отказа кэш пропускается на `[cache] + retry_after_seconds` без обращений к Valkey. В журнал — один + `warning` «Cache is unavailable» на отказ и `info` «Cache is + available again» при первом успехе. Пароль в журнал не попадает: он + есть только в настройках пула. - Клиенты внешних сервисов: адреса и секреты из `settings` (`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки переводятся в доменные исключения. Логи — по `logging.md`, без diff --git a/.claude/rules/repo-layer.md b/.claude/rules/repo-layer.md index f735bfeb..3d7792e8 100644 --- a/.claude/rules/repo-layer.md +++ b/.claude/rules/repo-layer.md @@ -36,3 +36,7 @@ paths: - Опциональные фильтры и лимиты — условное дополнение выборки (`if limit is not None: ...`). - Логов в репозиториях нет: ни `get_logger`, ни `print`. +- Repo кэша (`chat_cache.py`) — то же правило над Valkey: первый + параметр `cache: Cache`, одна команда на функцию, ключ и формат + значения (JSON ↔ DTO) живут здесь. Ключ включает + `CACHE_KEY_PREFIX` (версию формата) и `cache.namespace` (имя базы). diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 706ef0e4..54d08fb0 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -22,8 +22,8 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл | Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера | | uvicorn | `127.0.0.1`, `reload=True` по `src/` | `0.0.0.0`, без reload | | Порт | `settings.app.port`: `APP__PORT` из `.env`, без него — 8080 | `APP__PORT` из `.env` внутри (на нём же healthcheck), `APP_OUT_PORT` снаружи | -| Хранилища | Postgres (и Redis/Valkey на «4») — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres и накатывает миграции | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) | -| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`) | +| Хранилища | Postgres и Valkey — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres, накатывает миграции и поднимает Valkey | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) | +| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`); кэш Valkey после рестарта пуст | ## Точка входа @@ -40,8 +40,8 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. запросы до `timeout_graceful_shutdown` (настройка `[app] graceful_shutdown_seconds`, не больше 8 с). Docker шлёт SIGKILL через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan - только логирует и закрывает клиенты (`engine.dispose()`, клиент - Redis/Valkey), долгих операций в нём нет. + только логирует и закрывает клиенты (`engine.dispose()`, + `cache.aclose()`), долгих операций в нём нет. Рубрика уровня 4 требует завершения не дольше 10 с. ## Makefile @@ -55,8 +55,9 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. `# -------------------------`, свой `.PHONY` у каждой цели, имена в snake_case. Apple Container не делать. - Запуск и общие цели: - - `run_dev: upgrade` — Postgres из compose и миграции, затем - `APP__RUN_MODE=console uv run python -m src`; + - `run_dev: upgrade start_cache` — Postgres из compose и миграции, + Valkey из compose, затем `APP__RUN_MODE=console uv run python -m + src`; - `run_docker: env_setup` (недостающие `.env` и `config.toml` из шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`), к нему `stop`, `down` (volume остаётся), `logs` @@ -64,7 +65,9 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. каждая строка — JSON); - `lint` (`ruff format .` + `ruff check --fix .`, дважды), `env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` — - случайный `POSTGRES_PASSWORD`), `student_test`. + случайные `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`; существующий + `.env` не меняется, новые строки переносятся руками), + `student_test`. Оба способа запуска — `run_docker` и `run_dev` — описываются в `REPORT.md`. Запуска одного контейнера без compose нет: API без @@ -73,11 +76,13 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. `stop_db`, `upgrade: start_db` (`uv run alembic upgrade head`), `revision: upgrade` (autogenerate, сообщение — `read -p`), `wipe_data` (`$(DC) down -v --remove-orphans` только после ввода - `yes`). Volume — именованный `postgres_data` в compose. С «4» — - `start_redis` / `stop_redis`, если выбран Redis или Valkey. -- `test_isolated: env_setup start_db` — образ на временной базе - (`student-tests.md`). Скрипт запускается `$(PYTHON)`, а не `uv run`: - uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку. + `yes`). Volume — именованный `postgres_data` в compose; `wipe_data` + пересоздаёт и Valkey, то есть чистит кэш. +- Valkey: `start_cache` (`$(DC) up -d --wait valkey`), `stop_cache`. +- `test_isolated: env_setup start_db start_cache` — образ на временной + базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша + разделены именем базы. Скрипт запускается `$(PYTHON)`, а не + `uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку. ## Troubleshooting diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 5a03cb8e..85f85401 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -9,10 +9,16 @@ paths: транзакции, вызовы внешних клиентов, логи. - Класс `Service`. `__init__` принимает - `db_session: AsyncSession` и хранит его в `self`; клиент Redis/Valkey, - если он нужен домену, — вторым параметром. Методы принимают - keyword-only параметры (`*,`) и вызываются только именованными - аргументами. + `db_session: AsyncSession` и хранит его в `self`; кэш Valkey + (`cache: Cache`), если он нужен домену, — вторым параметром + (`ChatService`, `MessageService`). Методы принимают keyword-only + параметры (`*,`) и вызываются только именованными аргументами. +- Кэш карточки чата (`chat_cache_repo`, спек `chat-cache`): + cache-aside — сначала кэш, при промахе БД и запись в кэш; новый чат + пишется в кэш **после** `commit()`, чтобы откат не оставил в кэше + чата, которого нет в БД. Отсутствующий чат не кэшируется. Кэшировать + можно только неизменяемое: историю, списки и сессии — нет. Отказ + Valkey сервис не обрабатывает: `Cache` уже вернул промах. - Repo: `from src.core.repos import chat as chat_repo`. Вызов — `db_session=self.db_session` и именованные аргументы. - Проверка доступа — здесь. Не участник получает то же исключение, что @@ -29,15 +35,17 @@ paths: `rollback()`, и в БД не остаётся ничего. Откат составной операции — проверка уровня 4. - Коммитит только сервис, repo не коммитит. Другой сервис создаётся с - тем же `db_session`, чтобы остаться в одной транзакции. + тем же `db_session` (и тем же кэшем), чтобы остаться в одной + транзакции. - Уникальность (`username`) держит ограничение БД, а не проверка перед вставкой: repo делает `ON CONFLICT DO NOTHING RETURNING`, `None` сервис превращает в доменное исключение (→ 409). Схема «сначала SELECT, потом INSERT» ломается на гонке регистрации даже внутри транзакции (READ COMMITTED), а эта гонка — проверка уровня 4. -- Недоступность Postgres или хранилища сессий — доменное +- Недоступность Postgres (там же хранятся сессии) — доменное `ServiceUnavailable` (→ 503), не 500 и никогда не пропуск запроса без - аутентификации (`infra.md`). + аутентификации (`infra.md`). Недоступность Valkey — не ошибка, а + промах кэша. - KDF пароля — в потоке, не в event loop (`auth.md`). - Курсор кодирует и разбирает сервис через `src/utils/cursor.py`: проверяет область (этот чат или этот пользователь) и возвращает diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index 0a6d8015..113b69bb 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -14,7 +14,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда ## Источники `Settings` - `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel` - (`App`, `Database`, `Auth`; с «4» — секция Redis или Valkey). Экземпляр один — + (`App`, `Database`, `Auth`, `Cache` — Valkey). Экземпляр один — `settings` на уровне модуля. Импорт везде `from src.config import settings`. Второй `Settings()` не создавать, поля в рантайме не менять. - Приоритет (`settings_customise_sources`): окружение процесса → `.env` @@ -47,8 +47,8 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда | Где | Что | В git | |---|---|---| -| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | -| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` (адрес, порты, учётные данные), пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольный адрес Postgres | нет; шаблон `.env.example` | +| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL сессии, таймауты, пул и срок записей `[cache]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | +| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` и `VALKEY_*` (адрес, порты, учётные данные), пароли MinIO / брокера с лаб 4–5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres и Valkey | нет; шаблон `.env.example` | | окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — | | `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да | @@ -57,7 +57,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда `Dockerfile.example` касается запекания в образ (`COPY`), а `config.toml` в образ не копируется, его монтируют на старте (`docker.md`). Но почти все секреты курса — пароли -Postgres, Redis, MinIO, брокера — нужны ещё и контейнеру зависимости, +Postgres, Valkey, MinIO, брокера — нужны ещё и контейнеру зависимости, а его настраивает только compose из `.env`. Поэтому такой секрет живёт в `.env` и попадает в приложение мостом. Если продублировать его в `config.toml`, как `postgres_password` в bp_proxies, получатся два @@ -116,13 +116,21 @@ compose полю секции: - консоль: приложение на хосте читает `.env`, мосты `DATABASE__HOST=127.0.0.1`, `DATABASE__PORT=${POSTGRES_OUT_PORT}` и - учётные данные из `POSTGRES_*`; + учётные данные из `POSTGRES_*`; для Valkey — + `CACHE__HOST=127.0.0.1`, `CACHE__PORT=${VALKEY_OUT_PORT}`, + `CACHE__PASSWORD=${VALKEY_PASSWORD}`; - docker: `.env` в контейнер не попадает, адрес и порт приходят из `environment` compose — `DATABASE__HOST: ${POSTGRES_HOST}`, - `DATABASE__PORT: ${POSTGRES_PORT}` в общем якоре `x-app-env`. + `DATABASE__PORT: ${POSTGRES_PORT}`, `CACHE__HOST: ${VALKEY_HOST}`, + `CACHE__PORT: ${VALKEY_PORT}` в общем якоре `x-app-env`. -Адрес и порт Postgres в compose — только переменные `.env`, литерал — -лишь адрес публикации `127.0.0.1` (`docker.md`). +Адреса и порты Postgres и Valkey в compose — только переменные `.env`, +литерал — лишь адрес публикации `127.0.0.1` (`docker.md`). + +Существующий `.env` `make env_setup` не меняет. Новая переменная из +`.env.example` (с `membership-cache` — строки `VALKEY_*` и `CACHE__*`) +переносится в рабочий `.env` руками; без `VALKEY_PASSWORD` compose +останавливается с сообщением об этом. `.env.example` skeleton lab2 предлагает «логические» имена: `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, @@ -132,10 +140,12 @@ compose полю секции: только приложение, поэтому это `[auth] session_ttl_seconds` в `config.toml`, а короткий срок для проверки истечения — `AUTH__SESSION_TTL_SECONDS=2` в окружении. Мост с контрактным именем -ничего бы не дал: по абзацу выше окружение его не перекрывает. Пароль -Postgres приходит мостом из `POSTGRES_PASSWORD`, а не строкой -подключения в файле (`*_URL_FILE`). Соответствие переменных реальной -конфигурации описать в `REPORT.md` (раздел «Архитектура и решения»). +ничего бы не дал: по абзацу выше окружение его не перекрывает. Пароли +Postgres и Valkey приходят мостами из `POSTGRES_PASSWORD` и +`VALKEY_PASSWORD`, а не строкой подключения в файле (`DATABASE_URL_FILE`, +`CACHE_URL_FILE`). `SESSION_STORE` — PostgreSQL, отдельной настройки +нет. Соответствие переменных реальной конфигурации описать в +`REPORT.md` (раздел «Архитектура и решения»). В настройки идёт только то, что отличается между установками, либо секрет. Остальное — константа. diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 7e7cd4c3..79bf64b1 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -40,13 +40,16 @@ paths: не доказана. Проверяются количество и уникальность `id`, а также отсутствие потерь при обходе всех страниц. - Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`): - образ из рабочего дерева на временной базе `test_`, публичный - smoke и весь набор против отдельного контейнера, затем уборка при - любом исходе. Его вывод — evidence набора против контейнера. + образ из рабочего дерева на временной базе `test_` с Valkey + стенда (ключи кэша разделены именем базы), публичный smoke и весь + набор против отдельного контейнера, затем уборка при любом исходе. + Его вывод — evidence набора против контейнера. `make student_test` — против любого запущенного стенда (`BASE_URL`), он оставляет данные в рабочей базе. - Проверкам, которым нужен особый стенд (TTL 2 с, остановленные - Postgres или Redis), обычный прогон не подходит. Сами тесты + Postgres или Valkey), обычный прогон не подходит. Попадание в кэш по + HTTP не отличить от чтения из БД: такие сценарии `chat-cache` — + исключения с evidence. Сами тесты контейнеры не трогают: стенд готовит явный hook или отдельная цель Makefile, как `make test-persistence` в skeleton. Механизм выбирает change `failure-checks`. diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index ac1a0398..59908ca6 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -1,14 +1,16 @@ --- name: run-mtusi-messenger -description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, лаба 2) — на хосте или в Docker. Use when asked to run / start / stop the server or the container, run the smoke test, `make test`, `make student_test` or `make test_isolated`, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the container, or call services directly without HTTP. +description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey, лаба 2) — на хосте или в Docker. Use when asked to run / start / stop the server or the container, run the smoke test, `make test`, `make student_test` or `make test_isolated`, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the container, or call services directly without HTTP. --- REST API мессенджера (пользователи, чаты, сообщения) — сервер на -FastAPI/uvicorn, данные в PostgreSQL из compose. Агент управляет им через -`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres и -накатывает миграции (`make upgrade`), запускает свой экземпляр сервера -в фоне, гоняет сценарий по HTTP, публичный smoke и собственные тесты, -шлёт одиночные запросы и останавливает сервер. Против контейнера +FastAPI/uvicorn, данные в PostgreSQL из compose, карточки чатов +кэшируются в Valkey из compose. Агент управляет им через +`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres, +накатывает миграции и поднимает Valkey (`make upgrade start_cache`), +запускает свой экземпляр сервера в фоне, гоняет сценарий по HTTP, +публичный smoke и собственные тесты, шлёт одиночные запросы и +останавливает сервер. Против контейнера (`make run_docker`) работают те же команды драйвера, кроме `start`/`stop`. Только стандартная библиотека Python. @@ -25,12 +27,16 @@ Argon2id, около 30 мс на регистрацию и вход, поэто ```bash uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор) -make env_setup # .env (случайный POSTGRES_PASSWORD) и config.toml, существующие не трогает +make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml, существующие не трогает ``` -Нужен запущенный Docker: Postgres живёт в compose. Без Postgres сервер -стартует, но `/health/ready` отвечает 503; `driver.py start` сам делает -`make upgrade`. +Нужен запущенный Docker: Postgres и Valkey живут в compose. Без +Postgres сервер стартует, но `/health/ready` отвечает 503; без Valkey +всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе). +`driver.py start` сам делает `make upgrade start_cache`. В `.env`, +созданном до `membership-cache`, нет строк Valkey: их переносят из +`.env.example` руками, иначе compose падает с `VALKEY_PASSWORD is +empty`. ## Run (agent path) @@ -43,7 +49,7 @@ python3 $D all # start → flow → tests/smoke.py → student-tests → st посмотреть лог, послать свой запрос): ```bash -python3 $D start # make upgrade, затем фон; ждёт /health/ready до 30 с +python3 $D start # make upgrade start_cache, затем фон; ждёт /health/ready до 30 с python3 $D status # listeners: [pid reloader, pid worker], ready: True python3 $D flow # ~50 проверок: регистрация с паролем, вход, 409, неверный пароль, # 401 с WWW-Authenticate, X-User-Id игнорируется, чат, 5 сообщений, @@ -52,13 +58,13 @@ python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name": python3 $D req POST /api/v1/auth/sessions --basic zoe_demo:Zoe-password-1 python3 $D req GET /api/v1/users/me --token python3 $D smoke # публичный tests/smoke.py против этого порта -python3 $D student # make student_test BASE_URL=http://localhost: — 99 тестов, ~11 с +python3 $D student # make student_test BASE_URL=http://localhost: — 103 теста, ~12 с python3 $D stop ``` | команда | что делает | |---|---| -| `start` | `make upgrade`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | +| `start` | `make upgrade start_cache`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | | `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого | | `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat и синтетический токен alice | | `req METHOD PATH [--token T \| --basic USER:PASS] [--data JSON]` | один запрос: статус, `x-request-id`, `www-authenticate` у 401, тело; код 2 при статусе ≥ 400 | @@ -76,16 +82,18 @@ python3 $D stop ## Run: контейнер (compose) -Образ `mtusi-messenger:lab2`, compose-сервисы `postgres`, `migrate` -(одноразовые миграции) и `api`. Внешний порт — аргументом make, чтобы не -столкнуться с 8080: +Образ `mtusi-messenger:lab2`, compose-сервисы `postgres`, `valkey`, +`migrate` (одноразовые миграции) и `api`. Внешний порт — аргументом +make, чтобы не столкнуться с 8080: ```bash -make run_docker APP_OUT_PORT=18090 # build + up -d: postgres → migrate → api +make run_docker APP_OUT_PORT=18090 # build + up -d: postgres, valkey → migrate → api docker compose ps -a --format '{{.Name}} {{.Ports}} {{.Status}}' python3 $D --port 18090 flow # те же проверки против контейнера docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f -scripts/restart.sh # рестарт API и Postgres: данные и токены остаются +docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head' + # ключи кэша; пароль — из VALKEYCLI_AUTH контейнера +scripts/restart.sh # рестарт API, Postgres и Valkey: данные и токены остаются, кэш пуст make test-persistence ACTION_SCRIPT=scripts/restart.sh # то же публичной проверкой make down # удалить контейнеры, volume с данными остаётся make wipe_data # удалить и данные: только после ввода yes @@ -127,8 +135,10 @@ asyncio.run(main()) EOF ``` -`ChatService` и `MessageService` создаются так же (`db_session=...`), -все методы keyword-only, commit делает сам сервис. Ошибки — доменные +`ChatService` и `MessageService` создаются с кэшем вторым параметром: +`ChatService(db_session=db_session, cache=cache)`, где `cache` — из +`src.infra.cache.instance` (`await cache.aclose()` в конце, нужен +`make start_cache`). Все методы keyword-only, commit делает сам сервис. Ошибки — доменные исключения из `src.core.exceptions` (базовый `DomainError`), не HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, неверный пароль в `login` — `InvalidCredentials`. Созданное так остаётся в рабочей @@ -137,7 +147,7 @@ HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, не ## Run (human path) ```bash -make run_dev # Postgres + миграции, затем 127.0.0.1:8080, reload по src/; Ctrl-C +make run_dev # Postgres + миграции, Valkey, затем 127.0.0.1:8080, reload по src/; Ctrl-C ``` Блокирует терминал — агенту не подходит, используй `driver.py start`. @@ -211,3 +221,12 @@ make lint # ruff; затрагивает и dr недоступен: `docker compose ps postgres`, `make start_db`. Запросы к API в это время получают 503 `unavailable`, после возврата Postgres проходят без рестарта сервера. +- **В логе `warning` «Cache is unavailable»** — Valkey остановлен, + завис или перезапускался: `docker compose ps valkey`, `make + start_cache`. Ответы при этом те же (из Postgres), `/health/ready` — + 200; через `[cache] retry_after_seconds` (5 с) после возврата Valkey — + `info` «Cache is available again». +- **`VALKEY_PASSWORD is empty, copy Valkey lines from .env.example`** у + любой команды compose — `.env` создан до `membership-cache`: перенести + строки `VALKEY_*` и `CACHE__*` из `.env.example`, пароль — `openssl + rand -hex 16`. diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 4b6ba10e..2db227de 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -6,9 +6,10 @@ python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] Команды: - start `make upgrade` (Postgres из compose и миграции), затем поднять - `python -m src` в фоне (console, reload) и дождаться - /health/ready; лог и pid — /tmp/mtusi-api-.{log,pid} + start `make upgrade start_cache` (Postgres из compose и миграции, + Valkey), затем поднять `python -m src` в фоне (console, + reload) и дождаться /health/ready; лог и pid — + /tmp/mtusi-api-.{log,pid} status кто слушает порт и что отвечает /health/ready flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале req один запрос: req METHOD PATH [--token T | --basic USER:PASS] @@ -135,16 +136,17 @@ def cmd_start(port: int) -> int: return 0 print(f"port {port} is busy:", listener_pids(port)) return 1 - # без Postgres сервис стартует, но /health/ready отвечает 503 + # без Postgres сервис стартует, но /health/ready отвечает 503; без + # Valkey работает, но мимо кэша upgrade = subprocess.run( - ["make", "upgrade"], + ["make", "upgrade", "start_cache"], cwd=ROOT, capture_output=True, text=True, check=False, ) if upgrade.returncode != 0: - print("make upgrade failed:") + print("make upgrade start_cache failed:") print((upgrade.stdout + upgrade.stderr)[-2000:]) return 1 env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)} diff --git a/.env.example b/.env.example index 3d1a1858..5ef99534 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,7 @@ # Шаблон .env: `make env_setup` создаёт из него .env, не перезаписывая -# существующий файл, и подставляет случайный POSTGRES_PASSWORD. .env не -# коммитить. .env читают compose, Makefile и приложение +# существующий файл, и подставляет случайные POSTGRES_PASSWORD и +# VALKEY_PASSWORD. В существующий .env новые строки переносятся руками. +# .env не коммитить. .env читают compose, Makefile и приложение # (pydantic-settings); в контейнеры он не попадает. # Параметры приложения — в формате настроек SECTION__FIELD, без секции — # только то, что приложение не читает. Комментарии — только отдельными @@ -38,6 +39,21 @@ DATABASE__USER=${POSTGRES_USER} DATABASE__PASSWORD=${POSTGRES_PASSWORD} DATABASE__NAME=${POSTGRES_DB} +# Valkey — кэш карточек чатов. Пароль читают и сервер (--requirepass), и +# приложение; пустой make env_setup заменяет случайным +VALKEY_PASSWORD= +# адрес и порт Valkey внутри сети compose: по ним ходит API в docker, +# порт слушает сам сервер +VALKEY_HOST=valkey +VALKEY_PORT=6379 +# порт на 127.0.0.1 хоста, куда публикуется Valkey: к нему подключается +# приложение в console +VALKEY_OUT_PORT=6380 +# мосты для console: в docker их задаёт environment compose +CACHE__HOST=127.0.0.1 +CACHE__PORT=${VALKEY_OUT_PORT} +CACHE__PASSWORD=${VALKEY_PASSWORD} + # make test_isolated: порт на 127.0.0.1, куда публикуется тестовый # контейнер API TEST_APP_PORT=18088 diff --git a/AGENTS.md b/AGENTS.md index 67085103..f0519ae2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,10 +4,10 @@ REST API мессенджера (пользователи, чаты, истор переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или -Valkey. Код перенесён из лабы 1, переход на lab2 идёт через changes -OpenSpec (раздел «Переходное состояние»). Стек: Python -3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в -stdout). +Valkey (выбран Valkey — кэш карточек чатов). Код перенесён из лабы 1, +переход на lab2 идёт через changes OpenSpec (раздел «Переходное +состояние»). Стек: Python 3.12, uv, FastAPI, pydantic v2, +pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey). Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные @@ -60,9 +60,10 @@ stdout). Пользователи, чаты, участники, сообщения и ещё действующие сессии переживают рестарт API и хранилищ без удаления volumes. Basic — только на `POST /auth/sessions`, остальное — Bearer; `X-User-Id` доступа не - даёт; пароли — только через password KDF (`auth.md`). Redis или - Valkey (одно из двух) — на «4», с описанной ролью. uvicorn с одним - worker: реплики — лаба 3. + даёт; пароли — только через password KDF (`auth.md`). Valkey — на + «4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey — + обход кэша, а не ошибка (`infra.md`). uvicorn с одним worker: + реплики — лаба 3. - `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные выводы команд. @@ -80,21 +81,25 @@ stdout). Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change -`session-auth`. Этот файл и `.claude/rules/` описывают целевое -состояние лабы 2, поэтому в остальном код с ними пока расходится: +`session-auth`, кэш Valkey — change `membership-cache`. Этот файл и +`.claude/rules/` описывают целевое состояние лабы 2, поэтому в +остальном код с ними пока расходится: - `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с `X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` — change `bench-postgres` (`bench.md`); -- Redis/Valkey ещё нет — change `membership-cache`; - сценарии основных спеков, которые выполнятся только после следующих changes, — внести в их `tasks.md`: в `failure-checks` — автоматическая проверка «Сбой при добавлении участников», «БД остановлена», «БД вернулась», «Соединения исчерпаны» - (`data-storage`), «Хранилище не готово» (`health`), «Истёкший токен», - «Срок не продлевается», «БД остановлена при запросе с токеном» - (`sessions`); пока это исключения в `spec_coverage.py` с ручным - evidence; + (`data-storage`), «Хранилище не готово», «Кэш недоступен» + (`health`), «Истёкший токен», «Срок не продлевается», «БД + остановлена при запросе с токеном» (`sessions`), «Valkey + остановлен», «Valkey завис», «Valkey вернулся» (`chat-cache`); пока + это исключения в `spec_coverage.py` с ручным evidence; +- в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления + базы: иначе в кэше останутся карточки чатов, созданных после снятия + backup (design change `membership-cache`, Risks); - `REPORT.md` заполнен по хранению и сессиям; Redis/Valkey, EXPLAIN и трек 2 — следующие changes. @@ -155,7 +160,7 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan | `service-layer.md` | `src/core/services/**` | | `repo-layer.md` | `src/core/repos/**` | | `dto.md` | `src/schemas/**` | - | `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, Redis/Valkey и другие клиенты | + | `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (без повторов, обход при отказе) и другие клиенты | | `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии | | `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно | | `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть | @@ -241,17 +246,18 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan | `make test [BASE_URL=...]` | публичный smoke против запущенного сервера | | `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` | | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`tests/README.md`) | -| `make run_dev` | `make upgrade` (Postgres из compose и миграции), затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload | +| `make run_dev` | `make upgrade` (Postgres из compose и миграции) и `make start_cache`, затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload | | `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` | -| `make env_setup` | `.env.example` → `.env` со случайным `POSTGRES_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает | -| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres → migrate → api; `config.toml` монтируется read-only | +| `make env_setup` | `.env.example` → `.env` со случайными `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) | +| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey → migrate → api; `config.toml` и `infra/valkey/valkey.conf` монтируются read-only | | `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся | | `make logs` | журнал API, каждая строка — JSON (`--no-log-prefix`) | | `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | +| `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст | | `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) | | `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` | -| `make wipe_data` | `down -v` — удалить данные стенда; только после ввода `yes` | -| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_`: сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) | +| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` | +| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) | | `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом | | `make bench [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) | | `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт | @@ -279,12 +285,13 @@ src/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py schemas/.py # pydantic-модели запросов и ответов = схемы контракта - dependencies.py # сессия БД, фабрики сервисов, разбор Basic, текущая сессия по Bearer, пагинация + dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта middlewares/ # X-Request-Id и access-лог; с лабы 3 — X-Instance-Id core/ repos/.py # атомарный доступ к хранилищу, модульные функции - services/.py # Service: логика, проверки доступа, id и время, логи + repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO + services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем exceptions/.py # доменные исключения, реэкспорт в __init__.py infra/ logger.py # structlog, get_logger(), contextvar-ы request_id / user_id @@ -293,6 +300,8 @@ src/ db/session.py # глобалы engine и session_factory процесса API db/errors.py # is_db_unavailable: какие ошибки драйвера — 503 db/models/ # модели SQLAlchemy (Base с created_at и to_dict) + cache/client.py # create_cache (redis-py без повторов, блокирующий пул), Cache: отказ — промах и пропуск + cache/instance.py # глобал cache процесса API schemas/ dataclasses/.py # DTO между repo → service → api enums/.py # StrEnum доменов, RunModeEnum @@ -315,14 +324,17 @@ bench/ # нагрузочный стенд из лабы 1 compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose -infra/ # конфигурации сервисов стенда (Postgres, Redis/Valkey); README.md — skeleton -scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh +infra/ # конфигурации сервисов стенда; README.md — skeleton + valkey/valkey.conf # лимит памяти и LRU, persistence выключен +scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: api, postgres, valkey Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck -docker-compose.yml # postgres, migrate, api; адреса и порты из .env, volume postgres_data +docker-compose.yml # postgres, valkey, migrate, api; адреса и порты из .env, volume postgres_data .dockerignore config_example.toml, .env.example evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone evidence/migrations/ # миграции с нуля и повторно, ошибка миграции +evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига +evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6 evidence/profile/<метка>.txt # результаты make bench_inproc @@ -382,7 +394,7 @@ KNOWN_ISSUES.md # найденные попутно дефекты, | Лаба | Что появляется | Где в коде | |---|---|---| | 1 | in-memory API, Dockerfile | `infra/memory.py`, `X-User-Id` в `get_current_user` | -| 2 | PostgreSQL, Basic → Bearer-сессия; Redis/Valkey на «4» | `infra/db/`, `migrations/`, repo на `AsyncSession`; `password` при регистрации (KDF); `get_current_user` на Bearer; `SESSION_TTL_SECONDS` | +| 2 | PostgreSQL, Basic → Bearer-сессия; Valkey на «4» | `infra/db/`, `migrations/`, repo на `AsyncSession`; `password` при регистрации (KDF); `get_current_user` на Bearer; `SESSION_TTL_SECONDS`; кэш карточки чата — `infra/cache/`, `repos/chat_cache.py` | | 3 | балансировщик, ≥2 реплики, идемпотентность | middleware `X-Instance-Id`; `Idempotency-Key` на POST сообщения; никакого состояния в памяти процесса | | 4 | приватный S3, вложения | клиент в `infra/`, домен `attachment` | | 5 | брокер, worker, превью | отдельная точка входа worker; загрузка отвечает 202 | @@ -395,7 +407,8 @@ KNOWN_ISSUES.md # найденные попутно дефекты, `solution/-`, затем перенести своё. - Переносить: `src/`, `student-tests/`, `migrations/`, `Dockerfile`, - `docker-compose.yml`, `pyproject.toml`, `uv.lock`, `.python-version`, + `docker-compose.yml`, `infra/valkey/` (без `infra/README.md` + skeleton), `pyproject.toml`, `uv.lock`, `.python-version`, `config_example.toml`, `AGENTS.md`, `CLAUDE.md`, `.claude/`, `openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`. - Сливать, а не копировать поверх: `Makefile`, `.env.example`, diff --git a/Makefile b/Makefile index 58dc0566..98838429 100644 --- a/Makefile +++ b/Makefile @@ -30,18 +30,21 @@ test-persistence: # Приложение на хосте (свои цели; цели skeleton выше не менять) # ------------------------- -# Postgres из compose и миграции, затем сервис на хосте: -# 127.0.0.1:APP__PORT, reload по src/ +# Postgres из compose и миграции, Valkey из compose, затем сервис на +# хосте: 127.0.0.1:APP__PORT, reload по src/ .PHONY: run_dev -run_dev: upgrade +run_dev: upgrade start_cache APP__RUN_MODE=console uv run python -m src # шаблоны копируются только если файла ещё нет: локальные значения -# не затираются. В новый .env подставляется случайный пароль Postgres: -# в шаблоне он пустой, общего пароля стенда в git нет +# не затираются. В новый .env подставляются случайные пароли Postgres и +# Valkey: в шаблоне они пустые, общего пароля стенда в git нет .PHONY: env_setup env_setup: - @test -f .env || sed "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" .env.example > .env + @test -f .env || sed \ + -e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \ + -e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \ + .env.example > .env @test -f config.toml || cp config_example.toml config.toml @echo "env ready: .env, config.toml" @@ -56,9 +59,9 @@ APP__PORT ?= 8080 APP_OUT_PORT ?= 8080 DC=docker compose -# стенд: postgres -> migrate -> api. env_setup создаёт недостающие .env -# и config.toml из шаблонов: без config.toml compose не запустится -# (bind с create_host_path: false), без пароля — тоже +# стенд: postgres, valkey -> migrate -> api. env_setup создаёт +# недостающие .env и config.toml из шаблонов: без config.toml compose не +# запустится (bind с create_host_path: false), без паролей — тоже .PHONY: run_docker run_docker: env_setup DOCKER_BUILDKIT=1 $(DC) build @@ -115,6 +118,21 @@ wipe_data: fi +# ------------------------- +# Valkey (кэш карточек чатов) +# ------------------------- + +# Valkey стенда; --wait ждёт его healthcheck. Volume нет: кэш после +# рестарта пуст, данные — в PostgreSQL +.PHONY: start_cache +start_cache: env_setup + $(DC) up -d --wait valkey + +.PHONY: stop_cache +stop_cache: + $(DC) stop valkey + + # ------------------------- # Load benchmark (трек 1) # ------------------------- @@ -167,9 +185,10 @@ student_test: # образ на временной базе test_: сборка, миграции, отдельный # контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test, # затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу для разбора. +# Valkey общий с рабочим стендом: ключи кэша разделены именем базы. # $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку .PHONY: test_isolated -test_isolated: env_setup start_db +test_isolated: env_setup start_db start_cache $(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) .PHONY: lint diff --git a/config_example.toml b/config_example.toml index 09d28898..5a58e9eb 100644 --- a/config_example.toml +++ b/config_example.toml @@ -31,3 +31,15 @@ request_timeout_seconds = 6 session_ttl_seconds = 3600 # сколько хэшей пароля Argon2id считается одновременно: 64 MiB на каждый kdf_concurrency = 4 + +[cache] +# Адрес, порт и пароль Valkey приходят из .env (мосты к VALKEY_*) и из +# environment compose; здесь их не указывать. +# секунды на соединение и ответ Valkey; дольше — запрос идёт в PostgreSQL +timeout_seconds = 0.2 +# секунды, на которые кэш пропускается после отказа Valkey +retry_after_seconds = 5 +# секунды жизни карточки чата в кэше +chat_ttl_seconds = 3600 +# соединений в пуле клиента Valkey +max_connections = 10 diff --git a/docker-compose.yml b/docker-compose.yml index a52824aa..c677e656 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,7 @@ -# Стенд лабы 2: PostgreSQL, одноразовые миграции и API. Правила — -# .claude/rules/docker.md. Значения — из .env (шаблон .env.example); -# литералы только у адреса публикации 127.0.0.1 и у режима docker. +# Стенд лабы 2: PostgreSQL, Valkey (кэш), одноразовые миграции и API. +# Правила — .claude/rules/docker.md. Значения — из .env (шаблон +# .env.example); литералы только у адреса публикации 127.0.0.1 и у режима +# docker. name: mtusi-lab2 # окружение приложения: одно для api и migrate, чтобы они не разъехались @@ -12,6 +13,9 @@ x-app-env: &app-env DATABASE__USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env_setup} DATABASE__PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup} DATABASE__NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup} + CACHE__HOST: ${VALKEY_HOST:-valkey} + CACHE__PORT: ${VALKEY_PORT:-6379} + CACHE__PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example} # config.toml только на чтение, длинной записью: без файла запуск падает, # а не создаёт на хосте каталог config.toml/ @@ -56,6 +60,46 @@ services: start_period: 30s start_interval: 1s + # кэш карточек чатов: без volume, persistence выключен в valkey.conf — + # после рестарта кэш пуст, данные остаются в PostgreSQL + valkey: + image: valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd + restart: unless-stopped + # $$ — переменные контейнера: пароль не попадает в command литералом. + # Через docker-entrypoint.sh образа: он запускает сервер не от root + command: + - sh + - -c + - exec docker-entrypoint.sh valkey-server /usr/local/etc/valkey/valkey.conf --port "$$VALKEY_PORT" --requirepass "$$VALKEY_PASSWORD" + environment: + VALKEY_PORT: ${VALKEY_PORT:-6379} + VALKEY_PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example} + # пароль для valkey-cli в контейнере (healthcheck), без -a в команде + VALKEYCLI_AUTH: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example} + ports: + # только localhost: к нему подключается приложение в console + - "127.0.0.1:${VALKEY_OUT_PORT:-6380}:${VALKEY_PORT:-6379}" + volumes: + - type: bind + source: ./infra/valkey/valkey.conf + target: /usr/local/etc/valkey/valkey.conf + read_only: true + bind: + create_host_path: false + networks: + default: + # любое значение VALKEY_HOST указывает на этот сервис + aliases: + - ${VALKEY_HOST:-valkey} + healthcheck: + # PONG только после AUTH: проверяет и запуск, и пароль + test: ["CMD-SHELL", 'test "$$(valkey-cli -p "$$VALKEY_PORT" ping)" = PONG'] + interval: 5s + timeout: 3s + retries: 10 + start_period: 10s + start_interval: 1s + migrate: # образ собирает сервис api (make run_docker, make test_isolated) image: mtusi-messenger:lab2 @@ -82,6 +126,9 @@ services: depends_on: postgres: condition: service_healthy + # без кэша API работает, но в штатном стенде он есть с первого запроса + valkey: + condition: service_healthy migrate: condition: service_completed_successfully # healthcheck — из образа; SIGKILL не раньше, чем через 10 с diff --git a/infra/valkey/valkey.conf b/infra/valkey/valkey.conf new file mode 100644 index 00000000..712cf74e --- /dev/null +++ b/infra/valkey/valkey.conf @@ -0,0 +1,15 @@ +# Valkey стенда — кэш карточек чатов (change membership-cache). +# Монтируется в контейнер только на чтение. Порт и пароль задаёт command +# в docker-compose.yml из переменных .env, здесь их нет. + +# лимит памяти; при нехватке вытесняются давно не читанные ключи +maxmemory 64mb +maxmemory-policy allkeys-lru + +# persistence выключен: источник истины — PostgreSQL, кэш после рестарта +# пуст и заполняется заново при чтении +save "" +appendonly no + +# без пароля сервер не примет соединения извне контейнера +protected-mode yes diff --git a/openspec/changes/membership-cache/.openspec.yaml b/openspec/changes/membership-cache/.openspec.yaml new file mode 100644 index 00000000..480ad4de --- /dev/null +++ b/openspec/changes/membership-cache/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-01 diff --git a/openspec/changes/membership-cache/design.md b/openspec/changes/membership-cache/design.md new file mode 100644 index 00000000..93fa3fc4 --- /dev/null +++ b/openspec/changes/membership-cache/design.md @@ -0,0 +1,221 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. + +Горячий путь сейчас: каждый из `GET /chats/{id}`, `POST …/messages` и +`GET …/messages` вызывает `ChatService.get_chat_for_member` → +`chat_repo.get_chat`. Это `SELECT` чата со скалярным подзапросом +`array_agg(user_id ORDER BY position)` по `chat_members`. Ещё до него +каждый запрос делает `SELECT` сессии (`session-auth`). `MessageService` +создаёт `ChatService` с тем же `db_session`. По контракту участников +не меняют и не удаляют, чаты тоже не меняются. + +Правила: клиент хранилища — глобал своего модуля, его импортируют +только `src/main.py` и `src/api/dependencies.py`, сервис получает его +вторым параметром конструктора (`infra.md`, `service-layer.md`). Конфиги +сервисов — в `infra/`, монтируются только на чтение (`docker.md`). + +Проверено на версиях этого change пробным контейнером: + +- `valkey/valkey:9.1.2-trixie` — digest индекса `sha256:418652cf…` + (тот же, что у `:9`). Volume образ не объявляет, рабочий каталог + `/data`. `valkey-cli` берёт пароль из `VALKEYCLI_AUTH`. +- redis-py 8.1.0 (`redis.asyncio`) по умолчанию **повторяет** запрос с + backoff. При `socket_timeout=0.2`: замороженный Valkey + (`docker pause`) — `TimeoutError` через 6,27 с, остановленный — + `ConnectionError` через 3,98 с. С `Retry(NoBackoff(), 0)` — 0,20 с и + 0,00 с. + +## Goals / Non-Goals + +**Goals:** + +- Повторное чтение карточки чата не ходит в PostgreSQL: один `SELECT` + на чат за срок жизни записи, а не на каждый запрос. +- Отказ Valkey добавляет к запросу не больше таймаута клиента (0,2 с) и + только в первом запросе после отказа. +- Кэш нельзя застать в устаревшем состоянии: в нём только неизменяемые + данные. Это верно, пока базу меняет только API; исключение — restore + (Risks). + +**Non-Goals:** + +- Кэш истории, списка чатов и сессий (граница — спек `chat-cache`). +- Автоматические проверки отказа Valkey на особом стенде — + `failure-checks`. Здесь — ручной прогон в `evidence/`. +- Замер выигрыша под нагрузкой — `bench-postgres`; трек 1 на «5» + (stampede, stale read) не выбран. + +## Decisions + +### 1. Что кэшируется: карточка чата целиком + +Ключ `messenger:v1:{database}:chat:{chat_id}`, значение — JSON +`{"id", "title", "member_ids", "created_at"}`. `member_ids` хранится в +порядке создания, `created_at` — RFC 3339 с микросекундами, как в API. +`v1` в ключе позволяет сменить формат значения без чистки: новый код +просто не видит старых ключей. `{database}` — `settings.database.name`: +`make test_isolated` с базой `test_` не делит записи с рабочей +(спек `chat-cache`, «Ключи по базе»). + +Одна карточка обслуживает и `GET /chats/{id}`, и проверку членства: +второй структуры (множества участников) не нужно. + +*Альтернатива:* отдельное множество `SISMEMBER chat:{id}:members`. +Отвергнута: две структуры на одни данные, а `GET /chats/{id}` всё равно +нужна вся карточка. + +### 2. Cache-aside с записью при создании, без инвалидации + +- Чтение: Valkey → при промахе `chat_repo.get_chat` → `SET` с `EX`. + Отсутствующий чат не кэшируется (нет «отрицательных» записей): + иначе чтение по `id` до коммита создания запомнило бы «нет такого». +- Создание: после `commit()` `ChatService.create_chat` пишет карточку в + кэш. Запись после commit, а не до: в кэше не бывает чата, которого нет + в БД (откат создания не оставит записи). +- Инвалидации нет: карточка неизменяема. Если контракт позволит менять + участников (в обязательный API это не входит), понадобится удаление + ключа в той же операции. +- Срок — `[cache] chat_ttl_seconds` (3600): он ограничивает память, а + не свежесть. Сверху — `maxmemory 64mb` и `allkeys-lru` в конфиге + Valkey. + +### 3. Valkey в стенде + +- Сервис `valkey` в compose: `valkey/valkey:9.1.2-trixie@sha256:…`, + `restart: unless-stopped`; конфиг `infra/valkey/valkey.conf` только на + чтение: `maxmemory`, `maxmemory-policy allkeys-lru`, `save ""`, + `appendonly no`, `protected-mode yes`. Порт сервера — `VALKEY_PORT`, + публикация — `127.0.0.1:${VALKEY_OUT_PORT}`, алиас в сети — `VALKEY_HOST` + (как у Postgres, решение 7 `postgres-storage`). +- Пароль — `VALKEY_PASSWORD` в `.env`, в контейнер — переменной + окружения, на сервер — `--requirepass` в `command` через `sh -c` из + переменной контейнера (`$$VALKEY_PASSWORD`). В compose он не литерал. + Healthcheck — `valkey-cli -p $$VALKEY_PORT ping` с `VALKEYCLI_AUTH`. + Пароль виден в аргументах процесса внутри контейнера — как + `POSTGRES_PASSWORD` в `docker inspect`; для локального стенда + с публикацией только на `127.0.0.1` это допустимо. +- Volume нет: persistence выключен, кэш после рестарта пуст, и это + штатно (спек `chat-cache`, «Очистка и рестарт кэша»). +- `api` ждёт `valkey: service_healthy`, как и Postgres: в штатном стенде + кэш есть с первого запроса. Работать без него API умеет (решение 5). + +*Альтернатива:* Valkey без пароля — он доступен только из сети compose и +с `127.0.0.1`. Отвергнута: шаблон skeleton предполагает учётные данные +(`CACHE_URL_FILE`), а случайный пароль из `make env_setup` ничего не стоит. + +### 4. Код: клиент в infra, ключ и формат в repo + +- `src/infra/cache/client.py` — фабрика `create_cache(settings.cache)`: + `redis.asyncio.Redis` с `socket_timeout` и `socket_connect_timeout` из + `[cache] timeout_seconds` (0,2), пулом на `max_connections` (10) и + **`retry=Retry(NoBackoff(), 0)`** — без повторов (Context). Пул — + `BlockingConnectionPool` с ожиданием свободного соединения не дольше + того же таймаута: обычный пул при всплеске запросов сразу бросает + `MaxConnectionsError`, и здоровый Valkey пропускался бы как + отказавший. +- Обёртка `Cache` (там же) с `get(key)` и `set(key, value, ttl)` + поверх клиента: при `RedisError` и `OSError` не бросает, а возвращает + промах или `False`. После отказа включается пропуск на + `[cache] retry_after_seconds` (5): обращений к Valkey нет, каждый + запрос идёт сразу в PostgreSQL. В журнал — `warning` «Cache is + unavailable» один раз на отказ и `info` «Cache is available again» при + первом успехе после пропуска. +- `src/infra/cache/instance.py` — глобал `cache = Cache(create_cache(...))` + по образцу `db/session.py`. Закрытие (`aclose`) — в lifespan. +- `src/core/repos/chat_cache.py` — `get_chat(cache, chat_id)` и + `put_chat(cache, chat)`: ключ и JSON ↔ `ChatFullDTO`. Логики и логов + нет, как в остальных repo. +- `ChatService(db_session, cache)`, `MessageService(db_session, cache)`: + второй параметр конструктора; `MessageService` создаёт `ChatService` с + тем же кэшем. Фабрики в `dependencies.py` передают глобал. + +*Альтернатива:* кэш как декоратор над `chat_repo.get_chat`. Отвергнута: +repo не знает о кэше по правилу слоя, а запись после commit живёт в +сервисе. + +### 5. Отказ Valkey: обход, а не 503 + +Кэш не критичен для обязательного пути, поэтому отказ — промах: +запрос идёт в PostgreSQL, ответ тот же. `/health/ready` Valkey не +проверяет (спек `health`). Анонимного доступа это не открывает: +аутентификация — `SELECT` сессии в PostgreSQL, кэш её не касается. + +Цена отказа: остановленный Valkey — ≈ 0 мс (соединение отклоняется +сразу), замороженный — 0,2 с в первом запросе после отказа, дальше +5 с без обращений. Без отключения повторов было бы 4–6 с на запрос +(Context). + +*Альтернатива:* 503 при недоступности Valkey. Отвергнута: рубрика +допускает «корректно обходит кэш», а кэш без обхода ухудшал бы +доступность. + +### 6. Настройки и запуск + +- `[cache]`: `host`, `port`, `password` (`SecretStr`) — из `.env`; + `timeout_seconds`, `retry_after_seconds`, `chat_ttl_seconds`, + `max_connections` — `config.toml`. +- `.env.example`: `VALKEY_PASSWORD=` (пустой; `make env_setup` подставляет + случайный, как пароль Postgres), `VALKEY_HOST=valkey`, + `VALKEY_PORT=6379`, `VALKEY_OUT_PORT=6380`; мосты + `CACHE__HOST=127.0.0.1`, `CACHE__PORT=${VALKEY_OUT_PORT}`, + `CACHE__PASSWORD=${VALKEY_PASSWORD}`. В `x-app-env` compose — + `CACHE__HOST: ${VALKEY_HOST:-valkey}`, `CACHE__PORT: ${VALKEY_PORT:-6379}`, + `CACHE__PASSWORD: ${VALKEY_PASSWORD:?…}`. +- Существующий `.env` `make env_setup` не трогает: строки Valkey + добавляются руками по `.env.example`, это записано в `REPORT.md`. В + рабочем `.env` их добавит apply. +- `Makefile`: `start_cache` (`up -d --wait valkey`), `stop_cache`; + `run_dev: upgrade start_cache`; `test_isolated: env_setup start_db + start_cache`. Драйвер скилла в `start` вызывает `make upgrade + start_cache`. +- `scripts/restart.sh`: `stop api` → `restart postgres valkey` → + `up -d --wait postgres valkey` → `start api`. + +### 7. Evidence + +| Файл | Что | +|---|---| +| `evidence/cache/hits.md` | 50 чтений карточки: `idx_scan` таблицы `chats` (`pg_stat_user_tables`) растёт на 1, `keyspace_hits` Valkey — на 49; ключ, его `TTL` и вид значения (без текстов); число ключей с префиксами рабочей и тестовой базы после `make test_isolated` | +| `evidence/cache/outage.md` | `stop`, `start`, `pause`, `unpause` Valkey: ответы и время, `/health/ready` 200, записи `warning`/`info` в журнале | +| `evidence/cache/flush-restart.md` | `FLUSHALL` → тот же ответ, ключ снова есть; `scripts/restart.sh` перезапускает Valkey (`StartedAt`), `make test-persistence` — `PASS` | + +## Risks / Trade-offs + +- [Восстановление БД из backup (трек 2) при живом кэше: restore + откатывает базу мимо API, и в кэше остаются карточки чатов, созданных + после снятия backup. Для такого чата `GET /chats/{id}` отвечает 200 + вместо 404, история — 200 с пустым списком вместо 404, а отправка + сообщения проходит проверку членства по кэшу и падает на внешнем + ключе (500). Так же действует любая правка базы в обход API] → + Процедура восстановления в `track2-backup-restore` очищает Valkey + (`FLUSHALL`) после restore; записано в её задачах и в `REPORT.md`. + Срок записи ограничивает ошибку часом, но не устраняет её. +- [`make wipe_data` удаляет volume Postgres, а Valkey без volume + пересоздаётся `down -v`] → Кэш очищается вместе с данными. +- [Пропуск кэша на 5 с после отказа: в это время PostgreSQL получает + весь поток чтений карточек] → Это нагрузка без кэша, на которую база + и рассчитана; срок — настройка. +- [Рестарт Valkey: первая команда по соединению пула, открытому до + рестарта, получает `Connection reset by peer` и включает пропуск на + 5 с. Проверено в консоли, через прокси портов Docker Desktop: проверка + соединения при выдаче из пула обрыва не видит, а один немедленный + повтор на `ConnectionError` тоже получал reset] → Ответы те же, из + PostgreSQL; после пропуска кэш работает. Повторов нет, как и решено + выше. +- [Карточка в кэше живёт до часа после того, как чат стал бы недоступен] + → Чаты не удаляются и не меняются по контракту; при появлении такой + операции — удаление ключа в ней (решение 2). +- [`redis` — имя пакета клиента при сервере Valkey] → redis-py + совместим по протоколу и зрелее `valkey-py`; выбор записан в + `REPORT.md`. + +## Migration Plan + +Порядок: зависимость и настройки → compose, конфиг Valkey, `.env`, +Makefile, hook → infra-клиент → repo и сервисы → тесты → документы → +commit → evidence → `REPORT.md`. На рабочем стенде: добавить строки +Valkey в `.env`, затем `make run_docker`. Откат: `git revert` коммитов +change; данные не затронуты, Valkey хранит только кэш. diff --git a/openspec/changes/membership-cache/proposal.md b/openspec/changes/membership-cache/proposal.md new file mode 100644 index 00000000..b2b4ab9e --- /dev/null +++ b/openspec/changes/membership-cache/proposal.md @@ -0,0 +1,87 @@ +# 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/`. diff --git a/openspec/changes/membership-cache/specs/chat-cache/spec.md b/openspec/changes/membership-cache/specs/chat-cache/spec.md new file mode 100644 index 00000000..4236a674 --- /dev/null +++ b/openspec/changes/membership-cache/specs/chat-cache/spec.md @@ -0,0 +1,119 @@ +# Spec Delta + +## Purpose + +Как сервис кэширует карточку чата в Valkey: что хранится в кэше и чего +в нём нет, источник истины, срок и вытеснение записей, почему не нужна +инвалидация, обход кэша при его недоступности и поведение после очистки. + +## ADDED Requirements + +### Requirement: Кэш карточки чата + +Карточка чата — `id`, `title`, `member_ids` в порядке создания и +`created_at` — SHALL читаться сначала из Valkey, при промахе — из +PostgreSQL с записью в кэш. Созданный чат SHALL записываться в кэш +после commit. Источник истины — PostgreSQL: кэш MUST NOT содержать +карточку, которой нет в PostgreSQL, и ответ API из кэша MUST совпадать с +ответом из PostgreSQL. Из той же карточки берётся проверка членства в +`GET /api/v1/chats/{chat_id}`, `POST …/messages` и `GET …/messages`. + +#### Scenario: Повторное чтение чата + +- **WHEN** участник дважды запрашивает `GET /api/v1/chats/{chat_id}` +- **THEN** оба ответа 200 и совпадают с ответом на создание чата, в том + числе порядок `member_ids` + +#### Scenario: Проверка членства по карточке + +- **WHEN** чат только что создан, его участник пишет в него сообщение, + а посторонний запрашивает чат +- **THEN** участник получает 201, посторонний — 404 + +#### Scenario: Чтение из кэша + +- **WHEN** карточку одного чата читают 50 раз подряд +- **THEN** PostgreSQL читает таблицу `chats` для этого чата не больше + одного раза, остальные ответы — из Valkey + +### Requirement: Граница кэша + +История сообщений, список чатов пользователя и сессии MUST NOT +кэшироваться: история и список меняются с каждой записью, а отзыв сессии +обязан действовать сразу. Карточка чата после создания не меняется, +поэтому кэш не инвалидируется: устаревшей карточки не бывает. + +#### Scenario: Сообщение видно сразу + +- **WHEN** участник отправил сообщение и сразу читает историю +- **THEN** сообщение есть в истории + +#### Scenario: Новый чат в списке + +- **WHEN** пользователь создал чат и сразу запрашивает `GET /api/v1/chats` +- **THEN** чат есть в списке + +### Requirement: Срок и вытеснение + +Запись карточки SHALL храниться не дольше срока из настроек. Память +Valkey SHALL быть ограничена, при её нехватке Valkey SHALL вытеснять +давно не читанные ключи (LRU). Persistence Valkey выключен: потеря +кэша MUST NOT приводить к потере данных. + +#### Scenario: Срок записи + +- **WHEN** карточка записана в кэш +- **THEN** у её ключа есть срок, не больше настроенного + +### Requirement: Обход недоступного кэша + +Если Valkey недоступен или не ответил за таймаут клиента, запрос SHALL +обслуживаться из PostgreSQL с тем же ответом, что и с кэшем. Сервис +MUST NOT отвечать 500 и MUST NOT обслуживать запрос как анонимный. +Добавка к времени ответа SHALL быть ограничена таймаутом клиента; после +отказа кэш SHALL пропускаться на время из настроек, без ожидания +таймаута в каждом запросе. Отказ SHALL записываться в журнал с уровнем +`warning`. Когда Valkey снова доступен, сервис SHALL использовать кэш +без перезапуска. + +#### Scenario: Valkey остановлен + +- **WHEN** контейнер Valkey остановлен, и участник читает чат, пишет + сообщение и читает историю +- **THEN** ответы 200, 201 и 200 с теми же телами, что при работающем + кэше + +#### Scenario: Valkey завис + +- **WHEN** Valkey принимает соединения, но не отвечает + (`docker compose pause`) +- **THEN** запросы обслуживаются из PostgreSQL, и время ответа растёт + не больше чем на таймаут клиента + +#### Scenario: Valkey вернулся + +- **WHEN** Valkey снова запущен, а API не перезапускался +- **THEN** через время пропуска кэш снова отдаёт карточки + +### Requirement: Очистка и рестарт кэша + +После `FLUSHALL` или рестарта Valkey сервис SHALL отвечать так же, как +до них, и заново заполнять кэш при чтении. + +#### Scenario: Очистка кэша + +- **WHEN** выполнен `FLUSHALL` в Valkey, и участник читает чат +- **THEN** ответ 200 с той же карточкой, а ключ чата снова есть в кэше + +### Requirement: Ключи по базе + +Ключ карточки SHALL включать имя базы PostgreSQL, из которой она +прочитана. Два экземпляра API с разными базами на одном Valkey MUST NOT +видеть карточки друг друга. + +#### Scenario: Временная база + +- **WHEN** `make test_isolated` работает с базой `test_` при + запущенном рабочем стенде +- **THEN** ключи карточек тестового прогона отличаются от рабочих + префиксом с именем базы diff --git a/openspec/changes/membership-cache/specs/container-run/spec.md b/openspec/changes/membership-cache/specs/container-run/spec.md new file mode 100644 index 00000000..88fed3c9 --- /dev/null +++ b/openspec/changes/membership-cache/specs/container-run/spec.md @@ -0,0 +1,102 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Запуск через compose + +`make run_docker` SHALL собирать образ и поднимать стенд через +`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций и API. +API SHALL стартовать после готовности PostgreSQL и Valkey и успешных +миграций. Перед этим цель SHALL создавать недостающие `.env` и +`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать +существующие. `make stop` SHALL останавливать сервисы, `make down` — +удалять контейнеры, сохраняя volume, `make logs` — показывать журнал API. + +#### Scenario: Штатный запуск + +- **WHEN** в свежем clone выполнен `make run_docker` +- **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и + `make student_test` проходит + +### Requirement: Порты из .env + +Порты стенда и консольного запуска SHALL браться из одного `.env`: +- внутренний порт API — `APP__PORT`: параметр приложения `[app] port` в + формате настроек, на нём же работает healthcheck; +- внешний порт API — `APP_OUT_PORT`: порт на `127.0.0.1` хоста, + приложение его не читает; +- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает + сам сервер и использует API в docker; +- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1` + хоста для запуска в консоли; +- порт Valkey внутри сети compose — `VALKEY_PORT`, внешний — + `VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли. + +Если переменная порта API не задана, SHALL действовать 8080. Параметры +приложения в `.env` SHALL записываться в формате настроек +(`SECTION__FIELD`). Имя без секции допускается только для переменных, +которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST +NOT быть записаны в compose литералами. + +#### Scenario: Другой внешний порт + +- **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен + `make run_docker` +- **THEN** API доступно на `localhost:8090`, а внутри контейнера + сервис слушает `APP__PORT` + +#### Scenario: Другой внутренний порт + +- **WHEN** в `.env` задано `APP__PORT=9090` +- **THEN** сервис внутри контейнера слушает 9090, контейнер становится + `healthy`, а API доступно на `localhost:$APP_OUT_PORT` + +#### Scenario: Другой порт Postgres + +- **WHEN** в `.env` заданы `POSTGRES_PORT=5544` и + `POSTGRES_OUT_PORT=5545`, а compose не правился +- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает + 200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545` + +#### Scenario: Другой порт Valkey + +- **WHEN** в `.env` заданы другие `VALKEY_PORT` и `VALKEY_OUT_PORT`, а + compose не правился +- **THEN** `make run_docker` и `make run_dev` подключаются к Valkey на + новых портах, и кэш работает + +### Requirement: Публикация только на localhost + +Порты API, PostgreSQL и Valkey SHALL публиковаться в compose только на +`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не +переменной. Учебный стенд MUST NOT быть доступен с других машин сети. + +#### Scenario: Адрес публикации + +- **WHEN** для запущенных контейнеров API, Postgres и Valkey выполняется + `docker port` +- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0` + +### Requirement: Данные переживают рестарт стенда + +Данные PostgreSQL SHALL храниться в именованном volume. Скрипт +`scripts/restart.sh` SHALL перезапускать API и все используемые +хранилища — PostgreSQL и Valkey, — сохраняя volume, схему и данные: без +удаления volume, очистки и повторного наполнения. Скрипт SHALL быть +исполняемым, завершаться с кодом 0 только после перезапуска, +укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка +`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL проходить. + +#### Scenario: Рестарт hook-ом + +- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен + `scripts/restart.sh` +- **THEN** контейнеры API, Postgres и Valkey перезапущены (новое время + старта в `docker inspect`), а после готовности запрос с прежним + токеном получает 200 и видит своё сообщение + +#### Scenario: Публичная проверка сохранности + +- **WHEN** на запущенном стенде выполняется `make test-persistence + ACTION_SCRIPT=scripts/restart.sh` +- **THEN** команда завершается с кодом 0 и печатает `PASS` diff --git a/openspec/changes/membership-cache/specs/health/spec.md b/openspec/changes/membership-cache/specs/health/spec.md new file mode 100644 index 00000000..2d35020e --- /dev/null +++ b/openspec/changes/membership-cache/specs/health/spec.md @@ -0,0 +1,31 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Readiness + +`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`, +когда сервис может безопасно обслуживать обязательные запросы, и 503 с +`code` `unavailable` в формате ошибки, когда не может. На лабе 2 +критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к +нему с коротким таймаутом при каждом обращении. Valkey — кэш, без него +обязательные запросы обслуживаются из PostgreSQL, поэтому его +недоступность MUST NOT делать сервис неготовым. Проверка MUST NOT +требовать идентификации. + +#### Scenario: Сервис запущен + +- **WHEN** запуск сервиса завершён, PostgreSQL доступен, и клиент + запрашивает `GET /health/ready` +- **THEN** ответ 200, тело `{"status": "ok"}` + +#### Scenario: Хранилище не готово + +- **WHEN** PostgreSQL недоступен +- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже + таймаута проверки, а `GET /health/live` при этом отвечает 200 + +#### Scenario: Кэш недоступен + +- **WHEN** Valkey остановлен, а PostgreSQL доступен +- **THEN** `GET /health/ready` отвечает 200 diff --git a/openspec/changes/membership-cache/specs/service-configuration/spec.md b/openspec/changes/membership-cache/specs/service-configuration/spec.md new file mode 100644 index 00000000..effbd498 --- /dev/null +++ b/openspec/changes/membership-cache/specs/service-configuration/spec.md @@ -0,0 +1,41 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Подключение к Valkey + +Адрес, порт и пароль Valkey SHALL задаваться в секции `[cache]`, таймаут +клиента, время пропуска кэша после отказа, срок записей и размер пула — +тоже. Пароль SHALL иметь один источник — `VALKEY_PASSWORD` в `.env`, +который читает и контейнер Valkey. Новый `.env` из `make env_setup` +SHALL получать случайный пароль. Пароль MUST NOT попадать в журнал. + +#### Scenario: Пароль Valkey в одном месте + +- **WHEN** в `.env` меняется `VALKEY_PASSWORD`, и стенд пересоздаётся +- **THEN** Valkey и сервис в консоли и в docker используют новый пароль + без правки других файлов + +#### Scenario: Пароль Valkey не в журнале + +- **WHEN** сервис стартует и обращается к Valkey, в том числе при его + недоступности +- **THEN** в журнале нет значения пароля + +## MODIFIED Requirements + +### Requirement: Консоль и docker без правки конфигурации + +Переключение между запуском в консоли и в docker MUST NOT требовать +правки `.env`, `config.toml` или compose, в том числе +комментирования и раскомментирования блоков. В консоли сервис SHALL +подключаться к PostgreSQL и Valkey по адресам публикации на хосте из +`.env`, в docker — по адресам и портам внутри сети compose, которые +compose передаёт в окружение контейнера из переменных `.env`. + +#### Scenario: Консоль, затем docker + +- **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен + `make run_docker`, а файлы конфигурации между запусками не менялись +- **THEN** оба запуска доходят до `/health/ready` 200, видят одни и те + же данные и пишут карточки чатов в Valkey diff --git a/openspec/changes/membership-cache/specs/student-tests/spec.md b/openspec/changes/membership-cache/specs/student-tests/spec.md new file mode 100644 index 00000000..79f23c96 --- /dev/null +++ b/openspec/changes/membership-cache/specs/student-tests/spec.md @@ -0,0 +1,68 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Покрытие сценариев основных спеков + +Для каждого сценария основных спеков `api-conventions`, +`identification`, `sessions`, `users`, `chats`, `messages`, +`pagination`, `data-storage`, `chat-cache` и `health`, который +воспроизводится по HTTP против работающего сервера, SHALL быть тест. Из +имени или описания теста SHALL быть понятно, какой capability и +сценарий он проверяет. Сценарии, которые по HTTP не воспроизвести, +SHALL быть перечислены с причиной и способом проверки. + +#### Scenario: Сверка покрытия + +- **WHEN** проверяющий берёт любой сценарий перечисленных спеков +- **THEN** находится проверяющий его тест либо запись в списке + исключений с причиной + +### Requirement: Прогон на временной базе + +`make test_isolated` SHALL проверять образ, собранный из рабочего +дерева, в связке compose на временной базе `test_<имя рабочей базы>` в +PostgreSQL стенда, с Valkey стенда. Команда SHALL: поднять PostgreSQL и +Valkey, собрать образ, создать базу заново, применить к ней миграции +сервисом миграций compose, запустить отдельный контейнер API из +определения сервиса compose, в котором подменено только имя базы, +опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, дождаться +готовности, выполнить публичный smoke (`make test`) и весь набор +(`make student_test`) против этого контейнера, затем остановить и +удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если +не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API +MUST NOT затрагиваться, а карточки чатов тестового прогона в Valkey +отделены от рабочих именем базы в ключе (capability `chat-cache`). +Параллельный запуск двух прогонов не поддерживается. + +#### Scenario: Успешный прогон + +- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и + выполнен `make test_isolated` +- **THEN** smoke и набор прошли, код выхода 0, ни базы `test_`, ни + тестового контейнера после команды нет, число строк в таблицах + рабочей базы не изменилось, а рабочий API продолжает отвечать + +#### Scenario: Упавшие тесты + +- **WHEN** во время `make test_isolated` падает хотя бы один тест +- **THEN** код выхода ненулевой, журнал тестового контейнера выведен, + контейнер удалён, база `test_` удалена + +#### Scenario: Прерывание + +- **WHEN** `make test_isolated` прерван Ctrl+C +- **THEN** тестовый контейнер остановлен и удалён, база `test_` + удалена + +#### Scenario: Хвост прошлого прогона + +- **WHEN** тестовый контейнер или база `test_` остались от прогона, + убитого без уборки +- **THEN** следующий `make test_isolated` удаляет их и начинает заново + +#### Scenario: Сохранить базу для разбора + +- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` +- **THEN** после прогона тестовый контейнер удалён, база `test_` + остаётся, а команда печатает её имя diff --git a/openspec/changes/membership-cache/tasks.md b/openspec/changes/membership-cache/tasks.md new file mode 100644 index 00000000..7b834578 --- /dev/null +++ b/openspec/changes/membership-cache/tasks.md @@ -0,0 +1,110 @@ +# 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. Зависимость и настройки + +- [x] 1.1 `uv add "redis>=8.1,<9"` в основную группу с комментарием + (клиент для Valkey). Проверка: `uv lock --check`; `uv run python -c + "import redis; print(redis.__version__)"` — 8.1.x. +- [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:`; + `make env_setup` в пустом каталоге даёт непустые `POSTGRES_PASSWORD` и + `VALKEY_PASSWORD`. + +## 2. Стенд + +- [x] 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`. +- [x] 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. Код + +- [x] 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` после возврата; пароля в журнале нет. +- [x] 3.2 `src/core/repos/chat_cache.py`: ключ с именем базы и `v1`, + JSON ↔ `ChatFullDTO` (решение 1). Проверка: карточка после записи и + чтения равна исходной, включая порядок `member_ids` и микросекунды + `created_at`. +- [x] 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. Тесты + +- [x] 4.1 Тесты сценариев `chat-cache`, видимых по HTTP: «Повторное + чтение чата», «Проверка членства по карточке», «Сообщение видно + сразу», «Новый чат в списке». Проверка: тесты проходят против + консольного сервиса. +- [x] 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. Инструменты и документы + +- [x] 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`). +- [x] 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 и отчёт. diff --git a/openspec/specs/chat-cache/spec.md b/openspec/specs/chat-cache/spec.md new file mode 100644 index 00000000..67ef1526 --- /dev/null +++ b/openspec/specs/chat-cache/spec.md @@ -0,0 +1,119 @@ +# chat-cache Specification + +## Purpose + +Как сервис кэширует карточку чата в Valkey: что хранится в кэше и чего +в нём нет, источник истины, срок и вытеснение записей, почему не нужна +инвалидация, обход кэша при его недоступности и поведение после очистки. + +## Requirements + +### Requirement: Кэш карточки чата + +Карточка чата — `id`, `title`, `member_ids` в порядке создания и +`created_at` — SHALL читаться сначала из Valkey, при промахе — из +PostgreSQL с записью в кэш. Созданный чат SHALL записываться в кэш +после commit. Источник истины — PostgreSQL: кэш MUST NOT содержать +карточку, которой нет в PostgreSQL, и ответ API из кэша MUST совпадать с +ответом из PostgreSQL. Из той же карточки берётся проверка членства в +`GET /api/v1/chats/{chat_id}`, `POST …/messages` и `GET …/messages`. + +#### Scenario: Повторное чтение чата + +- **WHEN** участник дважды запрашивает `GET /api/v1/chats/{chat_id}` +- **THEN** оба ответа 200 и совпадают с ответом на создание чата, в том + числе порядок `member_ids` + +#### Scenario: Проверка членства по карточке + +- **WHEN** чат только что создан, его участник пишет в него сообщение, + а посторонний запрашивает чат +- **THEN** участник получает 201, посторонний — 404 + +#### Scenario: Чтение из кэша + +- **WHEN** карточку одного чата читают 50 раз подряд +- **THEN** PostgreSQL читает таблицу `chats` для этого чата не больше + одного раза, остальные ответы — из Valkey + +### Requirement: Граница кэша + +История сообщений, список чатов пользователя и сессии MUST NOT +кэшироваться: история и список меняются с каждой записью, а отзыв сессии +обязан действовать сразу. Карточка чата после создания не меняется, +поэтому кэш не инвалидируется: устаревшей карточки не бывает. + +#### Scenario: Сообщение видно сразу + +- **WHEN** участник отправил сообщение и сразу читает историю +- **THEN** сообщение есть в истории + +#### Scenario: Новый чат в списке + +- **WHEN** пользователь создал чат и сразу запрашивает `GET /api/v1/chats` +- **THEN** чат есть в списке + +### Requirement: Срок и вытеснение + +Запись карточки SHALL храниться не дольше срока из настроек. Память +Valkey SHALL быть ограничена, при её нехватке Valkey SHALL вытеснять +давно не читанные ключи (LRU). Persistence Valkey выключен: потеря +кэша MUST NOT приводить к потере данных. + +#### Scenario: Срок записи + +- **WHEN** карточка записана в кэш +- **THEN** у её ключа есть срок, не больше настроенного + +### Requirement: Обход недоступного кэша + +Если Valkey недоступен или не ответил за таймаут клиента, запрос SHALL +обслуживаться из PostgreSQL с тем же ответом, что и с кэшем. Сервис +MUST NOT отвечать 500 и MUST NOT обслуживать запрос как анонимный. +Добавка к времени ответа SHALL быть ограничена таймаутом клиента; после +отказа кэш SHALL пропускаться на время из настроек, без ожидания +таймаута в каждом запросе. Отказ SHALL записываться в журнал с уровнем +`warning`. Когда Valkey снова доступен, сервис SHALL использовать кэш +без перезапуска. + +#### Scenario: Valkey остановлен + +- **WHEN** контейнер Valkey остановлен, и участник читает чат, пишет + сообщение и читает историю +- **THEN** ответы 200, 201 и 200 с теми же телами, что при работающем + кэше + +#### Scenario: Valkey завис + +- **WHEN** Valkey принимает соединения, но не отвечает + (`docker compose pause`) +- **THEN** запросы обслуживаются из PostgreSQL, и время ответа растёт + не больше чем на таймаут клиента + +#### Scenario: Valkey вернулся + +- **WHEN** Valkey снова запущен, а API не перезапускался +- **THEN** через время пропуска кэш снова отдаёт карточки + +### Requirement: Очистка и рестарт кэша + +После `FLUSHALL` или рестарта Valkey сервис SHALL отвечать так же, как +до них, и заново заполнять кэш при чтении. + +#### Scenario: Очистка кэша + +- **WHEN** выполнен `FLUSHALL` в Valkey, и участник читает чат +- **THEN** ответ 200 с той же карточкой, а ключ чата снова есть в кэше + +### Requirement: Ключи по базе + +Ключ карточки SHALL включать имя базы PostgreSQL, из которой она +прочитана. Два экземпляра API с разными базами на одном Valkey MUST NOT +видеть карточки друг друга. + +#### Scenario: Временная база + +- **WHEN** `make test_isolated` работает с базой `test_` при + запущенном рабочем стенде +- **THEN** ключи карточек тестового прогона отличаются от рабочих + префиксом с именем базы diff --git a/openspec/specs/container-run/spec.md b/openspec/specs/container-run/spec.md index ce05c80d..a26c4bf4 100644 --- a/openspec/specs/container-run/spec.md +++ b/openspec/specs/container-run/spec.md @@ -3,21 +3,21 @@ ## Purpose Как стенд сервиса запускается и настраивается: compose с PostgreSQL, -одноразовыми миграциями и API (`make run_docker`), публикация портов -только на localhost, конфигурация на старте, сохранность данных при -рестарте стенда и явное удаление учебных данных. +Valkey, одноразовыми миграциями и API (`make run_docker`), публикация +портов только на localhost, конфигурация на старте, сохранность данных +при рестарте стенда и явное удаление учебных данных. ## Requirements ### Requirement: Запуск через compose `make run_docker` SHALL собирать образ и поднимать стенд через -`docker compose`: PostgreSQL, одноразовый сервис миграций и API. API -SHALL стартовать после готовности PostgreSQL и успешных миграций. -Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из -шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие. -`make stop` SHALL останавливать сервисы, `make down` — удалять -контейнеры, сохраняя volume, `make logs` — показывать журнал API. +`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций и API. +API SHALL стартовать после готовности PostgreSQL и Valkey и успешных +миграций. Перед этим цель SHALL создавать недостающие `.env` и +`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать +существующие. `make stop` SHALL останавливать сервисы, `make down` — +удалять контейнеры, сохраняя volume, `make logs` — показывать журнал API. #### Scenario: Штатный запуск @@ -35,13 +35,15 @@ SHALL стартовать после готовности PostgreSQL и усп - порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает сам сервер и использует API в docker; - внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1` - хоста для запуска в консоли. + хоста для запуска в консоли; +- порт Valkey внутри сети compose — `VALKEY_PORT`, внешний — + `VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли. Если переменная порта API не задана, SHALL действовать 8080. Параметры приложения в `.env` SHALL записываться в формате настроек (`SECTION__FIELD`). Имя без секции допускается только для переменных, -которые приложение не читает. Адрес и порт PostgreSQL MUST NOT быть -записаны в compose литералами. +которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST +NOT быть записаны в compose литералами. #### Scenario: Другой внешний порт @@ -63,6 +65,13 @@ SHALL стартовать после готовности PostgreSQL и усп - **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает 200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545` +#### Scenario: Другой порт Valkey + +- **WHEN** в `.env` заданы другие `VALKEY_PORT` и `VALKEY_OUT_PORT`, а + compose не правился +- **THEN** `make run_docker` и `make run_dev` подключаются к Valkey на + новых портах, и кэш работает + ### Requirement: Оба способа запуска описаны в REPORT.md Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два @@ -80,13 +89,13 @@ SHALL стартовать после готовности PostgreSQL и усп ### Requirement: Публикация только на localhost -Порты API и PostgreSQL SHALL публиковаться в compose только на +Порты API, PostgreSQL и Valkey SHALL публиковаться в compose только на `127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не переменной. Учебный стенд MUST NOT быть доступен с других машин сети. #### Scenario: Адрес публикации -- **WHEN** для запущенных контейнеров API и Postgres выполняется +- **WHEN** для запущенных контейнеров API, Postgres и Valkey выполняется `docker port` - **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0` @@ -121,19 +130,20 @@ compose, и приложению, SHALL передаваться через `env Данные PostgreSQL SHALL храниться в именованном volume. Скрипт `scripts/restart.sh` SHALL перезапускать API и все используемые -хранилища, сохраняя volume, схему и данные: без удаления volume, -очистки и повторного наполнения. Скрипт SHALL быть исполняемым, -завершаться с кодом 0 только после перезапуска, укладываться в 90 с и -MUST NOT печатать секреты. Публичная проверка `make test-persistence -ACTION_SCRIPT=scripts/restart.sh` SHALL проходить. +хранилища — PostgreSQL и Valkey, — сохраняя volume, схему и данные: без +удаления volume, очистки и повторного наполнения. Скрипт SHALL быть +исполняемым, завершаться с кодом 0 только после перезапуска, +укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка +`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL +проходить. #### Scenario: Рестарт hook-ом - **WHEN** пользователь вошёл, отправил сообщение, затем выполнен `scripts/restart.sh` -- **THEN** контейнеры API и Postgres перезапущены (новое время старта в - `docker inspect`), а после готовности запрос с прежним токеном - получает 200 и видит своё сообщение +- **THEN** контейнеры API, Postgres и Valkey перезапущены (новое время + старта в `docker inspect`), а после готовности запрос с прежним + токеном получает 200 и видит своё сообщение #### Scenario: Публичная проверка сохранности diff --git a/openspec/specs/health/spec.md b/openspec/specs/health/spec.md index 0c035491..a49b2725 100644 --- a/openspec/specs/health/spec.md +++ b/openspec/specs/health/spec.md @@ -25,7 +25,9 @@ MUST NOT зависеть от состояния хранилища. когда сервис может безопасно обслуживать обязательные запросы, и 503 с `code` `unavailable` в формате ошибки, когда не может. На лабе 2 критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к -нему с коротким таймаутом при каждом обращении. Проверка MUST NOT +нему с коротким таймаутом при каждом обращении. Valkey — кэш, без него +обязательные запросы обслуживаются из PostgreSQL, поэтому его +недоступность MUST NOT делать сервис неготовым. Проверка MUST NOT требовать идентификации. #### Scenario: Сервис запущен @@ -40,6 +42,11 @@ MUST NOT зависеть от состояния хранилища. - **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже таймаута проверки, а `GET /health/live` при этом отвечает 200 +#### Scenario: Кэш недоступен + +- **WHEN** Valkey остановлен, а PostgreSQL доступен +- **THEN** `GET /health/ready` отвечает 200 + ### Requirement: Health вне версии API и без идентификации Эндпоинты health SHALL находиться вне префикса `/api/v1`, MUST NOT diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 0e1f769c..aa4324ac 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -109,16 +109,36 @@ SHALL иметь один источник — `POSTGRES_PASSWORD` в `.env`, к Переключение между запуском в консоли и в docker MUST NOT требовать правки `.env`, `config.toml` или compose, в том числе комментирования и раскомментирования блоков. В консоли сервис SHALL -подключаться к Postgres по адресу публикации на хосте из `.env`, в -docker — по адресу и порту Postgres внутри сети compose, которые compose -передаёт в окружение контейнера из переменных `.env`. +подключаться к PostgreSQL и Valkey по адресам публикации на хосте из +`.env`, в docker — по адресам и портам внутри сети compose, которые +compose передаёт в окружение контейнера из переменных `.env`. #### Scenario: Консоль, затем docker - **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен `make run_docker`, а файлы конфигурации между запусками не менялись -- **THEN** оба запуска доходят до `/health/ready` 200 и видят одни и - те же данные +- **THEN** оба запуска доходят до `/health/ready` 200, видят одни и те + же данные и пишут карточки чатов в Valkey + +### Requirement: Подключение к Valkey + +Адрес, порт и пароль Valkey SHALL задаваться в секции `[cache]`, таймаут +клиента, время пропуска кэша после отказа, срок записей и размер пула — +тоже. Пароль SHALL иметь один источник — `VALKEY_PASSWORD` в `.env`, +который читает и контейнер Valkey. Новый `.env` из `make env_setup` +SHALL получать случайный пароль. Пароль MUST NOT попадать в журнал. + +#### Scenario: Пароль Valkey в одном месте + +- **WHEN** в `.env` меняется `VALKEY_PASSWORD`, и стенд пересоздаётся +- **THEN** Valkey и сервис в консоли и в docker используют новый пароль + без правки других файлов + +#### Scenario: Пароль Valkey не в журнале + +- **WHEN** сервис стартует и обращается к Valkey, в том числе при его + недоступности +- **THEN** в журнале нет значения пароля ### Requirement: Срок жизни сессии diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index b32cbf30..9ac8d4f6 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -134,12 +134,12 @@ SHALL проходить против сервера, запущенного н ### Requirement: Покрытие сценариев основных спеков Для каждого сценария основных спеков `api-conventions`, -`identification`, `users`, `chats`, `messages`, `pagination`, -`data-storage` и `health`, который воспроизводится по HTTP против -работающего сервера, SHALL быть тест. Из имени или описания теста SHALL -быть понятно, какой capability и сценарий он проверяет. Сценарии, -которые по HTTP не воспроизвести, SHALL быть перечислены с причиной и -способом проверки. +`identification`, `sessions`, `users`, `chats`, `messages`, +`pagination`, `data-storage`, `chat-cache` и `health`, который +воспроизводится по HTTP против работающего сервера, SHALL быть тест. Из +имени или описания теста SHALL быть понятно, какой capability и +сценарий он проверяет. Сценарии, которые по HTTP не воспроизвести, +SHALL быть перечислены с причиной и способом проверки. #### Scenario: Сверка покрытия @@ -178,16 +178,18 @@ SHALL проходить против сервера, запущенного н `make test_isolated` SHALL проверять образ, собранный из рабочего дерева, в связке compose на временной базе `test_<имя рабочей базы>` в -PostgreSQL стенда. Команда SHALL: собрать образ, создать базу заново, -применить к ней миграции сервисом миграций compose, запустить отдельный -контейнер API из определения сервиса compose, в котором подменено только -имя базы, опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, -дождаться готовности, выполнить публичный smoke (`make test`) и весь -набор (`make student_test`) против этого контейнера, затем остановить и +PostgreSQL стенда, с Valkey стенда. Команда SHALL: поднять PostgreSQL и +Valkey, собрать образ, создать базу заново, применить к ней миграции +сервисом миграций compose, запустить отдельный контейнер API из +определения сервиса compose, в котором подменено только имя базы, +опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, дождаться +готовности, выполнить публичный smoke (`make test`) и весь набор +(`make student_test`) против этого контейнера, затем остановить и удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API -MUST NOT затрагиваться. Параллельный запуск двух прогонов не -поддерживается. +MUST NOT затрагиваться, а карточки чатов тестового прогона в Valkey +отделены от рабочих именем базы в ключе (capability `chat-cache`). +Параллельный запуск двух прогонов не поддерживается. #### Scenario: Успешный прогон diff --git a/pyproject.toml b/pyproject.toml index 63532855..640eae7d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,6 +18,8 @@ dependencies = [ "alembic>=1.20.0,<2", # Argon2id для паролей: bcrypt режет пароль на 72 байтах, lab7 — Argon2id "argon2-cffi>=25.1.0,<26", + # клиент Valkey: протокол тот же, redis.asyncio зрелее valkey-py + "redis>=8.1,<9", ] [project.optional-dependencies] diff --git a/scripts/restart.sh b/scripts/restart.sh index 6c996850..64a81780 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -2,15 +2,16 @@ set -eu # Restart hook для make test-persistence (tests/README.md) по образцу # scripts/restart.example.sh; правила — .claude/rules/docker.md. -# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres) с -# сохранением volume, схемы и данных: без down -v, очистки и повторного -# наполнения. start api запускает и его зависимость migrate: повторный -# прогон миграций ничего не меняет. Готовность API ждёт сам тест. -# Секреты не печатает. +# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres и +# Valkey) с сохранением volume, схемы и данных: без down -v, FLUSHALL и +# повторного наполнения. Кэш Valkey после рестарта пуст: persistence у +# него выключен, данные — в Postgres. start api запускает и его +# зависимость migrate: повторный прогон миграций ничего не меняет. +# Готовность API ждёт сам тест. Секреты не печатает. cd "$(dirname "$0")/.." docker compose stop api -docker compose restart postgres -# тот же контейнер: --wait только дожидается его healthcheck -docker compose up -d --wait postgres +docker compose restart postgres valkey +# те же контейнеры: --wait только дожидается их healthcheck +docker compose up -d --wait postgres valkey docker compose start api diff --git a/src/api/dependencies.py b/src/api/dependencies.py index a909a9b4..23048998 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -1,4 +1,8 @@ -"""Зависимости ручек: сессия БД, сервисы, вход и текущая сессия, страница.""" +"""Зависимости ручек: сессия БД, сервисы, вход и текущая сессия, страница. + +Сервисы получают сессию БД, а чаты и сообщения — ещё и кэш процесса +(`src/infra/cache/instance.py`). +""" import asyncio import base64 @@ -21,6 +25,7 @@ from src.core.services import ( SessionService, UserService, ) +from src.infra.cache.instance import cache from src.infra.db import is_db_unavailable, ping from src.infra.db.session import engine, session_factory from src.infra.logger import AbstractLogger, current_user_id, get_logger @@ -85,11 +90,11 @@ async def get_user_service(db_session: DbSessionDep) -> UserService: async def get_chat_service(db_session: DbSessionDep) -> ChatService: - return ChatService(db_session=db_session) + return ChatService(db_session=db_session, cache=cache) async def get_message_service(db_session: DbSessionDep) -> MessageService: - return MessageService(db_session=db_session) + return MessageService(db_session=db_session, cache=cache) async def get_session_service(db_session: DbSessionDep) -> SessionService: diff --git a/src/config/settings.py b/src/config/settings.py index d923ffba..5dc3104b 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -93,6 +93,28 @@ class Auth(BaseModel): kdf_concurrency: int = Field(default=4, gt=0) +class Cache(BaseModel): + """Подключение к Valkey (кэш карточек чатов). + + Адрес и пароль приходят из `.env`: в console — мостами к `VALKEY_*`, + в docker — из `environment` compose. Таймауты и срок записей — из + `config.toml`. + """ + + host: str = "127.0.0.1" + port: int = Field(default=6379, ge=1, le=65535) + password: SecretStr = SecretStr("") + + # секунды на соединение и ответ; дольше — запрос идёт в PostgreSQL + timeout_seconds: float = Field(default=0.2, gt=0) + # секунды, на которые кэш пропускается после отказа Valkey + retry_after_seconds: float = Field(default=5, gt=0) + # секунды жизни карточки чата в кэше + chat_ttl_seconds: int = Field(default=3600, gt=0) + # соединений в пуле клиента + max_connections: int = Field(default=10, ge=1) + + class Settings(BaseSettings): model_config = SettingsConfigDict( extra="ignore", @@ -105,6 +127,7 @@ class Settings(BaseSettings): app: App = App() database: Database = Database() auth: Auth = Auth() + cache: Cache = Cache() @classmethod def settings_customise_sources( diff --git a/src/core/repos/chat_cache.py b/src/core/repos/chat_cache.py new file mode 100644 index 00000000..25181056 --- /dev/null +++ b/src/core/repos/chat_cache.py @@ -0,0 +1,61 @@ +"""Карточка чата в Valkey: ключ и формат значения. + +Ключ — `messenger:v1:{база}:chat:{chat_id}`: имя базы разделяет рабочий +стенд и `make test_isolated` на одном Valkey. Значение — JSON карточки, +время — в формате API, с микросекундами. Отказ Valkey здесь не виден: +`Cache` отдаёт промах (design change `membership-cache`, решения 1, 5). +""" + +import json +from uuid import UUID + +from src.infra.cache import Cache +from src.schemas import dataclasses +from src.utils.constants import CACHE_KEY_PREFIX +from src.utils.utc import from_rfc3339, to_rfc3339 + + +def _key(cache: Cache, chat_id: UUID) -> str: + return f"{CACHE_KEY_PREFIX}:{cache.namespace}:chat:{chat_id}" + + +async def get_chat( + cache: Cache, + *, + chat_id: UUID, +) -> dataclasses.ChatFullDTO | None: + """Карточка из кэша; `None` — промах или Valkey недоступен.""" + value = await cache.get(_key(cache, chat_id)) + if value is None: + return None + data = json.loads(value) + return dataclasses.ChatFullDTO( + id=UUID(data["id"]), + title=data["title"], + member_ids=tuple(UUID(member_id) for member_id in data["member_ids"]), + created_at=from_rfc3339(data["created_at"]), + ) + + +async def put_chat( + cache: Cache, + *, + chat: dataclasses.ChatFullDTO, + ttl_seconds: int, +) -> bool: + """Записать карточку со сроком; `False` — Valkey недоступен.""" + value = json.dumps( + { + "id": str(chat.id), + "title": chat.title, + "member_ids": [str(member_id) for member_id in chat.member_ids], + "created_at": to_rfc3339(chat.created_at), + }, + ensure_ascii=False, + separators=(",", ":"), + ) + return await cache.set( + _key(cache, chat.id), + value, + ttl_seconds=ttl_seconds, + ) diff --git a/src/core/services/chat.py b/src/core/services/chat.py index e17b28b4..7f33d6c8 100644 --- a/src/core/services/chat.py +++ b/src/core/services/chat.py @@ -3,10 +3,13 @@ from uuid import UUID, uuid4 from sqlalchemy.ext.asyncio import AsyncSession +from src.config import settings from src.core import exceptions from src.core.repos import chat as chat_repo +from src.core.repos import chat_cache as chat_cache_repo from src.core.repos import user as user_repo from src.core.services.pagination import decode_page_cursor, split_page +from src.infra.cache import Cache from src.infra.logger import AbstractLogger, get_logger from src.schemas import dataclasses from src.utils.cursor import user_chats_scope @@ -16,8 +19,15 @@ logger: AbstractLogger = get_logger().bind(module="chat_service") class ChatService: - def __init__(self, db_session: AsyncSession) -> None: + """Чаты; карточка чата кэшируется в Valkey. + + Карточка после создания не меняется, поэтому кэш не инвалидируется + (design change `membership-cache`, решение 2). + """ + + def __init__(self, db_session: AsyncSession, cache: Cache) -> None: self.db_session = db_session + self.cache = cache async def create_chat( self, @@ -58,6 +68,13 @@ class ChatService: ) await self.db_session.commit() log.info("Created chat", chat_id=chat.id) + # после commit: откат создания не оставит в кэше чата, которого + # нет в БД + await chat_cache_repo.put_chat( + cache=self.cache, + chat=chat, + ttl_seconds=settings.cache.chat_ttl_seconds, + ) return chat async def get_chat_for_member( @@ -69,11 +86,24 @@ class ChatService: """Чат, если пользователь в нём состоит; иначе `ChatNotFound`. Нет чата и чужой чат неразличимы: 404 не раскрывает существование. + Карточка — из кэша, при промахе — из БД с записью в кэш. Чат, + которого нет, не кэшируется. """ - chat = await chat_repo.get_chat( - db_session=self.db_session, + chat = await chat_cache_repo.get_chat( + cache=self.cache, chat_id=chat_id, ) + if chat is None: + chat = await chat_repo.get_chat( + db_session=self.db_session, + chat_id=chat_id, + ) + if chat is not None: + await chat_cache_repo.put_chat( + cache=self.cache, + chat=chat, + ttl_seconds=settings.cache.chat_ttl_seconds, + ) if chat is None or user_id not in chat.member_ids: raise exceptions.ChatNotFound return chat diff --git a/src/core/services/message.py b/src/core/services/message.py index f0ecb989..bc9c99be 100644 --- a/src/core/services/message.py +++ b/src/core/services/message.py @@ -5,6 +5,7 @@ from sqlalchemy.ext.asyncio import AsyncSession from src.core.repos import message as message_repo from src.core.services.chat import ChatService from src.core.services.pagination import decode_page_cursor, split_page +from src.infra.cache import Cache from src.infra.logger import AbstractLogger, get_logger from src.schemas import dataclasses from src.utils.cursor import chat_messages_scope @@ -14,8 +15,14 @@ logger: AbstractLogger = get_logger().bind(module="message_service") class MessageService: - def __init__(self, db_session: AsyncSession) -> None: + """Сообщения; история не кэшируется, членство — по карточке чата.""" + + def __init__(self, db_session: AsyncSession, cache: Cache) -> None: self.db_session = db_session + self.cache = cache + + def _chats(self) -> ChatService: + return ChatService(db_session=self.db_session, cache=self.cache) async def send_message( self, @@ -25,9 +32,10 @@ class MessageService: text: str, ) -> dataclasses.MessageFullDTO: log = logger.bind(method="send_message", chat_id=chat_id) - # состав чата не меняется, поэтому проверка членства не устареет; - # составной внешний ключ сообщения — страховка на уровне БД - await ChatService(db_session=self.db_session).get_chat_for_member( + # состав чата не меняется, поэтому проверка членства (в том числе + # по кэшу) не устареет; составной внешний ключ сообщения — + # страховка на уровне БД + await self._chats().get_chat_for_member( chat_id=chat_id, user_id=sender_id, ) @@ -58,7 +66,7 @@ class MessageService: limit: int, cursor: str | None, ) -> dataclasses.MessagePageDTO: - await ChatService(db_session=self.db_session).get_chat_for_member( + await self._chats().get_chat_for_member( chat_id=chat_id, user_id=user_id, ) diff --git a/src/infra/cache/__init__.py b/src/infra/cache/__init__.py new file mode 100644 index 00000000..4a6e53f5 --- /dev/null +++ b/src/infra/cache/__init__.py @@ -0,0 +1,6 @@ +from src.infra.cache.client import Cache, create_cache + +__all__ = [ + "Cache", + "create_cache", +] diff --git a/src/infra/cache/client.py b/src/infra/cache/client.py new file mode 100644 index 00000000..ab47a9a5 --- /dev/null +++ b/src/infra/cache/client.py @@ -0,0 +1,113 @@ +"""Клиент Valkey без повторов и с обходом при отказе. + +redis-py по умолчанию повторяет команду с backoff: замороженный Valkey +задерживал запрос на 6 с вместо таймаута клиента (design change +`membership-cache`, Context). Здесь повторов нет, а после отказа кэш +пропускается на `[cache] retry_after_seconds`: запросы идут сразу в +PostgreSQL, не дожидаясь таймаута каждый раз. +""" + +import time + +from redis.asyncio import BlockingConnectionPool, Redis +from redis.backoff import NoBackoff +from redis.exceptions import RedisError +from redis.retry import Retry + +from src.config.settings import Cache as CacheSettings +from src.infra.logger import AbstractLogger, get_logger + +logger: AbstractLogger = get_logger().bind(module="cache") + + +class Cache: + """Кэш поверх клиента Valkey: отказ — промах, а не исключение. + + `namespace` — имя базы PostgreSQL, из которой читаются значения: на + одном Valkey ключи разных баз не пересекаются. + """ + + def __init__( + self, + client: Redis, + *, + namespace: str, + retry_after_seconds: float, + ) -> None: + self.namespace = namespace + self._client = client + self._retry_after_seconds = retry_after_seconds + # monotonic-время конца пропуска; None — кэш работает + self._skip_until: float | None = None + + async def get(self, key: str) -> str | None: + """Значение ключа; `None` — промах, в том числе из-за отказа.""" + if self._skipping(): + return None + try: + value = await self._client.get(key) + except (RedisError, OSError) as e: + self._failed(e) + return None + self._succeeded() + return value + + async def set(self, key: str, value: str, *, ttl_seconds: int) -> bool: + """Записать со сроком; `False` — не записано из-за отказа.""" + if self._skipping(): + return False + try: + await self._client.set(key, value, ex=ttl_seconds) + except (RedisError, OSError) as e: + self._failed(e) + return False + self._succeeded() + return True + + async def aclose(self) -> None: + await self._client.aclose() + + def _skipping(self) -> bool: + return ( + self._skip_until is not None + and time.monotonic() < self._skip_until + ) + + def _failed(self, error: Exception) -> None: + # warning — один на отказ: неудачные пробы после пропуска молчат + if self._skip_until is None: + logger.warning( + "Cache is unavailable", + error=str(error), + error_type=type(error).__name__, + retry_after_seconds=self._retry_after_seconds, + ) + self._skip_until = time.monotonic() + self._retry_after_seconds + + def _succeeded(self) -> None: + if self._skip_until is not None: + self._skip_until = None + logger.info("Cache is available again") + + +def create_cache(cache: CacheSettings, *, namespace: str) -> Cache: + """Кэш с пулом и таймаутами из `[cache]`; соединения — лениво.""" + # BlockingConnectionPool: при всплеске запросов ждёт свободное + # соединение, а обычный пул сразу бросал бы MaxConnectionsError, и + # здоровый Valkey пропускался бы как отказавший + pool = BlockingConnectionPool( + host=cache.host, + port=cache.port, + password=cache.password.get_secret_value() or None, + max_connections=cache.max_connections, + timeout=cache.timeout_seconds, + socket_timeout=cache.timeout_seconds, + socket_connect_timeout=cache.timeout_seconds, + retry=Retry(NoBackoff(), 0), + decode_responses=True, + ) + return Cache( + Redis.from_pool(pool), + namespace=namespace, + retry_after_seconds=cache.retry_after_seconds, + ) diff --git a/src/infra/cache/instance.py b/src/infra/cache/instance.py new file mode 100644 index 00000000..90666237 --- /dev/null +++ b/src/infra/cache/instance.py @@ -0,0 +1,13 @@ +"""Кэш процесса API (Valkey). + +Создаётся при импорте по `settings.cache`, соединения пул открывает +лениво. Импортируют модуль только `src/main.py` (закрытие в lifespan) и +`src/api/dependencies.py`, как `src/infra/db/session.py`. Ключи — по +имени базы из `settings.database`: `make test_isolated` с базой +`test_` не видит карточек рабочей. +""" + +from src.config import settings +from src.infra.cache.client import create_cache + +cache = create_cache(settings.cache, namespace=settings.database.name) diff --git a/src/main.py b/src/main.py index 8e5fde34..e003e1aa 100644 --- a/src/main.py +++ b/src/main.py @@ -8,6 +8,7 @@ from src.api import errors from src.api.middlewares import RequestContextMiddleware from src.api.routers import health_router, v1_router from src.config import settings +from src.infra.cache.instance import cache from src.infra.db.session import engine from src.infra.logger import AbstractLogger, get_logger from src.infra.password import prepare_dummy_hash @@ -19,10 +20,12 @@ logger: AbstractLogger = get_logger().bind(module="startup") @asynccontextmanager async def lifespan(_: FastAPI) -> AsyncIterator[None]: database = settings.database - # engine подключается лениво: без Postgres сервис стартует, а - # /health/ready отвечает 503 + # engine и кэш подключаются лениво: без Postgres сервис стартует, а + # /health/ready отвечает 503; без Valkey запросы идут в Postgres if not database.password.get_secret_value(): logger.warning("Database password is empty") + if not settings.cache.password.get_secret_value(): + logger.warning("Cache password is empty") # ~30 мс CPU при старте: время ответа на вход с неизвестным username # ровное с первого запроса await prepare_dummy_hash() @@ -34,11 +37,14 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: database_host=database.host, database_port=database.port, database_name=database.name, + cache_host=settings.cache.host, + cache_port=settings.cache.port, ) try: yield finally: await engine.dispose() + await cache.aclose() logger.info("Stopped API") diff --git a/src/utils/constants.py b/src/utils/constants.py index 51d2a0f3..0a58ee91 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -53,3 +53,8 @@ READINESS_DB_TIMEOUT_SECONDS = 2 # секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой # срок; дальше соединение обрывается DB_CLOSE_TIMEOUT_SECONDS = 2 + +# кэш (Valkey) +# начало ключей; v1 — формат значений: новый формат — v2, и старые ключи +# не читаются без чистки кэша +CACHE_KEY_PREFIX = "messenger:v1" diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py index 3466d274..84362383 100644 --- a/student-tests/run_isolated.py +++ b/student-tests/run_isolated.py @@ -5,8 +5,10 @@ подменой только `DATABASE__NAME`, прогоняет `make test` и `make student_test`, затем удаляет контейнер и базу — при любом исходе, в том числе по Ctrl+C. Рабочая база и рабочий контейнер API не -трогаются. Только stdlib: всё через docker compose и make. Решение 12 -design change `postgres-storage`. +трогаются. Valkey стенда общий: ключи кэша включают имя базы, и +карточки тестового прогона не смешиваются с рабочими. Только stdlib: +всё через docker compose и make. Решение 12 design change +`postgres-storage`. Запускается напрямую `$(PYTHON)`, как проверки skeleton, а не через `uv run`: uv пересылает SIGINT дочернему процессу, хотя тот уже получил diff --git a/student-tests/spec_coverage.py b/student-tests/spec_coverage.py index 547269d8..23f80826 100644 --- a/student-tests/spec_coverage.py +++ b/student-tests/spec_coverage.py @@ -19,6 +19,7 @@ CAPABILITIES = ( "messages", "pagination", "data-storage", + "chat-cache", "health", ) SCENARIO_RE = re.compile(r"^#### Scenario: (.+?)\s*$", re.MULTILINE) @@ -47,6 +48,41 @@ EXCLUDED: dict[Scenario, Exclusion] = { check="тот же ручной сбой, затем make logs: запись error с " "traceback и тем же request_id", ), + ("chat-cache", "Чтение из кэша"): Exclusion( + reason="по HTTP ответ из кэша не отличить от ответа из PostgreSQL", + check="idx_scan таблицы chats и keyspace_hits Valkey за 50 " + "чтений — evidence/cache/hits.md", + ), + ("chat-cache", "Срок записи"): Exclusion( + reason="срок ключа виден только в Valkey", + check="TTL ключа карточки через valkey-cli — evidence/cache/hits.md", + ), + ("chat-cache", "Valkey остановлен"): Exclusion( + reason="нужно остановить Valkey, тесты стенд не трогают", + check="evidence/cache/outage.md; автоматическая проверка — " + "change failure-checks", + ), + ("chat-cache", "Valkey завис"): Exclusion( + reason="нужен docker compose pause для Valkey", + check="evidence/cache/outage.md: время ответа; автоматическая " + "проверка — change failure-checks", + ), + ("chat-cache", "Valkey вернулся"): Exclusion( + reason="нужно остановить и снова запустить Valkey", + check="evidence/cache/outage.md: warning и info в журнале, " + "ключи снова пишутся; автоматическая проверка — change " + "failure-checks", + ), + ("chat-cache", "Очистка кэша"): Exclusion( + reason="нужен FLUSHALL в Valkey, тесты стенд не трогают", + check="evidence/cache/flush-restart.md", + ), + ("chat-cache", "Временная база"): Exclusion( + reason="ключи видны только в Valkey, а набор не знает, на какой " + "базе работает", + check="число ключей с префиксами рабочей и тестовой базы после " + "make test_isolated — evidence/cache/hits.md", + ), ("data-storage", "Прежний пользователь после рестарта"): Exclusion( reason="нужен рестарт стенда, тесты сервер не трогают", check="make test-persistence ACTION_SCRIPT=scripts/restart.sh: " @@ -80,6 +116,11 @@ EXCLUDED: dict[Scenario, Exclusion] = { "/health/live — 200; автоматическая проверка — change " "failure-checks", ), + ("health", "Кэш недоступен"): Exclusion( + reason="нужно остановить Valkey, тесты стенд не трогают", + check="evidence/cache/outage.md: /health/ready — 200; " + "автоматическая проверка — change failure-checks", + ), ("identification", "Кнопка Authorize в Swagger"): Exclusion( reason="это интерфейс /docs в браузере", check="схемы bearerAuth и basicAuth, из которых строится кнопка, " diff --git a/student-tests/test_chat_cache.py b/student-tests/test_chat_cache.py new file mode 100644 index 00000000..9f910cdc --- /dev/null +++ b/student-tests/test_chat_cache.py @@ -0,0 +1,83 @@ +"""Спек `chat-cache`: что видно по HTTP при кэше карточки чата. + +Попадание в кэш, срок записи и отказ Valkey по HTTP не различить: это +исключения в `spec_coverage.py` с evidence. +""" + +from typing import Any + +import pytest + +from api_client import API, Actor, Api +from contract import assert_error, assert_ok + + +@pytest.mark.spec("chat-cache", "Повторное чтение чата") +def test_repeated_reads_match_creation( + api: Api, + alice: Actor, + bob: Actor, + eve: Actor, +) -> None: + # порядок участников не совпадает ни с сортировкой, ни с порядком + # регистрации: кэш обязан сохранить его как есть + created = api.create_chat(bob, eve, alice, title="Кэш «карточки»") + path = f"{API}/chats/{created['id']}" + first = assert_ok(api.request("GET", path, actor=alice), 200, "Chat") + second = assert_ok(api.request("GET", path, actor=eve), 200, "Chat") + assert first == second == created + assert first["member_ids"] == [bob.id, eve.id, alice.id] + + +@pytest.mark.spec("chat-cache", "Проверка членства по карточке") +def test_membership_from_new_chat( + api: Api, + alice: Actor, + bob: Actor, + eve: Actor, +) -> None: + chat = api.create_chat(alice, bob) + api.send_message(bob, chat["id"], "сразу после создания") + path = f"{API}/chats/{chat['id']}" + assert_error(api.request("GET", path, actor=eve), 404) + assert_error( + api.request( + "POST", + f"{path}/messages", + actor=eve, + json={"text": "посторонний"}, + ), + 404, + ) + + +@pytest.mark.spec("chat-cache", "Сообщение видно сразу") +def test_message_visible_at_once( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + # история уже прочитана: если бы она кэшировалась, второе чтение + # отдало бы старую страницу + assert api.all_messages(bob, chat["id"]) == [] + message = api.send_message(alice, chat["id"], "видно сразу") + assert api.all_messages(bob, chat["id"]) == [message] + + +@pytest.mark.spec("chat-cache", "Новый чат в списке") +def test_new_chat_listed_at_once( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + listed = [ + item["id"] for page in api.chat_pages(bob) for item in page["items"] + ] + assert listed == [chat["id"]] + second = api.create_chat(alice, bob, title="Второй") + listed = [ + item["id"] for page in api.chat_pages(bob) for item in page["items"] + ] + assert listed == [chat["id"], second["id"]] diff --git a/uv.lock b/uv.lock index b9618549..37e12f00 100644 --- a/uv.lock +++ b/uv.lock @@ -617,6 +617,7 @@ dependencies = [ { name = "fastapi", extra = ["all"] }, { name = "pydantic" }, { name = "pydantic-settings" }, + { name = "redis" }, { name = "sqlalchemy", extra = ["asyncio"] }, { name = "structlog" }, { name = "uvicorn" }, @@ -645,6 +646,7 @@ requires-dist = [ { name = "fastapi", extras = ["all"], specifier = ">=0.137.2,<1.0.0" }, { name = "pydantic", specifier = ">=2.6.3,<3.0.0" }, { name = "pydantic-settings", specifier = ">=2.15.0,<3.0.0" }, + { name = "redis", specifier = ">=8.1,<9" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.11.13,<1.0.0" }, { name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.1.1,<2.2" }, { name = "structlog", specifier = ">=24.1.0,<25.0.0" }, @@ -943,6 +945,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" }, ] +[[package]] +name = "redis" +version = "8.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/a8/99/604f0b666d4c616d891cf77ebb9db6bb21601344c051aebf1b72b9ff915f/redis-8.1.0.tar.gz", hash = "sha256:6e1a19beef9225c83efd689c7e6b7da2d5215b1f42cd13b7fc3714d0a09c7b25", size = 5254356, upload-time = "2026-07-30T08:51:00.269Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/66/9d/c5731f6e3608663d4d3656fd8d3aecee8b509c3082818f5a13eae925baea/redis-8.1.0-py3-none-any.whl", hash = "sha256:a4fe1aac3d3b3cc791d4b3d5931c5a956045dc951ee74d1c913ee3ac4d2ee9fb", size = 560618, upload-time = "2026-07-30T08:50:58.497Z" }, +] + [[package]] name = "referencing" version = "0.36.2"