Pular para o conteúdo
~/rafael-ferreira

Filas no Markmedi: como o Horizon separa o lembrete do paciente da campanha de e-mail

Supervisores com capacidade fixa, invariantes de timeout testadas, rate limit global para o SES e um ledger de idempotência: como organizei as filas do Markmedi com Laravel Horizon.

6 min de leitura #markmedi #laravel #horizon #redis #filas

Num sistema de clínica, a fila de jobs carrega coisas com urgências muito diferentes. O lembrete da consulta de amanhã precisa sair no horário. A transcrição de uma consulta pode levar minutos de processamento de IA. Uma campanha de e-mail para quatro mil contatos pode ocupar um worker por meia hora. E o vídeo de evolução de fotos de um paciente usa ffmpeg e memória. Se tudo isso divide a mesma fila, a campanha de marketing atrasa o lembrete, e o paciente não aparece.

O Markmedi roda em Redis com Laravel Horizon, e a organização das filas foi uma das partes em que mais apanhei até chegar ao desenho atual.

Supervisores com capacidade fixa

Em vez de deixar o Horizon balancear processos automaticamente, cada supervisor tem número fixo de processos (mínimo igual ao máximo) e consome um conjunto pequeno de filas. Isso troca um pouco de eficiência por previsibilidade: eu sei exatamente quantos workers existem para cada tipo de trabalho e quanta memória o contêiner vai usar.

Supervisor

Filas (em ordem de prioridade)

Processos

Para quê

clinic

critical, default

2

Gatilhos de lembrete e confirmação, webhooks de provedores, notificações transacionais e o trabalho comum da clínica

ai

ai

2

Transcrição, resumos, anamnese assistida, análises

emails

emails

1

Disparo de campanhas e envio de e-mail marketing

media

media

1

Gravações, vídeos de evolução, exportação de prontuário

O ponto importante é o que fica dentro do supervisor clinic. A fila critical recebe os jobs que disparam lembretes e pedidos de confirmação e o processamento dos webhooks de WhatsApp, SMS e e-mail. Como o supervisor consome critical antes de default, esses jobs passam na frente. As notificações transacionais em si (o WhatsApp do lembrete, o e-mail de confirmação) saem na default do mesmo supervisor. Não existe uma fila exclusiva de WhatsApp. O que existe é o isolamento do que é pesado e não urgente: IA, mídia e marketing nunca consomem a capacidade da clínica.

Quatro supervisores do Horizon com capacidade fixa: clinic com critical e default, ai, emails e media

Também configurei limites de espera por fila, que disparam alerta quando um job fica parado tempo demais: 30 segundos para critical, 60 para default, 2 minutos para e-mails e 5 minutos para IA e mídia.

Uma invariante de timeout que virou teste

Um bug clássico de fila em Redis é o job ser entregue duas vezes. Acontece quando o job demora mais que o retry_after da conexão: o Redis acha que o worker morreu e entrega o job a outro worker, enquanto o primeiro ainda está trabalhando. Para isso não depender de alguém lembrar, existe um teste de configuração com uma tabela de todos os jobs relevantes. Ele confere a fila de cada um e a cadeia de tempos:

timeout do job < timeout do supervisor < retry_after da conexão

O timeout do job é menor que o do supervisor, que é menor que o retry_after da conexão; se o job passa do retry_after, o Redis o entrega a outro worker

O mesmo arquivo confere o total de workers e garante que mídia e campanhas não consomem capacidade da clínica. Mudar a configuração do Horizon sem atualizar o teste quebra o CI, e é exatamente isso que eu quero.

Rate limit global para o Amazon SES

Cada destinatário de uma campanha é um job, e esses jobs passam por um rate limiter chamado ses-send. Ele é global, e não por clínica, porque o limite de envio do SES é da conta inteira, não de cada cliente. Um limite por clínica permitiria que dez clínicas disparando ao mesmo tempo estourassem a cota da conta e começassem a tomar erro de throttling.

