Servidor WebSocket (stcall-ws)

O stcall-ws é um servidor Bun nativo que atua como camada intermediária entre os navegadores dos agentes e o Asterisk ARI.

Arquitetura

Navegadores dos Agentes (60+)
    │
    │ WebSocket (:3001)
    │ JWT auth
    ▼
┌──────────────────────────┐
│       stcall-ws          │
│                          │
│  ┌─────────────────────┐ │
│  │ Agent Registry      │ │    ← Map de agentes conectados
│  │ (Map<id, WebSocket>)│ │
│  └─────────────────────┘ │
│                          │
│  ┌─────────────────────┐ │
│  │ Event Router        │ │    ← Filtra e roteia eventos ARI
│  │ (Filter + Dispatch) │ │
│  └─────────────────────┘ │
│                          │
│  ┌─────────────────────┐ │
│  │ Command Handler     │ │    ← Executa comandos no Asterisk
│  │ (ARI HTTP Client)   │ │
│  └─────────────────────┘ │
│                          │
│  ┌─────────────────────┐ │
│  │ Call Tracker        │ │    ← Registra chamadas no PostgreSQL
│  │ (Prisma ORM)        │ │
│  └─────────────────────┘ │
│                          │
│  ┌─────────────────────┐ │
│  │ PJSIP Sync          │ │    ← Sincroniza endpoints com FreePBX
│  │ (MySQL/MariaDB)     │ │
│  └─────────────────────┘ │
└────────────┬─────────────┘
             │
    ┌────────┼────────┐
    │        │        │
    ▼        ▼        ▼
Asterisk  PostgreSQL  MySQL
  ARI      (stCall)  (FreePBX)

Stack Tecnológica

Conexão com Asterisk ARI

O stcall-ws mantém uma conexão WebSocket persistente com o Asterisk ARI:

• URL: ws://asterisk:8088/ari/events?app=stCall
• Autenticação: Basic auth (username/password)
• Reconexão automática: Com backoff exponencial
• Heartbeat: Configurável via HEARTBEAT_INTERVAL

Tipos de Eventos ARI

Registro de Agentes

Quando um agente conecta:

1. Extrai token JWT da URL (?token=...) ou header Authorization
2. Valida o token (formato, campos, expiração, assinatura)
3. Registra no Agent Registry (Map em memória)
4. Armazena: agentId, WebSocket, connectedAt, lastPing, channels

agents.set("agent-123", {
  agentId: "agent-123",
  websocket: WebSocketConnection,
  connectedAt: new Date(),
  lastPing: new Date(),
  channels: new Set<string>()
})

O token JWT não é armazenado no servidor - apenas os metadados extraídos.

Roteamento de Eventos

O Event Router filtra eventos do Asterisk e envia apenas os relevantes para cada agente:

• Eventos de canal do agente → enviados ao agente
• Eventos de sistema → enviados a todos os admins
• Eventos de chamada → enviados ao agente responsável

Execução de Comandos

Agentes enviam comandos via WebSocket, que são executados no Asterisk via ARI HTTP:

Agente → WebSocket → stcall-ws → ARI HTTP → Asterisk
                                          ↓
Agente ← WebSocket ← stcall-ws ← Resposta

Cada comando tem um requestId para correlacionar a resposta.

Serviços

Call Tracker

Registra chamadas no PostgreSQL:

• Cria registro no StasisStart
• Atualiza status nas mudanças de canal
• Registra finalização e duração

PJSIP Sync

Sincroniza endpoints WebRTC com o MySQL do FreePBX:

• Cria ps_endpoints, ps_auths, ps_aors
• Gerencia credenciais de autenticação

Queue Tracker

Monitora filas de chamadas e status de agentes.

Direct Call Tracker

Rastreia chamadas diretas (ramal a ramal).

Health Check

Endpoint HTTP para monitoramento:

GET http://hostname:3001/health

Retorna:

• Status do servidor
• Estado da conexão com Asterisk
• Quantidade de agentes conectados
• Uptime em segundos
• Uso de memória