B2BCall-dialer/docs/TRUNKS.md

Trunks (Troncos SIP)

Agente.md seções 41-42. Primeiro recurso que grava configuração real no filesystem do FreeSWITCH (gateways Sofia) em vez de só responder via mod_xml_curl.

Modelo

trunks (tenant-scoped, RLS): host, proxy, realm, register, username/password_enc (AES-256-GCM, mesmo padrão de sip_password_enc), from_user/from_domain, register_proxy/outbound_proxy, expire_seconds, retry_seconds, dtmf_mode, ping/ping_frequency, transport, max_cps/max_channels, e status/status_updated_at (refletidos pelos eventos do FreeSWITCH, nunca escritos manualmente pela API).

Mecanismo: por que arquivo + rescan, e não XML Curl "configuration"

Ao contrário de Extensions (resolvido 100% via mod_xml_curl na hora do lookup), gateways Sofia não têm um binding XML Curl limpo e específico sem reativar a seção configuration inteira — e isso já causou problemas reais na fase XML Curl (chamadas HTTP desnecessárias no boot pra configs de outros módulos). Em vez disso, b2bcall-fs-config:

1. Gera um arquivo <trunk_id>.xml por trunk habilitado em sip_profiles/external/ (volume Docker compartilhado com o FreeSWITCH — o profile external da config vanilla já tem <X-PRE-PROCESS cmd="include" data="external/*.xml"/>, então não precisou editar a config do profile).
2. Roda sofia profile external rescan via ESL — relê os gateways sem derrubar chamadas em andamento (diferente de restart).

Achado real (fase Realtime Monitoring): rescan só lê arquivos novos/alterados — apagar o arquivo .xml de um trunk removido não tira o gateway da memória do Sofia, ele fica "fantasma" indefinidamente (confirmado criando e apagando um trunk de teste via API e checando sofia status gateway depois do rescan). Corrigido: trunk-sync.ts agora roda sofia profile external killgw <nome> pra cada gateway removido, antes do rescan — descarrega um gateway específico na hora, sem precisar reiniciar o profile inteiro. Reverificado ponta a ponta (criar → aparece em sofia status gateway → apagar via API → some imediatamente).

Gatilho de sincronização

apps/api não roda no Docker (ainda está no host) e fs-config não expõe porta pro host — então a notificação "algo mudou, resincroniza" vai por Redis pub/sub (b2bcall:trunks:sync), o mesmo mecanismo já usado pra eventos normalizados. apps/api publica depois de criar/apagar um trunk; fs-config também roda uma sincronização completa ao subir (cobre trunks criados enquanto ele estava fora do ar).

Achado real: a primeira sincronização no boot corria antes da conexão ESL do fs-config terminar de se estabelecer, gerando um erro cosmético ("FreeSWITCH ESL nao conectado") — a escrita dos arquivos funcionava, só o rescan falhava. Corrigido com FreeSwitchTelephonyProvider.waitUntilConnected() (timeout de 5s) antes de tentar o rescan.

Status do trunk (secao 42)

b2bcall-fs-events já escutava sofia::gateway_state desde a fase Event Socket (normalizado pra GATEWAY_UP/GATEWAY_DOWN); nesta fase, ele passou a também escrever esse estado de volta em Trunk.status. Como o nome do gateway no FreeSWITCH é o Trunk.id (UUID) e o evento não diz de qual tenant é, a busca percorre os tenants ativos (packages/database's withTenantContext) até achar o trunk dono daquele id — aceitável dado que mudança de estado de trunk é rara, não é um evento de alto volume por chamada.

Mapeamento de estados brutos do Sofia pro enum interno (apps/freeswitch-events/src/trunk-status.ts):

UP, REGED       → REGISTERED/UP
TRYING, REGISTER → TRYING
FAILED, FAIL_WAIT → FAILED
DOWN            → DOWN
NOREG, UNREGED  → UNREGISTERED
qualquer outro  → UNKNOWN

Verificado

Criei um trunk de teste apontando pra um host inexistente (sip.trunk-inexistente.invalid, nunca resolve — RFC 2606) via API:

• fs-config sincronizou (count: 1), escreveu o arquivo .xml, rodou o rescan com sucesso.
• sofia status gateway no FreeSWITCH mostrou o gateway real, estado FAIL_WAIT (esperado — host não existe).
• Confirma o pipeline API → Postgres → fs-config → arquivo XML → rescan → FreeSWITCH funcionando ponta a ponta sem precisar de nenhum tronco/ credencial real.

O que falta

• Quota de troncos — implementada na fase Plans/Entitlements (ver docs/ENTITLEMENTS.md), assertQuota chamado antes de criar.
• GET /trunks não mostra sofia status gateway ao vivo, só o último status conhecido no banco — resolvido na fase Realtime Monitoring via WebSocket (ver docs/REALTIME.md).

Correção: GATEWAY_UP/DOWN → Trunk.status (fase Realtime Monitoring)

Documentado antes como "não confirmado com evento real" — na verdade nunca funcionava, e a causa raiz não tinha nada a ver com o tipo de falha do gateway. b2bcall-fs-events assinava os eventos CUSTOM do ESL passando "CUSTOM" como o último elemento da lista pro comando event json, sem nenhum subclass depois — e o protocolo do FreeSWITCH exige que os nomes de subclass (sofia::gateway_state, sofia::register, callcenter::info, ...) venham imediatamente depois do token CUSTOM no mesmo comando event json, senão zero eventos CUSTOM chegam, de qualquer subclass. Achado e corrigido durante a fase Agentes/Realtime Monitoring (mesmo bug afetava callcenter::info, ver docs/AGENTS.md). Reverificado ponta a ponta: criar um trunk com register: true apontando pra um host inexistente → Trunk.status no banco passa de UNKNOWN pra FAILED sozinho, sem polling, assim que o Sofia tenta e falha o registro.