how-i-build

keepalive

Um Cloudflare Worker que impede serviços em plano gratuito de dormir e publica cada ping como uma página de status pública.

2026No arPrivadoAutor único
TypeScriptTypeScriptCloudflare WorkersCloudflare WorkersReactReactViteVite

A API do Orbit roda no plano gratuito do Render, e os bancos no plano gratuito da Supabase. Os dois são gratuitos porque dormem: o Render depois de 15 minutos sem tráfego, a Supabase depois de um período do que ela chama de baixa atividade. API dormindo quer dizer que a primeira pessoa a abrir o app espera um cold start, e banco pausado quer dizer que ele simplesmente não responde.

O keepalive é a peça pequena que impede isso. É um Cloudflare Worker com dois crons: um pinga a API e os sites a cada 10 minutos, o outro chama cada banco a cada hora. O que ele vê fica salvo no Workers KV e vira uma página de status em keepalive.byjuliocesa.dev, feita em React e Vite e servida como arquivos estáticos pelo próprio Worker. Quando um serviço passa de no ar para fora do ar, ele pode mandar um alerta para um webhook.

O repositório é privado. A página, o JSON e o badge são públicos.

Um Worker que mantém o Render acordado

A primeira versão fazia uma coisa só: um GET no /system/ping do Orbit a cada 10 minutos, que é menos que os 15 que o Render espera antes de dormir, e uma chamada diária para cada banco. Um Worker no plano gratuito da Cloudflare roda crons sem custo, então o preço de manter os planos gratuitos acordados é mais um plano gratuito.

Decisão

Um Cloudflare Worker com cron triggers, a API pingada a cada 10 minutos e os bancos uma vez por dia, cada banco expondo uma função public.keepalive() pelo endpoint REST.

Trade-offs

  • Tudo depende de a Cloudflare continuar oferecendo crons no plano gratuito.
  • Ele mantém os serviços acordados, não os deixa rápidos. Um cold start que acontece mesmo assim continua sendo um cold start.

Um registro por cron, por causa da cota de escrita

O plano gratuito do KV permite 1.000 escritas por dia. Um cron a cada 10 minutos são 144 execuções por dia, e escrever uma chave por serviço multiplicava isso por cada serviço da lista. A cota acabava sozinha.

Decisão

Tudo o que um cron descobre vai para um único registro: o último estado de cada serviço, um resumo diário de 90 dias, os últimos 288 pings e os incidentes abertos. Uma execução, uma escrita.

Trade-offs

  • O formato dos dados é decidido pela cota, não pelo que seria mais fácil de ler.
  • Cada execução reescreve o registro inteiro, então ele precisa continuar pequeno.

No mesmo dia entraram mais duas regras. Uma falha só conta depois de uma segunda tentativa, para que uma resposta lenta isolada não abra incidente. E a resposta precisa conter um trecho de texto esperado: uma página de erro servida com HTTP 200 continua sendo falha. A lista de alvos também saiu do código e foi para o KV, então um serviço entra ou sai com npm run config, sem deploy.

Uma rota de saúde que falha quando o trabalho para

Um monitor externo vigiava a página de status, e a página sempre respondia 200. Se o cron parasse, a página continuava mostrando o último dado que tinha, com cara de tudo certo, e o monitor não via problema nenhum.

Decisão

/api/health devolve 500 quando um cron atrasa: mais de 30 minutos desde a última execução do cron de 10 minutos, mais de 3 horas para o cron dos bancos. O monitor externo passou a apontar para lá em vez da página.

A pergunta do monitor mudou de "o servidor responde?" para "o trabalho está acontecendo?". Só a segunda valia a pena.

Chamadas de hora em hora, porque uma por dia não era atividade

O banco de desenvolvimento foi pausado em 27 de setembro mesmo recebendo a chamada diária, e a chamada chegava até ele: a latência era igual à do banco de produção. A Supabase pausa projetos que considera de baixa atividade e pede alguns requests por dia. Um por dia não bastava.

Decisão

O cron dos bancos roda de hora em hora (0 * * * *). A checagem RDAP do domínio continua uma vez por dia, às 03:00 UTC.

Trade-offs

  • Vinte e quatro chamadas por dia por banco em vez de uma, por uma regra que a Supabase não diz em número.
  • O limite de saúde do cron dos bancos era de 26 horas enquanto a chamada era diária; hoje é de 3 horas.

Uma página de status lida de relance

A página foi redesenhada do zero com duas skills de design: uma definiu a direção, a outra construiu e mandou revisar. A direção fez de cada serviço uma linha larga, com a faixa de histórico ocupando a maior parte, para que o estado inteiro seja lido de relance no celular. A alternativa mais forte era um quadro de partidas em monoespaçada; escolhi as linhas.

Decisão

Uma linha larga por serviço, com a faixa de histórico como elemento principal. Geist e Geist Mono, fundo grafite com destaque cobalto e ícones Phosphor. Saíram o laranja, a Archivo como fonte da interface e os cantos retos; o logo ficou.

A revisão pediu seis ajustes na primeira rodada e aprovou a segunda. A faixa tem três janelas: 24 horas em 72 fatias de 20 minutos, 7 dias em 84 fatias e 90 dias em uma fatia por dia. Uma resposta de 2 segundos ou mais é marcada como lenta.

Monitorar o que não dorme

O LyricsLens e o BetoBita rodam na Vercel, que não coloca sites para dormir, então eles nunca precisaram ser mantidos acordados. Entraram na lista mesmo assim, como monitoramento na página pública. Antes de adicionar o BetoBita, uma checagem levou 7,98 segundos; o primeiro ping do keepalive mediu 587 ms.

A lista tem sete alvos hoje: a API e o app web do Orbit, este site, o LyricsLens, o BetoBita e os bancos de desenvolvimento e de produção.

Referências