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:
@@ -85,10 +85,11 @@ paths:
|
|||||||
Проверка токена — один `SELECT` по `token_hash` с `JOIN` на
|
Проверка токена — один `SELECT` по `token_hash` с `JOIN` на
|
||||||
пользователя; `now` для `expires_at > now` передаёт сервис, срок
|
пользователя; `now` для `expires_at > now` передаёт сервис, срок
|
||||||
сравнивается по часам приложения.
|
сравнивается по часам приложения.
|
||||||
- Redis/Valkey сессии не хранит: он — кэш состава чатов
|
- Valkey сессии не хранит: он — кэш карточек чатов (спек
|
||||||
(`membership-cache`). Любое хранилище сессий обязано пережить рестарт,
|
`chat-cache`, change `membership-cache`). Любое хранилище сессий
|
||||||
соблюдать срок и отзыв, при недоступности отвечать 503 и никогда не
|
обязано пережить рестарт, соблюдать срок и отзыв, при недоступности
|
||||||
пропускать запрос как анонимный или доверенный.
|
отвечать 503 и никогда не пропускать запрос как анонимный или
|
||||||
|
доверенный.
|
||||||
|
|
||||||
## Текущий пользователь
|
## Текущий пользователь
|
||||||
|
|
||||||
|
|||||||
+35
-17
@@ -140,8 +140,8 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t
|
|||||||
- С лабы 2 compose — основной запуск стенда: API без Postgres запросы
|
- С лабы 2 compose — основной запуск стенда: API без Postgres запросы
|
||||||
не обслуживает. Проверка и запуск — по README:
|
не обслуживает. Проверка и запуск — по README:
|
||||||
`docker compose --env-file .env config --quiet`, затем
|
`docker compose --env-file .env config --quiet`, затем
|
||||||
`up -d --build`, ожидание `/health/ready`. Роли — api и postgres, на
|
`up -d --build`, ожидание `/health/ready`. Роли — api, postgres и
|
||||||
«4» ещё Redis или Valkey (`contracts/infrastructure.json`).
|
valkey (`contracts/infrastructure.json`: Redis или Valkey на «4»).
|
||||||
`compose.example.yaml` — лишь список ролей, стенд — свой
|
`compose.example.yaml` — лишь список ролей, стенд — свой
|
||||||
`docker-compose.yml` (compose находит его сам, как и `compose.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}`, для
|
- Postgres наружу — только `127.0.0.1:${POSTGRES_OUT_PORT}`, для
|
||||||
console-режима. Пароль — `POSTGRES_PASSWORD` в `.env`, в приложение
|
console-режима. Пароль — `POSTGRES_PASSWORD` в `.env`, в приложение
|
||||||
мостом (`settings.md`).
|
мостом (`settings.md`).
|
||||||
- Redis или Valkey: те же пины, healthcheck и volume. Если это
|
- Valkey (сервис `valkey`, кэш карточек чатов): тот же пин тега с
|
||||||
единственное хранилище сессий, persistence включён (`appendonly yes`
|
патч-версией и digest индекса, `restart: unless-stopped`, healthcheck,
|
||||||
или RDB с обоснованным интервалом): без него рестарт стирает сессии,
|
`api` ждёт `service_healthy`. Отличия от Postgres:
|
||||||
и `make test-persistence` падает.
|
- volume нет: persistence выключен в `infra/valkey/valkey.conf`
|
||||||
- Конфигурации сервисов (`postgresql.conf`, `redis.conf`) — в `infra/`,
|
(`save ""`, `appendonly no`), кэш после рестарта пуст, а данные —
|
||||||
монтируются read-only (`infra/README.md`). В `REPORT.md` — таблица
|
в Postgres. Если бы в Valkey жили сессии, persistence был бы
|
||||||
роль → сервис → версия/digest → healthcheck → volume → порт → способ
|
обязателен: без него рестарт стёр бы их, и `make test-persistence`
|
||||||
передачи credentials.
|
упал бы;
|
||||||
|
- пароль — `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`
|
## `scripts/restart.sh`
|
||||||
|
|
||||||
Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||||
(`tests/README.md`), по образцу `scripts/restart.example.sh`.
|
(`tests/README.md`), по образцу `scripts/restart.example.sh`.
|
||||||
|
|
||||||
- Перезапускает API и **все** используемые хранилища: Postgres и, если
|
- Перезапускает API и **все** используемые хранилища: Postgres и
|
||||||
есть, Redis или Valkey. Volumes, схему и данные сохраняет: без
|
Valkey. Volumes, схему и данные сохраняет: без `down -v`, `FLUSHALL`,
|
||||||
`down -v`, `FLUSHALL`, повторного seed и изменения тестовых данных.
|
повторного seed и изменения тестовых данных. Кэш Valkey после
|
||||||
- Порядок: `stop api` → `restart postgres` → `up -d --wait postgres`
|
рестарта пуст сам: persistence у него выключен.
|
||||||
(тот же контейнер, ожидание healthcheck) → `start api`. `start api`
|
- Порядок: `stop api` → `restart postgres valkey` → `up -d --wait
|
||||||
запускает и зависимость `migrate`: повторный прогон миграций —
|
postgres valkey` (те же контейнеры, ожидание healthcheck) →
|
||||||
no-op.
|
`start api`. `start api` запускает и зависимость `migrate`: повторный
|
||||||
|
прогон миграций — no-op.
|
||||||
- `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`,
|
- `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`,
|
||||||
`git update-index --chmod=+x`). Возвращает 0 только после действия,
|
`git update-index --chmod=+x`). Возвращает 0 только после действия,
|
||||||
укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает.
|
укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает.
|
||||||
|
|||||||
+38
-20
@@ -6,17 +6,18 @@ paths:
|
|||||||
# Инфраструктура (`src/infra/`)
|
# Инфраструктура (`src/infra/`)
|
||||||
|
|
||||||
Всё, что не содержит бизнес-логики и может смениться от лабы к лабе:
|
Всё, что не содержит бизнес-логики и может смениться от лабы к лабе:
|
||||||
логгер, PostgreSQL (`db/`), с «4» — клиент Redis или Valkey, дальше —
|
логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), дальше — S3, брокер,
|
||||||
S3, брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация)
|
телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет:
|
||||||
здесь нет: они в сервисах, атомарные операции — в repo.
|
они в сервисах, атомарные операции — в repo.
|
||||||
|
|
||||||
- Клиент хранилища (engine Postgres, с «4» клиент Redis/Valkey) —
|
- Клиент хранилища (engine Postgres, кэш Valkey) — глобал своего модуля
|
||||||
глобал своего модуля (`db/session.py`): создаётся при импорте по
|
(`db/session.py`, `cache/instance.py`): создаётся при импорте по
|
||||||
`settings` (настройки читаются один раз на процесс), соединения
|
`settings` (настройки читаются один раз на процесс), соединения
|
||||||
открывает лениво, при первом запросе. Модуль не импортирует пакет
|
открывает лениво, при первом запросе. Пакет `src/infra/<клиент>/` этот
|
||||||
`src/infra/<клиент>/` и модели, поэтому alembic и скрипты клиента не
|
модуль не импортирует, модели тоже, поэтому alembic и скрипты клиента
|
||||||
создают. Закрытие (`engine.dispose()`) — в lifespan `src/main.py`.
|
не создают. Закрытие (`engine.dispose()`, `cache.aclose()`) — в
|
||||||
Почему не `app.state` — design change `postgres-storage`, решение 5.
|
lifespan `src/main.py`. Почему не `app.state` — design change
|
||||||
|
`postgres-storage`, решение 5.
|
||||||
- Глобал импортируют только `src/main.py` (закрытие) и
|
- Глобал импортируют только `src/main.py` (закрытие) и
|
||||||
`src/api/dependencies.py`; сервисы получают сессию или клиент через
|
`src/api/dependencies.py`; сервисы получают сессию или клиент через
|
||||||
конструктор из зависимости и сами глобал не импортируют. Процессу со
|
конструктор из зависимости и сами глобал не импортируют. Процессу со
|
||||||
@@ -25,10 +26,12 @@ S3, брокер, телеметрия. Бизнес-правил (уникал
|
|||||||
`ping`; `session.py` — глобалы `engine` и `session_factory`;
|
`ping`; `session.py` — глобалы `engine` и `session_factory`;
|
||||||
`errors.py` — `is_db_unavailable`; модели — `models/`
|
`errors.py` — `is_db_unavailable`; модели — `models/`
|
||||||
(`migrations.md`). Драйвер — asyncpg.
|
(`migrations.md`). Драйвер — asyncpg.
|
||||||
|
- `cache/`: `client.py` — фабрика `create_cache` и обёртка `Cache`;
|
||||||
|
`instance.py` — глобал `cache`. Ключи и формат значений — в repo
|
||||||
|
(`src/core/repos/chat_cache.py`), не здесь.
|
||||||
- Источник истины — PostgreSQL. SQLite, файлы и память процесса его не
|
- Источник истины — PostgreSQL. SQLite, файлы и память процесса его не
|
||||||
заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в
|
заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в
|
||||||
Postgres; исключение — сессии, если их хранилище выбрано в Redis или
|
Postgres: сессии в Valkey не лежат (`auth.md`).
|
||||||
Valkey (`auth.md`).
|
|
||||||
- Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у
|
- Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у
|
||||||
подключения и запроса есть таймауты (`connect_timeout_seconds`,
|
подключения и запроса есть таймауты (`connect_timeout_seconds`,
|
||||||
серверный `statement_timeout`, срок запроса `request_timeout_seconds`).
|
серверный `statement_timeout`, срок запроса `request_timeout_seconds`).
|
||||||
@@ -45,21 +48,36 @@ S3, брокер, телеметрия. Бизнес-правил (уникал
|
|||||||
оказались бы текст сообщений, а с `session-auth` — хэши паролей и
|
оказались бы текст сообщений, а с `session-auth` — хэши паролей и
|
||||||
токенов (`logging.md`, «Чего в логах быть не должно»).
|
токенов (`logging.md`, «Чего в логах быть не должно»).
|
||||||
- `/health/ready` проверяет критичные зависимости через infra:
|
- `/health/ready` проверяет критичные зависимости через infra:
|
||||||
`SELECT 1` в Postgres с коротким таймаутом, Redis или Valkey — если
|
`SELECT 1` в Postgres с коротким таймаутом. Valkey не проверяется: это
|
||||||
без него не работает обязательный путь (хранилище сессий).
|
кэш, без него обязательный путь идёт в Postgres. Недоступность
|
||||||
Недоступность — 503. Какие зависимости критичны, фиксируется в
|
критичной зависимости — 503. Какие зависимости критичны, фиксируется
|
||||||
`REPORT.md`.
|
в `REPORT.md`.
|
||||||
- Потеря соединения и таймауты драйвера на бизнес-запросе — 503
|
- Потеря соединения и таймауты драйвера на бизнес-запросе — 503
|
||||||
`unavailable` без деталей (`api-contract.md`), не 500 и не обход
|
`unavailable` без деталей (`api-contract.md`), не 500 и не обход
|
||||||
аутентификации. Перевод — в `get_db_session`: `is_db_unavailable`
|
аутентификации. Перевод — в `get_db_session`: `is_db_unavailable`
|
||||||
решает, отказ ли это, сессия закрывается через `invalidate()`, в
|
решает, отказ ли это, сессия закрывается через `invalidate()`, в
|
||||||
журнал — `warning`. Остальные `DBAPIError` (ограничения, синтаксис) —
|
журнал — `warning`. Остальные `DBAPIError` (ограничения, синтаксис) —
|
||||||
дефект, им положен 500.
|
дефект, им положен 500.
|
||||||
- Redis или Valkey — одно из двух, на «4». Роль (сессии с TTL или
|
- Valkey (не Redis) — кэш карточки чата (спек `chat-cache`, design
|
||||||
осмысленный кэш), источник истины, политика expiry и инвалидации —
|
change `membership-cache`). Роль, источник истины, срок, вытеснение и
|
||||||
в `REPORT.md`. Если это единственное хранилище сессий, нужен
|
отсутствие инвалидации — в `REPORT.md`. Клиент — redis-py
|
||||||
persistence, который выдерживает рестарт (`docker.md`). При его
|
(`redis.asyncio`):
|
||||||
недоступности — 503 либо корректный обход кэша.
|
- **без повторов**: `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`
|
- Клиенты внешних сервисов: адреса и секреты из `settings`
|
||||||
(`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки
|
(`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки
|
||||||
переводятся в доменные исключения. Логи — по `logging.md`, без
|
переводятся в доменные исключения. Логи — по `logging.md`, без
|
||||||
|
|||||||
@@ -36,3 +36,7 @@ paths:
|
|||||||
- Опциональные фильтры и лимиты — условное дополнение выборки
|
- Опциональные фильтры и лимиты — условное дополнение выборки
|
||||||
(`if limit is not None: ...`).
|
(`if limit is not None: ...`).
|
||||||
- Логов в репозиториях нет: ни `get_logger`, ни `print`.
|
- Логов в репозиториях нет: ни `get_logger`, ни `print`.
|
||||||
|
- Repo кэша (`chat_cache.py`) — то же правило над Valkey: первый
|
||||||
|
параметр `cache: Cache`, одна команда на функцию, ключ и формат
|
||||||
|
значения (JSON ↔ DTO) живут здесь. Ключ включает
|
||||||
|
`CACHE_KEY_PREFIX` (версию формата) и `cache.namespace` (имя базы).
|
||||||
|
|||||||
+17
-12
@@ -22,8 +22,8 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл
|
|||||||
| Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера |
|
| Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера |
|
||||||
| uvicorn | `127.0.0.1`, `reload=True` по `src/` | `0.0.0.0`, без reload |
|
| 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` снаружи |
|
| Порт | `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`) |
|
| Хранилища | 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`) |
|
| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`); кэш Valkey после рестарта пуст |
|
||||||
|
|
||||||
## Точка входа
|
## Точка входа
|
||||||
|
|
||||||
@@ -40,8 +40,8 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
|
|||||||
запросы до `timeout_graceful_shutdown` (настройка
|
запросы до `timeout_graceful_shutdown` (настройка
|
||||||
`[app] graceful_shutdown_seconds`, не больше 8 с). Docker шлёт SIGKILL
|
`[app] graceful_shutdown_seconds`, не больше 8 с). Docker шлёт SIGKILL
|
||||||
через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan
|
через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan
|
||||||
только логирует и закрывает клиенты (`engine.dispose()`, клиент
|
только логирует и закрывает клиенты (`engine.dispose()`,
|
||||||
Redis/Valkey), долгих операций в нём нет.
|
`cache.aclose()`), долгих операций в нём нет.
|
||||||
Рубрика уровня 4 требует завершения не дольше 10 с.
|
Рубрика уровня 4 требует завершения не дольше 10 с.
|
||||||
|
|
||||||
## Makefile
|
## Makefile
|
||||||
@@ -55,8 +55,9 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
|
|||||||
`# -------------------------`, свой `.PHONY` у каждой цели, имена в
|
`# -------------------------`, свой `.PHONY` у каждой цели, имена в
|
||||||
snake_case. Apple Container не делать.
|
snake_case. Apple Container не делать.
|
||||||
- Запуск и общие цели:
|
- Запуск и общие цели:
|
||||||
- `run_dev: upgrade` — Postgres из compose и миграции, затем
|
- `run_dev: upgrade start_cache` — Postgres из compose и миграции,
|
||||||
`APP__RUN_MODE=console uv run python -m src`;
|
Valkey из compose, затем `APP__RUN_MODE=console uv run python -m
|
||||||
|
src`;
|
||||||
- `run_docker: env_setup` (недостающие `.env` и `config.toml` из
|
- `run_docker: env_setup` (недостающие `.env` и `config.toml` из
|
||||||
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`),
|
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`),
|
||||||
к нему `stop`, `down` (volume остаётся), `logs`
|
к нему `stop`, `down` (volume остаётся), `logs`
|
||||||
@@ -64,7 +65,9 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
|
|||||||
каждая строка — JSON);
|
каждая строка — JSON);
|
||||||
- `lint` (`ruff format .` + `ruff check --fix .`, дважды),
|
- `lint` (`ruff format .` + `ruff check --fix .`, дважды),
|
||||||
`env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` —
|
`env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` —
|
||||||
случайный `POSTGRES_PASSWORD`), `student_test`.
|
случайные `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`; существующий
|
||||||
|
`.env` не меняется, новые строки переносятся руками),
|
||||||
|
`student_test`.
|
||||||
|
|
||||||
Оба способа запуска — `run_docker` и `run_dev` — описываются в
|
Оба способа запуска — `run_docker` и `run_dev` — описываются в
|
||||||
`REPORT.md`. Запуска одного контейнера без compose нет: API без
|
`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`),
|
`stop_db`, `upgrade: start_db` (`uv run alembic upgrade head`),
|
||||||
`revision: upgrade` (autogenerate, сообщение — `read -p`),
|
`revision: upgrade` (autogenerate, сообщение — `read -p`),
|
||||||
`wipe_data` (`$(DC) down -v --remove-orphans` только после ввода
|
`wipe_data` (`$(DC) down -v --remove-orphans` только после ввода
|
||||||
`yes`). Volume — именованный `postgres_data` в compose. С «4» —
|
`yes`). Volume — именованный `postgres_data` в compose; `wipe_data`
|
||||||
`start_redis` / `stop_redis`, если выбран Redis или Valkey.
|
пересоздаёт и Valkey, то есть чистит кэш.
|
||||||
- `test_isolated: env_setup start_db` — образ на временной базе
|
- Valkey: `start_cache` (`$(DC) up -d --wait valkey`), `stop_cache`.
|
||||||
(`student-tests.md`). Скрипт запускается `$(PYTHON)`, а не `uv run`:
|
- `test_isolated: env_setup start_db start_cache` — образ на временной
|
||||||
uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку.
|
базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша
|
||||||
|
разделены именем базы. Скрипт запускается `$(PYTHON)`, а не
|
||||||
|
`uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку.
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
|
|||||||
@@ -9,10 +9,16 @@ paths:
|
|||||||
транзакции, вызовы внешних клиентов, логи.
|
транзакции, вызовы внешних клиентов, логи.
|
||||||
|
|
||||||
- Класс `<Domain>Service`. `__init__` принимает
|
- Класс `<Domain>Service`. `__init__` принимает
|
||||||
`db_session: AsyncSession` и хранит его в `self`; клиент Redis/Valkey,
|
`db_session: AsyncSession` и хранит его в `self`; кэш Valkey
|
||||||
если он нужен домену, — вторым параметром. Методы принимают
|
(`cache: Cache`), если он нужен домену, — вторым параметром
|
||||||
keyword-only параметры (`*,`) и вызываются только именованными
|
(`ChatService`, `MessageService`). Методы принимают keyword-only
|
||||||
аргументами.
|
параметры (`*,`) и вызываются только именованными аргументами.
|
||||||
|
- Кэш карточки чата (`chat_cache_repo`, спек `chat-cache`):
|
||||||
|
cache-aside — сначала кэш, при промахе БД и запись в кэш; новый чат
|
||||||
|
пишется в кэш **после** `commit()`, чтобы откат не оставил в кэше
|
||||||
|
чата, которого нет в БД. Отсутствующий чат не кэшируется. Кэшировать
|
||||||
|
можно только неизменяемое: историю, списки и сессии — нет. Отказ
|
||||||
|
Valkey сервис не обрабатывает: `Cache` уже вернул промах.
|
||||||
- Repo: `from src.core.repos import chat as chat_repo`. Вызов —
|
- Repo: `from src.core.repos import chat as chat_repo`. Вызов —
|
||||||
`db_session=self.db_session` и именованные аргументы.
|
`db_session=self.db_session` и именованные аргументы.
|
||||||
- Проверка доступа — здесь. Не участник получает то же исключение, что
|
- Проверка доступа — здесь. Не участник получает то же исключение, что
|
||||||
@@ -29,15 +35,17 @@ paths:
|
|||||||
`rollback()`, и в БД не остаётся ничего. Откат составной операции —
|
`rollback()`, и в БД не остаётся ничего. Откат составной операции —
|
||||||
проверка уровня 4.
|
проверка уровня 4.
|
||||||
- Коммитит только сервис, repo не коммитит. Другой сервис создаётся с
|
- Коммитит только сервис, repo не коммитит. Другой сервис создаётся с
|
||||||
тем же `db_session`, чтобы остаться в одной транзакции.
|
тем же `db_session` (и тем же кэшем), чтобы остаться в одной
|
||||||
|
транзакции.
|
||||||
- Уникальность (`username`) держит ограничение БД, а не проверка
|
- Уникальность (`username`) держит ограничение БД, а не проверка
|
||||||
перед вставкой: repo делает `ON CONFLICT DO NOTHING RETURNING`,
|
перед вставкой: repo делает `ON CONFLICT DO NOTHING RETURNING`,
|
||||||
`None` сервис превращает в доменное исключение (→ 409). Схема «сначала
|
`None` сервис превращает в доменное исключение (→ 409). Схема «сначала
|
||||||
SELECT, потом INSERT» ломается на гонке регистрации даже внутри
|
SELECT, потом INSERT» ломается на гонке регистрации даже внутри
|
||||||
транзакции (READ COMMITTED), а эта гонка — проверка уровня 4.
|
транзакции (READ COMMITTED), а эта гонка — проверка уровня 4.
|
||||||
- Недоступность Postgres или хранилища сессий — доменное
|
- Недоступность Postgres (там же хранятся сессии) — доменное
|
||||||
`ServiceUnavailable` (→ 503), не 500 и никогда не пропуск запроса без
|
`ServiceUnavailable` (→ 503), не 500 и никогда не пропуск запроса без
|
||||||
аутентификации (`infra.md`).
|
аутентификации (`infra.md`). Недоступность Valkey — не ошибка, а
|
||||||
|
промах кэша.
|
||||||
- KDF пароля — в потоке, не в event loop (`auth.md`).
|
- KDF пароля — в потоке, не в event loop (`auth.md`).
|
||||||
- Курсор кодирует и разбирает сервис через `src/utils/cursor.py`:
|
- Курсор кодирует и разбирает сервис через `src/utils/cursor.py`:
|
||||||
проверяет область (этот чат или этот пользователь) и возвращает
|
проверяет область (этот чат или этот пользователь) и возвращает
|
||||||
|
|||||||
+22
-12
@@ -14,7 +14,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда
|
|||||||
## Источники `Settings`
|
## Источники `Settings`
|
||||||
|
|
||||||
- `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel`
|
- `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel`
|
||||||
(`App`, `Database`, `Auth`; с «4» — секция Redis или Valkey). Экземпляр один —
|
(`App`, `Database`, `Auth`, `Cache` — Valkey). Экземпляр один —
|
||||||
`settings` на уровне модуля. Импорт везде `from src.config import
|
`settings` на уровне модуля. Импорт везде `from src.config import
|
||||||
settings`. Второй `Settings()` не создавать, поля в рантайме не менять.
|
settings`. Второй `Settings()` не создавать, поля в рантайме не менять.
|
||||||
- Приоритет (`settings_customise_sources`): окружение процесса → `.env`
|
- Приоритет (`settings_customise_sources`): окружение процесса → `.env`
|
||||||
@@ -47,8 +47,8 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда
|
|||||||
|
|
||||||
| Где | Что | В git |
|
| Где | Что | В git |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` |
|
| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL сессии, таймауты, пул и срок записей `[cache]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` |
|
||||||
| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` (адрес, порты, учётные данные), пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольный адрес Postgres | нет; шаблон `.env.example` |
|
| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` и `VALKEY_*` (адрес, порты, учётные данные), пароли MinIO / брокера с лаб 4–5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres и Valkey | нет; шаблон `.env.example` |
|
||||||
| окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — |
|
| окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — |
|
||||||
| `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да |
|
| `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`), а
|
`Dockerfile.example` касается запекания в образ (`COPY`), а
|
||||||
`config.toml` в образ не копируется, его монтируют на старте
|
`config.toml` в образ не копируется, его монтируют на старте
|
||||||
(`docker.md`). Но почти все секреты курса — пароли
|
(`docker.md`). Но почти все секреты курса — пароли
|
||||||
Postgres, Redis, MinIO, брокера — нужны ещё и контейнеру зависимости,
|
Postgres, Valkey, MinIO, брокера — нужны ещё и контейнеру зависимости,
|
||||||
а его настраивает только compose из `.env`. Поэтому такой секрет живёт
|
а его настраивает только compose из `.env`. Поэтому такой секрет живёт
|
||||||
в `.env` и попадает в приложение мостом. Если продублировать его в
|
в `.env` и попадает в приложение мостом. Если продублировать его в
|
||||||
`config.toml`, как `postgres_password` в bp_proxies, получатся два
|
`config.toml`, как `postgres_password` в bp_proxies, получатся два
|
||||||
@@ -116,13 +116,21 @@ compose полю секции:
|
|||||||
|
|
||||||
- консоль: приложение на хосте читает `.env`, мосты
|
- консоль: приложение на хосте читает `.env`, мосты
|
||||||
`DATABASE__HOST=127.0.0.1`, `DATABASE__PORT=${POSTGRES_OUT_PORT}` и
|
`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` в контейнер не попадает, адрес и порт приходят из
|
- docker: `.env` в контейнер не попадает, адрес и порт приходят из
|
||||||
`environment` compose — `DATABASE__HOST: ${POSTGRES_HOST}`,
|
`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`, литерал —
|
Адреса и порты Postgres и Valkey в compose — только переменные `.env`,
|
||||||
лишь адрес публикации `127.0.0.1` (`docker.md`).
|
литерал — лишь адрес публикации `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`,
|
`.env.example` skeleton lab2 предлагает «логические» имена: `APP_HOST`,
|
||||||
`APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`,
|
`APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`,
|
||||||
@@ -132,10 +140,12 @@ compose полю секции:
|
|||||||
только приложение, поэтому это `[auth] session_ttl_seconds` в
|
только приложение, поэтому это `[auth] session_ttl_seconds` в
|
||||||
`config.toml`, а короткий срок для проверки истечения —
|
`config.toml`, а короткий срок для проверки истечения —
|
||||||
`AUTH__SESSION_TTL_SECONDS=2` в окружении. Мост с контрактным именем
|
`AUTH__SESSION_TTL_SECONDS=2` в окружении. Мост с контрактным именем
|
||||||
ничего бы не дал: по абзацу выше окружение его не перекрывает. Пароль
|
ничего бы не дал: по абзацу выше окружение его не перекрывает. Пароли
|
||||||
Postgres приходит мостом из `POSTGRES_PASSWORD`, а не строкой
|
Postgres и Valkey приходят мостами из `POSTGRES_PASSWORD` и
|
||||||
подключения в файле (`*_URL_FILE`). Соответствие переменных реальной
|
`VALKEY_PASSWORD`, а не строкой подключения в файле (`DATABASE_URL_FILE`,
|
||||||
конфигурации описать в `REPORT.md` (раздел «Архитектура и решения»).
|
`CACHE_URL_FILE`). `SESSION_STORE` — PostgreSQL, отдельной настройки
|
||||||
|
нет. Соответствие переменных реальной конфигурации описать в
|
||||||
|
`REPORT.md` (раздел «Архитектура и решения»).
|
||||||
|
|
||||||
В настройки идёт только то, что отличается между установками, либо
|
В настройки идёт только то, что отличается между установками, либо
|
||||||
секрет. Остальное — константа.
|
секрет. Остальное — константа.
|
||||||
|
|||||||
@@ -40,13 +40,16 @@ paths:
|
|||||||
не доказана. Проверяются количество и уникальность `id`, а также
|
не доказана. Проверяются количество и уникальность `id`, а также
|
||||||
отсутствие потерь при обходе всех страниц.
|
отсутствие потерь при обходе всех страниц.
|
||||||
- Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`):
|
- Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`):
|
||||||
образ из рабочего дерева на временной базе `test_<db>`, публичный
|
образ из рабочего дерева на временной базе `test_<db>` с Valkey
|
||||||
smoke и весь набор против отдельного контейнера, затем уборка при
|
стенда (ключи кэша разделены именем базы), публичный smoke и весь
|
||||||
любом исходе. Его вывод — evidence набора против контейнера.
|
набор против отдельного контейнера, затем уборка при любом исходе.
|
||||||
|
Его вывод — evidence набора против контейнера.
|
||||||
`make student_test` — против любого запущенного стенда (`BASE_URL`),
|
`make student_test` — против любого запущенного стенда (`BASE_URL`),
|
||||||
он оставляет данные в рабочей базе.
|
он оставляет данные в рабочей базе.
|
||||||
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные
|
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные
|
||||||
Postgres или Redis), обычный прогон не подходит. Сами тесты
|
Postgres или Valkey), обычный прогон не подходит. Попадание в кэш по
|
||||||
|
HTTP не отличить от чтения из БД: такие сценарии `chat-cache` —
|
||||||
|
исключения с evidence. Сами тесты
|
||||||
контейнеры не трогают: стенд готовит явный hook или отдельная цель
|
контейнеры не трогают: стенд готовит явный hook или отдельная цель
|
||||||
Makefile, как `make test-persistence` в skeleton. Механизм выбирает
|
Makefile, как `make test-persistence` в skeleton. Механизм выбирает
|
||||||
change `failure-checks`.
|
change `failure-checks`.
|
||||||
|
|||||||
@@ -1,14 +1,16 @@
|
|||||||
---
|
---
|
||||||
name: run-mtusi-messenger
|
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 мессенджера (пользователи, чаты, сообщения) — сервер на
|
REST API мессенджера (пользователи, чаты, сообщения) — сервер на
|
||||||
FastAPI/uvicorn, данные в PostgreSQL из compose. Агент управляет им через
|
FastAPI/uvicorn, данные в PostgreSQL из compose, карточки чатов
|
||||||
`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres и
|
кэшируются в Valkey из compose. Агент управляет им через
|
||||||
накатывает миграции (`make upgrade`), запускает свой экземпляр сервера
|
`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres,
|
||||||
в фоне, гоняет сценарий по HTTP, публичный smoke и собственные тесты,
|
накатывает миграции и поднимает Valkey (`make upgrade start_cache`),
|
||||||
шлёт одиночные запросы и останавливает сервер. Против контейнера
|
запускает свой экземпляр сервера в фоне, гоняет сценарий по HTTP,
|
||||||
|
публичный smoke и собственные тесты, шлёт одиночные запросы и
|
||||||
|
останавливает сервер. Против контейнера
|
||||||
(`make run_docker`) работают те же команды драйвера, кроме
|
(`make run_docker`) работают те же команды драйвера, кроме
|
||||||
`start`/`stop`. Только стандартная библиотека Python.
|
`start`/`stop`. Только стандартная библиотека Python.
|
||||||
|
|
||||||
@@ -25,12 +27,16 @@ Argon2id, около 30 мс на регистрацию и вход, поэто
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор)
|
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 сервер
|
Нужен запущенный Docker: Postgres и Valkey живут в compose. Без
|
||||||
стартует, но `/health/ready` отвечает 503; `driver.py start` сам делает
|
Postgres сервер стартует, но `/health/ready` отвечает 503; без Valkey
|
||||||
`make upgrade`.
|
всё работает, но мимо кэша (`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)
|
## Run (agent path)
|
||||||
|
|
||||||
@@ -43,7 +49,7 @@ python3 $D all # start → flow → tests/smoke.py → student-tests → st
|
|||||||
посмотреть лог, послать свой запрос):
|
посмотреть лог, послать свой запрос):
|
||||||
|
|
||||||
```bash
|
```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 status # listeners: [pid reloader, pid worker], ready: True
|
||||||
python3 $D flow # ~50 проверок: регистрация с паролем, вход, 409, неверный пароль,
|
python3 $D flow # ~50 проверок: регистрация с паролем, вход, 409, неверный пароль,
|
||||||
# 401 с WWW-Authenticate, X-User-Id игнорируется, чат, 5 сообщений,
|
# 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 POST /api/v1/auth/sessions --basic zoe_demo:Zoe-password-1
|
||||||
python3 $D req GET /api/v1/users/me --token <token из ответа выше>
|
python3 $D req GET /api/v1/users/me --token <token из ответа выше>
|
||||||
python3 $D smoke # публичный tests/smoke.py против этого порта
|
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
|
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, если никого |
|
| `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого |
|
||||||
| `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat и синтетический токен alice |
|
| `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 |
|
| `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)
|
## Run: контейнер (compose)
|
||||||
|
|
||||||
Образ `mtusi-messenger:lab2`, compose-сервисы `postgres`, `migrate`
|
Образ `mtusi-messenger:lab2`, compose-сервисы `postgres`, `valkey`,
|
||||||
(одноразовые миграции) и `api`. Внешний порт — аргументом make, чтобы не
|
`migrate` (одноразовые миграции) и `api`. Внешний порт — аргументом
|
||||||
столкнуться с 8080:
|
make, чтобы не столкнуться с 8080:
|
||||||
|
|
||||||
```bash
|
```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}}'
|
docker compose ps -a --format '{{.Name}} {{.Ports}} {{.Status}}'
|
||||||
python3 $D --port 18090 flow # те же проверки против контейнера
|
python3 $D --port 18090 flow # те же проверки против контейнера
|
||||||
docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f
|
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 test-persistence ACTION_SCRIPT=scripts/restart.sh # то же публичной проверкой
|
||||||
make down # удалить контейнеры, volume с данными остаётся
|
make down # удалить контейнеры, volume с данными остаётся
|
||||||
make wipe_data # удалить и данные: только после ввода yes
|
make wipe_data # удалить и данные: только после ввода yes
|
||||||
@@ -127,8 +135,10 @@ asyncio.run(main())
|
|||||||
EOF
|
EOF
|
||||||
```
|
```
|
||||||
|
|
||||||
`ChatService` и `MessageService` создаются так же (`db_session=...`),
|
`ChatService` и `MessageService` создаются с кэшем вторым параметром:
|
||||||
все методы keyword-only, commit делает сам сервис. Ошибки — доменные
|
`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`), не
|
исключения из `src.core.exceptions` (базовый `DomainError`), не
|
||||||
HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, неверный
|
HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, неверный
|
||||||
пароль в `login` — `InvalidCredentials`. Созданное так остаётся в рабочей
|
пароль в `login` — `InvalidCredentials`. Созданное так остаётся в рабочей
|
||||||
@@ -137,7 +147,7 @@ HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, не
|
|||||||
## Run (human path)
|
## Run (human path)
|
||||||
|
|
||||||
```bash
|
```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`.
|
Блокирует терминал — агенту не подходит, используй `driver.py start`.
|
||||||
@@ -211,3 +221,12 @@ make lint # ruff; затрагивает и dr
|
|||||||
недоступен: `docker compose ps postgres`, `make start_db`. Запросы к
|
недоступен: `docker compose ps postgres`, `make start_db`. Запросы к
|
||||||
API в это время получают 503 `unavailable`, после возврата Postgres
|
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`.
|
||||||
|
|||||||
@@ -6,9 +6,10 @@
|
|||||||
python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] <cmd>
|
python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] <cmd>
|
||||||
|
|
||||||
Команды:
|
Команды:
|
||||||
start `make upgrade` (Postgres из compose и миграции), затем поднять
|
start `make upgrade start_cache` (Postgres из compose и миграции,
|
||||||
`python -m src` в фоне (console, reload) и дождаться
|
Valkey), затем поднять `python -m src` в фоне (console,
|
||||||
/health/ready; лог и pid — /tmp/mtusi-api-<port>.{log,pid}
|
reload) и дождаться /health/ready; лог и pid —
|
||||||
|
/tmp/mtusi-api-<port>.{log,pid}
|
||||||
status кто слушает порт и что отвечает /health/ready
|
status кто слушает порт и что отвечает /health/ready
|
||||||
flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале
|
flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале
|
||||||
req один запрос: req METHOD PATH [--token T | --basic USER:PASS]
|
req один запрос: req METHOD PATH [--token T | --basic USER:PASS]
|
||||||
@@ -135,16 +136,17 @@ def cmd_start(port: int) -> int:
|
|||||||
return 0
|
return 0
|
||||||
print(f"port {port} is busy:", listener_pids(port))
|
print(f"port {port} is busy:", listener_pids(port))
|
||||||
return 1
|
return 1
|
||||||
# без Postgres сервис стартует, но /health/ready отвечает 503
|
# без Postgres сервис стартует, но /health/ready отвечает 503; без
|
||||||
|
# Valkey работает, но мимо кэша
|
||||||
upgrade = subprocess.run(
|
upgrade = subprocess.run(
|
||||||
["make", "upgrade"],
|
["make", "upgrade", "start_cache"],
|
||||||
cwd=ROOT,
|
cwd=ROOT,
|
||||||
capture_output=True,
|
capture_output=True,
|
||||||
text=True,
|
text=True,
|
||||||
check=False,
|
check=False,
|
||||||
)
|
)
|
||||||
if upgrade.returncode != 0:
|
if upgrade.returncode != 0:
|
||||||
print("make upgrade failed:")
|
print("make upgrade start_cache failed:")
|
||||||
print((upgrade.stdout + upgrade.stderr)[-2000:])
|
print((upgrade.stdout + upgrade.stderr)[-2000:])
|
||||||
return 1
|
return 1
|
||||||
env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)}
|
env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)}
|
||||||
|
|||||||
+18
-2
@@ -1,6 +1,7 @@
|
|||||||
# Шаблон .env: `make env_setup` создаёт из него .env, не перезаписывая
|
# Шаблон .env: `make env_setup` создаёт из него .env, не перезаписывая
|
||||||
# существующий файл, и подставляет случайный POSTGRES_PASSWORD. .env не
|
# существующий файл, и подставляет случайные POSTGRES_PASSWORD и
|
||||||
# коммитить. .env читают compose, Makefile и приложение
|
# VALKEY_PASSWORD. В существующий .env новые строки переносятся руками.
|
||||||
|
# .env не коммитить. .env читают compose, Makefile и приложение
|
||||||
# (pydantic-settings); в контейнеры он не попадает.
|
# (pydantic-settings); в контейнеры он не попадает.
|
||||||
# Параметры приложения — в формате настроек SECTION__FIELD, без секции —
|
# Параметры приложения — в формате настроек SECTION__FIELD, без секции —
|
||||||
# только то, что приложение не читает. Комментарии — только отдельными
|
# только то, что приложение не читает. Комментарии — только отдельными
|
||||||
@@ -38,6 +39,21 @@ DATABASE__USER=${POSTGRES_USER}
|
|||||||
DATABASE__PASSWORD=${POSTGRES_PASSWORD}
|
DATABASE__PASSWORD=${POSTGRES_PASSWORD}
|
||||||
DATABASE__NAME=${POSTGRES_DB}
|
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, куда публикуется тестовый
|
# make test_isolated: порт на 127.0.0.1, куда публикуется тестовый
|
||||||
# контейнер API
|
# контейнер API
|
||||||
TEST_APP_PORT=18088
|
TEST_APP_PORT=18088
|
||||||
|
|||||||
@@ -4,10 +4,10 @@ REST API мессенджера (пользователи, чаты, истор
|
|||||||
переносится через все семь лабораторных курса и на каждой обрастает
|
переносится через все семь лабораторных курса и на каждой обрастает
|
||||||
инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL
|
инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL
|
||||||
как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или
|
как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или
|
||||||
Valkey. Код перенесён из лабы 1, переход на lab2 идёт через changes
|
Valkey (выбран Valkey — кэш карточек чатов). Код перенесён из лабы 1,
|
||||||
OpenSpec (раздел «Переходное состояние»). Стек: Python
|
переход на lab2 идёт через changes OpenSpec (раздел «Переходное
|
||||||
3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в
|
состояние»). Стек: Python 3.12, uv, FastAPI, pydantic v2,
|
||||||
stdout).
|
pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey).
|
||||||
|
|
||||||
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
|
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
|
||||||
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
|
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
|
||||||
@@ -60,9 +60,10 @@ stdout).
|
|||||||
Пользователи, чаты, участники, сообщения и ещё действующие сессии
|
Пользователи, чаты, участники, сообщения и ещё действующие сессии
|
||||||
переживают рестарт API и хранилищ без удаления volumes. Basic — только
|
переживают рестарт API и хранилищ без удаления volumes. Basic — только
|
||||||
на `POST /auth/sessions`, остальное — Bearer; `X-User-Id` доступа не
|
на `POST /auth/sessions`, остальное — Bearer; `X-User-Id` доступа не
|
||||||
даёт; пароли — только через password KDF (`auth.md`). Redis или
|
даёт; пароли — только через password KDF (`auth.md`). Valkey — на
|
||||||
Valkey (одно из двух) — на «4», с описанной ролью. uvicorn с одним
|
«4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey —
|
||||||
worker: реплики — лаба 3.
|
обход кэша, а не ошибка (`infra.md`). uvicorn с одним worker:
|
||||||
|
реплики — лаба 3.
|
||||||
- `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни
|
- `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни
|
||||||
в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные
|
в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные
|
||||||
выводы команд.
|
выводы команд.
|
||||||
@@ -80,21 +81,25 @@ stdout).
|
|||||||
|
|
||||||
Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на
|
Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на
|
||||||
PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change
|
PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change
|
||||||
`session-auth`. Этот файл и `.claude/rules/` описывают целевое
|
`session-auth`, кэш Valkey — change `membership-cache`. Этот файл и
|
||||||
состояние лабы 2, поэтому в остальном код с ними пока расходится:
|
`.claude/rules/` описывают целевое состояние лабы 2, поэтому в
|
||||||
|
остальном код с ними пока расходится:
|
||||||
|
|
||||||
- `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с
|
- `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с
|
||||||
`X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` —
|
`X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` —
|
||||||
change `bench-postgres` (`bench.md`);
|
change `bench-postgres` (`bench.md`);
|
||||||
- Redis/Valkey ещё нет — change `membership-cache`;
|
|
||||||
- сценарии основных спеков, которые выполнятся только после следующих
|
- сценарии основных спеков, которые выполнятся только после следующих
|
||||||
changes, — внести в их `tasks.md`: в `failure-checks` —
|
changes, — внести в их `tasks.md`: в `failure-checks` —
|
||||||
автоматическая проверка «Сбой при добавлении участников», «БД
|
автоматическая проверка «Сбой при добавлении участников», «БД
|
||||||
остановлена», «БД вернулась», «Соединения исчерпаны»
|
остановлена», «БД вернулась», «Соединения исчерпаны»
|
||||||
(`data-storage`), «Хранилище не готово» (`health`), «Истёкший токен»,
|
(`data-storage`), «Хранилище не готово», «Кэш недоступен»
|
||||||
«Срок не продлевается», «БД остановлена при запросе с токеном»
|
(`health`), «Истёкший токен», «Срок не продлевается», «БД
|
||||||
(`sessions`); пока это исключения в `spec_coverage.py` с ручным
|
остановлена при запросе с токеном» (`sessions`), «Valkey
|
||||||
evidence;
|
остановлен», «Valkey завис», «Valkey вернулся» (`chat-cache`); пока
|
||||||
|
это исключения в `spec_coverage.py` с ручным evidence;
|
||||||
|
- в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления
|
||||||
|
базы: иначе в кэше останутся карточки чатов, созданных после снятия
|
||||||
|
backup (design change `membership-cache`, Risks);
|
||||||
- `REPORT.md` заполнен по хранению и сессиям; Redis/Valkey, EXPLAIN и
|
- `REPORT.md` заполнен по хранению и сессиям; Redis/Valkey, EXPLAIN и
|
||||||
трек 2 — следующие changes.
|
трек 2 — следующие changes.
|
||||||
|
|
||||||
@@ -155,7 +160,7 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan
|
|||||||
| `service-layer.md` | `src/core/services/**` |
|
| `service-layer.md` | `src/core/services/**` |
|
||||||
| `repo-layer.md` | `src/core/repos/**` |
|
| `repo-layer.md` | `src/core/repos/**` |
|
||||||
| `dto.md` | `src/schemas/**` |
|
| `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, токен, срок и отзыв сессии |
|
| `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии |
|
||||||
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
|
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
|
||||||
| `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть |
|
| `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 test [BASE_URL=...]` | публичный smoke против запущенного сервера |
|
||||||
| `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` |
|
| `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` |
|
||||||
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`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 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 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 → migrate → api; `config.toml` монтируется read-only |
|
| `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 stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся |
|
||||||
| `make logs` | журнал API, каждая строка — JSON (`--no-log-prefix`) |
|
| `make logs` | журнал API, каждая строка — JSON (`--no-log-prefix`) |
|
||||||
| `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` |
|
| `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 upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) |
|
||||||
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
|
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
|
||||||
| `make wipe_data` | `down -v` — удалить данные стенда; только после ввода `yes` |
|
| `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 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 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 [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) |
|
||||||
| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт |
|
| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт |
|
||||||
@@ -279,12 +285,13 @@ src/
|
|||||||
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
|
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
|
||||||
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py
|
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py
|
||||||
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта
|
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта
|
||||||
dependencies.py # сессия БД, фабрики сервисов, разбор Basic, текущая сессия по Bearer, пагинация
|
dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
|
||||||
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта
|
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта
|
||||||
middlewares/ # X-Request-Id и access-лог; с лабы 3 — X-Instance-Id
|
middlewares/ # X-Request-Id и access-лог; с лабы 3 — X-Instance-Id
|
||||||
core/
|
core/
|
||||||
repos/<domain>.py # атомарный доступ к хранилищу, модульные функции
|
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
|
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
|
||||||
infra/
|
infra/
|
||||||
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id
|
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id
|
||||||
@@ -293,6 +300,8 @@ src/
|
|||||||
db/session.py # глобалы engine и session_factory процесса API
|
db/session.py # глобалы engine и session_factory процесса API
|
||||||
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
|
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
|
||||||
db/models/ # модели SQLAlchemy (Base с created_at и to_dict)
|
db/models/ # модели SQLAlchemy (Base с created_at и to_dict)
|
||||||
|
cache/client.py # create_cache (redis-py без повторов, блокирующий пул), Cache: отказ — промах и пропуск
|
||||||
|
cache/instance.py # глобал cache процесса API
|
||||||
schemas/
|
schemas/
|
||||||
dataclasses/<domain>.py # DTO между repo → service → api
|
dataclasses/<domain>.py # DTO между repo → service → api
|
||||||
enums/<domain>.py # StrEnum доменов, RunModeEnum
|
enums/<domain>.py # StrEnum доменов, RunModeEnum
|
||||||
@@ -315,14 +324,17 @@ bench/ # нагрузочный стенд из лабы 1
|
|||||||
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
|
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
|
||||||
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд
|
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд
|
||||||
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
|
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
|
||||||
infra/ # конфигурации сервисов стенда (Postgres, Redis/Valkey); README.md — skeleton
|
infra/ # конфигурации сервисов стенда; README.md — skeleton
|
||||||
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh
|
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
|
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
|
.dockerignore
|
||||||
config_example.toml, .env.example
|
config_example.toml, .env.example
|
||||||
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone
|
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone
|
||||||
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
|
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
|
||||||
|
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
|
||||||
|
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
|
||||||
evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md
|
evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md
|
||||||
evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
|
evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
|
||||||
evidence/profile/<метка>.txt # результаты make bench_inproc
|
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` |
|
| 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 сообщения; никакого состояния в памяти процесса |
|
| 3 | балансировщик, ≥2 реплики, идемпотентность | middleware `X-Instance-Id`; `Idempotency-Key` на POST сообщения; никакого состояния в памяти процесса |
|
||||||
| 4 | приватный S3, вложения | клиент в `infra/`, домен `attachment` |
|
| 4 | приватный S3, вложения | клиент в `infra/`, домен `attachment` |
|
||||||
| 5 | брокер, worker, превью | отдельная точка входа worker; загрузка отвечает 202 |
|
| 5 | брокер, worker, превью | отдельная точка входа worker; загрузка отвечает 202 |
|
||||||
@@ -395,7 +407,8 @@ KNOWN_ISSUES.md # найденные попутно дефекты,
|
|||||||
`solution/<group>-<surname>`, затем перенести своё.
|
`solution/<group>-<surname>`, затем перенести своё.
|
||||||
|
|
||||||
- Переносить: `src/`, `student-tests/`, `migrations/`, `Dockerfile`,
|
- Переносить: `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/`,
|
`config_example.toml`, `AGENTS.md`, `CLAUDE.md`, `.claude/`,
|
||||||
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`.
|
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`.
|
||||||
- Сливать, а не копировать поверх: `Makefile`, `.env.example`,
|
- Сливать, а не копировать поверх: `Makefile`, `.env.example`,
|
||||||
|
|||||||
@@ -30,18 +30,21 @@ test-persistence:
|
|||||||
# Приложение на хосте (свои цели; цели skeleton выше не менять)
|
# Приложение на хосте (свои цели; цели skeleton выше не менять)
|
||||||
# -------------------------
|
# -------------------------
|
||||||
|
|
||||||
# Postgres из compose и миграции, затем сервис на хосте:
|
# Postgres из compose и миграции, Valkey из compose, затем сервис на
|
||||||
# 127.0.0.1:APP__PORT, reload по src/
|
# хосте: 127.0.0.1:APP__PORT, reload по src/
|
||||||
.PHONY: run_dev
|
.PHONY: run_dev
|
||||||
run_dev: upgrade
|
run_dev: upgrade start_cache
|
||||||
APP__RUN_MODE=console uv run python -m src
|
APP__RUN_MODE=console uv run python -m src
|
||||||
|
|
||||||
# шаблоны копируются только если файла ещё нет: локальные значения
|
# шаблоны копируются только если файла ещё нет: локальные значения
|
||||||
# не затираются. В новый .env подставляется случайный пароль Postgres:
|
# не затираются. В новый .env подставляются случайные пароли Postgres и
|
||||||
# в шаблоне он пустой, общего пароля стенда в git нет
|
# Valkey: в шаблоне они пустые, общего пароля стенда в git нет
|
||||||
.PHONY: env_setup
|
.PHONY: env_setup
|
||||||
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
|
@test -f config.toml || cp config_example.toml config.toml
|
||||||
@echo "env ready: .env, config.toml"
|
@echo "env ready: .env, config.toml"
|
||||||
|
|
||||||
@@ -56,9 +59,9 @@ APP__PORT ?= 8080
|
|||||||
APP_OUT_PORT ?= 8080
|
APP_OUT_PORT ?= 8080
|
||||||
DC=docker compose
|
DC=docker compose
|
||||||
|
|
||||||
# стенд: postgres -> migrate -> api. env_setup создаёт недостающие .env
|
# стенд: postgres, valkey -> migrate -> api. env_setup создаёт
|
||||||
# и config.toml из шаблонов: без config.toml compose не запустится
|
# недостающие .env и config.toml из шаблонов: без config.toml compose не
|
||||||
# (bind с create_host_path: false), без пароля — тоже
|
# запустится (bind с create_host_path: false), без паролей — тоже
|
||||||
.PHONY: run_docker
|
.PHONY: run_docker
|
||||||
run_docker: env_setup
|
run_docker: env_setup
|
||||||
DOCKER_BUILDKIT=1 $(DC) build
|
DOCKER_BUILDKIT=1 $(DC) build
|
||||||
@@ -115,6 +118,21 @@ wipe_data:
|
|||||||
fi
|
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)
|
# Load benchmark (трек 1)
|
||||||
# -------------------------
|
# -------------------------
|
||||||
@@ -167,9 +185,10 @@ student_test:
|
|||||||
# образ на временной базе test_<POSTGRES_DB>: сборка, миграции, отдельный
|
# образ на временной базе test_<POSTGRES_DB>: сборка, миграции, отдельный
|
||||||
# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test,
|
# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test,
|
||||||
# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу для разбора.
|
# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу для разбора.
|
||||||
|
# Valkey общий с рабочим стендом: ключи кэша разделены именем базы.
|
||||||
# $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку
|
# $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку
|
||||||
.PHONY: test_isolated
|
.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,)
|
$(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,)
|
||||||
|
|
||||||
.PHONY: lint
|
.PHONY: lint
|
||||||
|
|||||||
@@ -31,3 +31,15 @@ request_timeout_seconds = 6
|
|||||||
session_ttl_seconds = 3600
|
session_ttl_seconds = 3600
|
||||||
# сколько хэшей пароля Argon2id считается одновременно: 64 MiB на каждый
|
# сколько хэшей пароля Argon2id считается одновременно: 64 MiB на каждый
|
||||||
kdf_concurrency = 4
|
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
@@ -1,6 +1,7 @@
|
|||||||
# Стенд лабы 2: PostgreSQL, одноразовые миграции и API. Правила —
|
# Стенд лабы 2: PostgreSQL, Valkey (кэш), одноразовые миграции и API.
|
||||||
# .claude/rules/docker.md. Значения — из .env (шаблон .env.example);
|
# Правила — .claude/rules/docker.md. Значения — из .env (шаблон
|
||||||
# литералы только у адреса публикации 127.0.0.1 и у режима docker.
|
# .env.example); литералы только у адреса публикации 127.0.0.1 и у режима
|
||||||
|
# docker.
|
||||||
name: mtusi-lab2
|
name: mtusi-lab2
|
||||||
|
|
||||||
# окружение приложения: одно для api и migrate, чтобы они не разъехались
|
# окружение приложения: одно для 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__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__PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup}
|
||||||
DATABASE__NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, 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 только на чтение, длинной записью: без файла запуск падает,
|
||||||
# а не создаёт на хосте каталог config.toml/
|
# а не создаёт на хосте каталог config.toml/
|
||||||
@@ -56,6 +60,46 @@ services:
|
|||||||
start_period: 30s
|
start_period: 30s
|
||||||
start_interval: 1s
|
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:
|
migrate:
|
||||||
# образ собирает сервис api (make run_docker, make test_isolated)
|
# образ собирает сервис api (make run_docker, make test_isolated)
|
||||||
image: mtusi-messenger:lab2
|
image: mtusi-messenger:lab2
|
||||||
@@ -82,6 +126,9 @@ services:
|
|||||||
depends_on:
|
depends_on:
|
||||||
postgres:
|
postgres:
|
||||||
condition: service_healthy
|
condition: service_healthy
|
||||||
|
# без кэша API работает, но в штатном стенде он есть с первого запроса
|
||||||
|
valkey:
|
||||||
|
condition: service_healthy
|
||||||
migrate:
|
migrate:
|
||||||
condition: service_completed_successfully
|
condition: service_completed_successfully
|
||||||
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с
|
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с
|
||||||
|
|||||||
@@ -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
|
||||||
@@ -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>`
|
||||||
|
остаётся, а команда печатает её имя
|
||||||
@@ -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 и отчёт.
|
||||||
@@ -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** ключи карточек тестового прогона отличаются от рабочих
|
||||||
|
префиксом с именем базы
|
||||||
@@ -3,21 +3,21 @@
|
|||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
|
Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
|
||||||
одноразовыми миграциями и API (`make run_docker`), публикация портов
|
Valkey, одноразовыми миграциями и API (`make run_docker`), публикация
|
||||||
только на localhost, конфигурация на старте, сохранность данных при
|
портов только на localhost, конфигурация на старте, сохранность данных
|
||||||
рестарте стенда и явное удаление учебных данных.
|
при рестарте стенда и явное удаление учебных данных.
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
### Requirement: Запуск через compose
|
### Requirement: Запуск через compose
|
||||||
|
|
||||||
`make run_docker` SHALL собирать образ и поднимать стенд через
|
`make run_docker` SHALL собирать образ и поднимать стенд через
|
||||||
`docker compose`: PostgreSQL, одноразовый сервис миграций и API. API
|
`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций и API.
|
||||||
SHALL стартовать после готовности PostgreSQL и успешных миграций.
|
API SHALL стартовать после готовности PostgreSQL и Valkey и успешных
|
||||||
Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из
|
миграций. Перед этим цель SHALL создавать недостающие `.env` и
|
||||||
шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие.
|
`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать
|
||||||
`make stop` SHALL останавливать сервисы, `make down` — удалять
|
существующие. `make stop` SHALL останавливать сервисы, `make down` —
|
||||||
контейнеры, сохраняя volume, `make logs` — показывать журнал API.
|
удалять контейнеры, сохраняя volume, `make logs` — показывать журнал API.
|
||||||
|
|
||||||
#### Scenario: Штатный запуск
|
#### Scenario: Штатный запуск
|
||||||
|
|
||||||
@@ -35,13 +35,15 @@ SHALL стартовать после готовности PostgreSQL и усп
|
|||||||
- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает
|
- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает
|
||||||
сам сервер и использует API в docker;
|
сам сервер и использует API в docker;
|
||||||
- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1`
|
- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1`
|
||||||
хоста для запуска в консоли.
|
хоста для запуска в консоли;
|
||||||
|
- порт Valkey внутри сети compose — `VALKEY_PORT`, внешний —
|
||||||
|
`VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли.
|
||||||
|
|
||||||
Если переменная порта API не задана, SHALL действовать 8080. Параметры
|
Если переменная порта API не задана, SHALL действовать 8080. Параметры
|
||||||
приложения в `.env` SHALL записываться в формате настроек
|
приложения в `.env` SHALL записываться в формате настроек
|
||||||
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
|
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
|
||||||
которые приложение не читает. Адрес и порт PostgreSQL MUST NOT быть
|
которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST
|
||||||
записаны в compose литералами.
|
NOT быть записаны в compose литералами.
|
||||||
|
|
||||||
#### Scenario: Другой внешний порт
|
#### Scenario: Другой внешний порт
|
||||||
|
|
||||||
@@ -63,6 +65,13 @@ SHALL стартовать после готовности PostgreSQL и усп
|
|||||||
- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает
|
- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает
|
||||||
200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545`
|
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
|
### Requirement: Оба способа запуска описаны в REPORT.md
|
||||||
|
|
||||||
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
|
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
|
||||||
@@ -80,13 +89,13 @@ SHALL стартовать после готовности PostgreSQL и усп
|
|||||||
|
|
||||||
### Requirement: Публикация только на localhost
|
### Requirement: Публикация только на localhost
|
||||||
|
|
||||||
Порты API и PostgreSQL SHALL публиковаться в compose только на
|
Порты API, PostgreSQL и Valkey SHALL публиковаться в compose только на
|
||||||
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
|
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
|
||||||
переменной. Учебный стенд MUST NOT быть доступен с других машин сети.
|
переменной. Учебный стенд MUST NOT быть доступен с других машин сети.
|
||||||
|
|
||||||
#### Scenario: Адрес публикации
|
#### Scenario: Адрес публикации
|
||||||
|
|
||||||
- **WHEN** для запущенных контейнеров API и Postgres выполняется
|
- **WHEN** для запущенных контейнеров API, Postgres и Valkey выполняется
|
||||||
`docker port`
|
`docker port`
|
||||||
- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0`
|
- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0`
|
||||||
|
|
||||||
@@ -121,19 +130,20 @@ compose, и приложению, SHALL передаваться через `env
|
|||||||
|
|
||||||
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
|
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
|
||||||
`scripts/restart.sh` SHALL перезапускать API и все используемые
|
`scripts/restart.sh` SHALL перезапускать API и все используемые
|
||||||
хранилища, сохраняя volume, схему и данные: без удаления volume,
|
хранилища — PostgreSQL и Valkey, — сохраняя volume, схему и данные: без
|
||||||
очистки и повторного наполнения. Скрипт SHALL быть исполняемым,
|
удаления volume, очистки и повторного наполнения. Скрипт SHALL быть
|
||||||
завершаться с кодом 0 только после перезапуска, укладываться в 90 с и
|
исполняемым, завершаться с кодом 0 только после перезапуска,
|
||||||
MUST NOT печатать секреты. Публичная проверка `make test-persistence
|
укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка
|
||||||
ACTION_SCRIPT=scripts/restart.sh` SHALL проходить.
|
`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL
|
||||||
|
проходить.
|
||||||
|
|
||||||
#### Scenario: Рестарт hook-ом
|
#### Scenario: Рестарт hook-ом
|
||||||
|
|
||||||
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
|
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
|
||||||
`scripts/restart.sh`
|
`scripts/restart.sh`
|
||||||
- **THEN** контейнеры API и Postgres перезапущены (новое время старта в
|
- **THEN** контейнеры API, Postgres и Valkey перезапущены (новое время
|
||||||
`docker inspect`), а после готовности запрос с прежним токеном
|
старта в `docker inspect`), а после готовности запрос с прежним
|
||||||
получает 200 и видит своё сообщение
|
токеном получает 200 и видит своё сообщение
|
||||||
|
|
||||||
#### Scenario: Публичная проверка сохранности
|
#### Scenario: Публичная проверка сохранности
|
||||||
|
|
||||||
|
|||||||
@@ -25,7 +25,9 @@ MUST NOT зависеть от состояния хранилища.
|
|||||||
когда сервис может безопасно обслуживать обязательные запросы, и 503 с
|
когда сервис может безопасно обслуживать обязательные запросы, и 503 с
|
||||||
`code` `unavailable` в формате ошибки, когда не может. На лабе 2
|
`code` `unavailable` в формате ошибки, когда не может. На лабе 2
|
||||||
критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к
|
критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к
|
||||||
нему с коротким таймаутом при каждом обращении. Проверка MUST NOT
|
нему с коротким таймаутом при каждом обращении. Valkey — кэш, без него
|
||||||
|
обязательные запросы обслуживаются из PostgreSQL, поэтому его
|
||||||
|
недоступность MUST NOT делать сервис неготовым. Проверка MUST NOT
|
||||||
требовать идентификации.
|
требовать идентификации.
|
||||||
|
|
||||||
#### Scenario: Сервис запущен
|
#### Scenario: Сервис запущен
|
||||||
@@ -40,6 +42,11 @@ MUST NOT зависеть от состояния хранилища.
|
|||||||
- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже
|
- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже
|
||||||
таймаута проверки, а `GET /health/live` при этом отвечает 200
|
таймаута проверки, а `GET /health/live` при этом отвечает 200
|
||||||
|
|
||||||
|
#### Scenario: Кэш недоступен
|
||||||
|
|
||||||
|
- **WHEN** Valkey остановлен, а PostgreSQL доступен
|
||||||
|
- **THEN** `GET /health/ready` отвечает 200
|
||||||
|
|
||||||
### Requirement: Health вне версии API и без идентификации
|
### Requirement: Health вне версии API и без идентификации
|
||||||
|
|
||||||
Эндпоинты health SHALL находиться вне префикса `/api/v1`, MUST NOT
|
Эндпоинты health SHALL находиться вне префикса `/api/v1`, MUST NOT
|
||||||
|
|||||||
@@ -109,16 +109,36 @@ SHALL иметь один источник — `POSTGRES_PASSWORD` в `.env`, к
|
|||||||
Переключение между запуском в консоли и в docker MUST NOT требовать
|
Переключение между запуском в консоли и в docker MUST NOT требовать
|
||||||
правки `.env`, `config.toml` или compose, в том числе
|
правки `.env`, `config.toml` или compose, в том числе
|
||||||
комментирования и раскомментирования блоков. В консоли сервис SHALL
|
комментирования и раскомментирования блоков. В консоли сервис SHALL
|
||||||
подключаться к Postgres по адресу публикации на хосте из `.env`, в
|
подключаться к PostgreSQL и Valkey по адресам публикации на хосте из
|
||||||
docker — по адресу и порту Postgres внутри сети compose, которые compose
|
`.env`, в docker — по адресам и портам внутри сети compose, которые
|
||||||
передаёт в окружение контейнера из переменных `.env`.
|
compose передаёт в окружение контейнера из переменных `.env`.
|
||||||
|
|
||||||
#### Scenario: Консоль, затем docker
|
#### Scenario: Консоль, затем docker
|
||||||
|
|
||||||
- **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен
|
- **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен
|
||||||
`make run_docker`, а файлы конфигурации между запусками не менялись
|
`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: Срок жизни сессии
|
### Requirement: Срок жизни сессии
|
||||||
|
|
||||||
|
|||||||
@@ -134,12 +134,12 @@ SHALL проходить против сервера, запущенного н
|
|||||||
### Requirement: Покрытие сценариев основных спеков
|
### Requirement: Покрытие сценариев основных спеков
|
||||||
|
|
||||||
Для каждого сценария основных спеков `api-conventions`,
|
Для каждого сценария основных спеков `api-conventions`,
|
||||||
`identification`, `users`, `chats`, `messages`, `pagination`,
|
`identification`, `sessions`, `users`, `chats`, `messages`,
|
||||||
`data-storage` и `health`, который воспроизводится по HTTP против
|
`pagination`, `data-storage`, `chat-cache` и `health`, который
|
||||||
работающего сервера, SHALL быть тест. Из имени или описания теста SHALL
|
воспроизводится по HTTP против работающего сервера, SHALL быть тест. Из
|
||||||
быть понятно, какой capability и сценарий он проверяет. Сценарии,
|
имени или описания теста SHALL быть понятно, какой capability и
|
||||||
которые по HTTP не воспроизвести, SHALL быть перечислены с причиной и
|
сценарий он проверяет. Сценарии, которые по HTTP не воспроизвести,
|
||||||
способом проверки.
|
SHALL быть перечислены с причиной и способом проверки.
|
||||||
|
|
||||||
#### Scenario: Сверка покрытия
|
#### Scenario: Сверка покрытия
|
||||||
|
|
||||||
@@ -178,16 +178,18 @@ SHALL проходить против сервера, запущенного н
|
|||||||
|
|
||||||
`make test_isolated` SHALL проверять образ, собранный из рабочего
|
`make test_isolated` SHALL проверять образ, собранный из рабочего
|
||||||
дерева, в связке compose на временной базе `test_<имя рабочей базы>` в
|
дерева, в связке compose на временной базе `test_<имя рабочей базы>` в
|
||||||
PostgreSQL стенда. Команда SHALL: собрать образ, создать базу заново,
|
PostgreSQL стенда, с Valkey стенда. Команда SHALL: поднять PostgreSQL и
|
||||||
применить к ней миграции сервисом миграций compose, запустить отдельный
|
Valkey, собрать образ, создать базу заново, применить к ней миграции
|
||||||
контейнер API из определения сервиса compose, в котором подменено только
|
сервисом миграций compose, запустить отдельный контейнер API из
|
||||||
имя базы, опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`,
|
определения сервиса compose, в котором подменено только имя базы,
|
||||||
дождаться готовности, выполнить публичный smoke (`make test`) и весь
|
опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, дождаться
|
||||||
набор (`make student_test`) против этого контейнера, затем остановить и
|
готовности, выполнить публичный smoke (`make test`) и весь набор
|
||||||
|
(`make student_test`) против этого контейнера, затем остановить и
|
||||||
удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если
|
удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если
|
||||||
не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API
|
не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API
|
||||||
MUST NOT затрагиваться. Параллельный запуск двух прогонов не
|
MUST NOT затрагиваться, а карточки чатов тестового прогона в Valkey
|
||||||
поддерживается.
|
отделены от рабочих именем базы в ключе (capability `chat-cache`).
|
||||||
|
Параллельный запуск двух прогонов не поддерживается.
|
||||||
|
|
||||||
#### Scenario: Успешный прогон
|
#### Scenario: Успешный прогон
|
||||||
|
|
||||||
|
|||||||
@@ -18,6 +18,8 @@ dependencies = [
|
|||||||
"alembic>=1.20.0,<2",
|
"alembic>=1.20.0,<2",
|
||||||
# Argon2id для паролей: bcrypt режет пароль на 72 байтах, lab7 — Argon2id
|
# Argon2id для паролей: bcrypt режет пароль на 72 байтах, lab7 — Argon2id
|
||||||
"argon2-cffi>=25.1.0,<26",
|
"argon2-cffi>=25.1.0,<26",
|
||||||
|
# клиент Valkey: протокол тот же, redis.asyncio зрелее valkey-py
|
||||||
|
"redis>=8.1,<9",
|
||||||
]
|
]
|
||||||
|
|
||||||
[project.optional-dependencies]
|
[project.optional-dependencies]
|
||||||
|
|||||||
+9
-8
@@ -2,15 +2,16 @@
|
|||||||
set -eu
|
set -eu
|
||||||
# Restart hook для make test-persistence (tests/README.md) по образцу
|
# Restart hook для make test-persistence (tests/README.md) по образцу
|
||||||
# scripts/restart.example.sh; правила — .claude/rules/docker.md.
|
# scripts/restart.example.sh; правила — .claude/rules/docker.md.
|
||||||
# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres) с
|
# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres и
|
||||||
# сохранением volume, схемы и данных: без down -v, очистки и повторного
|
# Valkey) с сохранением volume, схемы и данных: без down -v, FLUSHALL и
|
||||||
# наполнения. start api запускает и его зависимость migrate: повторный
|
# повторного наполнения. Кэш Valkey после рестарта пуст: persistence у
|
||||||
# прогон миграций ничего не меняет. Готовность API ждёт сам тест.
|
# него выключен, данные — в Postgres. start api запускает и его
|
||||||
# Секреты не печатает.
|
# зависимость migrate: повторный прогон миграций ничего не меняет.
|
||||||
|
# Готовность API ждёт сам тест. Секреты не печатает.
|
||||||
cd "$(dirname "$0")/.."
|
cd "$(dirname "$0")/.."
|
||||||
|
|
||||||
docker compose stop api
|
docker compose stop api
|
||||||
docker compose restart postgres
|
docker compose restart postgres valkey
|
||||||
# тот же контейнер: --wait только дожидается его healthcheck
|
# те же контейнеры: --wait только дожидается их healthcheck
|
||||||
docker compose up -d --wait postgres
|
docker compose up -d --wait postgres valkey
|
||||||
docker compose start api
|
docker compose start api
|
||||||
|
|||||||
@@ -1,4 +1,8 @@
|
|||||||
"""Зависимости ручек: сессия БД, сервисы, вход и текущая сессия, страница."""
|
"""Зависимости ручек: сессия БД, сервисы, вход и текущая сессия, страница.
|
||||||
|
|
||||||
|
Сервисы получают сессию БД, а чаты и сообщения — ещё и кэш процесса
|
||||||
|
(`src/infra/cache/instance.py`).
|
||||||
|
"""
|
||||||
|
|
||||||
import asyncio
|
import asyncio
|
||||||
import base64
|
import base64
|
||||||
@@ -21,6 +25,7 @@ from src.core.services import (
|
|||||||
SessionService,
|
SessionService,
|
||||||
UserService,
|
UserService,
|
||||||
)
|
)
|
||||||
|
from src.infra.cache.instance import cache
|
||||||
from src.infra.db import is_db_unavailable, ping
|
from src.infra.db import is_db_unavailable, ping
|
||||||
from src.infra.db.session import engine, session_factory
|
from src.infra.db.session import engine, session_factory
|
||||||
from src.infra.logger import AbstractLogger, current_user_id, get_logger
|
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:
|
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:
|
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:
|
async def get_session_service(db_session: DbSessionDep) -> SessionService:
|
||||||
|
|||||||
@@ -93,6 +93,28 @@ class Auth(BaseModel):
|
|||||||
kdf_concurrency: int = Field(default=4, gt=0)
|
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):
|
class Settings(BaseSettings):
|
||||||
model_config = SettingsConfigDict(
|
model_config = SettingsConfigDict(
|
||||||
extra="ignore",
|
extra="ignore",
|
||||||
@@ -105,6 +127,7 @@ class Settings(BaseSettings):
|
|||||||
app: App = App()
|
app: App = App()
|
||||||
database: Database = Database()
|
database: Database = Database()
|
||||||
auth: Auth = Auth()
|
auth: Auth = Auth()
|
||||||
|
cache: Cache = Cache()
|
||||||
|
|
||||||
@classmethod
|
@classmethod
|
||||||
def settings_customise_sources(
|
def settings_customise_sources(
|
||||||
|
|||||||
@@ -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,
|
||||||
|
)
|
||||||
@@ -3,10 +3,13 @@ from uuid import UUID, uuid4
|
|||||||
|
|
||||||
from sqlalchemy.ext.asyncio import AsyncSession
|
from sqlalchemy.ext.asyncio import AsyncSession
|
||||||
|
|
||||||
|
from src.config import settings
|
||||||
from src.core import exceptions
|
from src.core import exceptions
|
||||||
from src.core.repos import chat as chat_repo
|
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.repos import user as user_repo
|
||||||
from src.core.services.pagination import decode_page_cursor, split_page
|
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.infra.logger import AbstractLogger, get_logger
|
||||||
from src.schemas import dataclasses
|
from src.schemas import dataclasses
|
||||||
from src.utils.cursor import user_chats_scope
|
from src.utils.cursor import user_chats_scope
|
||||||
@@ -16,8 +19,15 @@ logger: AbstractLogger = get_logger().bind(module="chat_service")
|
|||||||
|
|
||||||
|
|
||||||
class ChatService:
|
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.db_session = db_session
|
||||||
|
self.cache = cache
|
||||||
|
|
||||||
async def create_chat(
|
async def create_chat(
|
||||||
self,
|
self,
|
||||||
@@ -58,6 +68,13 @@ class ChatService:
|
|||||||
)
|
)
|
||||||
await self.db_session.commit()
|
await self.db_session.commit()
|
||||||
log.info("Created chat", chat_id=chat.id)
|
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
|
return chat
|
||||||
|
|
||||||
async def get_chat_for_member(
|
async def get_chat_for_member(
|
||||||
@@ -69,11 +86,24 @@ class ChatService:
|
|||||||
"""Чат, если пользователь в нём состоит; иначе `ChatNotFound`.
|
"""Чат, если пользователь в нём состоит; иначе `ChatNotFound`.
|
||||||
|
|
||||||
Нет чата и чужой чат неразличимы: 404 не раскрывает существование.
|
Нет чата и чужой чат неразличимы: 404 не раскрывает существование.
|
||||||
|
Карточка — из кэша, при промахе — из БД с записью в кэш. Чат,
|
||||||
|
которого нет, не кэшируется.
|
||||||
"""
|
"""
|
||||||
chat = await chat_repo.get_chat(
|
chat = await chat_cache_repo.get_chat(
|
||||||
db_session=self.db_session,
|
cache=self.cache,
|
||||||
chat_id=chat_id,
|
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:
|
if chat is None or user_id not in chat.member_ids:
|
||||||
raise exceptions.ChatNotFound
|
raise exceptions.ChatNotFound
|
||||||
return chat
|
return chat
|
||||||
|
|||||||
@@ -5,6 +5,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
|
|||||||
from src.core.repos import message as message_repo
|
from src.core.repos import message as message_repo
|
||||||
from src.core.services.chat import ChatService
|
from src.core.services.chat import ChatService
|
||||||
from src.core.services.pagination import decode_page_cursor, split_page
|
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.infra.logger import AbstractLogger, get_logger
|
||||||
from src.schemas import dataclasses
|
from src.schemas import dataclasses
|
||||||
from src.utils.cursor import chat_messages_scope
|
from src.utils.cursor import chat_messages_scope
|
||||||
@@ -14,8 +15,14 @@ logger: AbstractLogger = get_logger().bind(module="message_service")
|
|||||||
|
|
||||||
|
|
||||||
class MessageService:
|
class MessageService:
|
||||||
def __init__(self, db_session: AsyncSession) -> None:
|
"""Сообщения; история не кэшируется, членство — по карточке чата."""
|
||||||
|
|
||||||
|
def __init__(self, db_session: AsyncSession, cache: Cache) -> None:
|
||||||
self.db_session = db_session
|
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(
|
async def send_message(
|
||||||
self,
|
self,
|
||||||
@@ -25,9 +32,10 @@ class MessageService:
|
|||||||
text: str,
|
text: str,
|
||||||
) -> dataclasses.MessageFullDTO:
|
) -> dataclasses.MessageFullDTO:
|
||||||
log = logger.bind(method="send_message", chat_id=chat_id)
|
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,
|
chat_id=chat_id,
|
||||||
user_id=sender_id,
|
user_id=sender_id,
|
||||||
)
|
)
|
||||||
@@ -58,7 +66,7 @@ class MessageService:
|
|||||||
limit: int,
|
limit: int,
|
||||||
cursor: str | None,
|
cursor: str | None,
|
||||||
) -> dataclasses.MessagePageDTO:
|
) -> dataclasses.MessagePageDTO:
|
||||||
await ChatService(db_session=self.db_session).get_chat_for_member(
|
await self._chats().get_chat_for_member(
|
||||||
chat_id=chat_id,
|
chat_id=chat_id,
|
||||||
user_id=user_id,
|
user_id=user_id,
|
||||||
)
|
)
|
||||||
|
|||||||
Vendored
+6
@@ -0,0 +1,6 @@
|
|||||||
|
from src.infra.cache.client import Cache, create_cache
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"Cache",
|
||||||
|
"create_cache",
|
||||||
|
]
|
||||||
Vendored
+113
@@ -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,
|
||||||
|
)
|
||||||
Vendored
+13
@@ -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
@@ -8,6 +8,7 @@ from src.api import errors
|
|||||||
from src.api.middlewares import RequestContextMiddleware
|
from src.api.middlewares import RequestContextMiddleware
|
||||||
from src.api.routers import health_router, v1_router
|
from src.api.routers import health_router, v1_router
|
||||||
from src.config import settings
|
from src.config import settings
|
||||||
|
from src.infra.cache.instance import cache
|
||||||
from src.infra.db.session import engine
|
from src.infra.db.session import engine
|
||||||
from src.infra.logger import AbstractLogger, get_logger
|
from src.infra.logger import AbstractLogger, get_logger
|
||||||
from src.infra.password import prepare_dummy_hash
|
from src.infra.password import prepare_dummy_hash
|
||||||
@@ -19,10 +20,12 @@ logger: AbstractLogger = get_logger().bind(module="startup")
|
|||||||
@asynccontextmanager
|
@asynccontextmanager
|
||||||
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
|
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
|
||||||
database = settings.database
|
database = settings.database
|
||||||
# engine подключается лениво: без Postgres сервис стартует, а
|
# engine и кэш подключаются лениво: без Postgres сервис стартует, а
|
||||||
# /health/ready отвечает 503
|
# /health/ready отвечает 503; без Valkey запросы идут в Postgres
|
||||||
if not database.password.get_secret_value():
|
if not database.password.get_secret_value():
|
||||||
logger.warning("Database password is empty")
|
logger.warning("Database password is empty")
|
||||||
|
if not settings.cache.password.get_secret_value():
|
||||||
|
logger.warning("Cache password is empty")
|
||||||
# ~30 мс CPU при старте: время ответа на вход с неизвестным username
|
# ~30 мс CPU при старте: время ответа на вход с неизвестным username
|
||||||
# ровное с первого запроса
|
# ровное с первого запроса
|
||||||
await prepare_dummy_hash()
|
await prepare_dummy_hash()
|
||||||
@@ -34,11 +37,14 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
|
|||||||
database_host=database.host,
|
database_host=database.host,
|
||||||
database_port=database.port,
|
database_port=database.port,
|
||||||
database_name=database.name,
|
database_name=database.name,
|
||||||
|
cache_host=settings.cache.host,
|
||||||
|
cache_port=settings.cache.port,
|
||||||
)
|
)
|
||||||
try:
|
try:
|
||||||
yield
|
yield
|
||||||
finally:
|
finally:
|
||||||
await engine.dispose()
|
await engine.dispose()
|
||||||
|
await cache.aclose()
|
||||||
logger.info("Stopped API")
|
logger.info("Stopped API")
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -53,3 +53,8 @@ READINESS_DB_TIMEOUT_SECONDS = 2
|
|||||||
# секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой
|
# секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой
|
||||||
# срок; дальше соединение обрывается
|
# срок; дальше соединение обрывается
|
||||||
DB_CLOSE_TIMEOUT_SECONDS = 2
|
DB_CLOSE_TIMEOUT_SECONDS = 2
|
||||||
|
|
||||||
|
# кэш (Valkey)
|
||||||
|
# начало ключей; v1 — формат значений: новый формат — v2, и старые ключи
|
||||||
|
# не читаются без чистки кэша
|
||||||
|
CACHE_KEY_PREFIX = "messenger:v1"
|
||||||
|
|||||||
@@ -5,8 +5,10 @@
|
|||||||
подменой только `DATABASE__NAME`, прогоняет `make test` и
|
подменой только `DATABASE__NAME`, прогоняет `make test` и
|
||||||
`make student_test`, затем удаляет контейнер и базу — при любом исходе,
|
`make student_test`, затем удаляет контейнер и базу — при любом исходе,
|
||||||
в том числе по Ctrl+C. Рабочая база и рабочий контейнер API не
|
в том числе по Ctrl+C. Рабочая база и рабочий контейнер API не
|
||||||
трогаются. Только stdlib: всё через docker compose и make. Решение 12
|
трогаются. Valkey стенда общий: ключи кэша включают имя базы, и
|
||||||
design change `postgres-storage`.
|
карточки тестового прогона не смешиваются с рабочими. Только stdlib:
|
||||||
|
всё через docker compose и make. Решение 12 design change
|
||||||
|
`postgres-storage`.
|
||||||
|
|
||||||
Запускается напрямую `$(PYTHON)`, как проверки skeleton, а не через
|
Запускается напрямую `$(PYTHON)`, как проверки skeleton, а не через
|
||||||
`uv run`: uv пересылает SIGINT дочернему процессу, хотя тот уже получил
|
`uv run`: uv пересылает SIGINT дочернему процессу, хотя тот уже получил
|
||||||
|
|||||||
@@ -19,6 +19,7 @@ CAPABILITIES = (
|
|||||||
"messages",
|
"messages",
|
||||||
"pagination",
|
"pagination",
|
||||||
"data-storage",
|
"data-storage",
|
||||||
|
"chat-cache",
|
||||||
"health",
|
"health",
|
||||||
)
|
)
|
||||||
SCENARIO_RE = re.compile(r"^#### Scenario: (.+?)\s*$", re.MULTILINE)
|
SCENARIO_RE = re.compile(r"^#### Scenario: (.+?)\s*$", re.MULTILINE)
|
||||||
@@ -47,6 +48,41 @@ EXCLUDED: dict[Scenario, Exclusion] = {
|
|||||||
check="тот же ручной сбой, затем make logs: запись error с "
|
check="тот же ручной сбой, затем make logs: запись error с "
|
||||||
"traceback и тем же request_id",
|
"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(
|
("data-storage", "Прежний пользователь после рестарта"): Exclusion(
|
||||||
reason="нужен рестарт стенда, тесты сервер не трогают",
|
reason="нужен рестарт стенда, тесты сервер не трогают",
|
||||||
check="make test-persistence ACTION_SCRIPT=scripts/restart.sh: "
|
check="make test-persistence ACTION_SCRIPT=scripts/restart.sh: "
|
||||||
@@ -80,6 +116,11 @@ EXCLUDED: dict[Scenario, Exclusion] = {
|
|||||||
"/health/live — 200; автоматическая проверка — change "
|
"/health/live — 200; автоматическая проверка — change "
|
||||||
"failure-checks",
|
"failure-checks",
|
||||||
),
|
),
|
||||||
|
("health", "Кэш недоступен"): Exclusion(
|
||||||
|
reason="нужно остановить Valkey, тесты стенд не трогают",
|
||||||
|
check="evidence/cache/outage.md: /health/ready — 200; "
|
||||||
|
"автоматическая проверка — change failure-checks",
|
||||||
|
),
|
||||||
("identification", "Кнопка Authorize в Swagger"): Exclusion(
|
("identification", "Кнопка Authorize в Swagger"): Exclusion(
|
||||||
reason="это интерфейс /docs в браузере",
|
reason="это интерфейс /docs в браузере",
|
||||||
check="схемы bearerAuth и basicAuth, из которых строится кнопка, "
|
check="схемы bearerAuth и basicAuth, из которых строится кнопка, "
|
||||||
|
|||||||
@@ -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"]]
|
||||||
@@ -617,6 +617,7 @@ dependencies = [
|
|||||||
{ name = "fastapi", extra = ["all"] },
|
{ name = "fastapi", extra = ["all"] },
|
||||||
{ name = "pydantic" },
|
{ name = "pydantic" },
|
||||||
{ name = "pydantic-settings" },
|
{ name = "pydantic-settings" },
|
||||||
|
{ name = "redis" },
|
||||||
{ name = "sqlalchemy", extra = ["asyncio"] },
|
{ name = "sqlalchemy", extra = ["asyncio"] },
|
||||||
{ name = "structlog" },
|
{ name = "structlog" },
|
||||||
{ name = "uvicorn" },
|
{ name = "uvicorn" },
|
||||||
@@ -645,6 +646,7 @@ requires-dist = [
|
|||||||
{ name = "fastapi", extras = ["all"], specifier = ">=0.137.2,<1.0.0" },
|
{ name = "fastapi", extras = ["all"], specifier = ">=0.137.2,<1.0.0" },
|
||||||
{ name = "pydantic", specifier = ">=2.6.3,<3.0.0" },
|
{ name = "pydantic", specifier = ">=2.6.3,<3.0.0" },
|
||||||
{ name = "pydantic-settings", specifier = ">=2.15.0,<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 = "ruff", marker = "extra == 'dev'", specifier = ">=0.11.13,<1.0.0" },
|
||||||
{ name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.1.1,<2.2" },
|
{ name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.1.1,<2.2" },
|
||||||
{ name = "structlog", specifier = ">=24.1.0,<25.0.0" },
|
{ 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" },
|
{ 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]]
|
[[package]]
|
||||||
name = "referencing"
|
name = "referencing"
|
||||||
version = "0.36.2"
|
version = "0.36.2"
|
||||||
|
|||||||
Reference in New Issue
Block a user