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:
Alby96 committed 2026-10-27 02:08:11 +01:00
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:&lt;n&gt;m|h|d</c>
/// (at least 5 minutes), <c>daily:HH:MM</c>, <c>weekly:mon,tue,…@HH:MM</c> and <c>monthly:&lt;1–28&gt;@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 &lt;&lt; (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;
}
}