Semântica de Entrega

Na manhã seguinte a uma grande abertura de vendas, chegam dois chamados ao suporte. A Ana recebeu três e-mails de confirmação idênticos. O Bruno não recebeu nenhum, embora seu pedido esteja confirmado e os ingressos estejam no app. Os dois problemas têm a mesma raiz: as mensagens atravessam várias máquinas e redes, qualquer uma delas pode falhar entre dois passos, e cada falha ou perde uma mensagem ou a repete. Esta página é sobre decidir qual das duas você pode tolerar, e sobre escrever consumidores para os quais uma repetição não causa dano.

Onde mensagens se perdem ou se duplicam

Siga um OrderConfirmed do order até o notification. Ele atravessa três trechos, e cada trecho tem a sua falha:

flowchart LR
    O["order<br/>(produtor)"] -->|"1 · envia"| B[("broker<br/>Kafka")]
    B -->|"2 · replica"| R[("réplicas")]
    B -->|"3 · entrega"| N["notification<br/>(consumidor)"]
    N -->|"4 · efeito colateral"| E["provedor de e-mail"]
    N -->|"5 · commit do offset"| B

Os três e-mails da Ana são o trecho 3–5: o notification enviou o e-mail e foi derrubado durante um deploy antes do commit, duas vezes. O e-mail que faltou para o Bruno é o trecho 1: o order salvou o pedido dele e caiu antes de publicar.

As três garantias de entrega

Uma garantia de entrega diz quantas vezes cada mensagem é processada na presença de falhas¹:

Exactly-once, com honestidade

"Entrega exactly-once" no sentido estrito é impossível sobre uma rede não confiável: o receptor nunca pode ter certeza de que o remetente viu a sua confirmação (o problema dos Dois Generais; veja Sistemas distribuídos). O que os sistemas realmente oferecem é processamento exactly-once dentro de uma fronteira:

• Produtor idempotente (enable.idempotence=true, padrão desde o Kafka 3.0). O broker dá a cada produtor um id e acompanha um número de sequência por partição; um lote reenviado com uma sequência já gravada é descartado. Elimina as duplicatas do trecho 1.
• Transações do Kafka². Um produtor pode escrever em várias partições e confirmar offsets de consumo de forma atômica. Consumidores com isolation.level=read_committed só veem transações confirmadas. Isso dá exactly-once para pipelines ler do Kafka → processar → escrever no Kafka (Kafka Streams: processing.guarantee=exactly_once_v2).
• A fronteira. Transações do Kafka não conseguem desenviar um e-mail, estornar uma cobrança no cartão ou desfazer uma linha no PostgreSQL. Assim que um efeito colateral sai do Kafka, você volta ao at-least-once.

Então a receita prática, usada em quase todo lugar, é:

Efetivamente uma vez = entrega at-least-once + processamento idempotente.

Consumidores idempotentes

Uma operação é idempotente se fazê-la duas vezes tem o mesmo efeito que fazê-la uma vez³. Um consumidor idempotente torna entregas duplicadas inofensivas. Há três famílias de técnicas:

A tabela de deduplicação é a solução geral. Ela exige que toda mensagem carregue um id de evento único (um UUID gerado uma vez, pelo produtor, quando o evento é criado — não a cada retry):

CREATE TABLE processed_events (
    consumer      TEXT        NOT NULL,
    event_id      UUID        NOT NULL,
    processed_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (consumer, event_id)
);

@Component
@RequiredArgsConstructor
public class OrderConfirmedListener {

    private final JdbcTemplate jdbc;
    private final ConfirmationEmails emails;

    @KafkaListener(topics = "order-events", groupId = "notification")
    @Transactional   // dedup row and business change commit together, or not at all
    public void on(OrderConfirmed event) {
        int inserted = jdbc.update("""
            INSERT INTO processed_events (consumer, event_id)
            VALUES ('notification', ?)
            ON CONFLICT DO NOTHING
            """, event.eventId());
        if (inserted == 0) {
            return;                     // duplicate delivery: already handled
        }
        emails.schedule(event);         // INSERT INTO outgoing_emails ... (same transaction)
    }
}

Dois detalhes tornam isso correto:

