Files

Matheus b940ce3e63 fix(events): eventos CUSTOM do ESL nunca eram entregues

Achado ao iniciar a fase de Realtime Monitoring: nenhum evento CUSTOM
(sofia::register, sofia::gateway_state, callcenter::info) jamais chegou em
b2bcall-fs-events nesta sessao, apesar do estado real do FreeSWITCH mudar de
verdade (confirmado originando uma chamada de teste pra dentro de uma fila
real com agente logado). Isso deixava dois gaps documentados como "nao
verificado" em docs/TRUNKS.md e docs/AGENTS.md.

Causa raiz: `event_json(...SUBSCRIBED_EVENTS)` mandava "CUSTOM" como ultimo
token do comando `event json`, sem nenhum subclass depois. O
mod_event_socket do FreeSWITCH exige que os subclasses (callcenter::info,
sofia::register, ...) venham imediatamente depois do token CUSTOM no mesmo
comando — sem isso, zero eventos CUSTOM sao entregues, de qualquer
subclass.

Corrigido separando PLAIN_EVENTS (nomes normais, cada um vira um listener
.on()) de CUSTOM_SUBCLASSES (so compoe o comando de subscricao — o client
ESL sempre emite "CUSTOM" como nome de evento, com o subclass real no
header Event-Subclass). Corrigido tambem um bug de nome de campo:
normalizeCustomEvent lia CC-Agent-Status, que nao existe; o campo real e
CC-Agent-State.

Com o pipeline corrigido, chegam eventos ricos de callcenter::info nunca
antes observados: agent-offering, bridge-agent-fail, members-count (fila em
tempo real) e member-queue-end (com CC-Cause/CC-Cancel-Reason e timestamps
de entrada/saida — atendida vs. abandonada). Adicionados como novos tipos
normalizados: AGENT_OFFERED_CALL, AGENT_BRIDGE_FAILED, QUEUE_MEMBER_COUNT,
QUEUE_MEMBER_LEFT.

De quebra, achado e corrigido um segundo bug real ao reverificar Trunks com
o pipeline de eventos funcionando: `sofia profile external rescan` nunca
descarregava um gateway cujo arquivo .xml foi apagado (fica fantasma na
memoria do Sofia indefinidamente). trunk-sync.ts agora roda `sofia profile
external killgw <nome>` pra cada gateway removido, antes do rescan.

Reverificado ponta a ponta pra ambos os bugs:
- Trunk com register:true apontando pra host inexistente: Trunk.status no
  banco passa de UNKNOWN pra FAILED sozinho, via evento, sem polling.
- Trunk apagado via API: gateway some imediatamente de `sofia status
  gateway`, sem esperar reinicio de profile.
- Chamada de teste real numa fila com agente logado: members-count,
  agent-offering, agent-state-change (CC-Agent-State correto: Waiting/
  Receiving), bridge-agent-fail, todos chegando certos no canal Redis
  b2bcall:events.

typecheck do workspace inteiro limpo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X1HxY46WGU4G1zmVDNKcWw

2026-08-28 11:41:09 -03:00

4.5 KiB

Raw Blame History

Event Socket

b2bcall-fs-events (apps/freeswitch-events) mantém a conexão ESL permanente com o FreeSWITCH (agente.md secao 21) — nenhum outro serviço deve rodar fs_cli via shell pra ações operacionais.

Biblioteca

Usa esl (v11, mantida ativamente, TypeScript nativo, zero dependências de libesl). A classe FreeSwitchClient já resolve reconexão com backoff sozinha (agente.md secao 195) — só precisamos reagir a connect/reconnecting/error e resubscrever a cada connect (a lib entrega um objeto de chamada novo a cada reconexão).

`packages/telephony`

