feat(data): scheduler engine, schedules table and housekeeping jobs
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)
This commit is contained in:
1 parent
0e84392f4f
commit
e5508e7e69
51 files changed
+3219
-30
No files matched your search
@@ -0,0 +1,322 @@
|
||||
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;
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user