Event Notification

O evento diz só o que mudou — id do recurso e versão —, nunca o que o recurso é. Quem precisa do detalhe chama a origem; quem não precisa segue sem ela. Payload mínimo e dado sempre atual, ao custo de uma chamada extra e de depender da origem no ar.

passos: 6
arquivos: 7
teste: 1
tecnologias: 5

Infraestrutura realTypeScriptBunElysiaRedisDocker

Cenário Relações Comparar

Baixar cartão

Cenário

O serviço de pagamentos de um banco digital aprova e estorna PIX. O notificador do cliente precisa do valor e das contas, então busca o pagamento na API; o contador de aprovações do dia só precisa saber que houve uma aprovação e não chama ninguém. Se a API cair, a notificação não se perde: espera na lista de pendentes do grupo.

Planta

Sequência

5/5

5 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

Avisa o fato, consumidor busca o detalhe.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

XADD+3

XACK+2

data+1

Event-Carried State Transfer

01
Um script Lua grava o pagamento no Hash, incrementa a versão e faz XADD da notificação no mesmo passo — nunca evento sem estado nem estado sem evento
02
A notificação é um CloudEvent com data = { paymentId, version }: nenhum campo do pagamento
03
O notificador busca GET /payments/:id com timeout; recebe sempre o estado atual e compara a versão para saber se o evento já foi superado
04
Origem fora do ar → o handler falha, a entrada não recebe XACK e é relida primeiro (XREADGROUP ... 0) na próxima passada
05
Pagamento que não existe mais (404) → XACK sem notificar
06
O contador usa só a notificação, com SADD pelo id do evento — reentrega conta uma vez

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Payload pequeno e estável
Dado sempre atual na busca
Origem não expõe seu formato interno no evento
Receptor que não precisa de detalhe não chama nada

Custos

Receptor que precisa de detalhe depende da origem no ar
Uma chamada extra por evento e por receptor
N receptores = N chamadas à origem
Ordem e atualidade viram responsabilidade da versão

apps/messaging-streaming/event-notification

7 arquivos

src/

event_payment.tsCloudEvent de notificação, gravação atômica estado + stream em Lua, leitura por consumer group com pendentes primeiro
api_payment.tsAPI Elysia de pagamentos, a origem consultada pelos receptores
receiver_payment.tsNotificador que busca detalhes e contador que não busca
config_payment.tsVariáveis de ambiente validadas no boot
receiver_payment.test.tstesteIntegração com Redis e HTTP reais: evento mínimo, busca, evento superado, origem fora do ar, recurso removido e contador
demo.tsdemoOrigem fora e depois de volta, estorno antes da leitura e contagem sem chamada