fix(redis): tear down half-open client socket + alert on stuck Redis

[overthelex]

Проблема (prod-інцидент 2026-07)

Після blue-green cutover постійний node-redis клієнт бекенда перейшов у half-open стан: TCP-сокет мертвий, але node-redis вважав з'єднання «connected» і не розривав його. Reconnect не спрацьовував, тому кожна операція cache / rate-limit / chat-search падала в 2500ms-таймаут CacheAdapter безкінечно (6+ хв), поки бекенд не перезапустили вручну. У UI це проявлялося як «Помилка мережі. Перевірте підключення.»

Наявні keepAlive + pingInterval (LEXAI-1795) самі по собі не рятували: pingInterval шле PING, але без read-таймауту node-redis ніколи не закриває напівживий сокет, а TCP-keepAlive виявляє це надто повільно.

Виправлення

• redis-client.ts: додано socket.socketTimeout = 60s — вікно без вхідних байтів закриває мертвий сокет і запускає reconnectStrategy. На живому з'єднанні PONG від pingInterval (знижено 30s→20s) тримає трафік значно нижче таймауту, тож спрацьовує лише на реально мертвому сокеті. Події ready/reconnecting/end під'єднані до хука стану.
• cache-adapter.ts: setMetricsCallback — викликається на кожній таймаут/помилці операції.
• metrics-service.ts: backend_redis_client_up (gauge) + redis_command_errors_total (counter). Назва gauge відрізняється від серверного redis_up з redis_exporter.
• http-server.ts: під'єднання gauge (через хук стану) і лічильника помилок.
• alert-rules.yml: два алерти:
  • BackendRedisClientDown — backend_redis_client_up == 0 за 2 хв (critical)
  • BackendRedisCommandErrors — rate(redis_command_errors_total) > 0.2/s за 3 хв (critical). Саме цей алерт ловить застряглий клієнт, поки gauge ще показує «up».

Тести

• cache-adapter.test.ts: +2 кейси на metrics callback (спрацьовує з лейблом операції на помилці; не спрацьовує на успіху). Усі 6 тестів проходять.
• TS: змінені файли компілюються без помилок.

Поза скоупом

• redis-consultation-message-bus.ts (pub/sub) не чіпав — socketTimeout на subscriber-з'єднанні має нюанси, а інцидент був у cache-клієнті.

🤖 Generated with Claude Code

---

Summary by cubic

Hardened the backend redis client to auto-tear half-open sockets and reconnect. Added metrics and alerts to detect a stuck client and prevent cascading cache/rate-limit timeouts.

• Bug Fixes

  • Add 60s socketTimeout and lower pingInterval to 20s to close dead sockets and trigger reconnects.
  • Emit connection state via a hook on ready/reconnecting/end.

• New Features

  • Metrics: backend_redis_client_up gauge and redis_command_errors_total counter; wired in http-server via the state hook and CacheAdapter.setMetricsCallback; tests added for the callback.
  • Alerts: BackendRedisClientDown (2m) and BackendRedisCommandErrors (>0.2/s for 3m).

^{Written for commit b7c0067. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="mcp_backend/src/utils/redis-client.ts">

<violation number="1" location="mcp_backend/src/utils/redis-client.ts:58">
P3: The Redis client unit test is now stale: it still expects a `disconnect` handler, while this code registers `ready`, `reconnecting`, and `end`. Updating `src/utils/__tests__/redis-client.test.ts` to assert the new events would keep CI aligned with the intended node-redis event model.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The Redis client unit test is now stale: it still expects a disconnect handler, while this code registers ready, reconnecting, and end. Updating src/utils/__tests__/redis-client.test.ts to assert the new events would keep CI aligned with the intended node-redis event model.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At mcp_backend/src/utils/redis-client.ts, line 58:

<comment>The Redis client unit test is now stale: it still expects a `disconnect` handler, while this code registers `ready`, `reconnecting`, and `end`. Updating `src/utils/__tests__/redis-client.test.ts` to assert the new events would keep CI aligned with the intended node-redis event model.</comment>

<file context>
@@ -36,11 +55,24 @@ export async function getRedisClient(): Promise<ReturnType<typeof createClient>
 
-    redisClient.on('disconnect', () => {
-      logger.warn('[Redis] Disconnected');
+    redisClient.on('ready', () => {
+      stateHook?.(true);
+    });
</file context>