Tempo real no Markmedi com Laravel Reverb: canais versionados e eventos "campainha"
Como a agenda, a fila de espera e a sala de consulta do Markmedi se atualizam sozinhas com Reverb, sem mandar dado de paciente pelo WebSocket e revogando acesso sem presence channels.
Numa clínica, a agenda é uma tela que fica aberta o dia inteiro. A recepcionista deixa a semana na tela, a médica deixa a fila de atendimento aberta no consultório, e alguém do outro lado da cidade remarca uma consulta pelo celular. Se a tela da recepção só descobre a mudança quando alguém aperta F5, o problema aparece no balcão: dois pacientes chegando para o mesmo horário, ou um paciente esperando uma sala que já foi liberada.
No Markmedi eu resolvi isso com o Laravel Reverb, o servidor de WebSockets oficial do Laravel. Neste texto eu explico como os canais são autorizados, por que o nome dos canais tem uma versão e por que os eventos que passam pelo socket não carregam quase nada.
Onde o Reverb roda
A infraestrutura do Markmedi é enxuta: um contêiner com Nginx, PHP-FPM, Horizon, o scheduler e o Reverb, todos gerenciados pelo Supervisor. O Reverb sobe com reverb:start numa porta própria, e o proxy encaminha o tráfego de WebSocket para ela. Como hoje existe uma réplica só, não preciso do modo de escala horizontal do Reverb (que usa Redis pub/sub para sincronizar vários servidores). Se um dia a aplicação ganhar mais réplicas, é uma mudança de configuração, não de arquitetura.
No front, uso o @laravel/echo-vue com o broadcaster do Reverb, configurado uma vez no app.ts. Os componentes Vue assinam canais por meio de composables, e a assinatura acompanha o ciclo de vida do componente: entrou na página, assina; saiu, deixa o canal.
Canais privados autorizados por permissão
Quase todos os canais são privados. A autorização em routes/channels.php não pergunta só "esse usuário pertence à clínica?". Ela pergunta se ele tem a permissão daquela tela. O canal da agenda exige ver todos os agendamentos ou ao menos os próprios; o de salas e equipamentos exige a permissão de recursos; o da fila exige a permissão da fila. O canal de transcrição de uma consulta é o mais restrito: exige poder atender, poder ver prontuário e ser o médico daquele atendimento (ou ter a permissão de ver todos).
Isso importa porque o RBAC do Markmedi é por clínica e configurável. Uma recepcionista pode ver a agenda e não ver prontuários. Se o canal só checasse a filiação à clínica, a autorização do WebSocket seria mais frouxa do que a das próprias telas.
O problema da revogação
A autorização de um canal privado acontece uma vez, na hora da assinatura. Depois disso o socket fica aberto. Se o dono da clínica tira a permissão de agenda de um funcionário às 10h, o navegador dele, aberto desde as 8h, continua recebendo eventos. Presence channels ajudariam a saber quem está conectado, mas não resolvem a revogação, e eu não queria manter estado de presença só para isso.
A solução foi colocar uma versão no nome do canal. Cada clínica tem uma coluna access_version. O canal da agenda se chama clinic.{id}.appointments.v{versão}, e a autorização recusa qualquer versão diferente da atual. Toda mudança de papel ou de filiação incrementa a versão e, depois do commit, dispara um evento ClinicAccessChanged no canal pessoal de cada membro.
// routes/channels.php (simplificado)
Broadcast::channel('clinic.{clinicId}.appointments.v{version}', function ($user, $clinicId, $version) {
$clinic = $user->clinics()->find($clinicId);
return $clinic
&& (int) $version === $clinic->access_version
&& $user->canInClinic($clinic, 'appointments.view_all', 'appointments.view_own');
});No navegador, o layout escuta esse evento no canal do usuário e faz uma nova visita do Inertia. As props voltam com a nova versão e as novas permissões, o composable percebe que o nome do canal mudou e assina de novo. Se o usuário perdeu a permissão, a nova assinatura é recusada, e o canal antigo deixa de existir para ele. A revogação vira uma consequência do nome do canal.

