Owner review 2, R10: every timer that queues work becomes a visible schedule, so the server and the desktop need one shared engine to run them. - Migration 0007: schedules table (system rows keyed by system_key) and jobs.schedule_id; Job.ScheduleId, JobDto.ScheduleId, JobRepository HasPendingAsync / ListPendingTargetsAsync / ListByScheduleAsync. - ScheduleRepository: seeding that keeps user edits, reset, compare-and-set claim of a run (one winner across processes), outcomes. - Scheduling: in-house recurrence (every/daily/weekly/monthly, DST gap moves forward, ambiguous time runs once), ScheduleActions resolving scan, verify, thumbnails, proxies, analysis, maintenance, backup, cleanup, duplicates and orphans into archive jobs, IScheduleHost, and the Scheduler loop (catch-up, clock going back, run now, CRUD as API v1 DTOs). - New job kinds Backup (16) and Cleanup (17) with handlers, shared clean-up steps (job history, audit log, trash report that never deletes) and host steps through ArchiveServiceOptions; read-only Duplicates and Orphans report handlers, so the server can run those kinds too. - JobEngine no longer purges history at start: the housekeeping schedule's job-history step does; JobEngine.CanRun and an EnqueueAsync with scheduleId. - Protocol DTOs for schedules; job kind names in en and it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> (cherry picked from commit eb0edd2483a493db7c6945d5b494461cabb2a4ad)
323 lines
14 KiB
C#
323 lines
14 KiB
C#
using System.Diagnostics.CodeAnalysis;
|
||
using System.Globalization;
|
||
using System.Text;
|
||
|
||
namespace Chronos.Data.Scheduling;
|
||
|
||
/// <summary>The shape of a <see cref="ScheduleRecurrence"/>.</summary>
|
||
public enum RecurrenceKind
|
||
{
|
||
/// <summary>A fixed interval: every n minutes, hours or days.</summary>
|
||
Every,
|
||
|
||
/// <summary>Every day at a wall-clock time.</summary>
|
||
Daily,
|
||
|
||
/// <summary>On some days of the week at a wall-clock time.</summary>
|
||
Weekly,
|
||
|
||
/// <summary>On one day of the month (1–28) at a wall-clock time.</summary>
|
||
Monthly,
|
||
}
|
||
|
||
/// <summary>Unit of an <see cref="RecurrenceKind.Every"/> interval.</summary>
|
||
public enum RecurrenceUnit
|
||
{
|
||
Minutes,
|
||
Hours,
|
||
Days,
|
||
}
|
||
|
||
/// <summary>
|
||
/// When a schedule fires (owner review 2, R10), in an in-house text form instead of cron: <c>every:<n>m|h|d</c>
|
||
/// (at least 5 minutes), <c>daily:HH:MM</c>, <c>weekly:mon,tue,…@HH:MM</c> and <c>monthly:<1–28>@HH:MM</c>.
|
||
/// 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.
|
||
/// </summary>
|
||
public sealed record ScheduleRecurrence
|
||
{
|
||
/// <summary>The shortest interval: a schedule never fires more than every 5 minutes.</summary>
|
||
public const int MinMinutes = 5;
|
||
|
||
public const int MaxMinutes = 24 * 60;
|
||
public const int MaxHours = 7 * 24;
|
||
public const int MaxDays = 366;
|
||
|
||
/// <summary>The last day a monthly schedule can name: every month has it.</summary>
|
||
public const int MaxDayOfMonth = 28;
|
||
|
||
/// <summary>Wire names of the days, Monday first, as the text form and the API write them.</summary>
|
||
public static IReadOnlyList<string> 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];
|
||
|
||
/// <summary>Bit <c>1 << (int)DayOfWeek</c> per weekly day; a field, so equality compares the days.</summary>
|
||
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; }
|
||
|
||
/// <summary>The interval's count of <see cref="Unit"/>; 0 for the other kinds.</summary>
|
||
public int Every { get; }
|
||
|
||
/// <summary>The interval's unit (<see cref="RecurrenceKind.Every"/> only).</summary>
|
||
public RecurrenceUnit Unit { get; }
|
||
|
||
/// <summary>Wall-clock time of a daily, weekly or monthly schedule, to the minute; midnight for an interval.</summary>
|
||
public TimeOnly Time { get; }
|
||
|
||
/// <summary>The days of a weekly schedule, Monday first; empty for the other kinds.</summary>
|
||
public IReadOnlyList<DayOfWeek> Days => [.. WeekOrder.Where(d => (_days & Bit(d)) != 0)];
|
||
|
||
/// <summary>Day of the month of a monthly schedule (1–28); 0 for the other kinds.</summary>
|
||
public int DayOfMonth { get; }
|
||
|
||
/// <summary>
|
||
/// 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.
|
||
/// </summary>
|
||
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),
|
||
};
|
||
|
||
/// <summary>Every <paramref name="every"/> <paramref name="unit"/> (at least <see cref="MinMinutes"/> minutes).</summary>
|
||
/// <exception cref="ArgumentOutOfRangeException">The interval is shorter than 5 minutes or longer than its unit allows.</exception>
|
||
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);
|
||
}
|
||
|
||
/// <summary>Every day at <paramref name="time"/> (seconds are dropped).</summary>
|
||
public static ScheduleRecurrence DailyAt(TimeOnly time) => new(RecurrenceKind.Daily, 0, default, Minute(time), 0, 0);
|
||
|
||
/// <summary>On <paramref name="days"/> at <paramref name="time"/>.</summary>
|
||
/// <exception cref="ArgumentException">No day given.</exception>
|
||
public static ScheduleRecurrence WeeklyAt(IEnumerable<DayOfWeek> 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);
|
||
}
|
||
|
||
/// <summary>On day <paramref name="dayOfMonth"/> (1–28) of every month at <paramref name="time"/>.</summary>
|
||
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);
|
||
}
|
||
|
||
/// <summary>The recurrence written as <paramref name="text"/> (any case, spaces around parts allowed).</summary>
|
||
/// <exception cref="FormatException">The text is not a valid recurrence.</exception>
|
||
public static ScheduleRecurrence Parse(string text) =>
|
||
TryParse(text, out var recurrence) ? recurrence : throw new FormatException($"'{text}' is not a schedule recurrence.");
|
||
|
||
/// <summary>Parses the text form; false for anything else, values out of range included.</summary>
|
||
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;
|
||
}
|
||
|
||
/// <summary>The canonical text form: <c>every:10m</c>, <c>daily:03:00</c>, <c>weekly:mon,thu@02:30</c>, <c>monthly:1@04:00</c>.</summary>
|
||
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();
|
||
|
||
/// <summary>The wire name of <paramref name="day"/>: <c>mon</c> … <c>sun</c>.</summary>
|
||
public static string DayName(DayOfWeek day) => DayNames[Array.IndexOf(WeekOrder, day)];
|
||
|
||
/// <summary>The day named <paramref name="name"/> (<see cref="DayNames"/>, any case); false for anything else.</summary>
|
||
public static bool TryParseDay(string? name, out DayOfWeek day)
|
||
{
|
||
var index = IndexOfDay(name);
|
||
day = index < 0 ? default : WeekOrder[index];
|
||
return index >= 0;
|
||
}
|
||
|
||
/// <summary>
|
||
/// The first occurrence strictly after <paramref name="afterUtc"/>, in UTC and to the minute. An interval is laid on the
|
||
/// grid of <paramref name="anchorUtc"/> (the previous due time: no drift, missed occurrences collapse into the next one),
|
||
/// or starts one interval after <paramref name="afterUtc"/>'s minute without an anchor. Daily, weekly and monthly times
|
||
/// are read in <paramref name="zone"/> (see the type's remarks for clock changes); they need no anchor.
|
||
/// </summary>
|
||
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.");
|
||
}
|
||
|
||
/// <summary>
|
||
/// The UTC instant of the wall-clock time <paramref name="local"/> in <paramref name="zone"/>: a time inside a
|
||
/// spring-forward gap moves forward by the gap, an ambiguous one takes its first occurrence (still on the larger offset).
|
||
/// </summary>
|
||
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);
|
||
}
|
||
|
||
/// <summary><c>10m</c>, <c>6h</c>, <c>7d</c>; null for anything else.</summary>
|
||
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;
|
||
}
|
||
|
||
/// <summary><c>mon,thu@02:30</c>; null for anything else.</summary>
|
||
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<DayOfWeek>();
|
||
foreach (var name in text[..at].Split(','))
|
||
{
|
||
if (!TryParseDay(name.Trim(), out var day)) return null;
|
||
days.Add(day);
|
||
}
|
||
return WeeklyAt(days, time);
|
||
}
|
||
|
||
/// <summary><c>1@04:00</c>; null for anything else.</summary>
|
||
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;
|
||
}
|
||
}
|