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