1. Mesma transação. A linha de deduplicação e a mudança de negócio são confirmadas juntas. Se o serviço cai antes do commit, nenhuma das duas existe e a mensagem reentregue é processada normalmente; depois do commit, a reentrega é pulada. O offset é confirmado depois da transação.
2. Efeitos colaterais externos são agendados, não executados, dentro da transação. emails.schedule só insere uma linha em outgoing_emails (com UNIQUE (order_id, kind)). Um enviador separado lê essa tabela e chama o provedor de e-mail passando o id da linha como chave de idempotência, então um retry da chamada não envia duas vezes. Provedores de e-mail, SMS e pagamentos costumam aceitar esse tipo de chave (veja Integrações).

Mantenha a tabela de deduplicação limitada: apague linhas mais antigas que a retenção do tópico mais uma margem (uma reentrega mais antiga que a retenção não pode acontecer).

/** @return true if an e-mail was sent, false if the event was a duplicate */
@Transactional
public boolean handle(OrderEvent e) {
    if (props.idempotent()) {
        int fresh = jdbc.sql("INSERT INTO processed_events (event_id) VALUES (?) ON CONFLICT DO NOTHING")
                .param(e.eventId())
                .update();
        if (fresh == 0) {
            log.info("duplicate event {} for order {} ignored", e.eventId(), e.orderId());
            return false;
        }
    }
    email.orderReceived(e); // throws -> the whole transaction rolls back, the dedupe row too
    jdbc.sql("""
            INSERT INTO notifications (event_id, order_id, email, kind, occurred_at)
            VALUES (?, ?, ?, ?, ?)
            """)
            .params(e.eventId(), e.orderId(), e.customerEmail(), e.eventType(),
                    OffsetDateTime.ofInstant(e.occurredAt(), ZoneOffset.UTC))
            .update();
    return true;
}

Ordenação

O Kafka garante ordem por partição, ou seja, por chave. Várias coisas ainda podem colocar eventos fora de ordem:

• Retries do produtor. Se o lote 1 falha e o lote 2 dá certo, o retry do lote 1 chega depois do lote 2. O produtor idempotente evita isso (ele mantém a ordem com até 5 requisições em voo por conexão).
• Chaves ou tópicos diferentes. SeatsHeld em inventory-events e OrderCancelled em order-events não têm ordem relativa nenhuma.
• Processamento paralelo dentro de um consumidor. Um pool de threads processa registros da mesma chave ao mesmo tempo.
• Retries no consumidor. Mover um registro com falha para um tópico de retry deixa registros posteriores da mesma chave passarem na frente (próxima seção).

Quando a ordem importa e o transporte não consegue garanti-la, torne o consumidor tolerante: carregue em cada evento uma versão (ou número de sequência) vinda da fonte da verdade, e ignore qualquer coisa mais antiga do que você já aplicou:

-- search keeps "seats left" per event; inventory stamps each change with a version
UPDATE event_availability
   SET seats_left = :seatsLeft, version = :version
 WHERE event_id = :eventId
   AND version < :version;     -- a late, older update changes nothing

Isso torna a atualização idempotente e insensível à ordem: aplicar as versões 7, 9, 8 deixa a versão 9.

Retries e dead letter queues

Um consumidor vai encontrar mensagens que não consegue processar. Por dois motivos bem diferentes:

• Falhas transitórias: o banco está reiniciando, o provedor de e-mail responde 503. Tentar de novo mais tarde vai funcionar.
• Falhas permanentes: o payload é JSON inválido, referencia um id de evento que não existe, um bug lança exceção em um campo específico. Tentar de novo vai falhar para sempre. Uma mensagem assim é uma mensagem venenosa (poison message).

Uma mensagem venenosa no início de uma partição bloqueia tudo o que vem atrás: o consumidor tenta de novo para sempre e o lag cresce para todos os outros pedidos daquela partição. A solução é uma dead letter queue (DLQ, no Kafka normalmente um dead letter topic, DLT): depois de um número limitado de tentativas, a mensagem é colocada de lado, junto com o erro, e o consumidor segue em frente.

