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 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 21:41:15 +03:00
co-authored by Claude Opus 5.5
parent 25a60d36cd
commit d7c9a5972b
7 changed files with 99 additions and 41 deletions
+13 -5
View File
@@ -62,17 +62,25 @@ paths:
change `membership-cache`). Роль, источник истины, срок, вытеснение и change `membership-cache`). Роль, источник истины, срок, вытеснение и
отсутствие инвалидации — в `REPORT.md`. Клиент — redis-py отсутствие инвалидации — в `REPORT.md`. Клиент — redis-py
(`redis.asyncio`): (`redis.asyncio`):
- **без повторов**: `retry=Retry(NoBackoff(), 0)`. По умолчанию - **один повтор, только на обрыв**: `retry=Retry(NoBackoff(), 1,
redis-py повторяет команду с backoff, и замороженный Valkey держал supported_errors=(ConnectionError,))`. По умолчанию redis-py
запрос 6 с вместо таймаута 0,2 с; повторяет команду с backoff, и замороженный Valkey держал запрос
6 с вместо 0,2 с. Таймаут не повторяется, а обрыв повторяется один
раз: после рестарта Valkey старое соединение пула иначе давало бы
отказ на первой команде;
- `Retry` — **из `redis.asyncio.retry`**. Синхронный `redis.retry.Retry`
асинхронное соединение принимает молча, но повтор с ним не
выполняется никогда (первая реализация так и ошиблась);
- `BlockingConnectionPool` на `[cache] max_connections` с ожиданием не - `BlockingConnectionPool` на `[cache] max_connections` с ожиданием не
дольше `timeout_seconds`: обычный пул при всплеске запросов сразу дольше `timeout_seconds`: обычный пул при всплеске запросов сразу
бросает `MaxConnectionsError`, и здоровый Valkey считался бы бросает `MaxConnectionsError`, и здоровый Valkey считался бы
отказавшим; отказавшим;
- `socket_timeout` и `socket_connect_timeout` — `[cache] - `socket_timeout` и `socket_connect_timeout` — `[cache]
timeout_seconds`. timeout_seconds`, а всю команду (пул, соединение, повтор, ответ)
ограничивает `asyncio.timeout` того же срока в `Cache`.
- Отказ Valkey — промах, а не 503 и не 500: `Cache.get` / `Cache.set` - Отказ Valkey — промах, а не 503 и не 500: `Cache.get` / `Cache.set`
ловят `RedisError` и `OSError`, отдают `None` / `False`, и запрос идёт в ловят `RedisError` и `OSError` (в том числе `TimeoutError` от
`asyncio.timeout`), отдают `None` / `False`, и запрос идёт в
Postgres. После отказа кэш пропускается на `[cache] Postgres. После отказа кэш пропускается на `[cache]
retry_after_seconds` без обращений к Valkey. В журнал — один retry_after_seconds` без обращений к Valkey. В журнал — один
`warning` «Cache is unavailable» на отказ и `info` «Cache is `warning` «Cache is unavailable» на отказ и `info` «Cache is
+2 -2
View File
@@ -160,7 +160,7 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan
| `service-layer.md` | `src/core/services/**` | | `service-layer.md` | `src/core/services/**` |
| `repo-layer.md` | `src/core/repos/**` | | `repo-layer.md` | `src/core/repos/**` |
| `dto.md` | `src/schemas/**` | | `dto.md` | `src/schemas/**` |
| `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (без повторов, обход при отказе) и другие клиенты | | `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиенты |
| `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии | | `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии |
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно | | `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
| `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть | | `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть |
@@ -300,7 +300,7 @@ src/
db/session.py # глобалы engine и session_factory процесса API db/session.py # глобалы engine и session_factory процесса API
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503 db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
db/models/ # модели SQLAlchemy (Base с created_at и to_dict) db/models/ # модели SQLAlchemy (Base с created_at и to_dict)
cache/client.py # create_cache (redis-py без повторов, блокирующий пул), Cache: отказ — промах и пропуск cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
cache/instance.py # глобал cache процесса API cache/instance.py # глобал cache процесса API
schemas/ schemas/
dataclasses/<domain>.py # DTO между repo → service → api dataclasses/<domain>.py # DTO между repo → service → api
+2 -1
View File
@@ -35,7 +35,8 @@ kdf_concurrency = 4
[cache] [cache]
# Адрес, порт и пароль Valkey приходят из .env (мосты к VALKEY_*) и из # Адрес, порт и пароль Valkey приходят из .env (мосты к VALKEY_*) и из
# environment compose; здесь их не указывать. # environment compose; здесь их не указывать.
# секунды на соединение и ответ Valkey; дольше — запрос идёт в PostgreSQL # секунды на всю команду Valkey (ожидание пула, соединение, ответ);
# дольше — запрос идёт в PostgreSQL
timeout_seconds = 0.2 timeout_seconds = 0.2
# секунды, на которые кэш пропускается после отказа Valkey # секунды, на которые кэш пропускается после отказа Valkey
retry_after_seconds = 5 retry_after_seconds = 5
+36 -20
View File
@@ -27,6 +27,17 @@
(`docker pause`) — `TimeoutError` через 6,27 с, остановленный — (`docker pause`) — `TimeoutError` через 6,27 с, остановленный —
`ConnectionError` через 3,98 с. С `Retry(NoBackoff(), 0)` — 0,20 с и `ConnectionError` через 3,98 с. С `Retry(NoBackoff(), 0)` — 0,20 с и
0,00 с. 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 ## Goals / Non-Goals
@@ -111,14 +122,21 @@
- `src/infra/cache/client.py` — фабрика `create_cache(settings.cache)`: - `src/infra/cache/client.py` — фабрика `create_cache(settings.cache)`:
`redis.asyncio.Redis` с `socket_timeout` и `socket_connect_timeout` из `redis.asyncio.Redis` с `socket_timeout` и `socket_connect_timeout` из
`[cache] timeout_seconds` (0,2), пулом на `max_connections` (10) и `[cache] timeout_seconds` (0,2), пулом на `max_connections` (10) и
**`retry=Retry(NoBackoff(), 0)`** — без повторов (Context). Пул — **`retry=Retry(NoBackoff(), 1, supported_errors=(ConnectionError,))`**
`BlockingConnectionPool` с ожиданием свободного соединения не дольше из `redis.asyncio.retry` — один немедленный повтор только на обрыв
того же таймаута: обычный пул при всплеске запросов сразу бросает соединения: после рестарта Valkey старое соединение переоткрывается
`MaxConnectionsError`, и здоровый Valkey пропускался бы как без отказа, а таймаут не повторяется, и зависший Valkey не держит
отказавший. запрос дольше (Context). Пул — `BlockingConnectionPool` с ожиданием
свободного соединения не дольше того же таймаута: обычный пул при
всплеске запросов сразу бросает `MaxConnectionsError`, и здоровый
Valkey пропускался бы как отказавший.
- Обёртка `Cache` (там же) с `get(key)` и `set(key, value, ttl)` - Обёртка `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 нет, каждый `[cache] retry_after_seconds` (5): обращений к Valkey нет, каждый
запрос идёт сразу в PostgreSQL. В журнал — `warning` «Cache is запрос идёт сразу в PostgreSQL. В журнал — `warning` «Cache is
unavailable» один раз на отказ и `info` «Cache is available again» при unavailable» один раз на отказ и `info` «Cache is available again» при
@@ -144,9 +162,10 @@ repo не знает о кэше по правилу слоя, а запись
аутентификация — `SELECT` сессии в PostgreSQL, кэш её не касается. аутентификация — `SELECT` сессии в PostgreSQL, кэш её не касается.
Цена отказа: остановленный Valkey — ≈ 0 мс (соединение отклоняется Цена отказа: остановленный Valkey — ≈ 0 мс (соединение отклоняется
сразу), замороженный — 0,2 с в первом запросе после отказа, дальше сразу), замороженный — 0,2 с в первом запросе после отказа (и в каждом
5 с без обращений. Без отключения повторов было бы 4–6 с на запрос из одновременных с ним), дальше 5 с без обращений. С повторами redis-py
(Context). по умолчанию было бы 4–6 с на запрос (Context). Рестарт Valkey отказом
не считается: старое соединение переоткрывается повтором.
*Альтернатива:* 503 при недоступности 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/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/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 и консоль пишут в кэш, прежний пароль отвергнут | | `evidence/cache/config.md` | другие `VALKEY_PORT` / `VALKEY_OUT_PORT` и новый `VALKEY_PASSWORD` без правки compose: docker и консоль пишут в кэш, прежний пароль отвергнут |
## Risks / Trade-offs ## Risks / Trade-offs
@@ -199,15 +218,12 @@ repo не знает о кэше по правилу слоя, а запись
- [Пропуск кэша на 5 с после отказа: в это время PostgreSQL получает - [Пропуск кэша на 5 с после отказа: в это время PostgreSQL получает
весь поток чтений карточек] → Это нагрузка без кэша, на которую база весь поток чтений карточек] → Это нагрузка без кэша, на которую база
и рассчитана; срок — настройка. и рассчитана; срок — настройка.
- [Рестарт Valkey при работающем API: первая команда по соединению - [Один повтор на `ConnectionError`: обрыв посреди чтения после почти
пула, открытому до рестарта, получает `ConnectionError` (в docker — всего таймаута плюс повторное соединение могли бы занять больше 0,2 с]
`Connection closed by server.`, в консоли через прокси портов Docker → Всю команду ограничивает `asyncio.timeout` в `Cache` (решение 4):
Desktop — `Connection reset by peer`) и включает пропуск на 5 с. 30 одновременных команд при замороженном Valkey — 200–201 мс.
Проверка соединения при выдаче из пула этого не видит, а один Повтор не поможет, если Valkey действительно лежит, но и не задержит:
немедленный повтор на `ConnectionError` в консоли тоже получал reset] отказ в соединении приходит сразу.
→ Ответы те же, из PostgreSQL; после пропуска кэш работает
(`evidence/cache/flush-restart.md`). Повторов нет, как и решено выше.
`scripts/restart.sh` перезапускает и API, поэтому там пул новый.
- [Карточка в кэше живёт до часа после того, как чат стал бы недоступен] - [Карточка в кэше живёт до часа после того, как чат стал бы недоступен]
→ Чаты не удаляются и не меняются по контракту; при появлении такой → Чаты не удаляются и не меняются по контракту; при появлении такой
операции — удаление ключа в ней (решение 2). операции — удаление ключа в ней (решение 2).
+19 -1
View File
@@ -43,7 +43,8 @@
## 3. Код ## 3. Код
- [x] 3.1 `src/infra/cache/`: фабрика клиента без повторов, обёртка - [x] 3.1 `src/infra/cache/`: фабрика клиента без повторов (после
verify — один повтор на обрыв, задача 7.1), обёртка
`Cache` с пропуском после отказа и журналом, глобал в `instance.py` `Cache` с пропуском после отказа и журналом, глобал в `instance.py`
(решения 4, 5). Проверка: разовым скриптом против Valkey стенда (решения 4, 5). Проверка: разовым скриптом против Valkey стенда
`set`/`get` работают; при `docker compose stop valkey` `get` `set`/`get` работают; при `docker compose stop valkey` `get`
@@ -111,3 +112,20 @@
- [x] 6.3 `make lint`, `make check`, `openspec validate membership-cache - [x] 6.3 `make lint`, `make check`, `openspec validate membership-cache
--strict`, `graphify update .`; показать изменения и после --strict`, `graphify update .`; показать изменения и после
подтверждения закоммитить evidence и отчёт. подтверждения закоммитить 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` и после
подтверждения закоммитить.
+2 -1
View File
@@ -105,7 +105,8 @@ class Cache(BaseModel):
port: int = Field(default=6379, ge=1, le=65535) port: int = Field(default=6379, ge=1, le=65535)
password: SecretStr = SecretStr("") password: SecretStr = SecretStr("")
# секунды на соединение и ответ; дольше — запрос идёт в PostgreSQL # секунды на всю команду кэша: ожидание пула, соединение, повтор и
# ответ; дольше — запрос идёт в PostgreSQL
timeout_seconds: float = Field(default=0.2, gt=0) timeout_seconds: float = Field(default=0.2, gt=0)
# секунды, на которые кэш пропускается после отказа Valkey # секунды, на которые кэш пропускается после отказа Valkey
retry_after_seconds: float = Field(default=5, gt=0) retry_after_seconds: float = Field(default=5, gt=0)
+25 -11
View File
@@ -1,18 +1,24 @@
"""Клиент Valkey без повторов и с обходом при отказе. """Клиент Valkey со сроком на команду и обходом при отказе.
redis-py по умолчанию повторяет команду с backoff: замороженный Valkey redis-py по умолчанию повторяет команду с backoff: замороженный Valkey
задерживал запрос на 6 с вместо таймаута клиента (design change задерживал запрос на 6 с вместо таймаута клиента (design change
`membership-cache`, Context). Здесь повторов нет, а после отказа кэш `membership-cache`, Context). Здесь повтор один и только на обрыв
пропускается на `[cache] retry_after_seconds`: запросы идут сразу в соединения (`ConnectionError`): старое соединение пула после рестарта
PostgreSQL, не дожидаясь таймаута каждый раз. Valkey переоткрывается сразу, а таймаут не повторяется. Вся команда —
ожидание пула, соединение, повтор и ответ — ограничена
`[cache] timeout_seconds`. После отказа кэш пропускается на
`[cache] retry_after_seconds`: запросы идут сразу в PostgreSQL, не
дожидаясь таймаута каждый раз.
""" """
import asyncio
import time import time
from redis.asyncio import BlockingConnectionPool, Redis from redis.asyncio import BlockingConnectionPool, Redis
from redis.asyncio.retry import Retry
from redis.backoff import NoBackoff from redis.backoff import NoBackoff
from redis.exceptions import ConnectionError as RedisConnectionError
from redis.exceptions import RedisError from redis.exceptions import RedisError
from redis.retry import Retry
from src.config.settings import Cache as CacheSettings from src.config.settings import Cache as CacheSettings
from src.infra.logger import AbstractLogger, get_logger from src.infra.logger import AbstractLogger, get_logger
@@ -32,10 +38,12 @@ class Cache:
client: Redis, client: Redis,
*, *,
namespace: str, namespace: str,
timeout_seconds: float,
retry_after_seconds: float, retry_after_seconds: float,
) -> None: ) -> None:
self.namespace = namespace self.namespace = namespace
self._client = client self._client = client
self._timeout_seconds = timeout_seconds
self._retry_after_seconds = retry_after_seconds self._retry_after_seconds = retry_after_seconds
# monotonic-время конца пропуска; None — кэш работает # monotonic-время конца пропуска; None — кэш работает
self._skip_until: float | None = None self._skip_until: float | None = None
@@ -45,7 +53,8 @@ class Cache:
if self._skipping(): if self._skipping():
return None return None
try: 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: except (RedisError, OSError) as e:
self._failed(e) self._failed(e)
return None return None
@@ -57,7 +66,8 @@ class Cache:
if self._skipping(): if self._skipping():
return False return False
try: 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: except (RedisError, OSError) as e:
self._failed(e) self._failed(e)
return False return False
@@ -74,11 +84,12 @@ class Cache:
) )
def _failed(self, error: Exception) -> None: def _failed(self, error: Exception) -> None:
# warning — один на отказ: неудачные пробы после пропуска молчат # warning — один на отказ: неудачные пробы после пропуска молчат.
# TimeoutError от asyncio.timeout без текста — тогда repr
if self._skip_until is None: if self._skip_until is None:
logger.warning( logger.warning(
"Cache is unavailable", "Cache is unavailable",
error=str(error), error=str(error) or repr(error),
error_type=type(error).__name__, error_type=type(error).__name__,
retry_after_seconds=self._retry_after_seconds, retry_after_seconds=self._retry_after_seconds,
) )
@@ -94,7 +105,9 @@ def create_cache(cache: CacheSettings, *, namespace: str) -> Cache:
"""Кэш с пулом и таймаутами из `[cache]`; соединения — лениво.""" """Кэш с пулом и таймаутами из `[cache]`; соединения — лениво."""
# BlockingConnectionPool: при всплеске запросов ждёт свободное # BlockingConnectionPool: при всплеске запросов ждёт свободное
# соединение, а обычный пул сразу бросал бы MaxConnectionsError, и # соединение, а обычный пул сразу бросал бы MaxConnectionsError, и
# здоровый Valkey пропускался бы как отказавший # здоровый Valkey пропускался бы как отказавший.
# Retry — из redis.asyncio: синхронный класс асинхронное соединение
# вызывает через await, и повтор молча не выполняется
pool = BlockingConnectionPool( pool = BlockingConnectionPool(
host=cache.host, host=cache.host,
port=cache.port, port=cache.port,
@@ -103,11 +116,12 @@ def create_cache(cache: CacheSettings, *, namespace: str) -> Cache:
timeout=cache.timeout_seconds, timeout=cache.timeout_seconds,
socket_timeout=cache.timeout_seconds, socket_timeout=cache.timeout_seconds,
socket_connect_timeout=cache.timeout_seconds, socket_connect_timeout=cache.timeout_seconds,
retry=Retry(NoBackoff(), 0), retry=Retry(NoBackoff(), 1, supported_errors=(RedisConnectionError,)),
decode_responses=True, decode_responses=True,
) )
return Cache( return Cache(
Redis.from_pool(pool), Redis.from_pool(pool),
namespace=namespace, namespace=namespace,
timeout_seconds=cache.timeout_seconds,
retry_after_seconds=cache.retry_after_seconds, retry_after_seconds=cache.retry_after_seconds,
) )