using System.Diagnostics.CodeAnalysis; using System.Globalization; using System.Text; namespace Chronos.Data.Scheduling; /// The shape of a . public enum RecurrenceKind { /// A fixed interval: every n minutes, hours or days. Every, /// Every day at a wall-clock time. Daily, /// On some days of the week at a wall-clock time. Weekly, /// On one day of the month (1–28) at a wall-clock time. Monthly, } /// Unit of an interval. public enum RecurrenceUnit { Minutes, Hours, Days, } /// /// When a schedule fires (owner review 2, R10), in an in-house text form instead of cron: every:<n>m|h|d /// (at least 5 minutes), daily:HH:MM, weekly:mon,tue,…@HH:MM and monthly:<1–28>@HH:MM. /// Intervals are fixed durations anchored to the previous due time, so they never drift and the occurrences missed meanwhile /// collapse into one; days of an interval are 24 hours, whatever the clocks do. Daily, weekly and monthly times are wall-clock /// times of the host's zone: a time a spring-forward gap skips moves forward by the gap (02:30 becomes 03:30), and a time the /// clocks go back over happens once, at its first occurrence. Instances compare by value. /// public sealed record ScheduleRecurrence { /// The shortest interval: a schedule never fires more than every 5 minutes. public const int MinMinutes = 5; public const int MaxMinutes = 24 * 60; public const int MaxHours = 7 * 24; public const int MaxDays = 366; /// The last day a monthly schedule can name: every month has it. public const int MaxDayOfMonth = 28; /// Wire names of the days, Monday first, as the text form and the API write them. public static IReadOnlyList DayNames { get; } = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]; private static readonly DayOfWeek[] WeekOrder = [DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Wednesday, DayOfWeek.Thursday, DayOfWeek.Friday, DayOfWeek.Saturday, DayOfWeek.Sunday]; /// Bit 1 << (int)DayOfWeek per weekly day; a field, so equality compares the days. private readonly int _days; private ScheduleRecurrence(RecurrenceKind kind, int every, RecurrenceUnit unit, TimeOnly time, int days, int dayOfMonth) { Kind = kind; Every = every; Unit = unit; Time = time; _days = days; DayOfMonth = dayOfMonth; } public RecurrenceKind Kind { get; } /// The interval's count of ; 0 for the other kinds. public int Every { get; } /// The interval's unit ( only). public RecurrenceUnit Unit { get; } /// Wall-clock time of a daily, weekly or monthly schedule, to the minute; midnight for an interval. public TimeOnly Time { get; } /// The days of a weekly schedule, Monday first; empty for the other kinds. public IReadOnlyList Days => [.. WeekOrder.Where(d => (_days & Bit(d)) != 0)]; /// Day of the month of a monthly schedule (1–28); 0 for the other kinds. public int DayOfMonth { get; } /// /// The longest time between two occurrences: the interval, a day, a week, or 31 days for a monthly schedule. A next run /// further away than two of them means the clock went back, and the next run is computed again. /// public TimeSpan Period => Kind switch { RecurrenceKind.Every => Unit switch { RecurrenceUnit.Minutes => TimeSpan.FromMinutes(Every), RecurrenceUnit.Hours => TimeSpan.FromHours(Every), _ => TimeSpan.FromDays(Every), }, RecurrenceKind.Daily => TimeSpan.FromDays(1), RecurrenceKind.Weekly => TimeSpan.FromDays(7), _ => TimeSpan.FromDays(31), }; /// Every (at least minutes). /// The interval is shorter than 5 minutes or longer than its unit allows. public static ScheduleRecurrence Interval(int every, RecurrenceUnit unit) { var (min, max) = unit switch { RecurrenceUnit.Minutes => (MinMinutes, MaxMinutes), RecurrenceUnit.Hours => (1, MaxHours), RecurrenceUnit.Days => (1, MaxDays), _ => throw new ArgumentOutOfRangeException(nameof(unit), unit, "Unknown unit."), }; ArgumentOutOfRangeException.ThrowIfLessThan(every, min); ArgumentOutOfRangeException.ThrowIfGreaterThan(every, max); return new ScheduleRecurrence(RecurrenceKind.Every, every, unit, default, 0, 0); } /// Every day at (seconds are dropped). public static ScheduleRecurrence DailyAt(TimeOnly time) => new(RecurrenceKind.Daily, 0, default, Minute(time), 0, 0); /// On at . /// No day given. public static ScheduleRecurrence WeeklyAt(IEnumerable days, TimeOnly time) { ArgumentNullException.ThrowIfNull(days); var mask = 0; foreach (var day in days) { if (!Enum.IsDefined(day)) throw new ArgumentOutOfRangeException(nameof(days), day, "Unknown day."); mask |= Bit(day); } if (mask == 0) throw new ArgumentException("A weekly schedule needs at least one day.", nameof(days)); return new ScheduleRecurrence(RecurrenceKind.Weekly, 0, default, Minute(time), mask, 0); } /// On day (1–28) of every month at . public static ScheduleRecurrence MonthlyAt(int dayOfMonth, TimeOnly time) { ArgumentOutOfRangeException.ThrowIfLessThan(dayOfMonth, 1); ArgumentOutOfRangeException.ThrowIfGreaterThan(dayOfMonth, MaxDayOfMonth); return new ScheduleRecurrence(RecurrenceKind.Monthly, 0, default, Minute(time), 0, dayOfMonth); } /// The recurrence written as (any case, spaces around parts allowed). /// The text is not a valid recurrence. public static ScheduleRecurrence Parse(string text) => TryParse(text, out var recurrence) ? recurrence : throw new FormatException($"'{text}' is not a schedule recurrence."); /// Parses the text form; false for anything else, values out of range included. public static bool TryParse([NotNullWhen(true)] string? text, [NotNullWhen(true)] out ScheduleRecurrence? recurrence) { recurrence = null; if (string.IsNullOrWhiteSpace(text)) return false; var colon = text.IndexOf(':', StringComparison.Ordinal); if (colon <= 0) return false; var kind = text[..colon].Trim().ToLowerInvariant(); var rest = text[(colon + 1)..].Trim(); try { recurrence = kind switch { "every" => ParseInterval(rest), "daily" => TryTime(rest, out var time) ? DailyAt(time) : null, "weekly" => ParseWeekly(rest), "monthly" => ParseMonthly(rest), _ => null, }; } catch (ArgumentException) { // A value out of range (every:4m, monthly:29@…). recurrence = null; } return recurrence is not null; } /// The canonical text form: every:10m, daily:03:00, weekly:mon,thu@02:30, monthly:1@04:00. public string Format() { var time = Time.ToString("HH:mm", CultureInfo.InvariantCulture); return Kind switch { RecurrenceKind.Every => string.Create(CultureInfo.InvariantCulture, $"every:{Every}{Unit switch { RecurrenceUnit.Minutes => 'm', RecurrenceUnit.Hours => 'h', _ => 'd' }}"), RecurrenceKind.Daily => "daily:" + time, RecurrenceKind.Weekly => new StringBuilder("weekly:").AppendJoin(',', Days.Select(DayName)).Append('@').Append(time).ToString(), _ => string.Create(CultureInfo.InvariantCulture, $"monthly:{DayOfMonth}@{time}"), }; } public override string ToString() => Format(); /// The wire name of : mon … sun. public static string DayName(DayOfWeek day) => DayNames[Array.IndexOf(WeekOrder, day)]; /// The day named (, any case); false for anything else. public static bool TryParseDay(string? name, out DayOfWeek day) { var index = IndexOfDay(name); day = index < 0 ? default : WeekOrder[index]; return index >= 0; } /// /// The first occurrence strictly after , in UTC and to the minute. An interval is laid on the /// grid of (the previous due time: no drift, missed occurrences collapse into the next one), /// or starts one interval after 's minute without an anchor. Daily, weekly and monthly times /// are read in (see the type's remarks for clock changes); they need no anchor. /// public DateTimeOffset Next(DateTimeOffset afterUtc, TimeZoneInfo zone, DateTimeOffset? anchorUtc = null) { ArgumentNullException.ThrowIfNull(zone); var after = afterUtc.ToUniversalTime(); if (Kind == RecurrenceKind.Every) { var period = Period.Ticks; if (anchorUtc is not { } anchor) return Truncate(after) + Period; var behind = after.UtcTicks - anchor.UtcTicks; var steps = behind / period; if (behind % period != 0 && behind < 0) steps--; return new DateTimeOffset(anchor.UtcTicks + (steps + 1) * period, TimeSpan.Zero); } var local = DateOnly.FromDateTime(TimeZoneInfo.ConvertTime(after, zone).DateTime); // From the day before: a time a gap moves forward can land after a later midnight. for (var i = -1; i <= 400; i++) { var day = local.AddDays(i); if (!Matches(day)) continue; var at = ToUtc(day.ToDateTime(Time), zone); if (at > after) return at; } throw new InvalidOperationException($"No occurrence of {Format()} within a year."); } /// /// The UTC instant of the wall-clock time in : a time inside a /// spring-forward gap moves forward by the gap, an ambiguous one takes its first occurrence (still on the larger offset). /// public static DateTimeOffset ToUtc(DateTime local, TimeZoneInfo zone) { ArgumentNullException.ThrowIfNull(zone); local = DateTime.SpecifyKind(local, DateTimeKind.Unspecified); TimeSpan offset; if (zone.IsInvalidTime(local)) offset = zone.GetUtcOffset(local.AddHours(-12)); else if (zone.IsAmbiguousTime(local)) offset = zone.GetAmbiguousTimeOffsets(local).Max(); else offset = zone.GetUtcOffset(local); return new DateTimeOffset(local.Ticks - offset.Ticks, TimeSpan.Zero); } /// 10m, 6h, 7d; null for anything else. private static ScheduleRecurrence? ParseInterval(string text) { if (text.Length < 2) return null; RecurrenceUnit? unit = char.ToLowerInvariant(text[^1]) switch { 'm' => RecurrenceUnit.Minutes, 'h' => RecurrenceUnit.Hours, 'd' => RecurrenceUnit.Days, _ => null, }; return unit is { } u && TryNumber(text[..^1], out var every) ? Interval(every, u) : null; } /// mon,thu@02:30; null for anything else. private static ScheduleRecurrence? ParseWeekly(string text) { var at = text.LastIndexOf('@'); if (at <= 0 || !TryTime(text[(at + 1)..], out var time)) return null; var days = new List(); foreach (var name in text[..at].Split(',')) { if (!TryParseDay(name.Trim(), out var day)) return null; days.Add(day); } return WeeklyAt(days, time); } /// 1@04:00; null for anything else. private static ScheduleRecurrence? ParseMonthly(string text) { var at = text.LastIndexOf('@'); return at > 0 && TryNumber(text[..at], out var day) && TryTime(text[(at + 1)..], out var time) ? MonthlyAt(day, time) : null; } private bool Matches(DateOnly day) => Kind switch { RecurrenceKind.Daily => true, RecurrenceKind.Weekly => (_days & Bit(day.DayOfWeek)) != 0, _ => day.Day == DayOfMonth, }; private static int Bit(DayOfWeek day) => 1 << (int)day; private static TimeOnly Minute(TimeOnly time) => new(time.Hour, time.Minute); private static DateTimeOffset Truncate(DateTimeOffset utc) => new(utc.UtcTicks - utc.UtcTicks % TimeSpan.TicksPerMinute, TimeSpan.Zero); private static int IndexOfDay(string? name) { for (var i = 0; i < DayNames.Count; i++) { if (string.Equals(DayNames[i], name, StringComparison.OrdinalIgnoreCase)) return i; } return -1; } private static bool TryNumber(string text, out int value) => int.TryParse(text.Trim(), NumberStyles.None, CultureInfo.InvariantCulture, out value); private static bool TryTime(string text, out TimeOnly time) { time = default; var parts = text.Trim().Split(':'); if (parts is not [var h, var m] || h.Length is < 1 or > 2 || m.Length != 2 || !TryNumber(h, out var hour) || !TryNumber(m, out var minute) || hour > 23 || minute > 59) return false; time = new TimeOnly(hour, minute); return true; } }