Relay MeshHub de integração orientado a eventos
Arquitetura de referência para sincronizar pedidos entre e-commerce, ERP, CRM e provedor de pagamentos com retentativas seguras, sem efeitos duplicados e com reprocessamento auditável.
- Disciplina
- Software sob medida
- Tecnologias
- TypeScript · PostgreSQL · Message broker · OpenTelemetry
- Demonstra
- Outbox transacional
- Sagas com compensação
- Idempotência ponta a ponta
- Operação sem engenheiro
O desafio
- 01
Webhooks chegam duplicados, fora de ordem ou não chegam. Sistemas externos ficam indisponíveis por minutos.
- 02
Gravar no banco e publicar uma mensagem são duas operações; se uma falhar, os sistemas divergem.
- 03
Quando algo dá errado, o time de operações precisa ver o que aconteceu e reprocessar sem chamar um engenheiro.
Restrições
- Sistemas legados
- Sem efeitos duplicados
- Operável por não engenheiros
Arquitetura
Componentes
- E-commerce
- Origem dos pedidos via webhook.
- Payments
- Confirmações de pagamento via webhook.
- Verified inbox
- Valida assinatura HMAC e descarta duplicatas pelo ID do evento.
- Order saga
- Máquina de estados com compensações para cada passo.
- Outbox
- Mensagens gravadas na mesma transação do estado.
- ERP
- Recebe pedidos e faturas com chave de idempotência.
- CRM
- Atualiza o histórico do cliente.
- Dead letters
- Falhas definitivas com contexto completo e botão de reprocessar.
Decisões de engenharia
D1Outbox transacional
- Escolha
- O estado do pedido e a mensagem a publicar são gravados na mesma transação; um relay publica depois.
- Alternativa descartada
- Gravar no banco e publicar no broker em sequência.
- Por quê
- Escritas duplas falham de forma parcial. Com a outbox, ou as duas coisas acontecem ou nenhuma acontece.
D2Pelo menos uma vez + consumidores idempotentes
- Escolha
- Toda chamada externa leva uma chave de idempotência derivada do evento de origem.
- Alternativa descartada
- Perseguir entrega exatamente uma vez no transporte.
- Por quê
- Exatamente uma vez na rede não existe na prática. Exatamente uma vez no efeito, sim, com idempotência.
D3Saga em vez de transação distribuída
- Escolha
- Cada passo tem uma compensação explícita (cancelar reserva, estornar fatura).
- Alternativa descartada
- Two-phase commit entre sistemas.
- Por quê
- ERPs e provedores de pagamento não participam de 2PC. Compensações são o que esses sistemas oferecem de fato.
D4Reprocessamento como funcionalidade
- Escolha
- Fila de mensagens mortas com contexto, motivo e reprocessamento pela interface.
- Alternativa descartada
- Logs para um engenheiro investigar.
- Por quê
- Falhas de integração são rotina. Quem opera precisa resolvê-las sem depender do time de desenvolvimento.
Detalhes de implementação
Webhooks entram por um endpoint que valida a assinatura, grava o evento bruto na inbox com o ID externo como chave única e responde rápido. O processamento acontece depois, fora do caminho da requisição.
A saga avança um passo por vez e grava, na mesma transação, o novo estado e as mensagens de saída. Um relay lê a outbox em ordem e publica com retentativas exponenciais.
Cada mensagem carrega um trace ID desde o webhook de origem, então a visão de operações mostra a história completa de um pedido em uma linha do tempo.
export async function advance(orderId: string, event: DomainEvent) {
await db.transaction(async (tx) => {
const saga = await tx.sagas.lockById(orderId); // SELECT … FOR UPDATE
const step = saga.transition(event); // pure: returns next state + commands
await tx.sagas.save(saga.id, step.state);
for (const command of step.commands) {
await tx.outbox.insert({
topic: command.topic,
payload: command.payload,
// Same source event => same key => the ERP applies it once.
idempotencyKey: `${event.id}:${command.topic}`,
traceId: event.traceId,
});
}
});
}Resultados
Não aplicável. Por ser uma demonstração interna, não há métricas de produção verificadas a relatar, e não publicamos números estimados como se fossem resultados.
Tem um problema parecido?
Conte o contexto. Discutimos a arquitetura antes de qualquer proposta comercial.
Próximo estudoLedgerlineInteligência contratual com recuperação avaliada