stateDiagram-v2
    state "Entregue" as Delivered
    state "Processada" as Processed
    state "Tópico de retry" as RetryTopic
    state "Dead letter" as DeadLetter
    [*] --> Delivered
    Delivered --> Processed : sucesso
    Delivered --> RetryTopic : erro transitório (tentativa < máx.)
    RetryTopic --> Delivered : depois do backoff (1 s, 4 s, 16 s)
    Delivered --> DeadLetter : erro permanente, ou máx. de tentativas
    DeadLetter --> Delivered : corrigida e reenviada por um operador
    Processed --> [*]

Com o Spring Kafka, retries não bloqueantes são declarativos: registros com falha vão para tópicos de retry com atrasos crescentes, enquanto o tópico principal continua fluindo.

@RetryableTopic(
    attempts = "4",                                      // 1 try + 3 retries
    backOff = @BackOff(delay = 1000, multiplier = 4.0),  // 1 s, 4 s, 16 s
    exclude = { InvalidEventException.class },           // permanent: straight to the DLT
    dltTopicSuffix = "-dlt")
@KafkaListener(topics = "order-events", groupId = "notification")
public void on(OrderConfirmed event) {
    confirmations.send(event);
}

@DltHandler
public void onDeadLetter(OrderConfirmed event,
                         @Header(KafkaHeaders.DLT_EXCEPTION_MESSAGE) String error) {
    log.error("order {} moved to order-events-dlt: {}", event.orderId(), error);
}

Operando uma DLQ:

• Alerte sobre ela. Uma DLQ com mensagens é um incidente em câmera lenta: cada mensagem é um cliente sem e-mail ou um pedido fora do warehouse. Abra um chamado ou acione o plantão quando ela não estiver vazia ou estiver crescendo.
• Guarde o contexto. Armazene o tópico, a partição e o offset originais, a exceção e o número de tentativas como cabeçalhos (o Spring faz isso).
• Reenvie (redrive). Depois de corrigir o bug, reenvie a DLQ para o tópico principal. Isso só é seguro porque os consumidores são idempotentes.
• Cuidado com a ordem. Retries não bloqueantes deixam eventos posteriores do mesmo pedido passarem na frente de um que está em retry. Se a ordem por chave é essencial (um OrderCancelled não pode ser aplicado antes do seu OrderConfirmed), use retries bloqueantes para erros transitórios (tentar no lugar, com backoff, pausando a partição) ou consumidores protegidos por versão.

@Bean
DefaultErrorHandler errorHandler(KafkaTemplate<String, String> template) {
    // after the retries, publish to <topic>-dlt, same partition, with the exception in headers
    DeadLetterPublishingRecoverer recoverer = new DeadLetterPublishingRecoverer(template);

    ExponentialBackOffWithMaxRetries backOff = new ExponentialBackOffWithMaxRetries(3);
    backOff.setInitialInterval(500L);  // 0.5 s, 1 s, 2 s
    backOff.setMultiplier(2.0);
    backOff.setMaxInterval(5_000L);

    DefaultErrorHandler handler = new DefaultErrorHandler(recoverer, backOff);
    // permanent failures: retrying is pointless, go straight to the DLT
    handler.addNotRetryableExceptions(JacksonException.class, IllegalArgumentException.class);
    return handler;
}

@KafkaListener(topics = "order-events-dlt", groupId = "notification-dlt")
public void onDeadLetter(ConsumerRecord<String, String> record) {
    // the listener's exception is wrapped: the CAUSE class says what really failed
    Header cause = record.headers().lastHeader(KafkaHeaders.DLT_EXCEPTION_CAUSE_FQCN);
    String why = cause == null ? "?" : new String(cause.value(), StandardCharsets.UTF_8);
    log.warn("dead letter at {}-{}@{}: {}", record.topic(), record.partition(), record.offset(), why);
    jdbc.sql("""
            INSERT INTO dead_letters (topic, partition, record_offset, record_key, payload, reason)
            VALUES (?, ?, ?, ?, ?, ?)
            """)
            .params(record.topic(), record.partition(), record.offset(), record.key(), record.value(), why)
            .update();
}

Backpressure no consumidor

