CS Fundamentals Trainer · Guias
Filas de mensagens e garantias de entrega
At-most-once, at-least-once e exactly-once na prática: o transactional outbox, consumidores idempotentes, visibility timeouts e dead-letter queues, executados no PostgreSQL.
14 min de leitura
Uma fila de mensagens permite que uma parte de um sistema entregue trabalho a outra sem esperar por ela. O produtor coloca uma mensagem; um consumidor a retira depois. Esse desacoplamento dá suavização de picos de tráfego, retentativas e escalonamento independente, e cria um problema novo: redes e processos falham entre os passos, então uma mensagem pode se perder ou ser entregue duas vezes. Este guia cobre o que uma fila oferece, o que "exactly once" realmente significa e os padrões (outbox, consumidor idempotente, dead-letter queue) que tornam um sistema correto de qualquer forma. Os dois padrões principais foram executados de verdade no PostgreSQL, e os resultados são mostrados.
1. Por que usar uma fila
Diagram: A producer, a queue, and consumers working in parallel
- Desacoplar no tempo: a API responde imediatamente ("pedido recebido") e o trabalho lento (enviar e-mail, redimensionar imagem, cobrar o cartão) acontece depois.
- Absorver picos: a fila cresce durante uma rajada e os consumidores a esvaziam no seu próprio ritmo, em vez de a rajada sobrecarregar o banco de dados. (Uma fila limitada também dá um lugar para aplicar backpressure.)
- Escalar e isolar: adicione consumidores para ir mais rápido; um consumidor com defeito não quebra o produtor.
- Repetir: uma mensagem que falhou pode ser tentada de novo mais tarde.
- Distribuir (fan out): um evento pode alimentar vários consumidores independentes (cobrança, índice de busca, analytics).
Os custos: mais peças móveis, nenhum resultado imediato, mensagens às vezes fora de ordem, duplicatas e mais dificuldade para depurar um fluxo que atravessa serviços. Não adicione uma fila onde uma simples chamada de função ou uma tabela de banco de dados resolveriam.
2. Filas e logs
Dois designs compartilham a palavra "fila":
| Fila de trabalho (SQS, RabbitMQ) | Log (Kafka, Kinesis) | |
|---|---|---|
| Uma mensagem é | removida depois de tratada | mantida por um período de retenção; os consumidores acompanham a sua posição (offset) |
| Vários consumidores independentes | cada um precisa da própria fila | cada grupo de consumidores lê os mesmos dados |
| Reprocessar dados antigos | não (a menos que você os tenha guardado) | sim, volte o offset |
| Ordenação | em geral no melhor esforço, ou por grupo de mensagens / fila FIFO | ordenada dentro de uma partição |
| Uso típico | jobs em segundo plano | fluxos de eventos, pipelines de dados, event sourcing |
Quanto à ordenação, um log dá ordem dentro de uma partição, e você escolhe a partição por uma chave (todos os eventos de um pedido vão para uma partição). Não há ordem total entre partições, então projete como se não houvesse nenhuma.
3. Garantias de entrega
O que acontece quando o consumidor ou a rede falham entre "recebi" e "terminei"? Há três contratos possíveis [1]:
- At most once (no máximo uma vez): a mensagem é entregue zero ou uma vez. O consumidor confirma (ack) antes de processar. Uma queda depois do ack perde a mensagem. Serve para dados de baixo valor (métricas, uma contagem de "curtidas").
- At least once (pelo menos uma vez): a mensagem é entregue uma ou mais vezes. O consumidor confirma depois de processar. Uma queda depois do processamento, mas antes do ack, faz a mensagem voltar: uma duplicata. É o padrão da maioria dos sistemas e aquele para o qual se deve projetar.
- Exactly once (exatamente uma vez): cada mensagem tem seu efeito uma vez. É o que todo mundo quer.
A verdade incômoda: entre duas máquinas ligadas por uma rede não confiável, você não consegue tornar a entrega em si exactly-once, porque o remetente nunca sabe se uma confirmação perdida significa "não recebido" ou "recebido, ack perdido". O que os sistemas oferecem é processamento (ou efeito) exactly-once, construído com entrega at-least-once mais deduplicação, ou com uma transação que inclui tanto a leitura da mensagem quanto a escrita do seu resultado. O Kafka, por exemplo, oferece produtores idempotentes e transações que dão semântica exactly-once dentro do Kafka (ler-processar-escrever entre tópicos do Kafka) [1], mas, quando seu consumidor chama um sistema externo (um serviço de e-mail, uma API de pagamento), essa chamada volta a ser at-least-once, a menos que aquele sistema também ofereça idempotência.
Então a regra de trabalho é:
entrega at-least-once + um consumidor idempotente = efetivamente exactly once
4. O visibility timeout (como uma fila de trabalho trata uma queda)
Em uma fila como o SQS, quando um consumidor recebe uma mensagem, ela não é apagada: fica invisível para os outros consumidores durante o visibility timeout. Se o consumidor termina, ele apaga a mensagem. Se cai ou demora demais, o timeout expira, a mensagem volta a ficar visível e outro consumidor a recebe [2]. Isso dá entrega at-least-once. Consequências:
- Defina o timeout maior que o tempo normal de processamento (e estenda-o para jobs longos), senão a mensagem de um consumidor lento, mas saudável, é entregue a um segundo consumidor, e o trabalho é feito duas vezes ao mesmo tempo.
- Faça o handler seguro para rodar duas vezes (seção 6), porque até um sistema bem ajustado ocasionalmente entrega duplicatas.
- Conte quantas vezes uma mensagem foi recebida; depois de um limite, mova-a para uma dead-letter queue (seção 7).
5. O problema da escrita dupla e o padrão outbox
Um bug muito comum: um serviço salva um pedido em seu banco de dados e publica um evento OrderPlaced.
BEGIN; INSERT INTO orders ...; COMMIT; -- 1
publish("order.placed", ...) -- 2 <- the process dies here: the order exists, no event
Troque a ordem, e uma queda gera um evento para um pedido que nunca foi salvo. Dois sistemas não podem ser atualizados atomicamente com uma escrita simples em cada um. A correção é o transactional outbox: grave o evento em uma tabela outbox na mesma transação de banco de dados que a linha de negócio e deixe um relay separado ler a tabela e publicar [3].
Diagram: Transactional outbox: the event is saved with the order, then relayed
Executei isto no PostgreSQL: três pedidos foram feitos, cada um com uma linha de outbox na mesma transação. A primeira execução do relay caiu depois de publicar, antes de marcar a linha como publicada (o pior momento). Ele reiniciou e rodou de novo. Resultado: o broker ficou com 4 mensagens para 3 ids distintos, uma duplicata, exatamente como o at-least-once prevê, e nenhum pedido se perdeu.
As tabelas e o relay que move linhas do outbox para o broker (Python com psycopg; publish representa o cliente do seu broker):
CREATE TABLE orders (id serial PRIMARY KEY, item text);
CREATE TABLE outbox (id bigserial PRIMARY KEY, topic text, payload jsonb, published_at timestamptz);
CREATE TABLE processed (message_id text PRIMARY KEY);
CREATE TABLE shipments (order_id int, item text);
def place_order(conn, item):
with conn.transaction(): # one transaction: order and event together
oid = conn.execute("INSERT INTO orders (item) VALUES (%s) RETURNING id", (item,)).fetchone()[0]
conn.execute("INSERT INTO outbox (topic, payload) VALUES ('order.placed', %s)",
(json.dumps({"order_id": oid, "item": item}),))
return oid
def relay_once(conn, publish):
with conn.transaction(): # the row locks last until commit
rows = conn.execute(
"SELECT id, topic, payload FROM outbox WHERE published_at IS NULL "
"ORDER BY id LIMIT 10 FOR UPDATE SKIP LOCKED").fetchall()
for id_, topic, payload in rows:
publish(f"outbox-{id_}", topic, payload) # may repeat if we crash before the UPDATE
conn.execute("UPDATE outbox SET published_at = now() WHERE id = %s", (id_,))
O select, a publicação e o update ficam em uma transação, então o lock obtido por FOR UPDATE é mantido até as linhas serem marcadas. Se o relay morre entre publish e o update, a transação sofre rollback, as linhas voltam a ficar não publicadas e a próxima execução as publica uma segunda vez: essa é a duplicata do experimento.
A consulta do relay, sozinha, reivindica linhas sem bloquear outros relays:
SELECT id, topic, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY id
LIMIT 10
FOR UPDATE SKIP LOCKED;
FOR UPDATE SKIP LOCKED trava as linhas que estão sendo tratadas e faz as outras instâncias do relay as pularem em vez de esperar, de modo que vários relays podem rodar em paralelo sem pegar a mesma linha. (Linhas que foram puladas podem ser publicadas um pouco fora de ordem, então os consumidores não devem depender de ordenação estrita entre linhas.) Uma alternativa ao polling é a captura de dados de mudança (CDC): ler o próprio write-ahead log do banco e publicar a partir dele; ferramentas como o Debezium fazem isso [3].
6. O consumidor idempotente
Uma operação é idempotente se fazê-la duas vezes tem o mesmo efeito que fazê-la uma vez. "Definir o status como enviado" é idempotente; "somar 10 ao saldo" não é. Para o segundo tipo, torne-a idempotente lembrando quais mensagens você já tratou. Dê a cada mensagem um id único (o id da linha do outbox serve) e registre-o na mesma transação que o efeito:
BEGIN;
INSERT INTO processed (message_id) VALUES ($1) ON CONFLICT DO NOTHING RETURNING message_id;
-- if no row came back: it was a duplicate, ROLLBACK or just COMMIT and stop
INSERT INTO shipments (order_id, item) VALUES ($2, $3);
COMMIT;
Na minha execução, o consumidor tratou as quatro mensagens em ordem e devolveu: enviada; duplicata (ignorada); enviada; enviada. São 3 envios para 3 pedidos, apesar da duplicata. Como o id e o envio estão em uma transação, uma queda não pode deixar um sem o outro.
Aqui está o consumidor em código (escolha uma linguagem nas abas; sua escolha é lembrada):
def handle(conn, message_id, order_id, item):
with conn.transaction():
row = conn.execute(
"INSERT INTO processed (message_id) VALUES (%s) "
"ON CONFLICT DO NOTHING RETURNING message_id",
(message_id,),
).fetchone()
if row is None:
return "duplicate" # already handled: do nothing
conn.execute("INSERT INTO shipments (order_id, item) VALUES (%s, %s)", (order_id, item))
return "shipped"
func handle(ctx context.Context, pool *pgxpool.Pool, messageID string, orderID int, item string) (string, error) {
tx, err := pool.Begin(ctx)
if err != nil {
return "", err
}
defer tx.Rollback(ctx) // no-op after Commit
tag, err := tx.Exec(ctx,
`INSERT INTO processed (message_id) VALUES ($1) ON CONFLICT DO NOTHING`, messageID)
if err != nil {
return "", err
}
if tag.RowsAffected() == 0 {
return "duplicate", nil
}
if _, err := tx.Exec(ctx,
`INSERT INTO shipments (order_id, item) VALUES ($1, $2)`, orderID, item); err != nil {
return "", err
}
return "shipped", tx.Commit(ctx)
}
// node-postgres; pool is a pg.Pool
async function handle(pool, messageId, orderId, item) {
const client = await pool.connect();
try {
await client.query("BEGIN");
const r = await client.query(
"INSERT INTO processed (message_id) VALUES ($1) ON CONFLICT DO NOTHING",
[messageId]
);
if (r.rowCount === 0) {
await client.query("ROLLBACK");
return "duplicate";
}
await client.query("INSERT INTO shipments (order_id, item) VALUES ($1, $2)", [orderId, item]);
await client.query("COMMIT");
return "shipped";
} catch (e) {
await client.query("ROLLBACK");
throw e;
} finally {
client.release();
}
}
// Npgsql
static async Task<string> Handle(NpgsqlDataSource db, string messageId, int orderId, string item)
{
await using var conn = await db.OpenConnectionAsync();
await using var tx = await conn.BeginTransactionAsync();
await using var dedupe = new NpgsqlCommand(
"INSERT INTO processed (message_id) VALUES (@m) ON CONFLICT DO NOTHING", conn, tx);
dedupe.Parameters.AddWithValue("m", messageId);
if (await dedupe.ExecuteNonQueryAsync() == 0)
{
await tx.RollbackAsync();
return "duplicate";
}
await using var ship = new NpgsqlCommand(
"INSERT INTO shipments (order_id, item) VALUES (@o, @i)", conn, tx);
ship.Parameters.AddWithValue("o", orderId);
ship.Parameters.AddWithValue("i", item);
await ship.ExecuteNonQueryAsync();
await tx.CommitAsync();
return "shipped";
}
Quando o efeito é em um sistema externo (enviar um e-mail, cobrar um cartão), passe o id da mensagem como chave de idempotência se o sistema aceitar uma, para que a segunda chamada seja reconhecida como repetição. A tabela processed cresce para sempre, então apague os ids antigos depois de um período de retenção maior que a mais longa reentrega que você espera.
7. Falhas, mensagens venenosas e a dead-letter queue
Uma mensagem venenosa (poison message) é uma que sempre falha (dados inválidos, um bug). Sem um limite, ela é repetida para sempre e bloqueia a fila atrás dela (em uma fila ordenada) ou queima CPU. As defesas padrão:
- Retry com backoff: espere 1 s, 2 s, 4 s … mais um jitter aleatório, para que as repetições não cheguem juntas.
- Um limite de tentativas e uma dead-letter queue (DLQ): depois de N tentativas fracassadas, mova a mensagem para uma fila separada, para um humano ou um job de reparo inspecionar. Alerte sobre a profundidade da DLQ, porque uma DLQ crescendo significa que algo está errado.
- Distinga erros permanentes de temporários: um erro de validação nunca vai dar certo (envie direto para a DLQ); um timeout provavelmente dará (tente de novo).
- Mantenha um jeito de reprocessar as mensagens da DLQ depois de corrigir o bug.
8. Ordenação, backpressure e monitoramento
- Ordenação: se dois eventos sobre a mesma coisa precisam ser processados em ordem, envie-os para a mesma partição ou grupo de mensagens e processe esse grupo sequencialmente. Aceite que as repetições podem reordenar mensagens, a menos que você as trate (números de versão na entidade permitem a um consumidor ignorar um evento obsoleto).
- Backpressure: se os produtores superam os consumidores, a fila cresce sem limite. Limite-a, descarte ou atrase o trabalho de baixa prioridade, escale os consumidores e observe a profundidade da fila e a idade da mensagem mais antiga, que é o número que os usuários sentem.
- Prefetch / tamanho do lote: um consumidor que pega muitas mensagens de uma vez e depois cai atrasa todas elas até o visibility timeout expirar.
- Monitoramento: profundidade, idade da mensagem mais antiga, tempo de processamento, retentativas, profundidade da DLQ, lag do consumidor (em um log: quão atrás do fim está o offset do consumidor).
9. Perguntas que entrevistadores gostam de acrescentar
"Dá para ter entrega exactly-once?"
Não através de uma rede não confiável, como propriedade apenas da entrega. Você pode ter efeito exactly-once com entrega at-least-once mais tratamento idempotente, ou com transações que cobrem tanto o offset da mensagem quanto o resultado (como o Kafka faz dentro dos seus próprios tópicos).
"Por que não publicar simplesmente no broker dentro da transação do banco de dados?"
Uma transação de banco de dados não consegue desfazer uma mensagem já enviada a um broker, e o broker não pode fazer parte do commit do banco. Esse é o problema da escrita dupla; o outbox move o evento para dentro do banco para que um commit cubra os dois.
"Fila ou tabela de banco de dados para jobs?"
Uma tabela com FOR UPDATE SKIP LOCKED é uma fila perfeitamente boa em volume moderado e dá transações junto com seus dados de graça. Um broker é melhor para throughput muito alto, fan-out para muitos consumidores ou quando você quer um log reprocessável.
"Como você mantém a ordem com vários consumidores?"
Particione por uma chave, de modo que tudo de uma entidade vá a um consumidor por vez, e abra mão da ordem global.
"E se o consumidor for lento?"
Escale os consumidores (até o número de partições em um log), torne o trabalho mais barato, separe jobs lentos e rápidos em filas diferentes e use backpressure a montante.
10. Coisas a mencionar em uma entrevista
- Por que uma fila (desacoplamento, picos, retentativas) e o que ela custa.
- As três garantias de entrega, e que at-least-once mais idempotência é a resposta prática para "exactly once".
- O problema da escrita dupla e o padrão outbox, e por que o relay pode publicar duplicatas.
- Consumidores idempotentes: ids de mensagem na mesma transação que o efeito, chaves de idempotência para chamadas externas.
- Visibility timeout, retentativas com backoff, mensagens venenosas, DLQ.
- Ordenação por chave, backpressure e as métricas a observar.
Resumo rápido
- Uma fila desacopla produtores e consumidores, absorve picos e permite retentativas.
- As redes falham entre os passos, então a entrega é at-most-once ou at-least-once; o "exactly once" é construído por cima.
- Confirme depois de processar e espere duplicatas.
- Use o outbox para que uma mudança de estado e o seu evento sejam salvos atomicamente.
- Torne os consumidores idempotentes: registre o id da mensagem na mesma transação que o efeito.
- Limite as retentativas, use backoff e envie mensagens venenosas para uma dead-letter queue.
- Observe a profundidade da fila e a idade da mensagem mais antiga.
Fontes
- Confluent, Kafka design: delivery semantics. At most once, at least once, exactly once; produtores idempotentes e transações.
- AWS, Amazon SQS visibility timeout.
- Chris Richardson, Pattern: Transactional outbox e Pattern: Transaction log tailing.
- Documentação do PostgreSQL, The Locking Clause:
FOR UPDATE ... SKIP LOCKED. - Documentação do PostgreSQL,
INSERT ... ON CONFLICT. - Debezium, Outbox event router.
- Martin Kleppmann, Designing Data-Intensive Applications, O'Reilly, 2017, capítulo 11 (processamento de fluxos) e capítulo 9 (consistência e consenso).
Pratique este tema: System Design System Design › Distributed systems