@hed-hog/core 0.0.399 → 0.0.401

package/src/profile/profile.service.spec.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, afterEach, jest } from '@jest/globals';
+import { NotFoundException } from '@nestjs/common';
+
+import { ProfileService } from './profile.service';
+
+/**
+ * O que estes casos protegem é uma frase só: "esta conta tem senha" precisa
+ * significar a mesma coisa aqui e no resto do core.
+ *
+ * `hasPasswordCredential` (usado pelo "esqueci minha senha") sempre exigiu
+ * credencial **ativa**, e a revogação é o que o convite de acesso enterprise usa
+ * para trocar "autorize o acesso" por "crie sua conta e defina a senha". Estas
+ * duas leituras do perfil ignoravam `revoked_at`: `changePassword` aceitava a
+ * senha de uma credencial revogada e regravava o hash nela, e o `hasPassword` do
+ * `GET /profile` — que o app usa para decidir se pede senha — dizia que sim.
+ */
+
+const makeDeps = () => ({
+  prisma: {
+    user: { findUnique: jest.fn() },
+    user_credential: { findFirst: jest.fn(), update: jest.fn() },
+  },
+  user: { registerUserActivity: jest.fn() },
+  jwt: {},
+  setting: {},
+  security: { validatePassword: jest.fn(), hashArgon2: jest.fn() },
+  challenge: { resolveAppKeyFromOrigin: jest.fn() },
+  token: {},
+  mail: { resolveRecipientLocale: jest.fn(), sendTemplatedMail: jest.fn() },
+  eventEmitter: { emit: jest.fn() },
+});
+
+const makeService = (deps = makeDeps()) => ({
+  service: new ProfileService(
+    deps.prisma as any,
+    deps.user as any,
+    deps.jwt as any,
+    deps.setting as any,
+    deps.security as any,
+    deps.challenge as any,
+    deps.token as any,
+    deps.mail as any,
+    deps.eventEmitter as any,
+  ),
+  deps,
+});
+
+describe('ProfileService', () => {
+  afterEach(() => jest.clearAllMocks());
+
+  describe('changePassword', () => {
+    it('procura apenas credencial de senha não revogada', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.user_credential.findFirst.mockResolvedValue(null);
+
+      await expect(
+        service.changePassword('pt-BR', 7, {
+          currentPassword: 'antiga',
+          newPassword: 'nova-senha-forte',
+        } as any),
+      ).rejects.toThrow(NotFoundException);
+
+      expect(deps.prisma.user_credential.findFirst).toHaveBeenCalledWith({
+        where: { user_id: 7, type: 'password', revoked_at: null },
+      });
+      // Nada de validar hash revogado: sem credencial ativa o fluxo para antes.
+      expect(deps.security.validatePassword).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('getProfile', () => {
+    it('conta apenas credencial de senha não revogada em hasPassword', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.user.findUnique.mockResolvedValue({ id: 7, name: 'Aluno' });
+      deps.prisma.user_credential.findFirst.mockResolvedValue(null);
+      const count = jest.fn().mockResolvedValue(0);
+      (deps.prisma.user_credential as any).count = count;
+
+      const result = await service.getProfile(7);
+
+      expect(count).toHaveBeenCalledWith({
+        where: { user_id: 7, type: 'password', revoked_at: null },
+      });
+      expect(result).toEqual({ id: 7, name: 'Aluno', hasPassword: false });
+    });
+
+    it('devolve hasPassword true quando existe credencial ativa', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.user.findUnique.mockResolvedValue({ id: 7, name: 'Aluno' });
+      (deps.prisma.user_credential as any).count = jest.fn().mockResolvedValue(1);
+
+      await expect(service.getProfile(7)).resolves.toMatchObject({
+        hasPassword: true,
+      });
+    });
+  });
+});

package/src/profile/profile.service.ts

@@ -24,6 +24,7 @@ import { SecurityService } from '../security/security.service';
 import { SettingService } from '../setting/setting.service';
 import { TokenService } from '../token/token.service';
 import { UserService } from '../user/user.service';
+import { isActivePasswordCredential } from '../user/user-credential.util';
 import { buildSecurityEventVars } from '../utils/security-event-vars';
 import { resolveWebAuthnOrigin } from '../utils/webauthn-origin';
 import { ChangeEmailDto } from './dto/change-email.dto';
@@ -101,7 +102,7 @@ export class ProfileService {
       throw new NotFoundException(getLocaleText('userNotFound', locale, 'User not found.'));
     }
 
-    const credentials = (user as unknown as User).user_credential?.filter((c) => c.type === 'password') || [];
+    const credentials = (user as unknown as User).user_credential?.filter(isActivePasswordCredential) || [];
     
     if (!await this.security.validatePassword(locale, credentials, password)) {
       throw new BadRequestException(getLocaleText('accessDenied', locale, 'Access denied.'));
@@ -325,7 +326,9 @@ export class ProfileService {
   async getProfile(userId: number) {
     const [user, passwordCredentials] = await Promise.all([
       this.prisma.user.findUnique({ where: { id: userId } }),
-      this.prisma.user_credential.count({ where: { user_id: userId, type: 'password' } }),
+      this.prisma.user_credential.count({
+        where: { user_id: userId, type: 'password', revoked_at: null },
+      }),
     ]);
 
     if (!user) return user;
@@ -457,7 +460,10 @@ export class ProfileService {
 
   async changePassword(locale:string, userId: number, {currentPassword, newPassword}: ChangePasswordDto, ipAddress?: string, userAgent?: string, origin?: string) {
     const credential =  await this.prisma.user_credential.findFirst({
-      where: { user_id: userId, type: 'password' },
+      // Credencial revogada não é senha atual: sem este filtro, `changePassword`
+      // aceitava a senha antiga de uma credencial revogada e a reativava por via
+      // indireta, gravando um hash novo na mesma linha.
+      where: { user_id: userId, type: 'password', revoked_at: null },
     });
 
     if (!credential) {

package/src/realtime/realtime-tick.coalescer.spec.ts

@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { RealtimeTickCoalescer } from './realtime-tick.coalescer';
+
+describe('RealtimeTickCoalescer', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('junta uma rajada num único disparo', () => {
+    // O heartbeat bate a cada 15s por aluno: com 200 ao vivo seriam ~13
+    // eventos/s. É esta compressão que torna o push viável.
+    const onFlush = jest.fn();
+    const coalescer = new RealtimeTickCoalescer(2000, onFlush);
+
+    for (let i = 0; i < 200; i += 1) coalescer.signal();
+    expect(onFlush).not.toHaveBeenCalled();
+
+    jest.advanceTimersByTime(2000);
+
+    expect(onFlush).toHaveBeenCalledTimes(1);
+    expect(onFlush).toHaveBeenCalledWith({ seq: 1, coalesced: 200 });
+  });
+
+  it('não dispara sozinho quando não houve sinal', () => {
+    const onFlush = jest.fn();
+    new RealtimeTickCoalescer(2000, onFlush);
+
+    jest.advanceTimersByTime(10_000);
+
+    expect(onFlush).not.toHaveBeenCalled();
+  });
+
+  it('abre uma janela nova depois do disparo', () => {
+    const onFlush = jest.fn();
+    const coalescer = new RealtimeTickCoalescer(2000, onFlush);
+
+    coalescer.signal();
+    jest.advanceTimersByTime(2000);
+    expect(onFlush).toHaveBeenCalledTimes(1);
+
+    coalescer.signal();
+    jest.advanceTimersByTime(2000);
+
+    expect(onFlush).toHaveBeenCalledTimes(2);
+    expect(onFlush).toHaveBeenLastCalledWith({ seq: 2, coalesced: 1 });
+  });
+
+  it('não se auto-perpetua depois de esvaziar', () => {
+    const onFlush = jest.fn();
+    const coalescer = new RealtimeTickCoalescer(2000, onFlush);
+
+    coalescer.signal();
+    jest.advanceTimersByTime(2000);
+    jest.advanceTimersByTime(60_000);
+
+    expect(onFlush).toHaveBeenCalledTimes(1);
+  });
+
+  it('dispose cancela o disparo pendente', () => {
+    // Um timer vivo no encerramento segura o processo e atrasa o drain do pod.
+    const onFlush = jest.fn();
+    const coalescer = new RealtimeTickCoalescer(2000, onFlush);
+
+    coalescer.signal();
+    coalescer.dispose();
+    jest.advanceTimersByTime(10_000);
+
+    expect(onFlush).not.toHaveBeenCalled();
+  });
+
+  it('flush manual entrega o que estiver pendente', () => {
+    const onFlush = jest.fn();
+    const coalescer = new RealtimeTickCoalescer(2000, onFlush);
+
+    coalescer.signal();
+    coalescer.signal();
+    coalescer.flush();
+
+    expect(onFlush).toHaveBeenCalledWith({ seq: 1, coalesced: 2 });
+
+    // Depois do flush manual, o timer que já estava agendado não deve emitir de
+    // novo com a fila vazia.
+    jest.advanceTimersByTime(2000);
+    expect(onFlush).toHaveBeenCalledTimes(1);
+  });
+});

package/src/realtime/realtime-tick.coalescer.ts

@@ -0,0 +1,60 @@
+/**
+ * Junta uma rajada de sinais num único disparo.
+ *
+ * Nasceu no LMS e vive aqui porque o problema não é de lá: qualquer feature com
+ * uma tela de acompanhamento tem a mesma rajada. No LMS é o heartbeat do player,
+ * que bate a cada 15s por aluno — com 200 alunos ao vivo são ~13 sinais por
+ * segundo, e um evento de realtime por batida faria cada admin com a tela aberta
+ * refazer a consulta 13x/s. Na loja é o beacon de navegação dos visitantes. O
+ * coalescer transforma isso num disparo a cada `windowMs`.
+ *
+ * A borda escolhida é a de saída (trailing): o primeiro sinal agenda o disparo
+ * para daqui a `windowMs` e os que chegarem no meio são absorvidos. Isso limita
+ * o pior caso a um disparo por janela, ao custo de até `windowMs` de latência —
+ * aceitável para uma tela de acompanhamento, e o número de sinais absorvidos vai
+ * junto no disparo para quem quiser instrumentar.
+ */
+export class RealtimeTickCoalescer {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private pending = 0;
+  private sequence = 0;
+
+  constructor(
+    private readonly windowMs: number,
+    private readonly onFlush: (info: { seq: number; coalesced: number }) => void,
+  ) {}
+
+  /** Registra um sinal. Só o primeiro da janela agenda o disparo. */
+  signal(): void {
+    this.pending += 1;
+    if (this.timer !== null) return;
+
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.flush();
+    }, this.windowMs);
+
+    // Um timer pendente não deve segurar o processo no shutdown do worker.
+    this.timer.unref?.();
+  }
+
+  /** Dispara agora o que estiver pendente, se houver. */
+  flush(): void {
+    if (this.pending === 0) return;
+
+    const coalesced = this.pending;
+    this.pending = 0;
+    this.sequence += 1;
+
+    this.onFlush({ seq: this.sequence, coalesced });
+  }
+
+  /** Cancela o disparo pendente. Usado no encerramento do módulo. */
+  dispose(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.pending = 0;
+  }
+}

package/src/realtime/realtime.service.spec.ts

@@ -37,6 +37,39 @@ describe('RealtimeService', () => {
     expect(() => bare.emitToUser(1, 'x', {})).not.toThrow();
   });
 
+  // Caminho que só existe com mais de um pod: quem cria a notificação quase
+  // nunca é o pod que segura o socket do usuário (4 réplicas, sem sticky
+  // session), então a entrega real depende deste re-emit a partir do Redis.
+  describe('handleRedisMessage', () => {
+    const message = (over: Record<string, unknown> = {}) =>
+      JSON.stringify({
+        target: { type: 'user', target: '7' },
+        event: 'notification:event',
+        payload: { type: 'notification.created' },
+        originInstanceId: 'outro-pod',
+        ...over,
+      });
+
+    it('re-emite localmente o que veio de outro pod', () => {
+      (service as any).handleRedisMessage(message());
+      expect(server.to).toHaveBeenCalledWith('user:7');
+      expect(server.emit).toHaveBeenCalledWith('notification:event', {
+        type: 'notification.created',
+      });
+    });
+
+    it('ignora a própria mensagem, já emitida localmente', () => {
+      const ownId = (service as any).instanceId;
+      (service as any).handleRedisMessage(message({ originInstanceId: ownId }));
+      expect(server.to).not.toHaveBeenCalled();
+    });
+
+    it('ignora payload malformado', () => {
+      expect(() => (service as any).handleRedisMessage('{')).not.toThrow();
+      expect(server.to).not.toHaveBeenCalled();
+    });
+  });
+
   it('tracks local connections per user', () => {
     expect(service.trackConnect(1)).toBe(1);
     expect(service.trackConnect(1)).toBe(2);

package/src/realtime/realtime.service.ts

@@ -36,6 +36,15 @@ export class RealtimeService implements OnModuleInit, OnModuleDestroy {
   private server: Server | null = null;
   private redisPublisher: RedisClientType | null = null;
   private redisSubscriber: RedisClientType | null = null;
+  // A `reconnectStrategy` que nunca devolve `false` faz `client.connect()` ficar
+  // retentando pra sempre quando o Redis está indisponível: a Promise nunca
+  // resolve nem rejeita, e `onModuleInit` trava o boot inteiro da API esperando
+  // por ela. Este teto bound só a tentativa inicial; a reconexão de um cliente
+  // já conectado continua indefinida.
+  private readonly redisConnectTimeoutMs = Math.max(
+    1000,
+    Number(process.env.REDIS_CONNECT_TIMEOUT_MS || 3000),
+  );
 
   /** Local (this-instance) socket count per user id, for presence/liveness. */
   private readonly localConnections = new Map<number, number>();
@@ -162,8 +171,8 @@ export class RealtimeService implements OnModuleInit, OnModuleDestroy {
       this.redisSubscriber = createClient(opts);
       this.redisPublisher.on('error', (e) => this.logger.warn(`Realtime Redis publisher error: ${e?.message ?? e}`));
       this.redisSubscriber.on('error', (e) => this.logger.warn(`Realtime Redis subscriber error: ${e?.message ?? e}`));
-      await this.redisPublisher.connect();
-      await this.redisSubscriber.connect();
+      await this.withConnectTimeout(this.redisPublisher.connect(), this.redisConnectTimeoutMs);
+      await this.withConnectTimeout(this.redisSubscriber.connect(), this.redisConnectTimeoutMs);
       await this.redisSubscriber.subscribe(this.channel, (msg) => this.handleRedisMessage(msg));
       this.logger.log(`Realtime Redis fan-out enabled on channel ${this.channel}`);
     } catch (error) {
@@ -184,4 +193,21 @@ export class RealtimeService implements OnModuleInit, OnModuleDestroy {
       /* ignore */
     }
   }
+
+  private async withConnectTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+    let timer: NodeJS.Timeout;
+    try {
+      return await Promise.race([
+        promise,
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`Redis connection timed out after ${timeoutMs}ms`)),
+            timeoutMs,
+          );
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer!);
+    }
+  }
 }

package/src/redis/redis-kv.service.ts

@@ -0,0 +1,261 @@
+import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { createClient, type RedisClientType } from 'redis';
+import { extractRedisErrorMessage, withConnectTimeout } from './redis-pubsub';
+import { isReadOnlyReplicaError, resolveMasterUrl } from './redis-master';
+
+/** Uma entrada do índice ordenado por tempo, já decodificada. */
+export type RedisScoredMember = {
+  member: string;
+  score: number;
+};
+
+/**
+ * Chave/valor com TTL sobre o Redis, para estado efêmero compartilhado entre as
+ * réplicas da API.
+ *
+ * Existe ao lado do `redis-pubsub.ts` — que só publica e assina — porque
+ * algumas features precisam GUARDAR estado por um tempo curto, não só avisar
+ * que algo mudou. O caso que motivou: o painel de visitantes ao vivo da loja,
+ * onde gravar cada navegação no Postgres colocaria carga de escrita no banco
+ * que serve a própria loja, exatamente o que o recurso não pode fazer. Aqui o
+ * dado vive na memória do Redis e expira sozinho, sem job de limpeza.
+ *
+ * **Toda falha degrada para inerte.** Mesma postura do pub/sub: sem
+ * `REDIS_URL`, ou com o Redis fora, cada método vira no-op (ou devolve vazio) e
+ * quem chamou segue seu caminho. Um recurso de observação nunca pode derrubar o
+ * fluxo que ele observa — daí nenhum método propagar erro.
+ */
+@Injectable()
+export class RedisKvService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(RedisKvService.name);
+  private readonly url = String(process.env.REDIS_URL || '').trim();
+  private readonly connectTimeoutMs = Math.max(
+    1000,
+    Number(process.env.REDIS_CONNECT_TIMEOUT_MS || 3000),
+  );
+  /** Uma queda do Redis dispara `error` a cada tentativa de reconexão. */
+  private readonly errorLogCooldownMs = 30000;
+  private lastErrorLogAt = 0;
+
+  private client: RedisClientType | null = null;
+  /** Reconexão em andamento, para não abrir uma por escrita durante o failover. */
+  private reconnecting: Promise<void> | null = null;
+
+  /** `false` = sem Redis; todo método é no-op e quem chama não precisa saber. */
+  get enabled(): boolean {
+    return this.client !== null;
+  }
+
+  async onModuleInit(): Promise<void> {
+    if (!this.url) {
+      this.logger.log('Redis key-value disabled because REDIS_URL is not configured.');
+      return;
+    }
+
+    this.client = await this.connectToMaster();
+    if (this.client) this.logger.log('Redis key-value enabled.');
+  }
+
+  /**
+   * Conecta no master, e não em quem o Service devolver.
+   *
+   * `REDIS_URL` aponta para um Service que balanceia entre master e réplica
+   * (veja `resolveMasterUrl`), então conectar direto na URL deixa metade dos
+   * processos escrevendo numa réplica e falhando com `READONLY`.
+   */
+  private async connectToMaster(): Promise<RedisClientType | null> {
+    try {
+      const url = await resolveMasterUrl(
+        this.url,
+        this.logger,
+        this.connectTimeoutMs,
+      );
+
+      const client = createClient({
+        url,
+        socket: {
+          reconnectStrategy: (retries: number) => Math.min(retries * 250, 5000),
+        },
+      }) as RedisClientType;
+
+      // Registrado antes do connect: uma falha no handshake vira erro tratado
+      // em vez de um evento 'error' sem dono derrubando o processo.
+      client.on('error', (error: unknown) => this.logClientError(error));
+
+      await withConnectTimeout(client.connect(), this.connectTimeoutMs);
+      return client;
+    } catch (error) {
+      this.logger.warn(
+        `Redis key-value disabled: ${extractRedisErrorMessage(error)}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Refaz a conexão depois de um `READONLY`.
+   *
+   * Um failover troca quem é o master, e o client fica preso no nó que virou
+   * réplica — daí em diante toda escrita falha. Reconectar redescobre o master.
+   * O guard serializa as tentativas: sem ele, um pico de escritas em cima do
+   * failover abriria uma conexão nova por requisição.
+   */
+  private async reconnectToMaster(): Promise<void> {
+    if (this.reconnecting) return this.reconnecting;
+
+    this.reconnecting = (async () => {
+      const stale = this.client;
+      this.client = null;
+      if (stale) {
+        try {
+          await stale.quit();
+        } catch {
+          // O nó virou réplica ou caiu; encerrando de qualquer forma.
+        }
+      }
+      this.client = await this.connectToMaster();
+    })().finally(() => {
+      this.reconnecting = null;
+    });
+
+    return this.reconnecting;
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    const client = this.client;
+    this.client = null;
+    if (!client) return;
+    try {
+      await client.quit();
+    } catch {
+      // Encerrando de qualquer forma.
+    }
+  }
+
+  /** Grava um objeto como JSON com expiração em segundos. */
+  async setJson(key: string, value: unknown, ttlSeconds: number): Promise<void> {
+    await this.run(async (client) => {
+      await client.set(key, JSON.stringify(value), { EX: Math.max(1, ttlSeconds) });
+    });
+  }
+
+  /** Lê e desserializa. Devolve `null` se não existe, expirou ou está corrompido. */
+  async getJson<T>(key: string): Promise<T | null> {
+    return (
+      (await this.run(async (client) => {
+        const raw = await client.get(key);
+        if (raw == null) return null;
+        try {
+          return JSON.parse(raw) as T;
+        } catch {
+          // Valor gravado por uma versão anterior com outro formato: tratar como
+          // ausente é melhor do que estourar na leitura do painel.
+          return null;
+        }
+      })) ?? null
+    );
+  }
+
+  /**
+   * Lê várias chaves numa ida só.
+   *
+   * `MGET` em vez de um `get` por chave: com dezenas de visitantes ao vivo, uma
+   * chamada por chave multiplicaria o round-trip pelo número de sessões a cada
+   * atualização do painel. Devolve na MESMA ordem das chaves pedidas, com `null`
+   * onde não havia valor.
+   */
+  async getJsonMany<T>(keys: string[]): Promise<Array<T | null>> {
+    if (!keys.length) return [];
+    const values = await this.run(async (client) => client.mGet(keys));
+    if (!values) return keys.map(() => null);
+
+    return values.map((raw) => {
+      if (raw == null) return null;
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return null;
+      }
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.run(async (client) => {
+      await client.del(key);
+    });
+  }
+
+  /** Põe (ou repontua) um membro no índice ordenado. */
+  async zadd(key: string, member: string, score: number): Promise<void> {
+    await this.run(async (client) => {
+      await client.zAdd(key, [{ value: member, score }]);
+    });
+  }
+
+  /** Membros com score dentro do intervalo, do mais antigo para o mais recente. */
+  async zrangeByScore(
+    key: string,
+    min: number,
+    max: number,
+  ): Promise<RedisScoredMember[]> {
+    const rows = await this.run(async (client) =>
+      client.zRangeByScoreWithScores(key, min, max),
+    );
+    return (rows ?? []).map((row) => ({ member: row.value, score: row.score }));
+  }
+
+  /**
+   * Remove do índice o que caiu fora da janela.
+   *
+   * O TTL cuida das chaves individuais, mas não do índice: sem esta poda o
+   * sorted set acumularia para sempre todo visitante que já passou pela loja, e
+   * cada leitura do painel ficaria mais cara que a anterior.
+   */
+  async zremRangeByScore(key: string, min: number, max: number): Promise<void> {
+    await this.run(async (client) => {
+      await client.zRemRangeByScore(key, min, max);
+    });
+  }
+
+  /**
+   * Executa contra o client, engolindo qualquer falha.
+   *
+   * É aqui que mora a promessa de degradar para inerte: quem chama recebe
+   * `undefined` e trata como "sem dado", em vez de precisar de try/catch em
+   * cada ponto de uso.
+   */
+  private async run<T>(fn: (client: RedisClientType) => Promise<T>): Promise<T | undefined> {
+    const client = this.client;
+    if (!client) return undefined;
+    try {
+      return await fn(client);
+    } catch (error) {
+      // `READONLY` quer dizer que este client está falando com uma réplica —
+      // um failover trocou o master debaixo dele. Reconectar redescobre quem é
+      // o master e a operação é refeita uma vez; qualquer outro erro segue a
+      // regra da casa e degrada para inerte.
+      if (isReadOnlyReplicaError(error)) {
+        await this.reconnectToMaster();
+        const reconnected = this.client;
+        if (reconnected) {
+          try {
+            return await fn(reconnected);
+          } catch (retryError) {
+            this.logClientError(retryError);
+            return undefined;
+          }
+        }
+      }
+
+      this.logClientError(error);
+      return undefined;
+    }
+  }
+
+  private logClientError(error: unknown): void {
+    const now = Date.now();
+    if (now - this.lastErrorLogAt < this.errorLogCooldownMs) return;
+    this.lastErrorLogAt = now;
+    this.logger.warn(`Redis key-value error: ${extractRedisErrorMessage(error)}`);
+  }
+}