From d7c9a5972b838d62eef4fc90a350376812c05b9b Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 1 Oct 2026 21:41:15 +0300 Subject: [PATCH] fix: retry Valkey once on a dropped connection The client passed the sync redis.retry.Retry to async connections, so no retry could ever run. Use redis.asyncio.retry.Retry with one immediate retry on ConnectionError only: after a Valkey restart the stale pooled connection is reopened instead of switching the cache off for 5 s. Timeouts are not retried, and asyncio.timeout bounds each cache command (pool wait, connect, retry, reply) by [cache] timeout_seconds. Co-Authored-By: Claude Opus 5.5 --- .claude/rules/infra.md | 18 +++++-- AGENTS.md | 4 +- config_example.toml | 3 +- openspec/changes/membership-cache/design.md | 56 +++++++++++++-------- openspec/changes/membership-cache/tasks.md | 20 +++++++- src/config/settings.py | 3 +- src/infra/cache/client.py | 36 +++++++++---- 7 files changed, 99 insertions(+), 41 deletions(-) diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 2c7442cf..a7809f84 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -62,17 +62,25 @@ paths: change `membership-cache`). Роль, источник истины, срок, вытеснение и отсутствие инвалидации — в `REPORT.md`. Клиент — redis-py (`redis.asyncio`): - - **без повторов**: `retry=Retry(NoBackoff(), 0)`. По умолчанию - redis-py повторяет команду с backoff, и замороженный Valkey держал - запрос 6 с вместо таймаута 0,2 с; + - **один повтор, только на обрыв**: `retry=Retry(NoBackoff(), 1, + supported_errors=(ConnectionError,))`. По умолчанию redis-py + повторяет команду с backoff, и замороженный Valkey держал запрос + 6 с вместо 0,2 с. Таймаут не повторяется, а обрыв повторяется один + раз: после рестарта Valkey старое соединение пула иначе давало бы + отказ на первой команде; + - `Retry` — **из `redis.asyncio.retry`**. Синхронный `redis.retry.Retry` + асинхронное соединение принимает молча, но повтор с ним не + выполняется никогда (первая реализация так и ошиблась); - `BlockingConnectionPool` на `[cache] max_connections` с ожиданием не дольше `timeout_seconds`: обычный пул при всплеске запросов сразу бросает `MaxConnectionsError`, и здоровый Valkey считался бы отказавшим; - `socket_timeout` и `socket_connect_timeout` — `[cache] - timeout_seconds`. + timeout_seconds`, а всю команду (пул, соединение, повтор, ответ) + ограничивает `asyncio.timeout` того же срока в `Cache`. - Отказ Valkey — промах, а не 503 и не 500: `Cache.get` / `Cache.set` - ловят `RedisError` и `OSError`, отдают `None` / `False`, и запрос идёт в + ловят `RedisError` и `OSError` (в том числе `TimeoutError` от + `asyncio.timeout`), отдают `None` / `False`, и запрос идёт в Postgres. После отказа кэш пропускается на `[cache] retry_after_seconds` без обращений к Valkey. В журнал — один `warning` «Cache is unavailable» на отказ и `info` «Cache is diff --git a/AGENTS.md b/AGENTS.md index a0f20502..e2e2585f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -160,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, кэш 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`: источники настроек, что куда класть | @@ -300,7 +300,7 @@ 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/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск cache/instance.py # глобал cache процесса API schemas/ dataclasses/.py # DTO между repo → service → api diff --git a/config_example.toml b/config_example.toml index 5a58e9eb..330fc7ba 100644 --- a/config_example.toml +++ b/config_example.toml @@ -35,7 +35,8 @@ kdf_concurrency = 4 [cache] # Адрес, порт и пароль Valkey приходят из .env (мосты к VALKEY_*) и из # environment compose; здесь их не указывать. -# секунды на соединение и ответ Valkey; дольше — запрос идёт в PostgreSQL +# секунды на всю команду Valkey (ожидание пула, соединение, ответ); +# дольше — запрос идёт в PostgreSQL timeout_seconds = 0.2 # секунды, на которые кэш пропускается после отказа Valkey retry_after_seconds = 5 diff --git a/openspec/changes/membership-cache/design.md b/openspec/changes/membership-cache/design.md index eb692668..41393448 100644 --- a/openspec/changes/membership-cache/design.md +++ b/openspec/changes/membership-cache/design.md @@ -27,6 +27,17 @@ (`docker pause`) — `TimeoutError` через 6,27 с, остановленный — `ConnectionError` через 3,98 с. С `Retry(NoBackoff(), 0)` — 0,20 с и 0,00 с. +- Класс `Retry` для асинхронного клиента — `redis.asyncio.retry.Retry`. + Синхронный `redis.retry.Retry` асинхронное соединение принимает молча, + но его `call_with_retry` возвращает корутину не дождавшись, и повтор + не выполняется никогда (найдено на verify: первая реализация + передавала синхронный класс). +- После рестарта Valkey соединение пула, открытое раньше, получает + `ConnectionError` на первой команде: проверка при выдаче из пула + обрыва не видит. С асинхронным `Retry(NoBackoff(), 1, + supported_errors=(ConnectionError,))` команда переоткрывает соединение + и проходит за 4 мс, а остановленный (1 мс) и замороженный (202 мс) + Valkey ведут себя как без повтора. ## Goals / Non-Goals @@ -111,14 +122,21 @@ - `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 пропускался бы как - отказавший. + **`retry=Retry(NoBackoff(), 1, supported_errors=(ConnectionError,))`** + из `redis.asyncio.retry` — один немедленный повтор только на обрыв + соединения: после рестарта Valkey старое соединение переоткрывается + без отказа, а таймаут не повторяется, и зависший Valkey не держит + запрос дольше (Context). Пул — `BlockingConnectionPool` с ожиданием + свободного соединения не дольше того же таймаута: обычный пул при + всплеске запросов сразу бросает `MaxConnectionsError`, и здоровый + Valkey пропускался бы как отказавший. - Обёртка `Cache` (там же) с `get(key)` и `set(key, value, ttl)` - поверх клиента: при `RedisError` и `OSError` не бросает, а возвращает - промах или `False`. После отказа включается пропуск на + поверх клиента. Вся команда — ожидание пула, соединение, повтор и + ответ — ограничена `asyncio.timeout([cache] timeout_seconds)`: без + этого при всплеске команда могла ждать пул 0,2 с и ещё 0,2 с ответа. + При `RedisError` и `OSError` (в том числе `TimeoutError`) обёртка не + бросает, а возвращает промах или `False`. После отказа включается + пропуск на `[cache] retry_after_seconds` (5): обращений к Valkey нет, каждый запрос идёт сразу в PostgreSQL. В журнал — `warning` «Cache is unavailable» один раз на отказ и `info` «Cache is available again» при @@ -144,9 +162,10 @@ repo не знает о кэше по правилу слоя, а запись аутентификация — `SELECT` сессии в PostgreSQL, кэш её не касается. Цена отказа: остановленный Valkey — ≈ 0 мс (соединение отклоняется -сразу), замороженный — 0,2 с в первом запросе после отказа, дальше -5 с без обращений. Без отключения повторов было бы 4–6 с на запрос -(Context). +сразу), замороженный — 0,2 с в первом запросе после отказа (и в каждом +из одновременных с ним), дальше 5 с без обращений. С повторами redis-py +по умолчанию было бы 4–6 с на запрос (Context). Рестарт Valkey отказом +не считается: старое соединение переоткрывается повтором. *Альтернатива:* 503 при недоступности Valkey. Отвергнута: рубрика допускает «корректно обходит кэш», а кэш без обхода ухудшал бы @@ -180,7 +199,7 @@ repo не знает о кэше по правилу слоя, а запись |---|---| | `evidence/cache/hits.md` | 50 чтений карточки: чтения таблицы `chats` (`seq_scan + idx_scan` в `pg_stat_user_tables`: таблица мала, и поиск по `id` идёт последовательным сканированием) растут на 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` → тот же ответ, ключ снова есть; рестарт одного Valkey при работающем API; `scripts/restart.sh` перезапускает Valkey (`StartedAt`), `make test-persistence` — `PASS` | +| `evidence/cache/flush-restart.md` | `FLUSHALL` → тот же ответ, ключ снова есть; рестарт одного Valkey при работающем API — без отказа и без `warning`; `scripts/restart.sh` перезапускает Valkey (`StartedAt`), `make test-persistence` — `PASS` | | `evidence/cache/config.md` | другие `VALKEY_PORT` / `VALKEY_OUT_PORT` и новый `VALKEY_PASSWORD` без правки compose: docker и консоль пишут в кэш, прежний пароль отвергнут | ## Risks / Trade-offs @@ -199,15 +218,12 @@ repo не знает о кэше по правилу слоя, а запись - [Пропуск кэша на 5 с после отказа: в это время PostgreSQL получает весь поток чтений карточек] → Это нагрузка без кэша, на которую база и рассчитана; срок — настройка. -- [Рестарт Valkey при работающем API: первая команда по соединению - пула, открытому до рестарта, получает `ConnectionError` (в docker — - `Connection closed by server.`, в консоли через прокси портов Docker - Desktop — `Connection reset by peer`) и включает пропуск на 5 с. - Проверка соединения при выдаче из пула этого не видит, а один - немедленный повтор на `ConnectionError` в консоли тоже получал reset] - → Ответы те же, из PostgreSQL; после пропуска кэш работает - (`evidence/cache/flush-restart.md`). Повторов нет, как и решено выше. - `scripts/restart.sh` перезапускает и API, поэтому там пул новый. +- [Один повтор на `ConnectionError`: обрыв посреди чтения после почти + всего таймаута плюс повторное соединение могли бы занять больше 0,2 с] + → Всю команду ограничивает `asyncio.timeout` в `Cache` (решение 4): + 30 одновременных команд при замороженном Valkey — 200–201 мс. + Повтор не поможет, если Valkey действительно лежит, но и не задержит: + отказ в соединении приходит сразу. - [Карточка в кэше живёт до часа после того, как чат стал бы недоступен] → Чаты не удаляются и не меняются по контракту; при появлении такой операции — удаление ключа в ней (решение 2). diff --git a/openspec/changes/membership-cache/tasks.md b/openspec/changes/membership-cache/tasks.md index dce99c0c..3f095835 100644 --- a/openspec/changes/membership-cache/tasks.md +++ b/openspec/changes/membership-cache/tasks.md @@ -43,7 +43,8 @@ ## 3. Код -- [x] 3.1 `src/infra/cache/`: фабрика клиента без повторов, обёртка +- [x] 3.1 `src/infra/cache/`: фабрика клиента без повторов (после + verify — один повтор на обрыв, задача 7.1), обёртка `Cache` с пропуском после отказа и журналом, глобал в `instance.py` (решения 4, 5). Проверка: разовым скриптом против Valkey стенда `set`/`get` работают; при `docker compose stop valkey` `get` @@ -111,3 +112,20 @@ - [x] 6.3 `make lint`, `make check`, `openspec validate membership-cache --strict`, `graphify update .`; показать изменения и после подтверждения закоммитить evidence и отчёт. + +## 7. Правки по verify + +- [x] 7.1 Клиент (решение 4): `Retry` из `redis.asyncio.retry` — один + немедленный повтор только на `ConnectionError`; вся команда `Cache` — + под `asyncio.timeout([cache] timeout_seconds)`. Проверка: разовым + скриптом против Valkey стенда — после `restart valkey` промах без + `warning`, `stop` — < 50 мс, `pause` — ≈ 0,2 с, 30 одновременных + команд при `pause` — не дольше 0,21 с; `driver.py all` — код 0. +- [x] 7.2 Документы под новое поведение: design (Context, решения 4–5, + Risks), `infra.md`, `AGENTS.md`, комментарии `[cache] timeout_seconds`, + `REPORT.md`. Проверка: `grep -rn "без повторов" .claude AGENTS.md + REPORT.md` — нет утверждений, что повторов нет совсем. +- [ ] 7.3 `make lint`, `make test_isolated`; после подтверждения — + commit фикса. Затем с него переснять `evidence/cache/outage.md` и + `evidence/cache/flush-restart.md`, обновить строки `REPORT.md` и после + подтверждения закоммитить. diff --git a/src/config/settings.py b/src/config/settings.py index 5dc3104b..ff61586a 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -105,7 +105,8 @@ class Cache(BaseModel): port: int = Field(default=6379, ge=1, le=65535) password: SecretStr = SecretStr("") - # секунды на соединение и ответ; дольше — запрос идёт в PostgreSQL + # секунды на всю команду кэша: ожидание пула, соединение, повтор и + # ответ; дольше — запрос идёт в PostgreSQL timeout_seconds: float = Field(default=0.2, gt=0) # секунды, на которые кэш пропускается после отказа Valkey retry_after_seconds: float = Field(default=5, gt=0) diff --git a/src/infra/cache/client.py b/src/infra/cache/client.py index ab47a9a5..5d0dd005 100644 --- a/src/infra/cache/client.py +++ b/src/infra/cache/client.py @@ -1,18 +1,24 @@ -"""Клиент Valkey без повторов и с обходом при отказе. +"""Клиент Valkey со сроком на команду и обходом при отказе. redis-py по умолчанию повторяет команду с backoff: замороженный Valkey задерживал запрос на 6 с вместо таймаута клиента (design change -`membership-cache`, Context). Здесь повторов нет, а после отказа кэш -пропускается на `[cache] retry_after_seconds`: запросы идут сразу в -PostgreSQL, не дожидаясь таймаута каждый раз. +`membership-cache`, Context). Здесь повтор один и только на обрыв +соединения (`ConnectionError`): старое соединение пула после рестарта +Valkey переоткрывается сразу, а таймаут не повторяется. Вся команда — +ожидание пула, соединение, повтор и ответ — ограничена +`[cache] timeout_seconds`. После отказа кэш пропускается на +`[cache] retry_after_seconds`: запросы идут сразу в PostgreSQL, не +дожидаясь таймаута каждый раз. """ +import asyncio import time from redis.asyncio import BlockingConnectionPool, Redis +from redis.asyncio.retry import Retry from redis.backoff import NoBackoff +from redis.exceptions import ConnectionError as RedisConnectionError 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 @@ -32,10 +38,12 @@ class Cache: client: Redis, *, namespace: str, + timeout_seconds: float, retry_after_seconds: float, ) -> None: self.namespace = namespace self._client = client + self._timeout_seconds = timeout_seconds self._retry_after_seconds = retry_after_seconds # monotonic-время конца пропуска; None — кэш работает self._skip_until: float | None = None @@ -45,7 +53,8 @@ class Cache: if self._skipping(): return None try: - value = await self._client.get(key) + async with asyncio.timeout(self._timeout_seconds): + value = await self._client.get(key) except (RedisError, OSError) as e: self._failed(e) return None @@ -57,7 +66,8 @@ class Cache: if self._skipping(): return False try: - await self._client.set(key, value, ex=ttl_seconds) + async with asyncio.timeout(self._timeout_seconds): + await self._client.set(key, value, ex=ttl_seconds) except (RedisError, OSError) as e: self._failed(e) return False @@ -74,11 +84,12 @@ class Cache: ) def _failed(self, error: Exception) -> None: - # warning — один на отказ: неудачные пробы после пропуска молчат + # warning — один на отказ: неудачные пробы после пропуска молчат. + # TimeoutError от asyncio.timeout без текста — тогда repr if self._skip_until is None: logger.warning( "Cache is unavailable", - error=str(error), + error=str(error) or repr(error), error_type=type(error).__name__, retry_after_seconds=self._retry_after_seconds, ) @@ -94,7 +105,9 @@ def create_cache(cache: CacheSettings, *, namespace: str) -> Cache: """Кэш с пулом и таймаутами из `[cache]`; соединения — лениво.""" # BlockingConnectionPool: при всплеске запросов ждёт свободное # соединение, а обычный пул сразу бросал бы MaxConnectionsError, и - # здоровый Valkey пропускался бы как отказавший + # здоровый Valkey пропускался бы как отказавший. + # Retry — из redis.asyncio: синхронный класс асинхронное соединение + # вызывает через await, и повтор молча не выполняется pool = BlockingConnectionPool( host=cache.host, port=cache.port, @@ -103,11 +116,12 @@ def create_cache(cache: CacheSettings, *, namespace: str) -> Cache: timeout=cache.timeout_seconds, socket_timeout=cache.timeout_seconds, socket_connect_timeout=cache.timeout_seconds, - retry=Retry(NoBackoff(), 0), + retry=Retry(NoBackoff(), 1, supported_errors=(RedisConnectionError,)), decode_responses=True, ) return Cache( Redis.from_pool(pool), namespace=namespace, + timeout_seconds=cache.timeout_seconds, retry_after_seconds=cache.retry_after_seconds, )