Cron Workers

Prefere o terminal? Veja comandos do CLI → crons.

Um cron worker é um disparador agendado que vive dentro do seu projeto. Você define um nome, uma expressão cron com timezone IANA, um destino e um payload JSON opcional. O Guara Cloud dispara no horário, entrega o payload no destino e persiste cada execução com status, número da tentativa, tempo e um motivo de falha estruturado quando algo dá errado.

Você não precisa subir um “serviço de cron” rodando o tempo todo nem incluir dependências de scheduler na sua aplicação. Cron workers são um recurso de primeira classe — como um serviço ou um banco — gerenciados inteiramente pelo dashboard.

Quando usar um cron worker

Use um cron worker sempre que algo precisa acontecer em horário fixo:

• Limpeza horária via HTTP chamando sua API (POST /jobs/cleanup-stale-uploads).
• Resumo diário que publica uma mensagem NATS consumida pelo seu worker para enviar e-mails.
• Aquecimento de cache publicando em um canal Redis ou Valkey a cada 15 minutos.
• Disparo de pipeline de dados empurrando um evento para o RabbitMQ que aciona um job.
• Notificação de banco via Postgres LISTEN/NOTIFY para distribuir trabalho entre listeners.

Conceitos principais

• Schedule: uma expressão cron e um timezone IANA. O intervalo mínimo entre disparos é de 60 segundos.
• Destino: onde o disparo cai. Seis tipos suportados: HTTP, NATS, Redis, Valkey, RabbitMQ e Postgres LISTEN/NOTIFY. Uma vez escolhido, o tipo do destino é imutável; você ainda pode editar a configuração (path, subject, channel, etc.).
• Payload: um objeto JSON opcional (até 64 KiB) enviado tal qual ao destino em todo disparo.
• Status: active, suspended ou deleted. Workers suspensos não disparam, mas mantêm configuração e histórico.
• Run: cada disparo gera um registro de execução com status (running, success, failed), triggered_by (schedule ou manual), número da tentativa, horário programado, início/fim e um failure_reason estruturado quando aplicável.
• Disparo manual: você pode disparar um worker sob demanda no dashboard, fora do schedule, para testes ou backfills pontuais.

Quota por projeto

A quantidade de cron workers em um projeto depende do plano:

Quando você atinge a quota do projeto, o dashboard mostra um prompt de upgrade no lugar de um erro genérico. Workers existentes continuam disparando normalmente — o limite só impede a criação de novos.

O que acontece em uma execução

Para cada disparo, o orchestrator abre um registro de execução, resolve os dados de conexão do destino (e quaisquer credenciais necessárias do catálogo), envia o payload e aguarda até o timeout configurado (5–300 s, padrão 30 s) pela confirmação do destino. Se o destino falha ou estoura o tempo, a execução é tentada de novo com backoff exponencial até o máximo de retentativas configurado (1–5, padrão 3). Erros permanentes (HTTP 4xx exceto 408/429, rejeições de validação) encerram o ciclo de retry. Erros de rede, 5xx e timeouts são reentregues.

Toda execução carrega um header traceparent no padrão W3C, então você consegue acompanhar o disparo ponta-a-ponta pelos seus serviços na visão de Traces.

Garantias de confiabilidade e segurança

• Disparo único por slot: o orchestrator é leader-elected, então cada slot do cron dispara exatamente uma vez, mesmo durante deploys ou reinícios.
• Limite de concorrência: cada worker tem um teto de execuções simultâneas em voo, evitando avalanches quando o destino está lento.
• Proteção SSRF no HTTP: destinos HTTP não conseguem alcançar loopback, RFC 1918, link-local, IPv4-mapped IPv6 ou carrier-grade NAT. Os erros aparecem como ssrf_blocked.
• Headers reservados bloqueados: headers customizados não podem sobrescrever Host, Authorization, Cookie, Connection, Upgrade, Transfer-Encoding, Content-Length, Traceparent ou Tracestate.
• Audit logging: create, update, suspend, resume, delete e disparo manual são todos registrados nos seus Audit Logs.

Continue por aqui