use chrono::{
DateTime, Datelike, MappedLocalTime, NaiveDate, NaiveDateTime, TimeZone, Timelike, Weekday,
};
use chrono_tz::Tz;
const EVERY_ALLOWED_MINUTES: &[u32] = &[5, 10, 15, 20, 30];
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Schedule {
Hourly { minutes: Vec<u32> },
Daily { hour: u32, minute: u32 },
Weekly {
weekday: Weekday,
hour: u32,
minute: u32,
},
Monthly { day: u32, hour: u32, minute: u32 },
At { datetime: NaiveDateTime },
}
pub(crate) fn parse_schedule(s: &str) -> Result<Schedule, String> {
let trimmed = s.trim();
if trimmed.is_empty() {
return Err(format!("empty schedule: '{s}'"));
}
if !trimmed.starts_with('@') {
if looks_like_legacy_interval(trimmed) {
return Err(format!(
"interval schedule '{trimmed}' was removed in 0.2.0; \
use '@every 5m' (5/10/15/20/30) for sub-hourly, or '@hourly' / '@daily HH:MM'"
));
}
return Err(format!(
"schedule must start with '@' (e.g. '@hourly', '@daily 09:00'), got '{trimmed}'"
));
}
let mut parts = trimmed.splitn(2, char::is_whitespace);
let head = parts.next().unwrap(); let rest = parts.next().unwrap_or("").trim();
match head {
"@hourly" => parse_hourly(rest, trimmed),
"@every" => parse_every(rest, trimmed),
"@daily" => {
let (h, m) = parse_hhmm(rest, trimmed)?;
Ok(Schedule::Daily { hour: h, minute: m })
}
"@weekly" => {
let mut sp = rest.splitn(2, char::is_whitespace);
let wd_s = sp
.next()
.filter(|s| !s.is_empty())
.ok_or_else(|| format!("@weekly missing weekday in '{trimmed}'"))?;
let time_s = sp
.next()
.ok_or_else(|| format!("@weekly missing time in '{trimmed}'"))?
.trim();
let weekday = parse_weekday(wd_s, trimmed)?;
let (h, m) = parse_hhmm(time_s, trimmed)?;
Ok(Schedule::Weekly {
weekday,
hour: h,
minute: m,
})
}
"@monthly" => {
let mut sp = rest.splitn(2, char::is_whitespace);
let d_s = sp
.next()
.filter(|s| !s.is_empty())
.ok_or_else(|| format!("@monthly missing day in '{trimmed}'"))?;
let time_s = sp
.next()
.ok_or_else(|| format!("@monthly missing time in '{trimmed}'"))?
.trim();
let d: u32 = d_s
.parse()
.map_err(|_| format!("@monthly invalid day '{d_s}' in '{trimmed}'"))?;
if !(1..=31).contains(&d) {
return Err(format!(
"@monthly day out of range (1-31): '{d}' in '{trimmed}'"
));
}
let (h, m) = parse_hhmm(time_s, trimmed)?;
Ok(Schedule::Monthly {
day: d,
hour: h,
minute: m,
})
}
"@at" => {
if rest.is_empty() {
return Err(format!("@at missing datetime in '{trimmed}'"));
}
let dt = NaiveDateTime::parse_from_str(rest, "%Y-%m-%dT%H:%M")
.map_err(|e| format!("@at invalid datetime '{rest}' in '{trimmed}': {e}"))?;
Ok(Schedule::At { datetime: dt })
}
other => Err(format!(
"unknown schedule keyword '{other}' in '{trimmed}' \
(expected @hourly / @every / @daily / @weekly / @monthly / @at)"
)),
}
}
fn looks_like_legacy_interval(s: &str) -> bool {
let mut chars = s.chars();
match chars.next_back() {
Some('s' | 'm' | 'h') => {
let num = chars.as_str();
!num.is_empty() && num.chars().all(|c| c.is_ascii_digit())
}
_ => false,
}
}
fn parse_hourly(rest: &str, orig: &str) -> Result<Schedule, String> {
if rest.is_empty() {
return Ok(Schedule::Hourly { minutes: vec![0] });
}
let mm = rest.strip_prefix(':').ok_or_else(|| {
format!("@hourly argument must be ':MM' (e.g. '@hourly :45'), got '{rest}' in '{orig}'")
})?;
if mm.contains(',') {
return Err(format!(
"@hourly takes a single ':MM'; comma lists are not supported \
(use '@every Nm' for an evenly-spaced set) in '{orig}'"
));
}
let m: u32 = mm
.parse()
.map_err(|_| format!("@hourly invalid minute '{mm}' in '{orig}'"))?;
if m >= 60 {
return Err(format!(
"@hourly minute out of range (0-59): '{m}' in '{orig}'"
));
}
Ok(Schedule::Hourly { minutes: vec![m] })
}
fn parse_every(rest: &str, orig: &str) -> Result<Schedule, String> {
if rest.is_empty() {
return Err(format!("@every missing interval in '{orig}'"));
}
let num = rest.strip_suffix('m').ok_or_else(|| {
format!("@every interval must be in minutes (e.g. '@every 10m'), got '{rest}' in '{orig}'")
})?;
let n: u32 = num
.parse()
.map_err(|_| format!("@every invalid interval '{rest}' in '{orig}'"))?;
if !EVERY_ALLOWED_MINUTES.contains(&n) {
return Err(format!(
"@every interval must be one of {EVERY_ALLOWED_MINUTES:?} minutes \
(a divisor of 60, so each hour expands identically), got '{n}m' in '{orig}'"
));
}
let minutes = (0..60).step_by(n as usize).collect();
Ok(Schedule::Hourly { minutes })
}
fn parse_hhmm(s: &str, orig: &str) -> Result<(u32, u32), String> {
let (h_s, m_s) = s
.split_once(':')
.ok_or_else(|| format!("expected HH:MM in '{orig}', got '{s}'"))?;
let h: u32 = h_s
.parse()
.map_err(|_| format!("invalid hour '{h_s}' in '{orig}'"))?;
let m: u32 = m_s
.parse()
.map_err(|_| format!("invalid minute '{m_s}' in '{orig}'"))?;
if h >= 24 {
return Err(format!("hour out of range (0-23): '{h}' in '{orig}'"));
}
if m >= 60 {
return Err(format!("minute out of range (0-59): '{m}' in '{orig}'"));
}
Ok((h, m))
}
fn parse_weekday(s: &str, orig: &str) -> Result<Weekday, String> {
match s {
"MON" => Ok(Weekday::Mon),
"TUE" => Ok(Weekday::Tue),
"WED" => Ok(Weekday::Wed),
"THU" => Ok(Weekday::Thu),
"FRI" => Ok(Weekday::Fri),
"SAT" => Ok(Weekday::Sat),
"SUN" => Ok(Weekday::Sun),
_ => Err(format!(
"invalid weekday '{s}' (expected MON/TUE/WED/THU/FRI/SAT/SUN) in '{orig}'"
)),
}
}
pub(crate) fn resolve_tz(name: Option<&str>) -> Result<Tz, String> {
if let Some(n) = name {
return n
.parse::<Tz>()
.map_err(|e| format!("invalid tz '{n}': {e}"));
}
if let Ok(tz_env) = std::env::var("TZ") {
if !tz_env.is_empty() {
if let Ok(tz) = tz_env.parse::<Tz>() {
return Ok(tz);
}
}
}
let sys = iana_time_zone::get_timezone().map_err(|e| format!("cannot detect user tz: {e}"))?;
sys.parse::<Tz>()
.map_err(|e| format!("system tz '{sys}' not in chrono-tz DB: {e}"))
}
pub(crate) fn next_scheduled_after(after_ms: u64, spec: &Schedule, tz: &Tz) -> Option<u64> {
let after_i64 = i64::try_from(after_ms).ok()?;
let after_utc = DateTime::<chrono::Utc>::from_timestamp_millis(after_i64)?;
let local_after = after_utc.with_timezone(tz);
match spec {
Schedule::Hourly { minutes } => {
let mut hour_start = local_after
.date_naive()
.and_hms_opt(local_after.hour(), 0, 0)?;
for _ in 0..(24 * 400) {
for m in minutes {
let naive = hour_start.with_minute(*m)?;
if let Some(ms) = pick_earlier_utc(tz, &naive) {
if ms > after_ms {
return Some(ms);
}
}
}
hour_start = hour_start.checked_add_signed(chrono::TimeDelta::hours(1))?;
}
None
}
Schedule::Daily { hour, minute } => {
let mut date = local_after.date_naive();
for _ in 0..400 {
if let Some(naive) = date.and_hms_opt(*hour, *minute, 0) {
if let Some(ms) = pick_earlier_utc(tz, &naive) {
if ms > after_ms {
return Some(ms);
}
}
}
date = date.succ_opt()?;
}
None
}
Schedule::Weekly {
weekday,
hour,
minute,
} => {
let mut date = local_after.date_naive();
for _ in 0..400 {
if date.weekday() == *weekday {
if let Some(naive) = date.and_hms_opt(*hour, *minute, 0) {
if let Some(ms) = pick_earlier_utc(tz, &naive) {
if ms > after_ms {
return Some(ms);
}
}
}
}
date = date.succ_opt()?;
}
None
}
Schedule::Monthly { day, hour, minute } => {
let mut year = local_after.year();
let mut month = local_after.month();
for _ in 0..(12 * 20) {
if let Some(date) = NaiveDate::from_ymd_opt(year, month, *day) {
if let Some(naive) = date.and_hms_opt(*hour, *minute, 0) {
if let Some(ms) = pick_earlier_utc(tz, &naive) {
if ms > after_ms {
return Some(ms);
}
}
}
}
if month == 12 {
month = 1;
year += 1;
} else {
month += 1;
}
}
None
}
Schedule::At { datetime } => {
let ms = pick_earlier_utc(tz, datetime)?;
if ms > after_ms {
Some(ms)
} else {
None
}
}
}
}
fn pick_earlier_utc(tz: &Tz, naive: &NaiveDateTime) -> Option<u64> {
let dt = match tz.from_local_datetime(naive) {
MappedLocalTime::Single(dt) => dt,
MappedLocalTime::Ambiguous(earlier, _) => earlier,
MappedLocalTime::None => return None,
};
u64::try_from(dt.timestamp_millis()).ok()
}
#[cfg(test)]
mod tests {
use super::*;
fn tz_utc() -> Tz {
"UTC".parse().unwrap()
}
fn tz_tokyo() -> Tz {
"Asia/Tokyo".parse().unwrap()
}
fn tz_la() -> Tz {
"America/Los_Angeles".parse().unwrap()
}
fn utc_ms(y: i32, mo: u32, d: u32, h: u32, mi: u32) -> u64 {
chrono::Utc
.with_ymd_and_hms(y, mo, d, h, mi, 0)
.single()
.unwrap()
.timestamp_millis() as u64
}
#[test]
fn legacy_interval_is_rejected_with_migration_hint() {
for s in ["10s", "5m", "1h", "6h"] {
let err = parse_schedule(s).unwrap_err();
assert!(
err.contains("removed in 0.2.0"),
"'{s}' should name the migration: {err}"
);
assert!(
err.contains("@every 5m"),
"'{s}' should point at @every: {err}"
);
}
}
#[test]
fn non_at_sign_is_rejected() {
let err = parse_schedule("daily 09:00").unwrap_err();
assert!(err.contains("must start with '@'"), "{err}");
assert!(parse_schedule("").is_err());
assert!(parse_schedule("💾").is_err()); }
#[test]
fn parse_hourly_bare_is_minute_zero() {
assert_eq!(
parse_schedule("@hourly").unwrap(),
Schedule::Hourly { minutes: vec![0] }
);
assert_eq!(
parse_schedule(" @hourly ").unwrap(),
Schedule::Hourly { minutes: vec![0] }
);
}
#[test]
fn parse_hourly_with_minute() {
assert_eq!(
parse_schedule("@hourly :45").unwrap(),
Schedule::Hourly { minutes: vec![45] }
);
assert_eq!(
parse_schedule("@hourly :00").unwrap(),
Schedule::Hourly { minutes: vec![0] }
);
}
#[test]
fn parse_hourly_rejects_bad_args() {
assert!(parse_schedule("@hourly 45").is_err()); assert!(parse_schedule("@hourly :60").is_err());
assert!(parse_schedule("@hourly :xx").is_err());
}
#[test]
fn parse_hourly_rejects_comma_list() {
let err = parse_schedule("@hourly :00,:15,:45").unwrap_err();
assert!(err.contains("comma lists are not supported"), "{err}");
}
#[test]
fn parse_every_expands_to_minute_set() {
assert_eq!(
parse_schedule("@every 10m").unwrap(),
Schedule::Hourly {
minutes: vec![0, 10, 20, 30, 40, 50]
}
);
assert_eq!(
parse_schedule("@every 15m").unwrap(),
Schedule::Hourly {
minutes: vec![0, 15, 30, 45]
}
);
assert_eq!(
parse_schedule("@every 30m").unwrap(),
Schedule::Hourly {
minutes: vec![0, 30]
}
);
assert_eq!(
parse_schedule("@every 5m").unwrap(),
Schedule::Hourly {
minutes: (0..60).step_by(5).collect()
}
);
}
#[test]
fn parse_every_rejects_non_allowlisted() {
for s in ["@every 7m", "@every 6m", "@every 12m", "@every 60m"] {
let err = parse_schedule(s).unwrap_err();
assert!(err.contains("must be one of"), "'{s}': {err}");
}
assert!(parse_schedule("@every 4m").is_err());
assert!(parse_schedule("@every 1h").is_err()); assert!(parse_schedule("@every").is_err());
}
#[test]
fn parse_daily() {
assert_eq!(
parse_schedule("@daily 09:00").unwrap(),
Schedule::Daily { hour: 9, minute: 0 }
);
assert!(parse_schedule("@daily").is_err());
assert!(parse_schedule("@daily 25:00").is_err());
assert!(parse_schedule("@daily 09:99").is_err());
assert!(parse_schedule("@daily 9").is_err());
}
#[test]
fn parse_weekly() {
assert_eq!(
parse_schedule("@weekly MON 09:00").unwrap(),
Schedule::Weekly {
weekday: Weekday::Mon,
hour: 9,
minute: 0
}
);
assert!(parse_schedule("@weekly Mon 09:00").is_err()); assert!(parse_schedule("@weekly XYZ 09:00").is_err());
assert!(parse_schedule("@weekly MON").is_err());
}
#[test]
fn parse_monthly() {
assert_eq!(
parse_schedule("@monthly 15 09:00").unwrap(),
Schedule::Monthly {
day: 15,
hour: 9,
minute: 0
}
);
assert!(parse_schedule("@monthly 0 09:00").is_err());
assert!(parse_schedule("@monthly 32 09:00").is_err());
assert!(parse_schedule("@monthly 15").is_err());
}
#[test]
fn parse_at() {
match parse_schedule("@at 2026-08-01T18:30").unwrap() {
Schedule::At { datetime } => {
assert_eq!(datetime.year(), 2026);
assert_eq!(datetime.month(), 8);
assert_eq!(datetime.day(), 1);
assert_eq!(datetime.hour(), 18);
assert_eq!(datetime.minute(), 30);
}
other => panic!("unexpected: {other:?}"),
}
assert!(parse_schedule("@at").is_err());
assert!(parse_schedule("@at 2026-08-01 18:30").is_err()); assert!(parse_schedule("@at bogus").is_err());
}
#[test]
fn parse_unknown_keyword() {
assert!(parse_schedule("@yearly").is_err());
assert!(parse_schedule("@").is_err());
}
#[test]
fn hourly_utc() {
let spec = Schedule::Hourly { minutes: vec![0] };
let tz = tz_utc();
let after = utc_ms(2026, 3, 1, 12, 30);
assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 13, 0)
);
let after2 = utc_ms(2026, 3, 1, 13, 0);
assert_eq!(
next_scheduled_after(after2, &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 14, 0)
);
}
#[test]
fn hourly_with_minute_offset() {
let spec = Schedule::Hourly { minutes: vec![45] };
let tz = tz_utc();
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 30), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 12, 45)
);
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 45), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 13, 45)
);
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 50), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 13, 45)
);
}
#[test]
fn hourly_minute_set_walks_and_wraps() {
let spec = parse_schedule("@every 20m").unwrap(); let tz = tz_utc();
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 0), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 12, 20)
);
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 20), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 12, 40)
);
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 40), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 13, 0)
);
assert_eq!(
next_scheduled_after(utc_ms(2026, 3, 1, 12, 41), &spec, &tz).unwrap(),
utc_ms(2026, 3, 1, 13, 0)
);
}
#[test]
fn hourly_minute_set_generates_dense_sequence() {
let spec = parse_schedule("@every 30m").unwrap();
let tz = tz_utc();
let mut cursor = utc_ms(2026, 3, 1, 12, 0);
let mut generated = Vec::new();
for _ in 0..4 {
cursor = next_scheduled_after(cursor, &spec, &tz).unwrap();
generated.push(cursor);
}
assert_eq!(
generated,
vec![
utc_ms(2026, 3, 1, 12, 30),
utc_ms(2026, 3, 1, 13, 0),
utc_ms(2026, 3, 1, 13, 30),
utc_ms(2026, 3, 1, 14, 0),
]
);
}
#[test]
fn daily_tokyo_next_is_today() {
let spec = Schedule::Daily { hour: 9, minute: 0 };
let tz = tz_tokyo();
let after = utc_ms(2026, 7, 18, 23, 0); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 7, 19, 0, 0)
);
}
#[test]
fn daily_tokyo_missed_becomes_tomorrow() {
let spec = Schedule::Daily { hour: 9, minute: 0 };
let tz = tz_tokyo();
let after = utc_ms(2026, 7, 19, 1, 0); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 7, 20, 0, 0)
);
}
#[test]
fn weekly_next_monday() {
let spec = Schedule::Weekly {
weekday: Weekday::Mon,
hour: 9,
minute: 0,
};
let tz = tz_tokyo();
let after = utc_ms(2026, 7, 19, 1, 0); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 7, 20, 0, 0)
);
}
#[test]
fn monthly_skips_missing_day() {
let spec = Schedule::Monthly {
day: 31,
hour: 9,
minute: 0,
};
let tz = tz_tokyo();
let after = utc_ms(2026, 1, 31, 15, 0); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 3, 31, 0, 0)
);
}
#[test]
fn at_returns_target_when_future() {
let spec = Schedule::At {
datetime: NaiveDate::from_ymd_opt(2026, 8, 1)
.unwrap()
.and_hms_opt(18, 30, 0)
.unwrap(),
};
let tz = tz_tokyo();
let after = utc_ms(2026, 7, 19, 0, 0);
assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 8, 1, 9, 30)
);
}
#[test]
fn at_returns_none_when_past() {
let spec = Schedule::At {
datetime: NaiveDate::from_ymd_opt(2026, 7, 1)
.unwrap()
.and_hms_opt(18, 30, 0)
.unwrap(),
};
let tz = tz_tokyo();
assert!(next_scheduled_after(utc_ms(2026, 7, 19, 0, 0), &spec, &tz).is_none());
}
#[test]
fn dst_spring_forward_skips_nonexistent_time() {
let spec = Schedule::Daily {
hour: 2,
minute: 30,
};
let tz = tz_la();
let after = utc_ms(2026, 3, 8, 7, 0); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 3, 9, 9, 30)
);
}
#[test]
fn dst_spring_forward_skips_missing_hour_for_hourly() {
let spec = Schedule::Hourly { minutes: vec![0] };
let tz = tz_la();
let after = utc_ms(2026, 3, 8, 9, 0);
assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 3, 8, 10, 0)
);
}
#[test]
fn dst_fall_back_fires_earlier_occurrence() {
let spec = Schedule::Daily {
hour: 1,
minute: 30,
};
let tz = tz_la();
let after = utc_ms(2026, 11, 1, 6, 0); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 11, 1, 8, 30)
);
}
#[test]
fn dst_fall_back_second_occurrence_is_skipped() {
let spec = Schedule::Daily {
hour: 1,
minute: 30,
};
let tz = tz_la();
let after = utc_ms(2026, 11, 1, 8, 30); assert_eq!(
next_scheduled_after(after, &spec, &tz).unwrap(),
utc_ms(2026, 11, 2, 9, 30)
);
}
#[test]
fn at_spring_forward_never_fires() {
let spec = Schedule::At {
datetime: NaiveDate::from_ymd_opt(2026, 3, 8)
.unwrap()
.and_hms_opt(2, 30, 0)
.unwrap(),
};
let tz = tz_la();
assert!(next_scheduled_after(utc_ms(2026, 3, 1, 0, 0), &spec, &tz).is_none());
}
#[test]
fn resolve_tz_explicit() {
assert_eq!(
resolve_tz(Some("Asia/Tokyo")).unwrap(),
chrono_tz::Asia::Tokyo
);
}
#[test]
fn resolve_tz_rejects_bogus() {
assert!(resolve_tz(Some("Not/A_Zone")).is_err());
}
#[test]
fn resolve_tz_respects_tz_env() {
let saved = std::env::var("TZ").ok();
unsafe { std::env::set_var("TZ", "Asia/Tokyo") };
let tz = resolve_tz(None).unwrap();
assert_eq!(tz, chrono_tz::Asia::Tokyo);
match saved {
Some(v) => unsafe { std::env::set_var("TZ", v) },
None => unsafe { std::env::remove_var("TZ") },
}
}
}