Queue-Based Load Leveling

Uma fila entre quem recebe as requisições e quem as processa: no pico, tudo é aceito e enfileirado; o consumidor drena no ritmo que o recurso protegido aguenta. Nada é rejeitado — o pico vira backlog temporário, e a resposta ao cliente passa a ser assíncrona. Use quando o processamento não acompanha a chegada nos picos e nenhuma requisição legítima pode ser descartada.

passos: 6
arquivos: 4
testes: 0
tecnologias: 6

Infraestrutura realTypeScriptBunElysiaPostgreSQLRedisDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Na virada do mês, 300 PIX chegam no mesmo instante; o motor de liquidação aguenta 50 por segundo. Rejeitar o excesso descartaria pagamentos legítimos; processar tudo em paralelo derrubaria o motor. A API aceita os 300 em milissegundos, o consumidor liquida 50 por segundo e a fila zera em cerca de 6 segundos. Um consumidor que morre depois de ler e antes de confirmar não perde o pagamento.

Planta

Sequência

8/8

8 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

6 passos

Fila absorve picos de carga.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

INSERT+3

XADD+3

XACK+2

01
A API grava o pagamento no PostgreSQL, publica no stream e só então responde 202 — nunca recusa por volume
02
O consumidor lê pelo consumer group, um item por vez, em intervalos fixos pela capacidade medida do motor (LEVELING_CONSUMER_RATE_PER_SECOND), não pela profundidade da fila
03
A liquidação é idempotente (WHERE status = 'queued'); só depois vêm XACK e XDEL
04
Item lido e não confirmado fica pendente; recover reivindica com XAUTOCLAIM o que está ocioso além do limite e o liquida
05
Pagamento gravado que nunca chegou à fila (a API caiu entre o INSERT e o XADD) é reenfileirado pela varredura de órfãos
06
GET /queue/status mostra backlog e pendentes; backlog crescendo fora do pico é falta de capacidade, não fila funcionando

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Nenhum pagamento legítimo rejeitado
O motor nunca passa da capacidade real
API e consumidor escalam separados
Item de consumidor morto é recuperado

Custos

Latência cresce durante o pico
Fila externa persistente para operar
Cliente precisa de polling ou callback
Backlog sustentado exige mais consumidores

apps/scalability/queue-load-leveling

4 arquivos

src/

api_pix.tsAceita, grava e enfileira; consulta de pagamento e da fila
consumer_pix.tsConsumidor em ritmo fixo, liquidação idempotente, XACK e recuperação
queue_pix.tsStream e consumer group, enfileiramento, órfãos e profundidade

sql/