Transactional Inbox

Problema

Um consumidor recebe a mesma mensagem mais de uma vez. Se cada entrega aplica o efeito de novo, o pedido gera duas cobranças, dois e-mails ou dois débitos.

O broker entrega ao menos uma vez. A janela entre gravar o efeito e confirmar o offset é o lugar em que a repetição aparece.

Antes e depois

Sem Inbox, gravar a cobrança e confirmar o Kafka são operações separadas. Uma reentrega repete a cobrança, porque nada lembra o identificador da mensagem. A ordem inversa confirma o broker antes do efeito e a cobrança pode se perder.

Com Inbox, a cobrança e o identificador entram na mesma transação local. O ack sai depois do commit. A próxima entrega encontra a mensagem e não repete o efeito.

Prós e contras

Quando usar

Use o padrão quando o efeito do consumidor não pode acontecer duas vezes e o broker pode entregar a mensagem de novo.

Exemplo em .NET

A cobrança e a inbox usam a mesma transação. A consulta antes do INSERT é intencionalmente incompleta: em produção, a chave única da mensagem precisa recusar a segunda inserção. O ack continua fora da transação. O consumidor sem inbox mostra o que falta.

// Fragmento ilustrativo. Charges e InboxMessages usam o mesmo DbContext
// e a mesma transação do banco. O ack do broker fica fora dessa transação.

await using var transaction =
    await dbContext.Database.BeginTransactionAsync(cancellationToken);

var seen = await dbContext.InboxMessages
    .AnyAsync(message => message.Id == orderCreated.MessageId, cancellationToken);

if (!seen)
{
    dbContext.InboxMessages.Add(
        InboxMessage.Create(orderCreated.MessageId, "OrderCreated"));
    dbContext.Charges.Add(Charge.For(orderCreated.OrderId));
    await dbContext.SaveChangesAsync(cancellationToken);
    await transaction.CommitAsync(cancellationToken);
}

await consumer.AcknowledgeAsync(orderCreated.MessageId, cancellationToken);

// Consumidor sem inbox, incompleto de propósito.
// Esta versão não guarda o identificador da mensagem.
// Se o processo parar antes do ack, a reentrega cria outra cobrança.
// Se o ack sair antes do commit, o efeito pode se perder.

dbContext.Charges.Add(Charge.For(orderCreated.OrderId));
await dbContext.SaveChangesAsync(cancellationToken);
await consumer.AcknowledgeAsync(orderCreated.MessageId, cancellationToken);

O que a Inbox não garante

• Não transforma a entrega do broker em exatamente uma vez.
• O ack depois do commit ainda pode acontecer mais de uma vez. A inbox é o que impede o segundo efeito.
• Confirmar o broker antes do commit pode perder o efeito. A inbox não corrige essa ordem.
• Consultar a inbox e inserir em outro comando abre corrida entre consumidores. A reserva é a inserção única.
• Uma mensagem inválida não deve ser marcada como processada. Senão o efeito ausente parece concluído.
• A retenção das linhas, o nome das tabelas e o limite de três tentativas são escolhas didáticas.