O composable que faz isso é pequeno: ele monta o nome com a versão vinda das props compartilhadas, observa mudanças de clínica ou de versão e troca a assinatura. Todas as telas em tempo real usam o mesmo composable, então ninguém precisa lembrar dessa regra ao criar uma tela nova.
Eventos "campainha"
A segunda decisão foi sobre o conteúdo das mensagens. A tentação é mandar o agendamento inteiro no evento: nome do paciente, horário, procedimento. O front recebe e atualiza a lista sem ir ao servidor. Funciona, mas cria dois problemas. O primeiro é que dado de paciente passa a trafegar por mais um caminho, que precisa das mesmas regras de visibilidade das telas. O segundo é que o payload do evento vira uma segunda API, com outro formato, que precisa ficar sincronizada com as props da página.
Por isso os eventos do Markmedi funcionam como campainha. Eles avisam que algo mudou e dizem o mínimo para o cliente decidir se aquilo interessa: o id do agendamento e o tipo da ação. Quem recebe pede os dados de novo pelo caminho normal, com um reload parcial do Inertia:
useVersionedClinicChannel('appointments', '.calendar.updated', () => {
router.reload({ only: ['appointments', 'stats'] });
});O reload parcial passa pelo controller, pelas policies e pelos escopos de tenant de sempre. O socket nunca mostra nada que a tela não mostraria, porque ele não mostra nada. O custo é uma requisição extra por evento, o que numa agenda de clínica é irrelevante.

Os eventos de broadcast também implementam ShouldDispatchAfterCommit. Sem isso, o cliente poderia receber a campainha, fazer o reload e ler o banco antes do commit da transação que originou o evento, vendo o estado antigo. Com o despacho depois do commit, quando a campainha toca, o dado já está lá.
Onde isso aparece
A remarcação é o exemplo mais claro. Quando uma consulta é remarcada, pela equipe ou por uma mudança que chega do Google Agenda do médico, a action publica o evento da agenda e todas as telas abertas daquela clínica se atualizam. Os bloqueios de horário seguem o mesmo caminho. A fila de atendimento usa um canal próprio: quando a recepção registra a chegada de um paciente, a médica vê a fila mudar no consultório. A tela de salas e equipamentos também escuta o seu canal, para que a ocupação de uma sala apareça sem recarregar a página.
Na sala de consulta, o Reverb carrega a transcrição. O áudio é dividido em segmentos, cada segmento é transcrito por um job na fila de IA, e quando um termina o job dispara um evento de segmento pronto no canal daquele atendimento. A médica vê o texto aparecer enquanto a consulta acontece. Esse é o canal com a autorização mais restrita, pelos motivos óbvios.
Progresso de jobs longos
O relatório de posicionamento, que analisa a presença digital de uma clínica, leva minutos e passa por várias etapas. O job publica eventos de progresso com ShouldBroadcastNow, para não entrar de novo numa fila só para avisar o progresso, e a página de carregamento mostra a etapa atual.
Esse é o único canal público do sistema, porque a página de diagnóstico pode ser vista antes de existir uma conta. O identificador do relatório é um UUID, e o evento só carrega números e o nome da etapa. Como WebSocket pode falhar por motivos que não controlo (rede corporativa, proxy, aba em segundo plano), a página também consulta o estado a cada poucos segundos. Se o socket funciona, o polling quase nunca é necessário; se não funciona, o usuário ainda chega ao resultado.
Testes
Nos testes, o broadcast usa o driver null e eu testo duas coisas separadas: que a action dispara o evento certo, com o payload mínimo, e que a autorização dos canais recusa versão antiga, permissão faltando e clínica alheia. A segunda parte é a que mais importa, porque um erro ali não aparece em nenhuma tela.
Fechando
O resumo do desenho é que o WebSocket só toca a campainha e quem abre a porta é o Inertia, com todas as regras de acesso que já existem. A versão no nome do canal resolve a revogação sem estado extra. Mais detalhes sobre as filas que alimentam esses eventos estão em Filas com Laravel Horizon, e as regras de acesso por clínica em Multitenancy e segurança. O contexto do projeto está na página do Markmedi.