O job de envio tem várias proteções em volta disso: número de exceções limitado, backoff progressivo (30 s, 2 min, 5 min) e um prazo máximo de 12 horas para tentar. Quando a campanha é pausada, o job não gasta uma vaga do rate limiter só para descobrir que está pausado: ele confere o estado, volta para a fila mais tarde e estende o próprio prazo. A arquitetura completa do módulo de e-mail está em e-mail marketing com BYOD e Amazon SES.

Job que sabe que ficou velho

Um lembrete é agendado para 24 horas antes da consulta. Se a recepção remarca a consulta depois disso, o job antigo continua na fila. A solução foi dar à consulta um reminder_version que muda a cada remarcação. O job carrega a versão que viu e, ao rodar, descarta a si mesmo se ela mudou. Ele também desiste se a consulta já foi concluída ou cancelada, se o paciente não tem como ser contatado ou se o plano da clínica não inclui aquele recurso.

Depois de uma remarcação, o reminder_version muda de 1 para 2; o job antigo percebe a diferença e se descarta, o novo envia o lembrete

Esse padrão de "conferir se ainda faz sentido" na hora de executar é mais robusto do que tentar cancelar jobs na fila, que é algo que o Redis não faz bem.

Um ledger para nunca enviar duas vezes

Mesmo com tudo isso, um job pode rodar duas vezes: um worker morre depois de enviar e antes de confirmar, ou um deploy reinicia o processo no pior momento. Para mensagens ao paciente, enviar duas vezes é um problema real. Toda mensagem de saída passa por uma tabela de ledger com uma chave de idempotência única, derivada do que a mensagem representa, como "receita pronta da prescrição X" ou "passo N da sequência Y".

try {
    $message = OutboundMessage::create(['idempotency_key' => $key, ...]);
} catch (UniqueConstraintViolationException) {
    return DispatchResult::alreadySent(); // perdeu a corrida: outro worker já enviou
}

O canal confere antes se a chave existe e, se perder a corrida no insert, trata a violação de unicidade como "já enviado". O fallback de SMS segue a mesma ideia: depois de um envio por WhatsApp, um job de SMS é agendado com alguns minutos de atraso e reaproveita a chave de idempotência do envio original, para continuar amarrado à mesma mensagem lógica.

Nada sai antes do commit

Outro cuidado é a ordem entre banco e fila. Notificações e eventos de domínio são despachados só depois do commit da transação. Sem isso, um job pode começar antes de a transação terminar, procurar a consulta que acabou de ser criada e não encontrar, ou pior, enviar a confirmação de um agendamento que sofreu rollback.

Testando a fila de verdade

Nos testes comuns a fila roda em modo síncrono, o que é ótimo para testar regra de negócio e inútil para testar confiabilidade. Por isso o CI tem um job separado que sobe Redis e Supervisor de verdade e roda testes de ciclo de vida da fila:

  • um job só é reentregue depois da janela de queda do worker;
  • um SIGTERM durante o deploy encerra o worker sem perder o backlog;
  • a recuperação depois de uma queda não duplica o efeito do job;
  • jobs de um mesmo relatório rodam serializados.

Esse tipo de teste cobre o que nenhum teste unitário alcança. Um exemplo é a configuração do Supervisor: o tempo de espera no desligamento precisa ser maior que o job mais longo, senão um deploy mata o worker no meio do trabalho.

Status em tempo real

Alguns jobs longos reportam progresso para a interface. A análise de posicionamento da clínica, por exemplo, emite eventos de progresso por WebSocket com o Reverb, e a tela tem um polling de reserva caso a conexão caia. Os detalhes estão em tempo real com Laravel Reverb.

Resumo

Separei o trabalho por urgência e custo, não por tecnologia. Fixei a capacidade de cada supervisor para que o servidor tenha comportamento previsível. As regras que mais causariam incidente (tempos, isolamento, idempotência) viraram testes. O Horizon fica com o que faz bem, visibilidade e supervisão, e a correção de cada envio fica no código da aplicação.

Este texto faz parte da série sobre o Markmedi. Para ver o que acontece antes do job entrar na fila, leia arquitetura, DDD e eventos.