Passo a passo de um serviço de notificações: canais, preferências, tentativas de entrega e retentativas

Objetivo

Entregar mensagens de vários produtores aos usuários por diversos canais, de acordo com as preferências de cada um, de modo que nenhum produtor fale diretamente com um provedor e que uma retentativa nunca envie a mensagem duas vezes.

Pré-requisitos

Uma lista de canais (e-mail, push, SMS, in-app) e seus provedores, um catálogo de tipos de notificação com canal padrão e urgência por tipo, e uma política sobre o que o usuário pode desativar.

Passos

1. Restrições: os produtores não devem ficar bloqueados esperando a entrega; os provedores falham de forma independente; para a maioria dos tipos, uma duplicata é pior que um atraso; campanhas em massa não podem atrasar mensagens transacionais.
2. Componentes: uma API de ingestão que aceita (idempotency_key, recipient, type, payload) e grava uma linha antes de responder; um roteador que expande cada notificação em entregas por canal depois de verificar as preferências e os horários de silêncio; uma fila por canal; workers de canal que renderizam os templates e chamam os provedores; um receptor de callbacks para bounces, reclamações e tokens inválidos.
3. Modelo de dados: notification(id, idempotency_key unique, recipient, type, payload, created_at); delivery(id, notification_id, channel, address, status, attempts, next_attempt_at, provider_message_id, last_error); preference(recipient, type, channel, enabled); device_token(recipient, token, platform, invalidated_at). A chave única torna inofensivas as retentativas dos produtores.
4. Retentativas: cada canal tem seu próprio cronograma de backoff, com jitter e um limite máximo; classifique os erros do provedor como passíveis de nova tentativa (timeouts, 5xx, rate limits) ou terminais (endereço inválido, descadastrado). No Web Push, a RFC 8030 exige um cabeçalho TTL em toda requisição de entrega, em segundos, e estabelece que, depois que ele expira, o serviço de push não deve tentar entregar; uma notificação urgente deve levar um TTL curto, em vez de ser retentada por horas depois de ter perdido a utilidade.
5. Modos de falha: um worker que cai depois de o provedor aceitar a mensagem, mas antes de a linha ser atualizada (gera duplicata; guarde o id da mensagem do provedor e prefira provedores com APIs de envio idempotentes); uma queda do provedor que aumenta o backlog (descarte os tipos sensíveis ao tempo conforme a idade, em vez de entregá-los atrasados); um template que falha em um locale (falhe aquela entrega, não o worker); campanhas que esgotam a capacidade do tráfego transacional (filas separadas ou prioridades); tokens invalidados silenciosamente (processe os callbacks e faça a limpeza).
6. Medição: tempo entre a ingestão e a aceitação pelo provedor, por canal; tentativas por entrega; taxa de falhas terminais por classe de erro; idade da fila; taxa de opt-out por tipo.
7. Não é para o início: failover entre múltiplos provedores, digests e agrupamento em lotes, limites de taxa por usuário, editor de templates, analytics de engajamento, experimentos de texto.

Resultado esperado

Os produtores chamam uma única API; cada entrega ou foi confirmada por um provedor, ou falhou de forma terminal com um motivo, ou continua agendada; reenviar uma requisição de um produtor não gera uma segunda mensagem.

Limites e base de verificação

Projeto proposto, sem medições. A supressão de duplicatas na fronteira com o provedor depende do provedor; sem uma API de envio idempotente, o projeto aceita duplicatas raras após uma queda.