Publicação confiável de eventos com transactional outbox

Objetivo

Garantir que toda mudança de estado confirmada gere o seu evento exatamente no momento em que a mudança é confirmada, sem precisar de uma transação distribuída entre o banco de dados e o message broker.

Pré-requisitos

Um serviço que seja dono do próprio banco de dados e publique eventos em um broker, e consumidores que tolerem duplicatas (deduplicando pelo id da mensagem). A página do padrão no microservices.io (citada) descreve o problema: o serviço precisa atualizar o banco de dados e enviar uma mensagem de forma atômica, e as mensagens de um mesmo agregado precisam manter a ordem entre as instâncias do serviço.

Passos

1. Crie uma tabela outbox com as colunas id (única, passa a ser o id da mensagem), aggregate_type, aggregate_id, event_type, payload (JSON), created_at e, apenas na variante com polling, published_at (anulável). Os nomes de coluna padrão do Debezium são id, aggregatetype, aggregateid, type e payload; nomes diferentes são mapeados pelas opções dele.
2. Na transação da aplicação que altera o estado, insira uma linha no outbox para cada evento e faça o commit. Nada mais acontece no caminho da requisição.
3. Escolha um relay:
   • Polling publisher: um worker seleciona as linhas ainda não publicadas na ordem de id (com FOR UPDATE SKIP LOCKED no PostgreSQL, para permitir vários workers), publica cada uma no broker usando o id da linha como id da mensagem e o id do agregado como chave de partição, e em seguida preenche published_at.
   • Log tailing: um conector de change data capture lê o log do banco de dados. O outbox event router do Debezium (citado) captura as inserções na tabela de outbox, encaminha cada linha para um tópico derivado do tipo do agregado e usa o id do agregado como chave da mensagem. Segundo a documentação, atualizações em linhas do outbox não são permitidas e exclusões são filtradas; por isso, nessa variante a tabela é apenas de inserção: as linhas são excluídas depois, nunca marcadas.
4. Aceite que uma falha entre a publicação e a marcação (ou, no log tailing, entre a publicação e o momento em que o conector registra sua posição) gera uma duplicata. A idempotência do produtor oferecida por alguns brokers cobre novas tentativas dentro de uma mesma sessão do produtor, mas não um relay reiniciado. Os consumidores deduplicam pelo id da mensagem.
5. Exclua ou arquive periodicamente as linhas já publicadas; mantenha a tabela pequena para que a consulta de polling continue barata.
6. Monitore a idade da linha não publicada mais antiga e a quantidade de linhas pendentes; dispare um alerta quando o relay parar de avançar.

Resultado esperado

Nenhum evento sem uma mudança confirmada e nenhuma mudança sem evento. Os consumidores recebem cada evento pelo menos uma vez, na ordem de cada agregado, desde que o relay preserve a ordem de inserção e o broker preserve a ordem por chave.

Limites e base de verificação

O polling acrescenta uma latência de um intervalo de polling; o log tailing exige infraestrutura de CDC e permissões no banco de dados. A ordem entre agregados diferentes não é garantida. Para testar, derrube o relay no meio de um lote e provoque uma falha na aplicação entre a escrita de negócio e o commit; o outbox não pode apresentar eventos órfãos nem eventos faltando.

Ordenação com um relay de polling

Vários workers de polling usando SKIP LOCKED não preservam a ordem por agregado: um worker pode publicar uma linha posterior de um agregado antes que outro worker publique uma anterior, e uma linha com id menor pode ficar visível depois de uma com id maior, porque as transações não fazem commit na ordem dos ids. Se os consumidores dependem da ordem por agregado, use um único worker de publicação ou divida os workers por um hash de aggregate_id, de modo que as linhas de um mesmo agregado sejam sempre tratadas pelo mesmo worker, e faça o polling a partir da linha não publicada mais antiga, e não a partir do último id visto. O relay por log tailing evita os dois problemas, porque lê os commits na ordem em que foram confirmados.