Tipos de Destino
Todo cron worker tem exatamente um destino. Seis tipos estão disponíveis, cobrindo as formas mais comuns de distribuir trabalho agendado em um projeto orientado a serviços.
| Destino | Use para |
|---|---|
| HTTP | Chamar um endpoint em um dos seus serviços |
| NATS | Publicar em um subject NATS para outros serviços consumirem |
| Redis | Publicar em um canal Redis Pub/Sub |
| Valkey | Publicar em um canal Valkey Pub/Sub (compatível com Redis) |
| RabbitMQ | Publicar em uma exchange com routing key |
| Postgres | Enviar um NOTIFY para um canal LISTEN/NOTIFY do Postgres |
O tipo de destino é escolhido na criação e não pode mudar depois. A configuração do destino (path, subject, channel, etc.) é editável a qualquer momento na página de detalhe do worker.
HTTP
Chama um path em um serviço do seu projeto. O cron worker resolve o endpoint interno em runtime — você não precisa copiar URLs.
| Campo | O que é |
|---|---|
| Serviço | Escolha entre os serviços do projeto. O worker usa o endpoint primário do serviço. |
| Path | O path sob o endpoint, começando com /. Máximo 2048 caracteres. Espaços e bytes de controle são rejeitados. |
| Headers | Headers HTTP customizados opcionais como pares Nome: valor. |
O worker sempre envia POST com o payload JSON no corpo e Content-Type: application/json. Ele também define Traceparent e Tracestate para que a requisição entre no mesmo trace do disparo.
Headers reservados
Você não pode sobrescrever estes headers — são gerenciados pela plataforma:
Host, Authorization, Cookie, Connection, Upgrade, Transfer-Encoding, Content-Length, Traceparent, Tracestate
Os nomes precisam seguir a RFC 7230 (tokens ASCII). Nomes inválidos são rejeitados na validação.
Proteção SSRF
Destinos HTTP ficam restritos aos seus próprios serviços. O orchestrator bloqueia qualquer host resolvido que caia em:
- Loopback (
127.0.0.0/8,::1) - Redes privadas RFC 1918 (
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16) - Link-local (
169.254.0.0/16,fe80::/10) - Carrier-grade NAT (RFC 6598,
100.64.0.0/10) - IPv6 unique-local (
fc00::/7) - IPv4-mapped IPv6
- Endereço não especificado (
0.0.0.0/8,::)
Tentativas bloqueadas são gravadas como execuções com failure_reason: ssrf_blocked para você ver no histórico.
NATS
Publica o payload JSON em um subject NATS. O cron worker lê os dados de conexão e credenciais do serviço NATS do catálogo automaticamente.
| Campo | O que é |
|---|---|
| Serviço | Um serviço NATS do catálogo no seu projeto. |
| Subject | O subject a publicar (por exemplo, jobs.daily-digest). |
A publicação é fire-and-forget no protocolo NATS. A execução vira success assim que o broker aceita a mensagem.
Redis e Valkey
Publica o payload JSON em um canal Redis ou Valkey Pub/Sub. O Valkey é o drop-in compatível com Redis disponível no catálogo.
| Campo | O que é |
|---|---|
| Serviço | Um serviço Redis ou Valkey do catálogo no seu projeto. |
| Channel | O nome do canal Pub/Sub (por exemplo, cache:warmup). |
O worker faz PUBLISH <channel> <payload> e considera a execução success assim que o servidor confirma a entrega ao canal. Atenção: Redis Pub/Sub não armazena nada — se nenhum subscriber estiver ouvindo, a mensagem é descartada (assim funciona o Redis Pub/Sub, não é uma limitação do Guara Cloud).
RabbitMQ
Publica o payload JSON em uma exchange RabbitMQ com uma routing key.
| Campo | O que é |
|---|---|
| Serviço | Um serviço RabbitMQ do catálogo no seu projeto. |
| Exchange | A exchange para publicar. |
| Routing key | A routing key (por exemplo, reports.daily). |
| Exigir entrega | Quando ativado, falha a execução se o broker reportar a mensagem como não roteável (nenhuma fila vinculada à exchange/routing key). Quando desativado (padrão), a publicação é fire-and-forget. |
Use Exigir entrega quando o schedule deve falhar de forma visível se nenhum consumidor estiver ouvindo — por exemplo, se um deploy mal configurado removeu o binding de um job crítico.
Postgres NOTIFY
Envia um NOTIFY do Postgres em um canal. Útil para distribuir trabalho a listeners dentro do banco ou para acionar fluxos baseados em pg_notify.
| Campo | O que é |
|---|---|
| Serviço | Um serviço Postgres do catálogo no seu projeto. |
| Channel | O nome do canal a notificar (por exemplo, jobs_pending). |
O worker embrulha o payload JSON em um pequeno envelope _meta com o run ID e um traceparent W3C, e roda NOTIFY <canal>, '<envelope>'. Os listeners recebem o envelope como string no payload do NOTIFY.
NOTIFY jobs_pending, '{"_meta":{"run_id":"...","traceparent":"00-..."},"payload":{...}}'Taxonomia de motivos de falha
Toda execução falha carrega um failure_reason estruturado que o histórico mostra com um rótulo amigável. O conjunto completo:
| Código | Quando dispara |
|---|---|
timeout | O destino não respondeu dentro do timeout configurado. |
dns | A resolução de DNS falhou. |
connection | A conexão TCP/socket falhou (recusada, derrubada, inalcançável). |
tls | O handshake TLS falhou (certificado inválido, protocolo não suportado). |
http_4xx | O destino HTTP retornou um 4xx que não era 408 / 429. Permanente — não retenta. |
http_5xx | O destino HTTP retornou um 5xx. Retenta até o limite configurado. |
ssrf_blocked | O destino HTTP resolve para um endereço bloqueado (privado, loopback, etc.). Permanente. |
credential | As credenciais do serviço de catálogo não puderam ser resolvidas ou foram rejeitadas. |
protocol | Erro de protocolo no destino (erro de publicação NATS, RabbitMQ não roteável, etc.). |
unknown | Qualquer outra coisa — confira o campo error para detalhes. |