feat: cache chat cards in Valkey

Valkey 9.1 in compose caches the immutable chat card (title, members,
created_at) used by GET /chats/{id} and by the membership check of the
message endpoints. Cache-aside with a write after commit, keys per
database, TTL plus allkeys-lru, persistence off. redis-py runs without
retries; on failure the cache is skipped for a few seconds and requests
go to PostgreSQL. Readiness does not depend on Valkey.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 21:17:55 +03:00
co-authored by Claude Opus 5.5
parent c7681b0e18
commit cae4b09147
46 changed files with 1769 additions and 210 deletions
+5 -4
View File
@@ -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 и никогда не пропускать запрос как анонимный или
доверенный.
## Текущий пользователь
+35 -17
View File
@@ -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 с. Готовность ждёт сам тест. Секреты не печатает.
+38 -20
View File
@@ -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`, без
+4
View File
@@ -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` (имя базы).
+17 -12
View File
@@ -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
+15 -7
View File
@@ -9,10 +9,16 @@ paths:
транзакции, вызовы внешних клиентов, логи.
- Класс `<Domain>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`:
проверяет область (этот чат или этот пользователь) и возвращает
+22 -12
View File
@@ -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` (раздел «Архитектура и решения»).
В настройки идёт только то, что отличается между установками, либо
секрет. Остальное — константа.
+7 -4
View File
@@ -40,13 +40,16 @@ paths:
не доказана. Проверяются количество и уникальность `id`, а также
отсутствие потерь при обходе всех страниц.
- Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`):
образ из рабочего дерева на временной базе `test_<db>`, публичный
smoke и весь набор против отдельного контейнера, затем уборка при
любом исходе. Его вывод — evidence набора против контейнера.
образ из рабочего дерева на временной базе `test_<db>` с 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`.
+40 -21
View File
@@ -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 <token из ответа выше>
python3 $D smoke # публичный tests/smoke.py против этого порта
python3 $D student # make student_test BASE_URL=http://localhost:<port> — 99 тестов, ~11 с
python3 $D student # make student_test BASE_URL=http://localhost:<port> — 103 теста, ~12 с
python3 $D stop
```
| команда | что делает |
|---|---|
| `start` | `make upgrade`, затем `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src` в своей группе процессов |
| `start` | `make upgrade start_cache`, затем `APP__RUN_MODE=console APP__PORT=<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`.
+8 -6
View File
@@ -6,9 +6,10 @@
python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] <cmd>
Команды:
start `make upgrade` (Postgres из compose и миграции), затем поднять
`python -m src` в фоне (console, reload) и дождаться
/health/ready; лог и pid — /tmp/mtusi-api-<port>.{log,pid}
start `make upgrade start_cache` (Postgres из compose и миграции,
Valkey), затем поднять `python -m src` в фоне (console,
reload) и дождаться /health/ready; лог и pid —
/tmp/mtusi-api-<port>.{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)}
+18 -2
View File
@@ -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
+40 -27
View File
@@ -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_<db>`: сборка, миграции, отдельный контейнер 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_<db>` с 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/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py
schemas/<domain>.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/<domain>.py # атомарный доступ к хранилищу, модульные функции
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем
exceptions/<domain>.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/<domain>.py # DTO между repo → service → api
enums/<domain>.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/<group>-<surname>`, затем перенести своё.
- Переносить: `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`,
+29 -10
View File
@@ -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_<POSTGRES_DB>: сборка, миграции, отдельный
# контейнер 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
+12
View File
@@ -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
+50 -3
View File
@@ -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 с
+15
View File
@@ -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
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-01
+221
View File
@@ -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_<db>` не делит записи с рабочей
(спек `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 хранит только кэш.
@@ -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/`.
@@ -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_<db>` при
запущенном рабочем стенде
- **THEN** ключи карточек тестового прогона отличаются от рабочих
префиксом с именем базы
@@ -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`
@@ -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
@@ -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
@@ -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_<db>`, ни
тестового контейнера после команды нет, число строк в таблицах
рабочей базы не изменилось, а рабочий API продолжает отвечать
#### Scenario: Упавшие тесты
- **WHEN** во время `make test_isolated` падает хотя бы один тест
- **THEN** код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база `test_<db>` удалена
#### Scenario: Прерывание
- **WHEN** `make test_isolated` прерван Ctrl+C
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>`
удалена
#### Scenario: Хвост прошлого прогона
- **WHEN** тестовый контейнер или база `test_<db>` остались от прогона,
убитого без уборки
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
#### Scenario: Сохранить базу для разбора
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>`
остаётся, а команда печатает её имя
+110
View File
@@ -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:<VALKEY_OUT_PORT>`;
`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 и отчёт.
+119
View File
@@ -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_<db>` при
запущенном рабочем стенде
- **THEN** ключи карточек тестового прогона отличаются от рабочих
префиксом с именем базы
+32 -22
View File
@@ -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: Публичная проверка сохранности
+8 -1
View File
@@ -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
+25 -5
View File
@@ -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: Срок жизни сессии
+16 -14
View File
@@ -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: Успешный прогон
+2
View File
@@ -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]
+9 -8
View File
@@ -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
+8 -3
View File
@@ -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:
+23
View File
@@ -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(
+61
View File
@@ -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,
)
+33 -3
View File
@@ -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
+13 -5
View File
@@ -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,
)
+6
View File
@@ -0,0 +1,6 @@
from src.infra.cache.client import Cache, create_cache
__all__ = [
"Cache",
"create_cache",
]
+113
View File
@@ -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,
)
+13
View File
@@ -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_<db>` не видит карточек рабочей.
"""
from src.config import settings
from src.infra.cache.client import create_cache
cache = create_cache(settings.cache, namespace=settings.database.name)
+8 -2
View File
@@ -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")
+5
View File
@@ -53,3 +53,8 @@ READINESS_DB_TIMEOUT_SECONDS = 2
# секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой
# срок; дальше соединение обрывается
DB_CLOSE_TIMEOUT_SECONDS = 2
# кэш (Valkey)
# начало ключей; v1 — формат значений: новый формат — v2, и старые ключи
# не читаются без чистки кэша
CACHE_KEY_PREFIX = "messenger:v1"
+4 -2
View File
@@ -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 дочернему процессу, хотя тот уже получил
+41
View File
@@ -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, из которых строится кнопка, "
+83
View File
@@ -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"]]
Generated
+11
View File
@@ -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"