Entrega e confiabilidade

Modelo de confiabilidade

Signal Client combina rotação de webhooks com persistência opcional de fallback para que tráfego em pico e falhas temporárias não se transformem em atualizações perdidas no lado do bot. O desenho é intencionalmente em camadas: primeiro tenta a entrega ao vivo pelo pool, depois enfileira envelopes que falharam e faz novas tentativas com backoff exponencial. Isso dá às equipes de bot um caminho prático para confiabilidade sem obrigar cada serviço produtor a implementar seu próprio scheduler de retry.

O FallbackWorker é a primitiva central de confiabilidade. Quando o sistema de fallback está habilitado e uma chamada de send falha, o worker persiste o envelope em um FallbackStore e tenta novamente em lotes executados em background. Depois de esgotar o número máximo de tentativas, o envelope é movido para uma partição de dead-letter para inspeção manual.

Referência de configuração de fallback

O objeto FallbackConfig controla todos os aspectos do sistema de retry. Todos os campos, exceto enabled e store, possuem padrões sensatos, então uma configuração mínima só precisa ativar a feature e escolher um backend de persistência.

Escolhendo um fallback store

A interface FallbackStore define um contrato de persistência com oito métodos: enqueue, claimBatch, markProcessed, reschedule, moveToDeadLetter, has, pendingCount e deadLetterCount. Duas implementações embutidas cobrem os cenários de implantação mais comuns. Você também pode implementar a interface por conta própria para backends customizados.

import { SignalClient } from '@spraxium/signal-client';

const client = new SignalClient({
  webhookUrls: [process.env.SIGNAL_WEBHOOK_URL_1!],
  hmacSecret: process.env.SIGNAL_HMAC_SECRET!,
  rateLimitStrategy: 'wait',
  fallback: {
    enabled: true,
    store: 'file',
    filePath: '.spraxium-signal-fallback.json',
    retryIntervalMs: 5_000,
    maxAttempts: 10,
    batchSize: 20,
    events: ['config.update', 'billing.status.changed'],
  },
});

FileFallbackStore mantém entradas pendentes, dead-letter e processadas em um único arquivo JSON. Ele carrega o arquivo sob demanda no primeiro acesso e grava novamente após cada mutação. A lista de entradas processadas é automaticamente reduzida para as últimas 5000 quando ultrapassa 10000, evitando crescimento sem limite. Esse store funciona bem em desenvolvimento local e em serviços pequenos com uma única instância.

RedisFallbackStore persiste entradas como chaves individuais no Redis sob o prefixo spraxium:signal:fallback:pending:, com dead-letters sob spraxium:signal:fallback:deadletter: e IDs processados em um conjunto em spraxium:signal:fallback:processed. O Redis é preferível para emissores com múltiplas instâncias, porque o estado de fallback é compartilhado entre réplicas sem coordenação pelo sistema de arquivos.

Backoff exponencial e jitter

Quando uma tentativa de retry falha, o worker reagenda o envelope usando uma fórmula de backoff exponencial com jitter aditivo. Essa fórmula evita tempestades de retry, espalhando as tentativas por intervalos cada vez maiores, enquanto o componente de jitter impede que vários envelopes tentem de novo exatamente no mesmo instante.

A fórmula exata é: retryIntervalMs * 2^min(attempt, 8) + random() * retryIntervalMs * 0.3. O expoente é limitado a 8 para evitar atrasos absurdamente longos em contagens altas de tentativa. Com retryIntervalMs padrão de 5000 e maxAttempts de 10, o backoff máximo antes do jitter fica em cerca de 1280 segundos, aproximadamente 21 minutos, na oitava tentativa.

Tratamento de dead-letter

Quando um envelope esgota o maxAttempts configurado, o worker o move para a partição de dead-letter via moveToDeadLetter. A entrada original é removida da fila pendente e armazenada com o último motivo de erro anexado. Envelopes em dead-letter nunca recebem retry automático, então exigem investigação manual.

No store em arquivo, entradas de dead-letter se acumulam no array deadLetter do arquivo JSON. No store em Redis, elas viram chaves individuais sob spraxium:signal:fallback:deadletter:. Ambos os stores acompanham essa quantidade via deadLetterCount, que você deve monitorar como parte das suas verificações operacionais de saúde.

O método stats do FallbackWorker retorna as contagens de pending e deadLetter em uma única chamada. Expor esses dados ao seu sistema de monitoramento é a forma mais simples de detectar falhas persistentes de entrega antes que elas afetem o comportamento visível do bot.

const { pending, deadLetter } = await client.fallback!.stats();

if (deadLetter > 0) {
  logger.warn(
    `Signal fallback: ${deadLetter} dead-letter envelopes require investigation`,
  );
}

if (pending > 100) {
  logger.warn(
    `Signal fallback: ${pending} pending envelopes, possible sustained delivery failure`,
  );
}

Ciclo de vida de uma entrada de fallback

Perfis de confiabilidade por cenário

Desligamento gracioso

Chame destroy no client durante a sequência de encerramento da sua aplicação para parar o FallbackWorker de forma limpa. Isso limpa o timer interno de setInterval e evita loops parciais de retry durante rolling deployments. O worker usa timer.unref() para não manter o processo Node.js vivo, mas destruir explicitamente o client garante uma limpeza determinística.

process.on('SIGTERM', () => {
  client.destroy();
  process.exit(0);
});

Se você pular a chamada de destroy, ciclos pendentes de retry podem ser executados parcialmente durante o shutdown, com potencial de produzir entregas em duplicidade. Em ambientes conteinerizados, onde desligamentos acontecem com frequência, isso é ainda mais importante.

Runbook operacional