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;
}
}