use crate::error::{ForgeError, Result};
use chrono::{DateTime, Datelike, Timelike, Utc};
#[derive(Debug, Clone)]
pub(crate) struct Cron {
minute: Vec<bool>, hour: Vec<bool>, dom: Vec<bool>, month: Vec<bool>, dow: Vec<bool>, dom_restricted: bool,
dow_restricted: bool,
}
impl Cron {
pub(crate) fn parse(expr: &str) -> Result<Self> {
let src = expand_macro(expr).unwrap_or(expr);
let fields: Vec<&str> = src.split_whitespace().collect();
if fields.len() != 5 {
return Err(ForgeError::invalid(format!(
"cron expression needs exactly 5 fields, got {}",
fields.len()
)));
}
let get = |i: usize| fields.get(i).copied().unwrap_or("");
let (minute, _) = parse_field(get(0), 0, 59, &[])?;
let (hour, _) = parse_field(get(1), 0, 23, &[])?;
let (dom, dom_restricted) = parse_field(get(2), 1, 31, &[])?;
let (month, _) = parse_field(get(3), 1, 12, MONTHS)?;
let (dow, dow_restricted) = parse_field(get(4), 0, 7, DAYS)?;
Ok(Self {
minute,
hour,
dom,
month,
dow,
dom_restricted,
dow_restricted,
})
}
fn matches(&self, dt: &DateTime<Utc>) -> bool {
let bit = |v: &[bool], i: usize| v.get(i).copied().unwrap_or(false);
let wd = dt.weekday().num_days_from_sunday() as usize; let dom_ok = bit(&self.dom, dt.day() as usize);
let dow_ok = bit(&self.dow, wd) || (wd == 0 && bit(&self.dow, 7));
let day_ok = match (self.dom_restricted, self.dow_restricted) {
(true, true) => dom_ok || dow_ok,
(true, false) => dom_ok,
(false, true) => dow_ok,
(false, false) => true,
};
bit(&self.minute, dt.minute() as usize)
&& bit(&self.hour, dt.hour() as usize)
&& bit(&self.month, dt.month() as usize)
&& day_ok
}
pub(crate) fn next_after(&self, after: DateTime<Utc>) -> Option<DateTime<Utc>> {
let mut t = (after + chrono::Duration::minutes(1))
.with_second(0)?
.with_nanosecond(0)?;
for _ in 0..(4 * 366 * 24 * 60) {
if self.matches(&t) {
return Some(t);
}
t += chrono::Duration::minutes(1);
}
None
}
pub(crate) fn prev_or_at(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
let mut t = at.with_second(0)?.with_nanosecond(0)?;
for _ in 0..(4 * 366 * 24 * 60) {
if self.matches(&t) {
return Some(t);
}
t -= chrono::Duration::minutes(1);
}
None
}
}
const MONTHS: &[(&str, usize)] = &[
("JAN", 1),
("FEB", 2),
("MAR", 3),
("APR", 4),
("MAY", 5),
("JUN", 6),
("JUL", 7),
("AUG", 8),
("SEP", 9),
("OCT", 10),
("NOV", 11),
("DEC", 12),
];
const DAYS: &[(&str, usize)] = &[
("SUN", 0),
("MON", 1),
("TUE", 2),
("WED", 3),
("THU", 4),
("FRI", 5),
("SAT", 6),
];
fn expand_macro(expr: &str) -> Option<&'static str> {
match expr.trim() {
"@yearly" | "@annually" => Some("0 0 1 1 *"),
"@monthly" => Some("0 0 1 * *"),
"@weekly" => Some("0 0 * * 0"),
"@daily" | "@midnight" => Some("0 0 * * *"),
"@hourly" => Some("0 * * * *"),
_ => None,
}
}
fn parse_field(
spec: &str,
min: usize,
max: usize,
names: &[(&str, usize)],
) -> Result<(Vec<bool>, bool)> {
if spec.is_empty() {
return Err(ForgeError::invalid("empty cron field"));
}
let mut set = vec![false; max + 1];
let restricted = spec != "*";
for part in spec.split(',') {
let (range, step) = match part.split_once('/') {
Some((r, s)) => {
let step = s
.parse::<usize>()
.map_err(|_| ForgeError::invalid(format!("invalid cron step: {s:?}")))?;
if step == 0 {
return Err(ForgeError::invalid("cron step must be > 0"));
}
(r, step)
}
None => (part, 1),
};
let (lo, hi) = if range == "*" {
(min, max)
} else if let Some((a, b)) = range.split_once('-') {
(
parse_num(a, min, max, names)?,
parse_num(b, min, max, names)?,
)
} else {
let v = parse_num(range, min, max, names)?;
(v, v)
};
if lo > hi {
return Err(ForgeError::invalid(format!(
"cron range start > end: {range:?}"
)));
}
let mut v = lo;
while v <= hi {
if let Some(slot) = set.get_mut(v) {
*slot = true;
}
v += step;
}
}
Ok((set, restricted))
}
fn parse_num(s: &str, min: usize, max: usize, names: &[(&str, usize)]) -> Result<usize> {
let n = if let Some(&(_, v)) = names.iter().find(|(name, _)| name.eq_ignore_ascii_case(s)) {
v
} else {
s.parse::<usize>()
.map_err(|_| ForgeError::invalid(format!("invalid cron number: {s:?}")))?
};
if n < min || n > max {
return Err(ForgeError::invalid(format!(
"cron value {n} out of range {min}..={max}"
)));
}
Ok(n)
}
#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::panic, clippy::indexing_slicing)]
mod tests {
use super::*;
fn at(s: &str) -> DateTime<Utc> {
DateTime::parse_from_rfc3339(s).unwrap().with_timezone(&Utc)
}
#[test]
fn star_matches_every_minute() {
let c = Cron::parse("* * * * *").unwrap();
let now = at("2026-06-06T10:30:00Z");
assert_eq!(c.next_after(now), Some(at("2026-06-06T10:31:00Z")));
}
#[test]
fn step_minutes() {
let c = Cron::parse("*/15 * * * *").unwrap();
assert!(c.minute[0] && c.minute[15] && c.minute[30] && c.minute[45]);
assert!(!c.minute[7]);
assert_eq!(
c.next_after(at("2026-06-06T10:31:00Z")),
Some(at("2026-06-06T10:45:00Z"))
);
}
#[test]
fn daily_at_specific_time() {
let c = Cron::parse("0 9 * * *").unwrap();
assert_eq!(
c.next_after(at("2026-06-06T10:00:00Z")),
Some(at("2026-06-07T09:00:00Z"))
);
}
#[test]
fn weekday_range() {
let c = Cron::parse("0 9 * * 1-5").unwrap();
assert_eq!(
c.next_after(at("2026-06-06T12:00:00Z")),
Some(at("2026-06-08T09:00:00Z"))
);
}
#[test]
fn daily_macro_equals_its_expansion() {
assert_eq!(
Cron::parse("@daily")
.unwrap()
.next_after(at("2026-06-06T10:00:00Z")),
Cron::parse("0 0 * * *")
.unwrap()
.next_after(at("2026-06-06T10:00:00Z"))
);
assert!(Cron::parse("@hourly").is_ok());
assert!(Cron::parse("@weekly").is_ok());
assert!(Cron::parse("@yearly").is_ok());
}
#[test]
fn named_months_and_days_parse() {
let named = Cron::parse("0 9 * jan MON-FRI").unwrap();
let numeric = Cron::parse("0 9 * 1 1-5").unwrap();
assert_eq!(
named.next_after(at("2026-06-06T12:00:00Z")),
numeric.next_after(at("2026-06-06T12:00:00Z"))
);
assert!(Cron::parse("0 9 * MON *").is_err());
}
#[test]
fn prev_or_at_finds_the_most_recent_tick() {
let every = Cron::parse("* * * * *").unwrap();
assert_eq!(
every.prev_or_at(at("2026-06-06T10:30:45Z")),
Some(at("2026-06-06T10:30:00Z"))
);
let daily = Cron::parse("0 9 * * *").unwrap();
assert_eq!(
daily.prev_or_at(at("2026-06-06T14:00:00Z")),
Some(at("2026-06-06T09:00:00Z"))
);
assert_eq!(
daily.prev_or_at(at("2026-06-06T09:00:00Z")),
Some(at("2026-06-06T09:00:00Z"))
);
}
#[test]
fn invalid_expressions_error() {
assert!(Cron::parse("* * * *").is_err()); assert!(Cron::parse("60 * * * *").is_err()); assert!(Cron::parse("*/0 * * * *").is_err()); assert!(Cron::parse("5-1 * * * *").is_err()); }
}