Entrega y confiabilidad

Modelo de confiabilidad

Signal Client combina rotación de webhooks con persistencia opcional de fallback para que el tráfico en ráfagas y las fallas temporales no se conviertan en actualizaciones perdidas del lado del bot. El diseño es intencionalmente por capas: primero intenta entrega en vivo a través del pool, luego encola envelopes fallidos y los reintenta con backoff exponencial. Esto da a los equipos de bot una ruta práctica hacia la confiabilidad sin forzar que cada servicio productor implemente su propio scheduler de reintentos.

FallbackWorker es la primitiva central de confiabilidad. Cuando el sistema de fallback está habilitado y una llamada send falla, el worker persiste el envelope en un FallbackStore y lo reintenta en batches en segundo plano. Tras agotar el máximo de intentos, el envelope se mueve a una partición dead-letter para inspección manual.

Referencia de configuración de fallback

El objeto FallbackConfig controla cada aspecto del sistema de reintentos. Todos los campos salvo enabled y store tienen defaults razonables, así que una configuración mínima solo necesita activar la función y elegir un backend de persistencia.

Elegir un fallback store

La interfaz FallbackStore define un contrato de persistencia con ocho métodos: enqueue, claimBatch, markProcessed, reschedule, moveToDeadLetter, has, pendingCount y deadLetterCount. Dos implementaciones incluidas cubren los escenarios de despliegue más comunes. También puedes implementar la interfaz para backends personalizados.

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 mantiene entradas pending, dead-letter y processed en un único archivo JSON. Carga el archivo de forma lazy en el primer acceso y hace flush después de cada mutación. La lista de processed se recorta automáticamente a las últimas 5000 entradas cuando supera 10000, evitando crecimiento sin límite. Este store funciona muy bien para desarrollo local y servicios pequeños de instancia única.

RedisFallbackStore persiste entradas como claves Redis individuales bajo el prefijo spraxium:signal:fallback:pending:, con entradas dead-letter bajo spraxium:signal:fallback:deadletter: y IDs procesados en un set en spraxium:signal:fallback:processed. Redis es preferible para emisores con múltiples instancias porque el estado de fallback se comparte entre réplicas sin coordinación de sistema de archivos.

Backoff exponencial y jitter

Cuando falla un intento de reintento, el worker reprograma el envelope usando una fórmula de backoff exponencial con jitter aditivo. La fórmula evita tormentas de reintentos al distribuir intentos en intervalos cada vez mayores, mientras el jitter evita que múltiples envelopes reintenten exactamente al mismo tiempo.

La fórmula exacta es: retryIntervalMs * 2^min(attempt, 8) + random() * retryIntervalMs * 0.3. El exponente se limita a 8 para evitar esperas absurdamente largas con muchos intentos. Con retryIntervalMs default 5000 y maxAttempts 10, el backoff máximo antes de jitter es aproximadamente 1280 segundos (alrededor de 21 minutos) en el octavo intento.

Manejo de dead-letter

Cuando un envelope agota maxAttempts configurado, el worker lo mueve a la partición dead-letter vía moveToDeadLetter. La entrada original se elimina de la cola pending y se guarda con el último motivo de error adjunto. Los envelopes dead-letter nunca se reintentan automáticamente, por lo que requieren investigación manual.

En file store, las entradas dead-letter se acumulan en el array deadLetter del archivo JSON. En Redis store, se mueven a claves individuales bajo spraxium:signal:fallback:deadletter:. Ambos stores rastrean el conteo con deadLetterCount, que deberías monitorear como parte de tus checks de salud operativa.

El método stats de FallbackWorker devuelve conteos pending y deadLetter en una sola llamada. Exponer esos datos a tu sistema de monitoreo es la forma más simple de detectar fallas persistentes de entrega antes de impactar comportamiento del bot orientado a usuarios.

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 una entrada fallback

Perfiles de confiabilidad por escenario

Apagado ordenado

Llama a destroy en el cliente durante la secuencia de apagado de tu aplicación para detener FallbackWorker limpiamente. Esto limpia el timer interno de setInterval y evita loops parciales de reintento durante despliegues rolling. El worker usa timer.unref() para no mantener vivo el proceso Node.js, pero destruir explícitamente el cliente asegura una limpieza determinística.

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

Si omites la llamada a destroy, ciclos pending de reintento podrían ejecutarse parcialmente durante shutdown, produciendo potenciales entregas duplicadas. En entornos containerizados donde los apagados son frecuentes, esto es especialmente importante.

Runbook operativo