TelephonyProvider (interface, agente.md secao 25) + FreeSwitchTelephonyProvider (implementação sobre esl). Métodos testados manualmente contra o FreeSWITCH rodando: originate, killCall, getChannels, getCalls, getGateways, getRegistrations, reloadXml. Os métodos de fila/agente (setAgentStatus, addAgentToQueue, ...) seguem a sintaxe documentada do mod_callcenter mas não foram exercitados contra uma fila real ainda — não existe nenhuma (fase Queues).
normalizeEslEvent(): traduz eventos ESL crus pro vocabulário interno (agente.md secao 24). Mapeamento de callcenter::info/sofia::* com nomes de campo confirmados contra uma fila real na fase Realtime Monitoring — ver "Achados" abaixo e docs/AGENTS.md.

Achados durante os testes

ACL implícita do Event Socket: sem apply-inbound-acl explícito, o FreeSWITCH 1.11 rejeita ("Access Denied, go away.") qualquer conexão que não seja loopback — mesmo com a senha certa. Descoberto porque b2bcall-fs-events (outro container) não conseguia conectar. Corrigido criando uma ACL própria (b2bcall_internal, em overrides/autoload_configs/acl.conf.xml) cobrindo loopback + a rede interna do Docker Compose (172.16.0.0/12, nunca 0.0.0.0/0).
Nessa mesma correção, um erro de digitação inicial (usar só localnet.auto, que cobre a rede Docker mas não loopback) quebrou até o fs_cli local — corrigido combinando as duas faixas na mesma ACL.
O logger JSON de packages/shared quebrava (TypeError: Do not know how to serialize a BigInt) porque a lib esl usa bigint nos campos de estatística de erro. Corrigido com um replacer no JSON.stringify.
Bug real, só descoberto na fase Realtime Monitoring: nenhum evento CUSTOM (sofia::gateway_state, sofia::register, callcenter::info) nunca chegou nesta sessão até então, apesar da subscrição incluir "CUSTOM" na lista de SUBSCRIBED_EVENTS. Causa: event_json(...events) manda "CUSTOM" como último token do comando event json, sem nenhum subclass depois — o mod_event_socket do FreeSWITCH exige que os subclasses venham imediatamente depois do token CUSTOM no mesmo comando pra serem entregues. Corrigido: SUBSCRIBED_EVENTS agora termina em "CUSTOM", "sofia::register", "sofia::unregister", "sofia::expire", "sofia::gateway_state", "callcenter::info", e o loop que registra listeners .on() só usa os nomes "planos" (PLAIN_EVENTS) mais um único .on("CUSTOM", ...) — os nomes de subclass nunca viram listener, só compõem o comando de subscrição.

Eventos consumidos e publicados

Lista completa em apps/freeswitch-events/src/main.ts (SUBSCRIBED_EVENTS), cobrindo a secao 23 do agente.md. HEARTBEAT só é logado em debug, nunca normalizado. Eventos normalizados são publicados em JSON no canal Redis b2bcall:events (pub/sub simples — vira a base pra WebSocket multi-tenant na fase Realtime Monitoring, que ainda não existe).

Verificado ponta a ponta

Sem SIP real disponível ainda, a verificação usou uma chamada loopback local:

docker exec b2bcall-freeswitch fs_cli -p "$ESL_PASSWORD" -x "originate null/_test_ &park()"
# ... uuid_kill pra encerrar

Resultado observado no canal Redis: CALL_CREATED → CALL_ANSWERED → CALL_ENDED (com hangupCause), todos com o callUuid correto.

Limitações desta fase

Reconciliação pós-reconexão (secao 195: "reconcile calls, agents, queues, registrations, gateways") não é possível ainda — não existem tabelas de calls/agents/queues persistidas pra reconciliar contra. Só a resubscrição de eventos está implementada. Revisitar quando essas tabelas existirem.
b2bcall-fs-events roda via tsx direto (sem etapa de build/dist) — simples mas ~99MB de RAM em runtime (razoável no orçamento atual, mas vale revisar se muitos workers assim rodarem juntos mais pra frente).

4.5 KiB Raw Blame History