Files
Chronos/src/Chronos.Data/Scheduling/ScheduleRecurrence.cs
T
Alby96 e5508e7e69 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)
2026-10-27 02:08:11 +01:00

323 lines
14 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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;
}
}