7. Mensageria Assíncrona

São 10:00 e o show no estádio abre as vendas. Cada POST /orders aceito pelo serviço order também precisa gerar um e-mail de confirmação. Se order chamar notification por HTTP, o fã espera pelo provedor de e-mail, uma queda do e-mail vira uma queda de pedidos, e os 2 milhões de fãs que chegam no mesmo segundo atingem todos os serviços de uma vez. Este lab troca esse acoplamento por três ideias da aula de mensageria: eventos em um log, entrega at-least-once tratada com idempotência e filas que absorvem um pico.

Ele constrói o capítulo 8 da história da disciplina. As decisões que você implementa são justificadas na aula: síncrono vs assíncrono, o transactional outbox, consumidores idempotentes, retries e mensagens mortas e a sala de espera da venda relâmpago.

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

Antes de começar

Seu repositório precisa estar no estado em que o lab 6 o deixou. Todo comando deste lab roda na raiz do seu repositório boxoffice.

boxoffice/
├── docker-compose.yaml     # db, db-replica, pgbouncer, redis, catalog-1..3, inventory, auth, gateway, edge
├── infra/                  # nginx/, postgres/, pgbouncer/
├── load/                   # k6 scripts of labs 0-6
├── scripts/
└── services/
    ├── auth/
    ├── catalog/
    ├── gateway/
    └── inventory/

Todo arquivo deste lab aparece completo nestas páginas, com o caminho no título, e também é publicado em https://insper.github.io/platform/2027.1/hands-on/7/code/<caminho> — por exemplo curl -fsSL -o docker-compose.yaml https://insper.github.io/platform/2027.1/hands-on/7/code/docker-compose.yaml.

Arquitetura

flowchart LR
    fan[Fã] -->|POST /orders| gw[gateway]
    gw --> order[order]
    order -->|INSERT do pedido| db[(PostgreSQL)]
    order -->|"POST /notifications (espera)"| notification[notification]
    notification -->|SMTP| mail[mailpit]
    notification -->|201 depois do e-mail| order
    order -->|201| gw

flowchart LR
    fan[Fã] -->|entra| wr[sala de espera]
    wr -->|admitido| gw[gateway]
    gw -->|POST /orders| order[order]
    order -->|"INSERT pedido + outbox (1 tx)"| db[(PostgreSQL)]
    order -->|201 na hora| gw
    relay[relay do outbox] -->|busca não publicados| db
    relay -->|publica OrderPlaced| kafka[(Kafka: order-events)]
    kafka -->|grupo de consumidores notification| notification[notification]
    notification -->|"processed_events (dedup)"| ndb[(PostgreSQL)]
    notification -->|SMTP| mail[mailpit]
    notification -.->|após 3 tentativas falhas| dlt[(order-events-dlt)]

A requisição do fã agora termina no commit do banco. Tudo o que vem depois — publicar, enviar o e-mail, tentar de novo — acontece de forma assíncrona e pode ser lento, falhar ou se repetir sem que o fã perceba.

O que você vai medir

Pré-requisitos

• Labs 1 a 6 concluídos: seu repositório boxoffice roda db (PostgreSQL), redis, catalog, inventory e o gateway com docker compose.
• Cerca de 2 GB extras de memória para o Docker (o Kafka é uma JVM).
• Leia a aula de mensageria, em especial Kafka, semânticas de entrega e o padrão outbox.

Passos

1. Kafka no Compose — um broker KRaft, o tópico order-events, o Kafka UI e o Mailpit; um passeio pela CLI.
2. Transactional outbox — o serviço order grava o pedido e o evento em uma transação; um relay o publica.
3. Consumidor idempotente e DLT — o serviço notification deduplica por eventId, tenta de novo com backoff e manda mensagens envenenadas para a DLT.
4. Sala de espera — uma FIFO no Redis que admite fãs a uma taxa fixa durante a abertura das vendas.
5. Meça — latência síncrona vs assíncrona, comportamento na queda, lag e drenagem, duplicatas, taxa de admissão.

Experimente no playground

Antes de escrever código, veja as duas formas que este lab constrói. Experimente: no primeiro simulador, rode o perfil load e observe cada serviço consumidor receber sua própria cópia de cada evento (fan-out); depois aumente o RPS alvo até um consumidor ficar para trás enquanto o produtor continua rápido. No segundo, rode spike e observe o backlog da fila crescer e drenar enquanto os workers seguem em ritmo constante.

O simulador completo está no playground.

Meça

O passo Meça tem os scripts k6 e a tabela de resultados. Preencha-a e guarde-a no seu repositório: ela faz parte da entrega.

Solução de problemas

Limpeza

Ao terminar (ou antes do lab 8), pare a stack e mantenha os dados, ou remova tudo:

docker compose stop                 # keep containers and volumes for the next lab
docker compose down -v              # or: remove containers, networks and volumes (all data)

O lab 8 começa deste estado; não é preciso guardar nada além do seu repositório.

Estado final

boxoffice/
├── docker-compose.yaml     # + kafka, kafka-init, kafka-ui, mailpit, order, notification
├── load/
│   ├── orders-load.js
│   └── waiting-room-spike.js
├── scripts/
│   └── kafka-lag.sh
└── services/
    ├── notification/       # new: idempotent consumer, DLT, e-mail
    └── order/              # new: orders, outbox relay, waiting room

Faça commit e tag: git add -A && git commit -m "lab 7: async messaging" && git tag lab7.

Checklist

• kafka, kafka-init, kafka-ui e mailpit rodam no docker-compose.yaml; order-events e order-events-dlt têm 6 partições cada
• order grava orders e outbox em uma transação; repetir o POST /orders com o mesmo holdId devolve o mesmo pedido e não cria evento novo
• o relay do outbox publica com chave = orderId e marca as linhas como publicadas; parar o Kafka não perde nenhum evento
• notification envia um e-mail por pedido mesmo depois de um reset de offsets (duplicatas são ignoradas)
• uma mensagem envenenada chega à order-events-dlt depois das tentativas, e a partição continua andando
• a sala de espera admite na taxa configurada; um POST /orders sem ticket de admissão é recusado durante a abertura das vendas
• tabela de resultados do passo Meça preenchida em results/lab7.md, com uma explicação curta de cada número
• autoverificação: docker compose down -v && docker compose up -d --build a partir de um clone limpo sobe tudo saudável; depois, push para o GitHub com a tag lab7

Relacionados

• Teoria: Mensageria e eventos · Filas e pub/sub · Kafka · Padrões: outbox, saga, CQRS · Semânticas de entrega
• Estudo de caso: Venda de ingressos (venda relâmpago do BoxOffice)
• Exercício: Orientado a eventos
• Próximo lab: 8. Observabilidade rastreia este fluxo de ponta a ponta, inclusive o salto pelo Kafka.

Começar: Kafka no Compose