Um consumidor Kafka puxa as mensagens, então nunca é inundado pelo broker — mas ele pode inundar quem ele chama. O serviço notification não deve exceder o limite de taxa do provedor de e-mail só porque há um backlog de 100.000 mensagens esperando. Controle o ritmo com max.poll.records e um rate limiter no cliente, pause as partições enquanto um circuit breaker mais adiante estiver aberto (veja Padrões de resiliência), e deixe o lag crescer: um backlog que escoa no ritmo do provedor é melhor que ser banido pelo provedor.

Evolução de schema

Eventos vivem mais que o código que os produziu: um tópico com 7 dias de retenção contém mensagens escritas pela versão da semana passada do order, e os consumidores que as leem podem ser meses mais velhos ou mais novos. Você não consegue implantar produtores e consumidores de forma atômica, então toda mudança de schema precisa ser compatível com as versões ainda em execução⁴.

Nunca compatível: renomear um campo, mudar seu tipo (total de número para string), mudar seu significado (total de reais para centavos), reutilizar um número de campo do Protobuf.

{
  "type": "record", "name": "OrderConfirmed", "namespace": "boxoffice.events",
  "fields": [
    { "name": "eventId",    "type": "string" },
    { "name": "orderId",    "type": "string" },
    { "name": "totalCents", "type": "long" },
    { "name": "currency",   "type": "string", "default": "BRL" },
    { "name": "couponCode", "type": ["null", "string"], "default": null }
  ]
}

As ferramentas:

• Formatos de serialização com schema: Avro, Protobuf ou JSON Schema. JSON puro sem schema "funciona" até a primeira quebra silenciosa.
• Um schema registry (Confluent Schema Registry, Apicurio, AWS Glue Schema Registry) guarda todas as versões, verifica a compatibilidade quando um produtor registra uma nova e deixa as mensagens carregarem um pequeno id de schema em vez do schema inteiro.
• Um envelope com metadados padronizados. A especificação CloudEvents da CNCF define atributos comuns para que ferramentas possam rotear e rastrear eventos sem interpretar o payload:

{
  "specversion": "1.0",
  "id": "e-9f2c",
  "source": "/boxoffice/order",
  "type": "com.boxoffice.order.confirmed.v2",
  "subject": "o-7731",
  "time": "2027-03-14T10:00:07Z",
  "datacontenttype": "application/json",
  "data": { "orderId": "o-7731", "totalCents": 78000, "currency": "BRL" }
}

Para uma mudança realmente incompatível, publique a nova versão em um tópico novo (order-events.v2), faça o produtor escrever nos dois durante um período de transição, migre os consumidores um a um e então aposente o tópico antigo.

Juntando tudo

Como se conecta

flowchart LR
    H1["salto 1: produtor → broker"] --> IP["produtor idempotente"]
    H1 --> OB["transactional outbox<br/>→ Padrões"]
    H2["salto 2: broker"] --> DUR["acks=all, min ISR 2<br/>→ Kafka"]
    H3["salto 3: broker → consumidor"] --> ALO["pelo menos uma vez:<br/>commit após processar"]
    TG["Dois Generais: não há entrega<br/>exatamente uma vez → aula 3"] --> EO
    ALO --> IDEM["consumidor idempotente<br/>tabela de dedup, chaves únicas"]
    IDEM --> EO["efetivamente uma vez"]
    ALO --> RETRY["retries com backoff<br/>→ Confiabilidade"]
    RETRY --> DLQ["dead letter queue<br/>alerta, redrive"]
    VER["atualizações guardadas por versão"] --> ORD["ordenação entre chaves"]
    REG["schema registry<br/>regras de compatibilidade"] --> EVO["evolução de schema"]

Componentes da paleta: queue · kafka · worker · notifications · sql (processed_events na mesma transação) · search ("lugares restantes" guardados por versão) · email (efeito colateral externo: volta a pelo menos uma vez) · alerting (DLQ não vazia). Cenários: notification-system, payment-system, retry-storm. Continua em: Sistemas distribuídos — idempotência, Confiabilidade — retry com backoff e jitter, Compute — integrações (chaves de idempotência com provedores), Observabilidade — alertas, Hands-on 7 — consumidor idempotente, Exercício — event-driven.