Validador de Cron Expression

Expressoes cron: uma mini DSL para agendamento baseado em tempo

Cron e a lingua franca dos jobs recorrentes no Unix. Uma expressao cron e uma string compacta com cinco (as vezes seis ou sete) campos separados por espaco que descreve "quando" algo deve rodar. O agendador — crond, timer do systemd, CronJob do Kubernetes, scheduler do GitHub Actions, Vercel Cron — desperta a cada minuto e dispara toda entrada cujo padrao bata com o relogio atual.

Apesar da simplicidade aparente, a sintaxe esta cheia de surpresas especificas de cada dialeto: dia da semana 0-indexado vs 1-indexado, operadores exclusivos do Quartz (L, W, #), logica AND vs OR entre os campos de dia, e armadilhas de fuso horario. Este validador checa estrutura e ranges dos campos para voce pegar erros de sintaxe antes de subir em producao.

O formato classico Unix Vixie com 5 campos

O cron Vixie original, distribuido na maioria das distros Linux, usa cinco campos:

* * * * *  comando
| | | | |
| | | | +-- dia da semana (0-6, 0=Domingo; ou SUN-SAT)
| | | +---- mes           (1-12 ou JAN-DEC)
| | +------ dia do mes    (1-31)
| +-------- hora          (0-23)
+---------- minuto        (0-59)

Operadores dentro de um campo:

• * — qualquer valor.
• , — lista, ex.: 1,15,30.
• - — intervalo, ex.: 1-5.
• / — passo, ex.: */15 (a cada 15) ou 10-30/5.
• L, W, # — apenas no Quartz: ultimo dia, dia util mais proximo, n-esimo dia da semana do mes.

Exemplos comentados

• 0 9 * * 1-5 — todo dia util as 09:00.
• */15 * * * * — a cada 15 minutos.
• 0 0 1 * * — todo dia 1 do mes a meia-noite.
• 30 2 * * 0 — todo domingo as 02:30.
• 0 12 1 1 * — meio-dia de 1 de janeiro.
• 0 0 * * 1#2 — segunda-feira da segunda semana do mes (Quartz).

Dialetos: Vixie, Quartz, AWS, Kubernetes, GitHub

Nem todo cron e o mesmo cron:

• Unix Vixie cron — 5 campos, dia da semana 0-6 (Domingo=0 ou 7).
• Quartz (Java) — 6 ou 7 campos: segundos minutos horas dom mes dow [ano], dia da semana 1-7 com Domingo=1. Suporta L (last), W (nearest weekday), # (n-esimo dia da semana).
• AWS EventBridge — 6 campos, inclui ano, exige ? em dom ou dow.
• Kubernetes CronJob — 5 campos puros, UTC por padrao; desde a 1.27 aceita timeZone na spec.
• GitHub Actions — 5 campos, somente UTC, intervalo minimo de 5 minutos e disparos podem ser pulados sob carga.
• Vercel Cron — 5 campos, UTC, ressalvas semelhantes.

Armadilhas comuns: dia da semana e logica dom+dow

Dois erros pegam quase todo dev:

• Domingo e 0 e tambem 7 no Vixie cron — aceito por compatibilidade com o cron original da AT&T. No Quartz Domingo e 1.
• dia do mes e dia da semana sao ORed, nao ANDed, quando ambos sao especificados. 0 0 13 * 5 dispara em todo dia 13 e toda sexta — nao "sexta-feira 13".
• Passo */0 e invalido; 0/15 e forma exclusiva do Quartz.
• Meses/dias da semana nomeados nao sao sensiveis a caixa, mas precisam ter tres letras (JAN, MON).

O Brasil simplifica uma coisa: desde 2019 o pais aboliu o horario de verao, entao um job agendado para 02:30 BRT nao e pulado nem duplicado duas vezes por ano como aconteceria nos EUA ou na UE.

Ferramentas: validar, decodificar e prever proximos disparos

Bibliotecas e sites recomendados:

• crontab.guru — o decodificador visual canonico; cola uma expressao e mostra o significado em ingles.
• cronstrue (npm) — descricao legivel por humano em varios idiomas.
• cron-validator, cron-parser (npm) — parse, validacao e calculo de proximos disparos em Node.
• Quartz (Java) — dialeto Quartz completo com CronExpression.
• croniter (Python) — iteracao compativel com Vixie das proximas execucoes.

FAQ

5 ou 6 campos — qual usar?

Agendadores de sabor Unix (Vixie, GitHub Actions, Kubernetes, Vercel) querem 5 campos. Quartz e AWS EventBridge usam 6+; so adote esse formato se o seu runner explicitamente suporta.

A relacao entre dom e dow e AND ou OR?

OR. Quando ambos os campos sao restringidos, o job dispara sempre que qualquer uma das condicoes bater. Para expressar "sexta-feira 13" voce precisa restringir um deles e checar o outro dentro do job.

Como prever os proximos disparos antes de subir?

Cole a expressao no crontab.guru ou rode cron-parser em Node para enumerar os proximos N disparos. No GitHub Actions, dispare manualmente com o evento workflow_dispatch para testar.

Qual fuso horario e usado?

A maioria dos runners gerenciados (GitHub Actions, Vercel, AWS) executa em UTC. O crond Linux usa o fuso do sistema (/etc/localtime). Kubernetes 1.27+ suporta um campo explicito timeZone na spec do CronJob.

Por que meu cron no GitHub Actions atrasa as vezes?

O GitHub agenda workflows em best effort. Sob pico de carga, disparos podem atrasar varios minutos ou ate ser pulados. Para timing rigoroso, use um agendador dedicado.