Files
Chronos/src/Chronos.Protocol/Schedules.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

98 lines
4.6 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.
namespace Chronos.Protocol;
/// <summary>
/// The parameters of a schedule's action (owner review 2, R10), flat: each action reads its own fields, the others stay
/// null (and are not stored). <c>scan</c>: <see cref="Force"/> (full scan), <see cref="Deep"/> (background deep analysis of
/// what it indexes). <c>verify</c>: <see cref="OlderThanDays"/> (only sequences not verified for that many days; 0: any),
/// <see cref="Percent"/> (share of the archive's sequences per run, least recently verified first). <c>thumbnails</c>,
/// <c>proxies</c>: <see cref="Force"/> (make again those already made). <c>analysis</c>: <see cref="Deep"/> (deep instead of
/// light). <c>maintenance</c>: <see cref="DryRun"/>. <c>backup</c>: <see cref="Keep"/> (copies kept). <c>cleanup</c>:
/// <see cref="Steps"/> (step names) and <see cref="OlderThanDays"/> (what is older goes; 0 keeps everything).
/// <c>duplicates</c>, <c>orphans</c>: none.
/// </summary>
public sealed record ScheduleParametersDto(
int? OlderThanDays = null,
int? Percent = null,
bool? Deep = null,
bool? DryRun = null,
bool? Force = null,
IReadOnlyList<string>? Steps = null,
int? Keep = null);
/// <summary>
/// When a schedule fires, structured. <see cref="Kind"/> = <c>every</c> (<see cref="Every"/> and <see cref="Unit"/>:
/// <c>minutes</c>, <c>hours</c> or <c>days</c>; at least 5 minutes), <c>daily</c> (<see cref="Time"/>), <c>weekly</c>
/// (<see cref="Days"/>: <c>mon</c> … <c>sun</c>; <see cref="Time"/>) or <c>monthly</c> (<see cref="DayOfMonth"/> 1–28;
/// <see cref="Time"/>). <see cref="Time"/> is <c>HH:MM</c>, wall-clock time of the host's time zone.
/// </summary>
public sealed record RecurrenceDto(
string Kind,
int? Every = null,
string? Unit = null,
string? Time = null,
IReadOnlyList<string>? Days = null,
int? DayOfMonth = null);
/// <summary>
/// A schedule (owner review 2, R10). <see cref="SystemKey"/> is set on the host's system schedules (the timers it runs,
/// shown so nothing runs out of sight): they can be edited, disabled and reset, never deleted. <see cref="Priority"/> is the
/// priority of the jobs it queues (<c>background</c>, <c>normal</c>, <c>user</c>). <see cref="LastOutcome"/>:
/// <c>queued</c>, <c>skipped-pending</c>, <c>skipped-offline</c>, <c>skipped-nothing</c>, <c>unavailable</c> or
/// <c>failed:&lt;reason&gt;</c>. <see cref="NextRun"/> is null while the schedule is disabled.
/// </summary>
public sealed record ScheduleDto(
Guid Id,
string? SystemKey,
string Name,
string Action,
string Target,
ScheduleParametersDto Parameters,
RecurrenceDto Recurrence,
bool CatchUp,
string Priority,
bool Enabled,
DateTimeOffset? NextRun,
DateTimeOffset? LastRun,
Guid? LastJobId,
string? LastOutcome,
Guid? CreatedBy,
DateTimeOffset Created,
DateTimeOffset Updated);
/// <summary>An action a schedule can take and whether this host runs it; <see cref="Reason"/> says why not (a code: <c>no-handler</c>, <c>postgres</c>, <c>proxies-disabled</c>…).</summary>
public sealed record ScheduleActionDto(string Name, bool Available, string? Reason);
/// <summary>
/// <c>GET /api/v1/schedules</c>: the schedules, system ones first, the actions with their availability, the host's time
/// zone (IANA or Windows id, as the host names it) and the clean-up steps its <c>cleanup</c> action runs.
/// </summary>
public sealed record SchedulesDto(IReadOnlyList<ScheduleDto> Items, IReadOnlyList<ScheduleActionDto> Actions, string TimeZone,
IReadOnlyList<string>? Steps = null);
/// <summary><c>POST /api/v1/schedules</c>: a new schedule; <see cref="Target"/> defaults to <c>current</c>, <see cref="Priority"/> to <c>background</c>.</summary>
public sealed record CreateScheduleRequest(
string Name,
string Action,
RecurrenceDto Recurrence,
ScheduleParametersDto? Parameters = null,
bool CatchUp = true,
string? Priority = null,
bool Enabled = true,
string? Target = null);
/// <summary>
/// <c>PATCH /api/v1/schedules/{id}</c>: the fields given replace the stored ones (<see cref="Parameters"/> as a whole). A
/// system schedule keeps its name and action.
/// </summary>
public sealed record UpdateScheduleRequest(
string? Name = null,
string? Action = null,
RecurrenceDto? Recurrence = null,
ScheduleParametersDto? Parameters = null,
bool? CatchUp = null,
string? Priority = null,
bool? Enabled = null);
/// <summary><c>POST /api/v1/schedules/{id}/run</c>: what running the schedule now did, and the schedule afterwards.</summary>
public sealed record ScheduleRunDto(ScheduleDto Schedule, string Outcome, Guid? JobId);