| 1 | //! When each entry of the dependency update file is checked: its |
| 2 | //! `schedule` (`interval`, `day`, `time`, `timezone`, `cronjob`), worked |
| 3 | //! out in the entry's time zone. Without a `time`, a time of day is picked |
| 4 | //! for the repository and kept, so that checks do not all start at once. |
| 5 | |
| 6 | use g1t_actions::cron; |
| 7 | |
| 8 | use crate::timezones; |
| 9 | |
| 10 | const MINUTE_MS: i64 = 60_000; |
| 11 | const DAY_MS: i64 = 86_400_000; |
| 12 | /// How far ahead a next run is looked for: a yearly schedule's is within it. |
| 13 | const HORIZON_DAYS: i64 = 400; |
| 14 | |
| 15 | /// `schedule.interval`. |
| 16 | #[derive(Clone, Copy, Debug, PartialEq, Eq)] |
| 17 | pub enum Interval { |
| 18 | /// Every weekday, Monday to Friday. |
| 19 | Daily, |
| 20 | /// Once a week, on `day` (Monday by default). |
| 21 | Weekly, |
| 22 | /// The first day of each month. |
| 23 | Monthly, |
| 24 | /// The first day of January, April, July and October. |
| 25 | Quarterly, |
| 26 | /// The first day of January and July. |
| 27 | Semiannually, |
| 28 | /// The first day of January. |
| 29 | Yearly, |
| 30 | /// When `cronjob` says. |
| 31 | Cron, |
| 32 | } |
| 33 | |
| 34 | impl Interval { |
| 35 | pub const ALL: [Interval; 7] = [ |
| 36 | Interval::Daily, |
| 37 | Interval::Weekly, |
| 38 | Interval::Monthly, |
| 39 | Interval::Quarterly, |
| 40 | Interval::Semiannually, |
| 41 | Interval::Yearly, |
| 42 | Interval::Cron, |
| 43 | ]; |
| 44 | |
| 45 | pub fn as_str(self) -> &'static str { |
| 46 | match self { |
| 47 | Interval::Daily => "daily", |
| 48 | Interval::Weekly => "weekly", |
| 49 | Interval::Monthly => "monthly", |
| 50 | Interval::Quarterly => "quarterly", |
| 51 | Interval::Semiannually => "semiannually", |
| 52 | Interval::Yearly => "yearly", |
| 53 | Interval::Cron => "cron", |
| 54 | } |
| 55 | } |
| 56 | |
| 57 | pub fn parse(text: &str) -> Option<Interval> { |
| 58 | Interval::ALL.into_iter().find(|interval| interval.as_str() == text) |
| 59 | } |
| 60 | } |
| 61 | |
| 62 | /// `schedule.day`, Sunday first, as cron counts. |
| 63 | pub const WEEKDAYS: [&str; 7] = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"]; |
| 64 | |
| 65 | /// A `schedule`, read and checked. |
| 66 | #[derive(Clone, Debug, PartialEq, Eq)] |
| 67 | pub struct Schedule { |
| 68 | pub interval: Interval, |
| 69 | /// 0 for Sunday to 6 for Saturday. |
| 70 | pub day: Option<u32>, |
| 71 | /// Hours and minutes. |
| 72 | pub time: Option<(u32, u32)>, |
| 73 | /// An IANA zone name; UTC when absent. |
| 74 | pub timezone: Option<String>, |
| 75 | /// For `cron`: five fields, read from `cronjob`. |
| 76 | pub cron: Option<String>, |
| 77 | } |
| 78 | |
| 79 | /// Days counted from 1970-01-01 to a date (Howard Hinnant's algorithm). |
| 80 | pub fn days_from_civil(year: i64, month: u32, day: u32) -> i64 { |
| 81 | let y = if month <= 2 { year - 1 } else { year }; |
| 82 | let era = y.div_euclid(400); |
| 83 | let yoe = y - era * 400; |
| 84 | let m = i64::from(month); |
| 85 | let doy = (153 * (if m > 2 { m - 3 } else { m + 9 }) + 2) / 5 + i64::from(day) - 1; |
| 86 | let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; |
| 87 | era * 146_097 + doe - 719_468 |
| 88 | } |
| 89 | |
| 90 | /// The date of a day counted from 1970-01-01. |
| 91 | pub fn civil_from_days(days: i64) -> (i64, u32, u32) { |
| 92 | let z = days + 719_468; |
| 93 | let era = z.div_euclid(146_097); |
| 94 | let doe = z.rem_euclid(146_097); |
| 95 | let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; |
| 96 | let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); |
| 97 | let mp = (5 * doy + 2) / 153; |
| 98 | let day = (doy - (153 * mp + 2) / 5 + 1) as u32; |
| 99 | let month = if mp < 10 { mp + 3 } else { mp - 9 } as u32; |
| 100 | (yoe + era * 400 + i64::from(month <= 2), month, day) |
| 101 | } |
| 102 | |
| 103 | /// 0 for Sunday. |
| 104 | fn weekday(days: i64) -> u32 { |
| 105 | (days + 4).rem_euclid(7) as u32 |
| 106 | } |
| 107 | |
| 108 | /// `hh:mm`, 00:00 to 23:59. |
| 109 | pub fn parse_time(text: &str) -> Option<(u32, u32)> { |
| 110 | let (hours, minutes) = text.trim().split_once(':')?; |
| 111 | if hours.len() != 2 || minutes.len() != 2 { |
| 112 | return None; |
| 113 | } |
| 114 | let (hours, minutes) = (hours.parse::<u32>().ok()?, minutes.parse::<u32>().ok()?); |
| 115 | (hours < 24 && minutes < 60).then_some((hours, minutes)) |
| 116 | } |
| 117 | |
| 118 | /// A time of day said the way people say it: `5pm`, `5:30 pm`, `17:00`, |
| 119 | /// `noon`, `midnight`. |
| 120 | fn spoken_time(text: &str) -> Option<(u32, u32)> { |
| 121 | let text = text.trim(); |
| 122 | match text { |
| 123 | "noon" => return Some((12, 0)), |
| 124 | "midnight" => return Some((0, 0)), |
| 125 | _ => {} |
| 126 | } |
| 127 | let (clock, half) = if let Some(clock) = text.strip_suffix("am") { |
| 128 | (clock.trim(), Some(false)) |
| 129 | } else if let Some(clock) = text.strip_suffix("pm") { |
| 130 | (clock.trim(), Some(true)) |
| 131 | } else { |
| 132 | (text, None) |
| 133 | }; |
| 134 | let (hours, minutes) = match clock.split_once(':') { |
| 135 | Some((hours, minutes)) if minutes.len() == 2 => (hours.parse::<u32>().ok()?, minutes.parse::<u32>().ok()?), |
| 136 | Some(_) => return None, |
| 137 | None => (clock.parse::<u32>().ok()?, 0), |
| 138 | }; |
| 139 | if minutes > 59 { |
| 140 | return None; |
| 141 | } |
| 142 | let hours = match half { |
| 143 | Some(pm) if (1..=12).contains(&hours) => hours % 12 + if pm { 12 } else { 0 }, |
| 144 | Some(_) => return None, |
| 145 | None if hours < 24 && clock.contains(':') => hours, |
| 146 | None => return None, |
| 147 | }; |
| 148 | Some((hours, minutes)) |
| 149 | } |
| 150 | |
| 151 | /// `cronjob` as five cron fields: a cron expression as it is, or one of |
| 152 | /// the natural forms: `every day at 5pm`, `every weekday at 9:30am`, |
| 153 | /// `every monday at 09:00`, `every hour`, `every 6 hours`. |
| 154 | pub fn cronjob(text: &str) -> Result<String, String> { |
| 155 | let text = text.trim(); |
| 156 | if text.split_whitespace().count() == 5 { |
| 157 | return cron::Schedule::parse(text).map(|_| text.split_whitespace().collect::<Vec<_>>().join(" ")); |
| 158 | } |
| 159 | let lower = text.to_lowercase(); |
| 160 | let words: Vec<&str> = lower.split_whitespace().collect(); |
| 161 | let unclear = || format!("`{text}` is neither a cron expression, such as `0 9 * * 1`, nor a schedule g1t reads, such as `every day at 5pm`."); |
| 162 | let Some(("every", rest)) = words.split_first().map(|(first, rest)| (*first, rest)) else { |
| 163 | return Err(unclear()); |
| 164 | }; |
| 165 | match rest { |
| 166 | ["hour"] => return Ok("0 * * * *".to_owned()), |
| 167 | [n, "hours"] => { |
| 168 | let n: u32 = n.parse().map_err(|_| unclear())?; |
| 169 | if !(1..=23).contains(&n) { |
| 170 | return Err(unclear()); |
| 171 | } |
| 172 | return Ok(format!("0 */{n} * * *")); |
| 173 | } |
| 174 | _ => {} |
| 175 | } |
| 176 | let at = rest.iter().position(|word| *word == "at").ok_or_else(unclear)?; |
| 177 | let (when, time) = (&rest[..at], rest[at + 1..].join(" ")); |
| 178 | let (hours, minutes) = spoken_time(&time).ok_or_else(unclear)?; |
| 179 | let days = match when { |
| 180 | ["day"] => "*".to_owned(), |
| 181 | ["weekday"] => "1-5".to_owned(), |
| 182 | [name] => { |
| 183 | let name = name.strip_suffix('s').filter(|bare| WEEKDAYS.contains(bare)).unwrap_or(name); |
| 184 | WEEKDAYS.iter().position(|day| *day == name).ok_or_else(unclear)?.to_string() |
| 185 | } |
| 186 | _ => return Err(unclear()), |
| 187 | }; |
| 188 | Ok(format!("{minutes} {hours} * * {days}")) |
| 189 | } |
| 190 | |
| 191 | /// The time of day a schedule without `time` runs at, picked from `seed` |
| 192 | /// (the repository and entry) so it stays the same. |
| 193 | pub fn default_time(seed: &str) -> (u32, u32) { |
| 194 | // FNV-1a. |
| 195 | let mut hash: u32 = 0x811c_9dc5; |
| 196 | for byte in seed.bytes() { |
| 197 | hash ^= u32::from(byte); |
| 198 | hash = hash.wrapping_mul(0x0100_0193); |
| 199 | } |
| 200 | let minute = hash % (24 * 60); |
| 201 | (minute / 60, minute % 60) |
| 202 | } |
| 203 | |
| 204 | /// UTC milliseconds for a local time in `zone`. |
| 205 | fn to_utc(zone: &str, local: i64) -> i64 { |
| 206 | let guess = local - i64::from(timezones::offset_minutes(zone, local.max(0) as u64)) * MINUTE_MS; |
| 207 | local - i64::from(timezones::offset_minutes(zone, guess.max(0) as u64)) * MINUTE_MS |
| 208 | } |
| 209 | |
| 210 | impl Schedule { |
| 211 | fn zone(&self) -> &str { |
| 212 | self.timezone.as_deref().unwrap_or("UTC") |
| 213 | } |
| 214 | |
| 215 | fn runs_on(&self, days: i64) -> bool { |
| 216 | let (_, month, day) = civil_from_days(days); |
| 217 | match self.interval { |
| 218 | Interval::Daily => (1..=5).contains(&weekday(days)), |
| 219 | Interval::Weekly => weekday(days) == self.day.unwrap_or(1), |
| 220 | Interval::Monthly => day == 1, |
| 221 | Interval::Quarterly => day == 1 && matches!(month, 1 | 4 | 7 | 10), |
| 222 | Interval::Semiannually => day == 1 && matches!(month, 1 | 7), |
| 223 | Interval::Yearly => day == 1 && month == 1, |
| 224 | Interval::Cron => false, |
| 225 | } |
| 226 | } |
| 227 | |
| 228 | /// The first time after `after_ms` the entry runs, in UTC |
| 229 | /// milliseconds. `seed` picks the time of day when `time` is absent. |
| 230 | pub fn next_run(&self, after_ms: u64, seed: &str) -> Option<u64> { |
| 231 | let after = after_ms as i64; |
| 232 | let zone = self.zone(); |
| 233 | let local_now = after + i64::from(timezones::offset_minutes(zone, after_ms)) * MINUTE_MS; |
| 234 | if self.interval == Interval::Cron { |
| 235 | let schedule = cron::Schedule::parse(self.cron.as_deref()?).ok()?; |
| 236 | let mut local = (local_now.div_euclid(MINUTE_MS) + 1) * MINUTE_MS; |
| 237 | let end = local + HORIZON_DAYS * DAY_MS; |
| 238 | while local < end { |
| 239 | if schedule.fires_at(local as u64) { |
| 240 | let utc = to_utc(zone, local); |
| 241 | if utc > after { |
| 242 | return Some(utc as u64); |
| 243 | } |
| 244 | } |
| 245 | local += MINUTE_MS; |
| 246 | } |
| 247 | return None; |
| 248 | } |
| 249 | let (hours, minutes) = self.time.unwrap_or_else(|| default_time(seed)); |
| 250 | let today = local_now.div_euclid(DAY_MS); |
| 251 | (today - 1..today + HORIZON_DAYS).find_map(|days| { |
| 252 | if !self.runs_on(days) { |
| 253 | return None; |
| 254 | } |
| 255 | let utc = to_utc(zone, days * DAY_MS + i64::from(hours) * 3_600_000 + i64::from(minutes) * MINUTE_MS); |
| 256 | (utc > after).then_some(utc as u64) |
| 257 | }) |
| 258 | } |
| 259 | |
| 260 | /// The schedule in words: "Weekdays at 05:00 (UTC)". |
| 261 | pub fn describe(&self, seed: &str) -> String { |
| 262 | let zone = self.zone(); |
| 263 | if self.interval == Interval::Cron { |
| 264 | return format!("Cron `{}` ({zone})", self.cron.as_deref().unwrap_or_default()); |
| 265 | } |
| 266 | let (hours, minutes) = self.time.unwrap_or_else(|| default_time(seed)); |
| 267 | let at = format!("{hours:02}:{minutes:02} ({zone})"); |
| 268 | let picked = if self.time.is_none() { ", a time picked for this repository" } else { "" }; |
| 269 | let when = match self.interval { |
| 270 | Interval::Daily => "Weekdays".to_owned(), |
| 271 | Interval::Weekly => { |
| 272 | let day = WEEKDAYS[self.day.unwrap_or(1) as usize]; |
| 273 | format!("{}{}s", day[..1].to_uppercase(), &day[1..]) |
| 274 | } |
| 275 | Interval::Monthly => "The 1st of each month".to_owned(), |
| 276 | Interval::Quarterly => "The 1st of January, April, July and October".to_owned(), |
| 277 | Interval::Semiannually => "The 1st of January and July".to_owned(), |
| 278 | Interval::Yearly => "January 1st".to_owned(), |
| 279 | Interval::Cron => unreachable!(), |
| 280 | }; |
| 281 | format!("{when} at {at}{picked}") |
| 282 | } |
| 283 | } |
| 284 | |
| 285 | #[cfg(test)] |
| 286 | mod tests { |
| 287 | use super::*; |
| 288 | use g1t_contracts::time::{parse_rfc3339, rfc3339}; |
| 289 | |
| 290 | fn at(text: &str) -> u64 { |
| 291 | parse_rfc3339(text).unwrap() |
| 292 | } |
| 293 | |
| 294 | fn schedule(interval: Interval) -> Schedule { |
| 295 | Schedule { interval, day: None, time: Some((5, 0)), timezone: None, cron: None } |
| 296 | } |
| 297 | |
| 298 | fn next(schedule: &Schedule, after: &str) -> String { |
| 299 | rfc3339(schedule.next_run(at(after), "seed").unwrap()) |
| 300 | } |
| 301 | |
| 302 | #[test] |
| 303 | fn dates_round_trip() { |
| 304 | for days in [-1000, 0, 19_000, 20_733, 60_000] { |
| 305 | let (y, m, d) = civil_from_days(days); |
| 306 | assert_eq!(days_from_civil(y, m, d), days); |
| 307 | } |
| 308 | assert_eq!(civil_from_days(days_from_civil(2026, 10, 7)), (2026, 10, 7)); |
| 309 | // 2026-10-07 is a Wednesday. |
| 310 | assert_eq!(weekday(days_from_civil(2026, 10, 7)), 3); |
| 311 | } |
| 312 | |
| 313 | #[test] |
| 314 | fn daily_runs_on_weekdays() { |
| 315 | let daily = schedule(Interval::Daily); |
| 316 | // Wednesday 04:00 runs at 05:00 the same day; 06:00 runs Thursday. |
| 317 | assert_eq!(next(&daily, "2026-10-07T04:00:00Z"), "2026-10-07T05:00:00.000Z"); |
| 318 | assert_eq!(next(&daily, "2026-10-07T06:00:00Z"), "2026-10-08T05:00:00.000Z"); |
| 319 | // Friday evening goes to Monday. |
| 320 | assert_eq!(next(&daily, "2026-10-09T06:00:00Z"), "2026-10-12T05:00:00.000Z"); |
| 321 | } |
| 322 | |
| 323 | #[test] |
| 324 | fn weekly_monthly_and_longer() { |
| 325 | let mut weekly = schedule(Interval::Weekly); |
| 326 | assert_eq!(next(&weekly, "2026-10-07T00:00:00Z"), "2026-10-12T05:00:00.000Z"); |
| 327 | weekly.day = Some(5); |
| 328 | assert_eq!(next(&weekly, "2026-10-07T00:00:00Z"), "2026-10-09T05:00:00.000Z"); |
| 329 | assert_eq!(next(&schedule(Interval::Monthly), "2026-10-07T00:00:00Z"), "2026-11-01T05:00:00.000Z"); |
| 330 | assert_eq!(next(&schedule(Interval::Quarterly), "2026-10-07T00:00:00Z"), "2027-01-01T05:00:00.000Z"); |
| 331 | assert_eq!(next(&schedule(Interval::Quarterly), "2026-02-07T00:00:00Z"), "2026-04-01T05:00:00.000Z"); |
| 332 | assert_eq!(next(&schedule(Interval::Semiannually), "2026-02-07T00:00:00Z"), "2026-07-01T05:00:00.000Z"); |
| 333 | assert_eq!(next(&schedule(Interval::Yearly), "2026-02-07T00:00:00Z"), "2027-01-01T05:00:00.000Z"); |
| 334 | } |
| 335 | |
| 336 | #[test] |
| 337 | fn time_zones_move_the_hour_with_daylight_saving() { |
| 338 | let mut daily = schedule(Interval::Daily); |
| 339 | daily.time = Some((9, 30)); |
| 340 | daily.timezone = Some("America/New_York".into()); |
| 341 | // Summer: 09:30 EDT is 13:30 UTC; winter: 14:30 UTC. |
| 342 | assert_eq!(next(&daily, "2026-07-01T00:00:00Z"), "2026-07-01T13:30:00.000Z"); |
| 343 | assert_eq!(next(&daily, "2026-12-01T00:00:00Z"), "2026-12-01T14:30:00.000Z"); |
| 344 | // Late in the UTC day it is still the same local day. |
| 345 | assert_eq!(next(&daily, "2026-07-01T03:00:00Z"), "2026-07-01T13:30:00.000Z"); |
| 346 | let mut tokyo = schedule(Interval::Weekly); |
| 347 | tokyo.time = Some((8, 0)); |
| 348 | tokyo.timezone = Some("Asia/Tokyo".into()); |
| 349 | // Monday 08:00 in Tokyo is Sunday 23:00 UTC. |
| 350 | assert_eq!(next(&tokyo, "2026-10-07T00:00:00Z"), "2026-10-11T23:00:00.000Z"); |
| 351 | } |
| 352 | |
| 353 | #[test] |
| 354 | fn cron_runs_in_its_zone() { |
| 355 | let mut cron = schedule(Interval::Cron); |
| 356 | cron.cron = Some("0 9 * * 1-5".into()); |
| 357 | assert_eq!(next(&cron, "2026-10-07T09:00:00Z"), "2026-10-08T09:00:00.000Z"); |
| 358 | cron.timezone = Some("America/New_York".into()); |
| 359 | assert_eq!(next(&cron, "2026-10-07T00:00:00Z"), "2026-10-07T13:00:00.000Z"); |
| 360 | cron.cron = Some("30 2 1 1 *".into()); |
| 361 | assert_eq!(next(&cron, "2026-10-07T00:00:00Z"), "2027-01-01T07:30:00.000Z"); |
| 362 | } |
| 363 | |
| 364 | #[test] |
| 365 | fn without_a_time_one_is_picked_and_kept() { |
| 366 | let mut daily = schedule(Interval::Daily); |
| 367 | daily.time = None; |
| 368 | let (hours, minutes) = default_time("rep_1:npm:/"); |
| 369 | assert!(hours < 24 && minutes < 60); |
| 370 | assert_eq!(default_time("rep_1:npm:/"), (hours, minutes)); |
| 371 | assert_ne!(default_time("rep_1:npm:/"), default_time("rep_2:npm:/")); |
| 372 | assert!(daily.describe("rep_1:npm:/").contains("a time picked for this repository")); |
| 373 | } |
| 374 | |
| 375 | #[test] |
| 376 | fn cronjobs_take_cron_or_words() { |
| 377 | assert_eq!(cronjob("0 9 * * *").unwrap(), "0 9 * * *"); |
| 378 | assert_eq!(cronjob("every day at 5pm").unwrap(), "0 17 * * *"); |
| 379 | assert_eq!(cronjob("every weekday at 9:30am").unwrap(), "30 9 * * 1-5"); |
| 380 | assert_eq!(cronjob("Every Monday at 09:00").unwrap(), "0 9 * * 1"); |
| 381 | assert_eq!(cronjob("every fridays at noon").unwrap(), "0 12 * * 5"); |
| 382 | assert_eq!(cronjob("every 6 hours").unwrap(), "0 */6 * * *"); |
| 383 | assert_eq!(cronjob("every hour").unwrap(), "0 * * * *"); |
| 384 | assert!(cronjob("0 9 * *").unwrap_err().contains("neither a cron expression")); |
| 385 | assert!(cronjob("61 9 * * *").is_err()); |
| 386 | assert!(cronjob("every day at 25pm").is_err()); |
| 387 | assert!(cronjob("sometimes").is_err()); |
| 388 | } |
| 389 | |
| 390 | #[test] |
| 391 | fn times_and_words() { |
| 392 | assert_eq!(parse_time("03:00"), Some((3, 0))); |
| 393 | assert_eq!(parse_time("23:59"), Some((23, 59))); |
| 394 | assert_eq!(parse_time("24:00"), None); |
| 395 | assert_eq!(parse_time("3:00"), None); |
| 396 | let mut weekly = schedule(Interval::Weekly); |
| 397 | weekly.day = Some(0); |
| 398 | assert_eq!(weekly.describe("x"), "Sundays at 05:00 (UTC)"); |
| 399 | assert_eq!(schedule(Interval::Daily).describe("x"), "Weekdays at 05:00 (UTC)"); |
| 400 | let mut cron = schedule(Interval::Cron); |
| 401 | cron.cron = Some("0 9 * * *".into()); |
| 402 | cron.timezone = Some("Europe/London".into()); |
| 403 | assert_eq!(cron.describe("x"), "Cron `0 9 * * *` (Europe/London)"); |
| 404 | } |
| 405 | } |