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`). Роль, источник истины, срок, вытеснение и
отсутствие инвалидации — в `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
+2 -2
View File
@@ -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/<domain>.py # DTO между repo → service → api
+2 -1
View File
@@ -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
+36 -20
View File
@@ -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).
+19 -1
View File
@@ -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` и после
подтверждения закоммитить.
+2 -1
View File
@@ -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)
+25 -11
View File
@@ -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,
)