Índice do curso
Lição 25 — Esperar pelos canais
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
O que será alcançado: saber quando um pedido está completo: quando cada canal que lhe cabe chegou ao que se espera dele, incluído o 997 do parceiro. E que um canal que demora demais gere um alerta sem dar o pedido por fechado, para que o que chegar tarde ainda o complete, mesmo que o router tenha sido reiniciado no meio.
Antes de começar é preciso ter: as lições 21 e 22 concluídas e o ambiente da 00 ligado.
A novidade de hoje, em uma frase
Desde a lição 10, o router espalha: manda cada evento do ciclo de vida do pedido para os canais dele. Nunca o reúne: não há um lugar que diga «este pedido já terminou». E na lição 21 viu-se que «terminar» não é o mesmo para todos: a API e o ERP terminam quando aceitam, o parceiro quando manda o 997. Espalhar e depois reunir as respostas é um padrão com nome, Scatter-Gather, e a parte de reunir se chama Aggregator. Hoje ele é construído, com uma ideia que vem da lição 15: o que é preciso reunir já está na base.
A imagem: organizar a ceia de fim de ano com três primos que trazem alguma coisa. A tia não dá a ceia por pronta quando cada primo disse «estou indo»: dá por pronta quando a comida está na mesa. Se às nove o da sobremesa não chegou, a tia não risca a sobremesa nem declara a ceia completa: telefona para perguntar. E se a sobremesa chega às nove e meia, a ceia se completa nessa hora. Se a tia sai um pouco para o quintal, não perde a conta: a mesa continua ali com o que já chegou.
1. Prepare a pasta
cd lecciones/25-esperar-a-los-canales
cp -R inicio mio
Abra primeiro mio/orden-router/reglas/maquina-de-estados.yaml e procure a seção completa. Ali está o que se
espera de cada canal e por quanto tempo se espera:
| Canal | llega_a |
plazo_s |
Por quê |
|---|---|---|---|
rest (a API) |
aceptada |
10 | O «sim» dela chega na mesma chamada |
bd (o ERP) |
aceptada |
10 | Igual |
edi (o parceiro) |
confirmada |
20 | O «sim» dele é o 997, e chega depois (lição 21) |
Agora abra mio/orden-router/juntar.camel.yaml. No alto há um desenho do pedido 4001 a meio caminho: a API e o ERP já
chegaram, o parceiro ainda não. E há uma rota, vigilar, já feita: um relógio (timer) que a cada 2 segundos lê
as regras e chama duas rotas:
| Rota | O que faz | Onde anota |
|---|---|---|
juntar |
Dá por COMPLETO cada evento cujos canais chegaram todos ao próprio llega_a |
Tabela completitud, uma linha por pedido e evento |
vencidos |
Alerta sobre cada canal que passou do prazo sem chegar | Tabela alerta e um WARN no log |
Por que um relógio, em vez de esperar que algo avise? Porque o que não chega não avisa. Um 997 que nunca vem não dispara evento nenhum. Alguém tem de olhar o relógio.
Repare no que não há: não há um agregador que guarde na memória do router quais canais já responderam. Cada
operação e o estado dela vivem na tabela operacion desde a lição 15. Reunir é perguntar à base.
2. Faça a previsão
Responda em um papel:
- A API e o ERP aceitaram o pedido 4001, e o 850 ficou depositado. O parceiro não mandou o 997. O pedido está completo?
- O pedido 3001 é de uma loja própria: não leva EDI (lição 11). Quando está completo?
- Passam 20 segundos e o 997 do pedido 4002 não chega. O que é melhor: dar o pedido por completo para que pare de atrapalhar, ou alertar e deixá-lo aberto? O que acontece em cada caso se o 997 chegar aos 30 segundos?
- O router é reiniciado enquanto o 4002 espera o 997. Perde-se o que já estava reunido?
Veja como está hoje:
./verifica inicio
Sai errado desde a primeira marca: o 4001 fica COMPLETO antes do 997, porque a versão de inicio/ dá por
completo um evento quando nenhum canal continua pendiente, e um 850 depositado está aceptada. E o 4002, ao vencer,
é fechado à força: fica completo sem que o parceiro tenha respondido nada.
3. Reúna e vigie
Em juntar.camel.yaml há dois TODO, um em cada rota. Os dois são uma consulta SQL que já está quase inteira.
TODO 1: completo é «cada canal chegou ao que lhe cabe»
A consulta de juntar junta cada operação com a regra do canal dela e agrupa por pedido e evento:
INSERT INTO completitud (orden, momento)
SELECT p.orden, p.momento
FROM operacion p JOIN jsonb_each(CAST(:#${variable.reglas} AS jsonb)) AS r(canal, regla) ON r.canal = p.canal
WHERE NOT EXISTS (SELECT 1 FROM completitud c WHERE c.orden = p.orden AND c.momento = p.momento)
GROUP BY p.orden, p.momento
HAVING bool_and(p.estado NOT IN ('pendiente', 'estacionada')) -- ← esta condición
ON CONFLICT DO NOTHING
RETURNING orden, momento
Lê-se assim:
| Peça | O que faz |
|---|---|
jsonb_each(…) AS r(canal, regla) |
Converte as regras em linhas: uma por canal, com o llega_a e o plazo_s de cada um |
JOIN … ON r.canal = p.canal |
Cola em cada operação a regra do canal dela |
GROUP BY p.orden, p.momento |
Reúne as operações de cada evento de cada pedido |
HAVING bool_and(…) |
O evento passa só se a condição for verdadeira para todas as operações dele |
ON CONFLICT DO NOTHING |
Um evento se completa uma única vez |
O trabalho é a condição do HAVING. Hoje ela diz «nenhuma continua pendente nem estacionada». Tem de dizer «cada
uma está em um estado do próprio llega_a»:
HAVING bool_and(jsonb_contains(r.regla -> 'llega_a', to_jsonb(p.estado)))
r.regla -> 'llega_a' é a lista da regra, por exemplo ["confirmada"]; to_jsonb(p.estado) é o estado da
operação como valor JSON; jsonb_contains pergunta se o segundo está no primeiro.
Repare em algo que sai de graça: o 3001 não tem operação edi, porque é de uma loja própria. Como não tem
linha, não conta: ninguém espera um 997 que não lhe cabe.
TODO 2: vencido alerta e não fecha
A consulta de vencidos hoje escreve em completitud: fecha o evento ao vencer. Mude-a para que escreva um
alerta em alerta, uma vez por canal:
| Mudança | O que escrever |
|---|---|
| Para onde | INSERT INTO alerta (orden, momento, canal, tipo, estado, espera) |
| O quê | SELECT p.orden, p.momento, p.canal, 'vencido', p.estado, r.regla ->> 'llega_a' (sem o DISTINCT) |
| Quais | Acrescente ao WHERE: NOT jsonb_contains(r.regla -> 'llega_a', to_jsonb(p.estado)), para alertar só sobre os canais que não chegaram |
| Uma vez | Deixe o ON CONFLICT DO NOTHING: a tabela alerta tem uma UNIQUE (orden, momento, canal, tipo) |
| Para o log | Acrescente RETURNING orden, momento, canal, estado, espera e outputType: SelectList |
E depois da consulta, um split sobre ${body} com um log em WARN para cada alerta novo, como o split de
juntar. A mensagem começa com VENCIDO orden ${body[orden]} momento ${body[momento]} canal ${body[canal]}.
4. Quebre um de propósito
Com tudo concluído, tire do WHERE de vencidos a condição NOT jsonb_contains(…). Rode ./verifica.
Antes, faça a previsão: o 4002 espera o 997 por mais de 20 segundos. A API e o ERP o aceitaram em poucos segundos. Quantos alertas são esperados?
Três em vez de um. Sem essa condição, o relógio alerta sobre todo canal que tenha passado do prazo, tenha chegado ou não: a API e o ERP, que já aceitaram, também saem como vencidos. Sai em vermelho a marca do alerta do 4002. Um alerta que dispara por algo que está bem ensina as pessoas a ignorar os alertas, e então o que importa se perde. Devolva a condição.
5. Confira
./verifica
O verifica manda um pedido de loja própria e um de franquia, espera o 997; depois desliga o sistema do parceiro e
manda o 4002, espera que vença, reinicia o router e volta a ligar o parceiro. Está concluída quando aparecem as
sete marcas verdes:
✅ Arrancaron el router (con su reloj que junta y vigila), los tres canales y el sondeo
✅ La 4001: API y ERP aceptada y el 850 depositado, pero sin 997 todavía no está COMPLETA
✅ La 3001 (tienda propia): COMPLETA con la API y el ERP; el socio no le toca y no se le espera
✅ La 4001: llegó el 997, el socio quedó confirmada y la orden COMPLETA
✅ La 4002 sin 997 pasó su plazo: un solo aviso (vencido, en «aceptada», se espera confirmada) y sigue abierta
✅ Log: el aviso del vencido está en el log del router
✅ Tras reiniciar el router, el 997 tardío confirmó al socio y la 4002 quedó COMPLETA, con su único aviso como historia
Leia a última com calma. O router foi reiniciado no meio da espera, e o 4002 se completou do mesmo jeito. Nada foi escrito para isso: o que estava sendo reunido nunca viveu na memória do router, vivia na base. Ao voltar, o relógio perguntou outra vez e encontrou o mesmo, mais o 997 que acabava de chegar.
Veja as duas tabelas:
docker compose -f ../../infra/compose.yaml exec estado psql -U router -d estado \
-c "SELECT * FROM completitud ORDER BY completa" -c "SELECT orden, canal, estado, espera, creada FROM alerta"
Não roda? ./verifica solucion testa a nossa, e
diff mio/orden-router/juntar.camel.yaml solucion/orden-router/juntar.camel.yaml mostra em que são diferentes.
| O que aparece | O que fazer |
|---|---|
La 4001 con el socio en «aceptada» ya quedó COMPLETA |
O HAVING continua com a condição de inicio/: troque-a pelo jsonb_contains |
La 3001 (tienda propia) no quedó COMPLETA |
O JOIN com as regras não está lá, ou bool_and foi trocado por outra coisa |
La 4002 sin 997: hay 0 avisos e completa=1 |
vencidos continua escrevendo em completitud: é em alerta |
La 4002 sin 997: hay 3 avisos |
Falta o NOT jsonb_contains(…) no WHERE de vencidos |
no está el WARN del vencido de la 4002 |
Falta o RETURNING com outputType: SelectList, ou o split com o log em WARN |
No está arriba socio-bot |
Suba o ambiente: docker compose -f infra/compose.yaml up -d --wait |
El puerto 8080 está ocupado |
Os serviços de outra execução ficaram no ar: DONDE=mio docker compose -f compose.yaml down |
O que isto ensina fora do curso
Espalhar é fácil; reunir é onde está o trabalho. Mandar algo para vários destinos qualquer multicast faz. Saber quando todos terminaram, cada um com a própria ideia de «terminei», é o que diz ao negócio que o pedido já está em toda parte.
O que não chega não avisa. Um sistema que só reage a eventos nunca fica sabendo do que falta. É preciso algo que olhe o relógio e pergunte.
Alertar não é fechar. Fechar à força ao vencer diz «terminou» de algo que não terminou, e se o que faltava chegar tarde já não muda nada. Alertar deixa que uma pessoa decida, e deixa que o que chega tarde ainda conte.
Se o estado vive fora do processo, o reinício não é um problema. Dissemos isso na lição 15 como teoria; hoje deu para ver: o router foi reiniciado no meio da espera e não perdeu nada, sem uma linha extra de código.
Exercício: a ceia de fim de ano
- Antes de rodar qualquer coisa, escreva em papel a previsão para a pergunta 4 acima: perde-se o que foi reunido ao
reiniciar? Depois de rodar
./verifica, compare-a com o que aconteceu e escreva onde vivia o que foi reunido. - Mude nas regras o
plazo_sdo parceiro para5e rode./verifica. Que marcas mudam, e por quê? O que aconteceria com as pessoas que atendem os alertas se o prazo fosse tão curto na vida real? Devolva-o a20. - Imagine que o router tivesse três réplicas, cada uma com o próprio relógio. Um pedido seria completado três vezes? Um vencido geraria
três alertas? (Dica: procure as duas
UNIQUEe oON CONFLICT.)
Por que foi feito assim
O que decidimos nesta lição, com o que descartamos e o que nos faria mudar de ideia:
- Reunir é perguntar à base, e um vencido alerta sem fechar
Revisão
- O que é um Scatter-Gather? Que parte do curso espalha e que parte reúne?
- O que cada canal espera para se dar por terminado, e onde isso está escrito?
- Por que é preciso um relógio para reunir?
- Por que o 3001 se completa sem 997?
- A pergunta de encerramento: ao vencer o prazo do parceiro, o router alerta e deixa o pedido aberto. Por que fechá-lo à força seria pior? Use o 997 tardio do 4002 na resposta.
A seguir: na lição 26 um cliente diz que o pedido dele não chegou. Há a base, o log e os destinos. O que consultar primeiro, e como reconstruir a viagem completa de um pedido?
Prefere e-mail? Escreva para hola@habil.mx