| | | 1 | | using System.Collections.Concurrent; |
| | | 2 | | using Cronos; |
| | | 3 | | using System.Management.Automation; |
| | | 4 | | using System.Collections; |
| | | 5 | | using Kestrun.Utilities; |
| | | 6 | | using static Kestrun.Scheduling.JobFactory; |
| | | 7 | | using Kestrun.Scripting; |
| | | 8 | | using Kestrun.Hosting; |
| | | 9 | | |
| | | 10 | | namespace Kestrun.Scheduling; |
| | | 11 | | |
| | | 12 | | /// <summary> |
| | | 13 | | /// Represents a service for managing scheduled tasks. |
| | | 14 | | /// Provides methods to schedule, cancel, pause, resume, and report on tasks. |
| | | 15 | | /// This service is designed to run within a Kestrun application context. |
| | | 16 | | /// It supports both C# and PowerShell jobs, allowing for flexible scheduling options. |
| | | 17 | | /// </summary> |
| | | 18 | | /// <remarks> |
| | | 19 | | /// The service uses a runspace pool for PowerShell jobs and supports scheduling via cron expressions or intervals. |
| | | 20 | | /// It also provides methods to retrieve task reports in various formats, including typed objects and PowerShell-friendl |
| | | 21 | | /// </remarks> |
| | | 22 | | /// <remarks> |
| | | 23 | | /// Initializes a new instance of the <see cref="SchedulerService"/> class. |
| | | 24 | | /// This constructor sets up the scheduler service with a specified runspace pool, logger, and optional time zone. |
| | | 25 | | /// The runspace pool is used for executing PowerShell scripts, while the logger is used for logging events. |
| | | 26 | | /// </remarks> |
| | | 27 | | /// <param name="pool">The runspace pool manager for executing PowerShell scripts.</param> |
| | | 28 | | /// <param name="log">The logger instance for logging events.</param> |
| | | 29 | | /// <param name="tz">The optional time zone information.</param> |
| | 18 | 30 | | public sealed class SchedulerService(KestrunRunspacePoolManager pool, Serilog.ILogger log, TimeZoneInfo? tz = null) : ID |
| | | 31 | | { |
| | | 32 | | /// <summary> |
| | | 33 | | /// The collection of scheduled tasks. |
| | | 34 | | /// This dictionary maps task names to their corresponding <see cref="ScheduledTask"/> instances. |
| | | 35 | | /// It is used to manage the lifecycle of scheduled tasks, including scheduling, execution, and cancellation. |
| | | 36 | | /// It is thread-safe and allows for concurrent access, ensuring that tasks can be added, removed, and executed |
| | | 37 | | /// simultaneously without causing data corruption or inconsistencies. |
| | | 38 | | /// </summary> |
| | 18 | 39 | | private readonly ConcurrentDictionary<string, ScheduledTask> _tasks = |
| | 18 | 40 | | new(StringComparer.OrdinalIgnoreCase); |
| | | 41 | | /// <summary> |
| | | 42 | | /// The runspace pool manager used for executing PowerShell scripts. |
| | | 43 | | /// This manager is responsible for managing the lifecycle of PowerShell runspaces, |
| | | 44 | | /// allowing for efficient execution of PowerShell scripts within the scheduler. |
| | | 45 | | /// It is used to create and manage runspaces for executing scheduled PowerShell jobs. |
| | | 46 | | /// The pool can be configured with various settings such as maximum runspaces, idle timeout, etc. |
| | | 47 | | /// </summary> |
| | 18 | 48 | | private readonly KestrunRunspacePoolManager _pool = pool; |
| | | 49 | | /// <summary> |
| | | 50 | | /// The logger instance used for logging events within the scheduler service. |
| | | 51 | | /// This logger is used to log information, warnings, and errors related to scheduled tasks. |
| | | 52 | | /// </summary> |
| | 18 | 53 | | private readonly Serilog.ILogger _log = log; |
| | | 54 | | /// <summary> |
| | | 55 | | /// The time zone used for scheduling and reporting. |
| | | 56 | | /// This is used to convert scheduled times to the appropriate time zone for display and execution. |
| | | 57 | | /// </summary> |
| | 18 | 58 | | private readonly TimeZoneInfo _tz = tz ?? TimeZoneInfo.Local; |
| | | 59 | | |
| | | 60 | | /// <summary> |
| | | 61 | | /// Gets the Kestrun host associated with the runspace pool. |
| | | 62 | | /// </summary> |
| | 0 | 63 | | public KestrunHost Host => _pool.Host; |
| | | 64 | | |
| | | 65 | | /*────────── C# JOBS ──────────*/ |
| | | 66 | | /// <summary> |
| | | 67 | | /// Schedules a C# job to run at a specified interval. |
| | | 68 | | /// </summary> |
| | | 69 | | /// <param name="name">The name of the job.</param> |
| | | 70 | | /// <param name="interval">The interval between job executions.</param> |
| | | 71 | | /// <param name="job">The asynchronous job delegate to execute.</param> |
| | | 72 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 73 | | public void Schedule(string name, TimeSpan interval, |
| | | 74 | | Func<CancellationToken, Task> job, bool runImmediately = false) |
| | 18 | 75 | | => ScheduleCore(name, job, cron: null, interval: interval, runImmediately); |
| | | 76 | | |
| | | 77 | | /// <summary> |
| | | 78 | | /// Schedules a C# job to run according to a cron expression. |
| | | 79 | | /// </summary> |
| | | 80 | | /// <param name="name">The name of the job.</param> |
| | | 81 | | /// <param name="cronExpr">The cron expression specifying the job schedule.</param> |
| | | 82 | | /// <param name="job">The asynchronous job delegate to execute.</param> |
| | | 83 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 84 | | public void Schedule(string name, string cronExpr, |
| | | 85 | | Func<CancellationToken, Task> job, bool runImmediately = false) |
| | | 86 | | { |
| | 7 | 87 | | var cron = CronExpression.Parse(cronExpr, CronFormat.IncludeSeconds); |
| | 7 | 88 | | ScheduleCore(name, job, cron, null, runImmediately); |
| | 7 | 89 | | } |
| | | 90 | | |
| | | 91 | | /*────────── PowerShell JOBS ──────────*/ |
| | | 92 | | /// <summary> |
| | | 93 | | /// Schedules a PowerShell job to run according to a cron expression. |
| | | 94 | | /// </summary> |
| | | 95 | | /// <param name="name">The name of the job.</param> |
| | | 96 | | /// <param name="cron">The cron expression specifying the job schedule.</param> |
| | | 97 | | /// <param name="scriptblock">The PowerShell script block to execute.</param> |
| | | 98 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 99 | | public void Schedule(string name, string cron, ScriptBlock scriptblock, bool runImmediately = false) |
| | | 100 | | { |
| | 1 | 101 | | JobConfig config = new(ScriptLanguage.PowerShell, scriptblock.ToString(), _log, _pool); |
| | 1 | 102 | | var job = Create(config); |
| | 1 | 103 | | Schedule(name, cron, job, runImmediately); |
| | 1 | 104 | | } |
| | | 105 | | /// <summary> |
| | | 106 | | /// Schedules a PowerShell job to run at a specified interval. |
| | | 107 | | /// </summary> |
| | | 108 | | /// <param name="name">The name of the job.</param> |
| | | 109 | | /// <param name="interval">The interval between job executions.</param> |
| | | 110 | | /// <param name="scriptblock">The PowerShell script block to execute.</param> |
| | | 111 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 112 | | public void Schedule(string name, TimeSpan interval, ScriptBlock scriptblock, bool runImmediately = false) |
| | | 113 | | { |
| | 0 | 114 | | JobConfig config = new(ScriptLanguage.PowerShell, scriptblock.ToString(), _log, _pool); |
| | 0 | 115 | | var job = Create(config); |
| | 0 | 116 | | Schedule(name, interval, job, runImmediately); |
| | 0 | 117 | | } |
| | | 118 | | /// <summary> |
| | | 119 | | /// Schedules a script job to run at a specified interval. |
| | | 120 | | /// </summary> |
| | | 121 | | /// <param name="name">The name of the job.</param> |
| | | 122 | | /// <param name="interval">The interval between job executions.</param> |
| | | 123 | | /// <param name="code">The script code to execute.</param> |
| | | 124 | | /// <param name="lang">The language of the script (e.g., PowerShell, CSharp).</param> |
| | | 125 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 126 | | public void Schedule(string name, TimeSpan interval, string code, ScriptLanguage lang, bool runImmediately = false) |
| | | 127 | | { |
| | 2 | 128 | | JobConfig config = new(lang, code, _log, _pool); |
| | 2 | 129 | | var job = Create(config); |
| | 2 | 130 | | Schedule(name, interval, job, runImmediately); |
| | 2 | 131 | | } |
| | | 132 | | |
| | | 133 | | /// <summary> |
| | | 134 | | /// Schedules a script job to run according to a cron expression. |
| | | 135 | | /// </summary> |
| | | 136 | | /// <param name="name">The name of the job.</param> |
| | | 137 | | /// <param name="cron">The cron expression specifying the job schedule.</param> |
| | | 138 | | /// <param name="code">The script code to execute.</param> |
| | | 139 | | /// <param name="lang">The language of the script (e.g., PowerShell, CSharp).</param> |
| | | 140 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 141 | | public void Schedule(string name, string cron, string code, ScriptLanguage lang, bool runImmediately = false) |
| | | 142 | | { |
| | 1 | 143 | | JobConfig config = new(lang, code, _log, _pool); |
| | 1 | 144 | | var job = Create(config); |
| | 1 | 145 | | Schedule(name, cron, job, runImmediately); |
| | 1 | 146 | | } |
| | | 147 | | |
| | | 148 | | /// <summary> |
| | | 149 | | /// Schedules a script job from a file to run at a specified interval. |
| | | 150 | | /// </summary> |
| | | 151 | | /// <param name="name">The name of the job.</param> |
| | | 152 | | /// <param name="interval">The interval between job executions.</param> |
| | | 153 | | /// <param name="fileInfo">The file containing the script code to execute.</param> |
| | | 154 | | /// <param name="lang">The language of the script (e.g., PowerShell, CSharp).</param> |
| | | 155 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 156 | | public void Schedule(string name, TimeSpan interval, FileInfo fileInfo, ScriptLanguage lang, bool runImmediately = f |
| | | 157 | | { |
| | 1 | 158 | | JobConfig config = new(lang, string.Empty, _log, _pool); |
| | 1 | 159 | | var job = Create(config, fileInfo); |
| | 1 | 160 | | Schedule(name, interval, job, runImmediately); |
| | 1 | 161 | | } |
| | | 162 | | |
| | | 163 | | /// <summary> |
| | | 164 | | /// Schedules a script job from a file to run according to a cron expression. |
| | | 165 | | /// </summary> |
| | | 166 | | /// <param name="name">The name of the job.</param> |
| | | 167 | | /// <param name="cron">The cron expression specifying the job schedule.</param> |
| | | 168 | | /// <param name="fileInfo">The file containing the script code to execute.</param> |
| | | 169 | | /// <param name="lang">The language of the script (e.g., PowerShell, CSharp).</param> |
| | | 170 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 171 | | public void Schedule(string name, string cron, FileInfo fileInfo, ScriptLanguage lang, bool runImmediately = false) |
| | | 172 | | { |
| | 1 | 173 | | JobConfig config = new(lang, string.Empty, _log, _pool); |
| | 1 | 174 | | var job = Create(config, fileInfo); |
| | 1 | 175 | | Schedule(name, cron, job, runImmediately); |
| | 1 | 176 | | } |
| | | 177 | | |
| | | 178 | | /// <summary> |
| | | 179 | | /// Asynchronously schedules a script job from a file to run at a specified interval. |
| | | 180 | | /// </summary> |
| | | 181 | | /// <param name="name">The name of the job.</param> |
| | | 182 | | /// <param name="interval">The interval between job executions.</param> |
| | | 183 | | /// <param name="fileInfo">The file containing the script code to execute.</param> |
| | | 184 | | /// <param name="lang">The language of the script (e.g., PowerShell, CSharp).</param> |
| | | 185 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 186 | | /// <param name="ct">The cancellation token to cancel the operation.</param> |
| | | 187 | | public async Task ScheduleAsync(string name, TimeSpan interval, FileInfo fileInfo, ScriptLanguage lang, bool runImme |
| | | 188 | | { |
| | 1 | 189 | | JobConfig config = new(lang, string.Empty, _log, _pool); |
| | 1 | 190 | | var job = await CreateAsync(config, fileInfo, ct); |
| | 1 | 191 | | Schedule(name, interval, job, runImmediately); |
| | 1 | 192 | | } |
| | | 193 | | |
| | | 194 | | /// <summary> |
| | | 195 | | /// Asynchronously schedules a script job from a file to run according to a cron expression. |
| | | 196 | | /// </summary> |
| | | 197 | | /// <param name="name">The name of the job.</param> |
| | | 198 | | /// <param name="cron">The cron expression specifying the job schedule.</param> |
| | | 199 | | /// <param name="fileInfo">The file containing the script code to execute.</param> |
| | | 200 | | /// <param name="lang">The language of the script (e.g., PowerShell, CSharp).</param> |
| | | 201 | | /// <param name="runImmediately">Whether to run the job immediately upon scheduling.</param> |
| | | 202 | | /// <param name="ct">The cancellation token to cancel the operation.</param> |
| | | 203 | | public async Task ScheduleAsync(string name, string cron, FileInfo fileInfo, ScriptLanguage lang, bool runImmediatel |
| | | 204 | | { |
| | 1 | 205 | | JobConfig config = new(lang, string.Empty, _log, _pool); |
| | 1 | 206 | | var job = await CreateAsync(config, fileInfo, ct); |
| | 1 | 207 | | Schedule(name, cron, job, runImmediately); |
| | 1 | 208 | | } |
| | | 209 | | /*────────── CONTROL ──────────*/ |
| | | 210 | | /// <summary> |
| | | 211 | | /// Cancels a scheduled job by its name. |
| | | 212 | | /// </summary> |
| | | 213 | | /// <param name="name">The name of the job to cancel.</param> |
| | | 214 | | /// <returns>True if the job was found and cancelled; otherwise, false.</returns> |
| | | 215 | | public bool Cancel(string name) |
| | | 216 | | { |
| | 25 | 217 | | if (string.IsNullOrWhiteSpace(name)) |
| | | 218 | | { |
| | 1 | 219 | | throw new ArgumentException("Task name cannot be null or empty.", nameof(name)); |
| | | 220 | | } |
| | | 221 | | |
| | 24 | 222 | | _log.Information("Cancelling scheduler job {Name}", name); |
| | 24 | 223 | | if (_tasks.TryRemove(name, out var task)) |
| | | 224 | | { |
| | 24 | 225 | | task.TokenSource.Cancel(); |
| | | 226 | | // Wait briefly for the loop to observe cancellation to avoid a race |
| | | 227 | | // where a final run completes after Cancel() returns and causes test flakiness. |
| | | 228 | | try |
| | | 229 | | { |
| | 24 | 230 | | if (task.Runner is { } r && !r.IsCompleted) |
| | | 231 | | { |
| | | 232 | | // First quick wait |
| | 24 | 233 | | if (!r.Wait(TimeSpan.FromMilliseconds(250))) |
| | | 234 | | { |
| | | 235 | | // Allow additional time (slower net8 CI, PowerShell warm-up) up to ~1s total. |
| | 0 | 236 | | var remaining = TimeSpan.FromMilliseconds(750); |
| | 0 | 237 | | var sw = System.Diagnostics.Stopwatch.StartNew(); |
| | 0 | 238 | | while (!r.IsCompleted && sw.Elapsed < remaining) |
| | | 239 | | { |
| | | 240 | | // small sleep; runner work is CPU-light |
| | 0 | 241 | | Thread.Sleep(25); |
| | | 242 | | } |
| | | 243 | | } |
| | | 244 | | } |
| | 24 | 245 | | } |
| | 0 | 246 | | catch (Exception) { /* swallow */ } |
| | 24 | 247 | | _log.Information("Scheduler job {Name} cancelled", name); |
| | 24 | 248 | | return true; |
| | | 249 | | } |
| | 0 | 250 | | return false; |
| | | 251 | | } |
| | | 252 | | |
| | | 253 | | /// <summary> |
| | | 254 | | /// Asynchronously cancels a scheduled job and optionally waits for its runner to complete. |
| | | 255 | | /// </summary> |
| | | 256 | | /// <param name="name">Job name.</param> |
| | | 257 | | /// <param name="timeout">Optional timeout (default 2s) to wait for completion after signalling cancellation.</param |
| | | 258 | | public async Task<bool> CancelAsync(string name, TimeSpan? timeout = null) |
| | | 259 | | { |
| | 0 | 260 | | timeout ??= TimeSpan.FromSeconds(2); |
| | 0 | 261 | | if (string.IsNullOrWhiteSpace(name)) |
| | | 262 | | { |
| | 0 | 263 | | throw new ArgumentException("Task name cannot be null or empty.", nameof(name)); |
| | | 264 | | } |
| | 0 | 265 | | if (!_tasks.TryRemove(name, out var task)) |
| | | 266 | | { |
| | 0 | 267 | | return false; |
| | | 268 | | } |
| | 0 | 269 | | _log.Information("Cancelling scheduler job (async) {Name}", name); |
| | 0 | 270 | | task.TokenSource.Cancel(); |
| | 0 | 271 | | var runner = task.Runner; |
| | 0 | 272 | | if (runner is null) |
| | | 273 | | { |
| | 0 | 274 | | return true; |
| | | 275 | | } |
| | | 276 | | try |
| | | 277 | | { |
| | 0 | 278 | | using var cts = new CancellationTokenSource(timeout.Value); |
| | 0 | 279 | | var completed = await Task.WhenAny(runner, Task.Delay(Timeout.InfiniteTimeSpan, cts.Token)) == runner; |
| | 0 | 280 | | if (!completed) |
| | | 281 | | { |
| | 0 | 282 | | _log.Warning("Timeout waiting for scheduler job {Name} to cancel", name); |
| | | 283 | | } |
| | 0 | 284 | | } |
| | 0 | 285 | | catch (Exception ex) |
| | | 286 | | { |
| | 0 | 287 | | _log.Debug(ex, "Error while awaiting cancellation for job {Name}", name); |
| | 0 | 288 | | } |
| | 0 | 289 | | return true; |
| | 0 | 290 | | } |
| | | 291 | | |
| | | 292 | | /// <summary> |
| | | 293 | | /// Cancels all scheduled jobs. |
| | | 294 | | /// </summary> |
| | | 295 | | public void CancelAll() |
| | | 296 | | { |
| | 82 | 297 | | foreach (var kvp in _tasks.Keys) |
| | | 298 | | { |
| | 23 | 299 | | _ = Cancel(kvp); |
| | | 300 | | } |
| | 18 | 301 | | } |
| | | 302 | | |
| | | 303 | | /// <summary> |
| | | 304 | | /// Generates a report of all scheduled jobs, including their last and next run times, and suspension status. |
| | | 305 | | /// </summary> |
| | | 306 | | /// <param name="displayTz">The time zone to display times in; defaults to UTC if not specified.</param> |
| | | 307 | | /// <returns>A <see cref="ScheduleReport"/> containing information about all scheduled jobs.</returns> |
| | | 308 | | public ScheduleReport GetReport(TimeZoneInfo? displayTz = null) |
| | | 309 | | { |
| | | 310 | | // default to Zulu |
| | 2 | 311 | | var timezone = displayTz ?? TimeZoneInfo.Utc; |
| | 2 | 312 | | var now = DateTimeOffset.UtcNow; |
| | | 313 | | |
| | 2 | 314 | | var jobs = _tasks.Values |
| | 2 | 315 | | .Select(t => |
| | 2 | 316 | | { |
| | 2 | 317 | | // store timestamps internally in UTC; convert only for the report |
| | 4 | 318 | | var (lastRunAt, nextRunAt) = t.GetTimestamps(); |
| | 4 | 319 | | var last = lastRunAt?.ToOffset(timezone.GetUtcOffset(lastRunAt.Value)); |
| | 4 | 320 | | var next = nextRunAt.ToOffset(timezone.GetUtcOffset(nextRunAt)); |
| | 2 | 321 | | |
| | 4 | 322 | | return new JobInfo(t.Name, last, next, t.IsSuspended); |
| | 2 | 323 | | }) |
| | 4 | 324 | | .OrderBy(j => j.NextRunAt) |
| | 2 | 325 | | .ToArray(); |
| | | 326 | | |
| | 2 | 327 | | return new ScheduleReport(now, jobs); |
| | | 328 | | } |
| | | 329 | | |
| | | 330 | | /// <summary> |
| | | 331 | | /// Generates a report of all scheduled jobs in a PowerShell-friendly hashtable format. |
| | | 332 | | /// </summary> |
| | | 333 | | /// <param name="displayTz">The time zone to display times in; defaults to UTC if not specified.</param> |
| | | 334 | | /// <returns>A <see cref="Hashtable"/> containing information about all scheduled jobs.</returns> |
| | | 335 | | public Hashtable GetReportHashtable(TimeZoneInfo? displayTz = null) |
| | | 336 | | { |
| | 1 | 337 | | var rpt = GetReport(displayTz); |
| | | 338 | | |
| | 1 | 339 | | var jobsArray = rpt.Jobs |
| | 2 | 340 | | .Select(j => new Hashtable |
| | 2 | 341 | | { |
| | 2 | 342 | | ["Name"] = j.Name, |
| | 2 | 343 | | ["LastRunAt"] = j.LastRunAt, |
| | 2 | 344 | | ["NextRunAt"] = j.NextRunAt, |
| | 2 | 345 | | ["IsSuspended"] = j.IsSuspended, |
| | 2 | 346 | | ["IsCompleted"] = j.IsCompleted |
| | 2 | 347 | | }) |
| | 1 | 348 | | .ToArray(); // powershell likes [] not IList<> |
| | | 349 | | |
| | 1 | 350 | | return new Hashtable |
| | 1 | 351 | | { |
| | 1 | 352 | | ["GeneratedAt"] = rpt.GeneratedAt, |
| | 1 | 353 | | ["Jobs"] = jobsArray |
| | 1 | 354 | | }; |
| | | 355 | | } |
| | | 356 | | |
| | | 357 | | |
| | | 358 | | /// <summary> |
| | | 359 | | /// Gets a snapshot of all scheduled jobs with their current state. |
| | | 360 | | /// </summary> |
| | | 361 | | /// <returns>An <see cref="IReadOnlyCollection{JobInfo}"/> containing job information for all scheduled jobs.</retur |
| | | 362 | | public IReadOnlyCollection<JobInfo> GetSnapshot() |
| | 22 | 363 | | => [.. _tasks.Values.Select(t => |
| | 22 | 364 | | { |
| | 32 | 365 | | var (lastRunAt, nextRunAt) = t.GetTimestamps(); |
| | 32 | 366 | | return new JobInfo(t.Name, lastRunAt, nextRunAt, t.IsSuspended, t.IsCompleted); |
| | 22 | 367 | | })]; |
| | | 368 | | |
| | | 369 | | |
| | | 370 | | /// <summary> |
| | | 371 | | /// Gets a snapshot of all scheduled jobs with their current state, optionally filtered and formatted. |
| | | 372 | | /// </summary> |
| | | 373 | | /// <param name="tz">The time zone to display times in; defaults to UTC if not specified.</param> |
| | | 374 | | /// <param name="asHashtable">Whether to return the result as PowerShell-friendly hashtables.</param> |
| | | 375 | | /// <param name="nameFilter">Optional glob patterns to filter job names.</param> |
| | | 376 | | /// <returns> |
| | | 377 | | /// An <see cref="IReadOnlyCollection{T}"/> containing job information for all scheduled jobs, |
| | | 378 | | /// either as <see cref="JobInfo"/> objects or hashtables depending on <paramref name="asHashtable"/>. |
| | | 379 | | /// </returns> |
| | | 380 | | public IReadOnlyCollection<object> GetSnapshot( |
| | | 381 | | TimeZoneInfo? tz = null, |
| | | 382 | | bool asHashtable = false, |
| | | 383 | | params string[] nameFilter) |
| | | 384 | | { |
| | 2 | 385 | | tz ??= TimeZoneInfo.Utc; |
| | | 386 | | |
| | | 387 | | bool Matches(string name) |
| | | 388 | | { |
| | | 389 | | if (nameFilter == null || nameFilter.Length == 0) |
| | | 390 | | { |
| | | 391 | | return true; |
| | | 392 | | } |
| | | 393 | | |
| | | 394 | | foreach (var pat in nameFilter) |
| | | 395 | | { |
| | | 396 | | if (RegexUtils.IsGlobMatch(name, pat)) |
| | | 397 | | { |
| | | 398 | | return true; |
| | | 399 | | } |
| | | 400 | | } |
| | | 401 | | |
| | | 402 | | return false; |
| | | 403 | | } |
| | | 404 | | |
| | | 405 | | // fast path: no filter, utc, typed objects |
| | 2 | 406 | | if (nameFilter.Length == 0 && tz.Equals(TimeZoneInfo.Utc) && !asHashtable) |
| | | 407 | | { |
| | 0 | 408 | | return [.. _tasks.Values.Select(t => |
| | 0 | 409 | | { |
| | 0 | 410 | | var (lastRunAt, nextRunAt) = t.GetTimestamps(); |
| | 0 | 411 | | return (object)new JobInfo(t.Name, lastRunAt, nextRunAt, t.IsSuspended, t.IsCompleted); |
| | 0 | 412 | | })]; |
| | | 413 | | } |
| | | 414 | | |
| | 2 | 415 | | var jobs = _tasks.Values |
| | 6 | 416 | | .Where(t => Matches(t.Name)) |
| | 2 | 417 | | .Select(t => |
| | 2 | 418 | | { |
| | 3 | 419 | | var (lastRunAt, nextRunAt) = t.GetTimestamps(); |
| | 3 | 420 | | var last = lastRunAt?.ToOffset(tz.GetUtcOffset(lastRunAt ?? DateTimeOffset.UtcNow)); |
| | 3 | 421 | | var next = nextRunAt.ToOffset(tz.GetUtcOffset(nextRunAt)); |
| | 3 | 422 | | return new JobInfo(t.Name, last, next, t.IsSuspended, t.IsCompleted); |
| | 2 | 423 | | }) |
| | 2 | 424 | | .OrderBy(j => j.NextRunAt) |
| | 2 | 425 | | .ToArray(); |
| | | 426 | | |
| | 2 | 427 | | if (!asHashtable) |
| | | 428 | | { |
| | 1 | 429 | | return [.. jobs.Cast<object>()]; |
| | | 430 | | } |
| | | 431 | | |
| | | 432 | | // PowerShell-friendly shape |
| | 2 | 433 | | return [.. jobs.Select(j => (object)new Hashtable |
| | 2 | 434 | | { |
| | 2 | 435 | | ["Name"] = j.Name, |
| | 2 | 436 | | ["LastRunAt"] = j.LastRunAt, |
| | 2 | 437 | | ["NextRunAt"] = j.NextRunAt, |
| | 2 | 438 | | ["IsSuspended"] = j.IsSuspended, |
| | 2 | 439 | | ["IsCompleted"] = j.IsCompleted |
| | 2 | 440 | | })]; |
| | | 441 | | } |
| | | 442 | | |
| | | 443 | | |
| | | 444 | | /// <summary> |
| | | 445 | | /// Pauses a scheduled job by its name. |
| | | 446 | | /// </summary> |
| | | 447 | | /// <param name="name">The name of the job to pause.</param> |
| | | 448 | | /// <returns>True if the job was found and paused; otherwise, false.</returns> |
| | 2 | 449 | | public bool Pause(string name) => Suspend(name); |
| | | 450 | | /// <summary> |
| | | 451 | | /// Resumes a scheduled job by its name. |
| | | 452 | | /// </summary> |
| | | 453 | | /// <param name="name">The name of the job to resume.</param> |
| | | 454 | | /// <returns>True if the job was found and resumed; otherwise, false.</returns> |
| | 2 | 455 | | public bool Resume(string name) => Suspend(name, false); |
| | | 456 | | |
| | | 457 | | /*────────── INTERNALS ──────────*/ |
| | | 458 | | |
| | | 459 | | /// <summary> |
| | | 460 | | /// Suspends or resumes a scheduled job by its name. |
| | | 461 | | /// This method updates the suspension status of the job, allowing it to be paused or resumed. |
| | | 462 | | /// If the job is found, its IsSuspended property is updated accordingly. |
| | | 463 | | /// </summary> |
| | | 464 | | /// <param name="name">The name of the job to suspend or resume.</param> |
| | | 465 | | /// <param name="suspend">True to suspend the job; false to resume it.</param> |
| | | 466 | | /// <returns>True if the job was found and its status was updated; otherwise, false.</returns> |
| | | 467 | | /// <exception cref="ArgumentException"></exception> |
| | | 468 | | /// <remarks> |
| | | 469 | | /// This method is used internally to control the execution of scheduled jobs. |
| | | 470 | | /// It allows for dynamic control over job execution without needing to cancel and reschedule them. |
| | | 471 | | /// </remarks> |
| | | 472 | | private bool Suspend(string name, bool suspend = true) |
| | | 473 | | { |
| | 4 | 474 | | if (string.IsNullOrWhiteSpace(name)) |
| | | 475 | | { |
| | 2 | 476 | | throw new ArgumentException("Task name cannot be null or empty.", nameof(name)); |
| | | 477 | | } |
| | | 478 | | |
| | 2 | 479 | | if (_tasks.TryGetValue(name, out var task)) |
| | | 480 | | { |
| | 2 | 481 | | task.IsSuspended = suspend; |
| | 2 | 482 | | _log.Information("Scheduler job {Name} {Action}", name, suspend ? "paused" : "resumed"); |
| | 2 | 483 | | return true; |
| | | 484 | | } |
| | 0 | 485 | | return false; |
| | | 486 | | } |
| | | 487 | | |
| | | 488 | | /// <summary> |
| | | 489 | | /// Schedules a new job. |
| | | 490 | | /// This method is the core implementation for scheduling jobs, allowing for both cron-based and interval-based sche |
| | | 491 | | /// It creates a new <see cref="ScheduledTask"/> instance and starts it in a background loop. |
| | | 492 | | /// The task is added to the internal collection of tasks, and its next run time is calculated based on the provided |
| | | 493 | | /// If both cron and interval are null, an exception is thrown. |
| | | 494 | | /// </summary> |
| | | 495 | | /// <param name="name">The name of the job.</param> |
| | | 496 | | /// <param name="job">The job to execute.</param> |
| | | 497 | | /// <param name="cron">The cron expression for scheduling.</param> |
| | | 498 | | /// <param name="interval">The interval for scheduling.</param> |
| | | 499 | | /// <param name="runImmediately">Whether to run the job immediately.</param> |
| | | 500 | | /// <exception cref="ArgumentException"></exception> |
| | | 501 | | /// <exception cref="InvalidOperationException"></exception> |
| | | 502 | | /// <remarks> |
| | | 503 | | /// This method is used internally to schedule jobs and should not be called directly. |
| | | 504 | | /// It handles the creation of the task, its scheduling, and the management of its execution loop. |
| | | 505 | | /// The task is run in a separate background thread to avoid blocking the main application flow. |
| | | 506 | | /// </remarks> |
| | | 507 | | private void ScheduleCore( |
| | | 508 | | string name, |
| | | 509 | | Func<CancellationToken, Task> job, |
| | | 510 | | CronExpression? cron, |
| | | 511 | | TimeSpan? interval, |
| | | 512 | | bool runImmediately) |
| | | 513 | | { |
| | 25 | 514 | | if (cron is null && interval == null) |
| | | 515 | | { |
| | 0 | 516 | | throw new ArgumentException("Either cron or interval must be supplied."); |
| | | 517 | | } |
| | | 518 | | |
| | 25 | 519 | | var cts = new CancellationTokenSource(); |
| | 25 | 520 | | var task = new ScheduledTask(name, job, cron, interval, runImmediately, cts) |
| | 25 | 521 | | { |
| | 25 | 522 | | NextRunAt = interval != null |
| | 25 | 523 | | ? DateTimeOffset.UtcNow + interval.Value |
| | 25 | 524 | | : (DateTimeOffset.UtcNow + NextCronDelay(cron!, _tz)).ToUniversalTime(), |
| | 25 | 525 | | }; |
| | | 526 | | |
| | 25 | 527 | | if (!_tasks.TryAdd(name, task)) |
| | | 528 | | { |
| | 1 | 529 | | throw new InvalidOperationException($"A task named '{name}' already exists."); |
| | | 530 | | } |
| | | 531 | | |
| | 48 | 532 | | task.Runner = Task.Run(() => LoopAsync(task), cts.Token); |
| | 24 | 533 | | _log.Debug("Scheduled job '{Name}' (cron: {Cron}, interval: {Interval})", name, cron?.ToString(), interval); |
| | 24 | 534 | | } |
| | | 535 | | |
| | | 536 | | /// <summary> |
| | | 537 | | /// Runs the scheduled task in a loop. |
| | | 538 | | /// This method handles the execution of the task according to its schedule, either immediately or based on a cron e |
| | | 539 | | /// It checks if the task is suspended and delays accordingly, while also being responsive to cancellation requests. |
| | | 540 | | /// </summary> |
| | | 541 | | /// <param name="task">The scheduled task to run.</param> |
| | | 542 | | /// <returns>A task representing the asynchronous operation.</returns> |
| | | 543 | | /// <remarks> |
| | | 544 | | /// This method is called internally by the scheduler to manage the execution of scheduled tasks. |
| | | 545 | | /// It ensures that tasks are run at the correct times and handles any exceptions that may occur during execution. |
| | | 546 | | /// The loop continues until the task is cancelled or the cancellation token is triggered. |
| | | 547 | | /// </remarks> |
| | | 548 | | private async Task LoopAsync(ScheduledTask task) |
| | | 549 | | { |
| | 24 | 550 | | var ct = task.TokenSource.Token; |
| | | 551 | | |
| | 24 | 552 | | if (task.RunImmediately && !task.IsSuspended) |
| | | 553 | | { |
| | 11 | 554 | | await SafeRun(task.Work, task, ct); |
| | | 555 | | } |
| | | 556 | | |
| | 35 | 557 | | while (!ct.IsCancellationRequested) |
| | | 558 | | { |
| | 35 | 559 | | if (task.IsSuspended) |
| | | 560 | | { |
| | | 561 | | // sleep a bit while suspended, but stay responsive to Cancel() |
| | 1 | 562 | | await Task.Delay(TimeSpan.FromSeconds(1), ct); |
| | 1 | 563 | | continue; |
| | | 564 | | } |
| | | 565 | | |
| | | 566 | | TimeSpan delay; |
| | 34 | 567 | | if (task.Interval is not null) |
| | | 568 | | { |
| | | 569 | | // Align to the intended NextRunAt rather than drifting by fixed interval; |
| | | 570 | | // this reduces flakiness when scheduling overhead is high. |
| | 27 | 571 | | var until = task.NextRunAt - DateTimeOffset.UtcNow; |
| | 27 | 572 | | delay = until > TimeSpan.Zero ? until : TimeSpan.Zero; |
| | | 573 | | } |
| | | 574 | | else |
| | | 575 | | { |
| | 7 | 576 | | delay = NextCronDelay(task.Cron!, _tz); |
| | 7 | 577 | | if (delay < TimeSpan.Zero) |
| | | 578 | | { |
| | 0 | 579 | | delay = TimeSpan.Zero; |
| | | 580 | | } |
| | | 581 | | } |
| | | 582 | | |
| | 44 | 583 | | try { await Task.Delay(delay, ct); } |
| | 48 | 584 | | catch (TaskCanceledException) { break; } |
| | | 585 | | |
| | 10 | 586 | | if (!ct.IsCancellationRequested) |
| | | 587 | | { |
| | 10 | 588 | | await SafeRun(task.Work, task, ct); |
| | | 589 | | } |
| | | 590 | | } |
| | 24 | 591 | | task.IsCompleted = true; |
| | 24 | 592 | | } |
| | | 593 | | |
| | | 594 | | /// <summary> |
| | | 595 | | /// Calculates the next delay for a cron expression. |
| | | 596 | | /// This method computes the time until the next occurrence of the cron expression based on the current UTC time. |
| | | 597 | | /// If there are no future occurrences, it logs a warning and returns a maximum value. |
| | | 598 | | /// </summary> |
| | | 599 | | /// <param name="expr">The cron expression to evaluate.</param> |
| | | 600 | | /// <param name="tz">The time zone to use for the evaluation.</param> |
| | | 601 | | /// <returns>The time span until the next occurrence of the cron expression.</returns> |
| | | 602 | | /// <remarks> |
| | | 603 | | /// This method is used internally to determine when the next scheduled run of a cron-based task should occur. |
| | | 604 | | /// It uses the Cronos library to calculate the next occurrence based on the current UTC time and the specified time |
| | | 605 | | /// If no future occurrence is found, it logs a warning and returns a maximum time span. |
| | | 606 | | /// </remarks> |
| | | 607 | | private TimeSpan NextCronDelay(CronExpression expr, TimeZoneInfo tz) |
| | | 608 | | { |
| | 14 | 609 | | var next = expr.GetNextOccurrence(DateTimeOffset.UtcNow, tz); |
| | 14 | 610 | | if (next is null) |
| | | 611 | | { |
| | 0 | 612 | | _log.Warning("Cron expression {Expr} has no future occurrence", expr); |
| | | 613 | | } |
| | | 614 | | |
| | 14 | 615 | | return next.HasValue ? next.Value - DateTimeOffset.UtcNow : TimeSpan.MaxValue; |
| | | 616 | | } |
| | | 617 | | |
| | | 618 | | /// <summary> |
| | | 619 | | /// Safely runs the scheduled task, handling exceptions and updating the task's state. |
| | | 620 | | /// This method executes the provided work function and updates the task's last run time and next run time according |
| | | 621 | | /// </summary> |
| | | 622 | | /// <param name="work">The work function to execute.</param> |
| | | 623 | | /// <param name="task">The scheduled task to run.</param> |
| | | 624 | | /// <param name="ct">The cancellation token.</param> |
| | | 625 | | /// <returns>A task representing the asynchronous operation.</returns> |
| | | 626 | | /// <remarks> |
| | | 627 | | /// This method is called internally by the scheduler to manage the execution of scheduled tasks. |
| | | 628 | | /// It ensures that tasks are run at the correct times and handles any exceptions that may occur during execution. |
| | | 629 | | /// </remarks> |
| | | 630 | | private async Task SafeRun(Func<CancellationToken, Task> work, ScheduledTask task, CancellationToken ct) |
| | | 631 | | { |
| | | 632 | | try |
| | | 633 | | { |
| | | 634 | | // If cancellation was requested after the loop's check and before entering here, bail out. |
| | 21 | 635 | | if (ct.IsCancellationRequested) |
| | | 636 | | { |
| | 0 | 637 | | return; |
| | | 638 | | } |
| | 21 | 639 | | var runStartedAt = DateTimeOffset.UtcNow; // capture start time |
| | 21 | 640 | | await work(ct); |
| | | 641 | | |
| | | 642 | | // compute next run (only if still scheduled). We compute fully *before* publishing |
| | | 643 | | // any timestamp changes so snapshots never see LastRunAt > NextRunAt. |
| | | 644 | | DateTimeOffset nextRun; |
| | 21 | 645 | | if (task.Interval != null) |
| | | 646 | | { |
| | 15 | 647 | | task.RunIteration++; // increment completed count |
| | 15 | 648 | | var interval = task.Interval.Value; |
| | 15 | 649 | | var next = task.AnchorAt + ((task.RunIteration + 1) * interval); |
| | 15 | 650 | | var now = DateTimeOffset.UtcNow; |
| | 23 | 651 | | while (next - now <= TimeSpan.Zero) |
| | | 652 | | { |
| | 8 | 653 | | task.RunIteration++; |
| | 8 | 654 | | next = task.AnchorAt + ((task.RunIteration + 1) * interval); |
| | 8 | 655 | | if (task.RunIteration > 10_000) { break; } |
| | | 656 | | } |
| | 15 | 657 | | nextRun = next; |
| | | 658 | | } |
| | | 659 | | else |
| | | 660 | | { |
| | 6 | 661 | | nextRun = task.Cron is not null ? task.Cron.GetNextOccurrence(runStartedAt, _tz) ?? DateTimeOffset.MaxVa |
| | | 662 | | } |
| | | 663 | | |
| | | 664 | | // Publish timestamps atomically to avoid inconsistent snapshot (race seen in CI where |
| | | 665 | | // LastRunAt advanced but NextRunAt still pointed to prior slot). |
| | 21 | 666 | | task.SetTimestamps(runStartedAt, nextRun); |
| | 21 | 667 | | } |
| | 0 | 668 | | catch (OperationCanceledException) when (ct.IsCancellationRequested) { /* ignore */ } |
| | 0 | 669 | | catch (Exception ex) |
| | | 670 | | { |
| | 0 | 671 | | _log.Error(ex, "[Scheduler] Job '{Name}' failed", task.Name); |
| | 0 | 672 | | } |
| | 21 | 673 | | } |
| | | 674 | | |
| | | 675 | | /// <summary> |
| | | 676 | | /// Disposes the scheduler and cancels all running tasks. |
| | | 677 | | /// </summary> |
| | | 678 | | /// <remarks> |
| | | 679 | | /// This method is called to clean up resources used by the scheduler service. |
| | | 680 | | /// It cancels all scheduled tasks and disposes of the runspace pool manager. |
| | | 681 | | /// </remarks> |
| | | 682 | | public void Dispose() |
| | | 683 | | { |
| | 17 | 684 | | CancelAll(); |
| | 17 | 685 | | _pool.Dispose(); |
| | 17 | 686 | | _log.Information("SchedulerService disposed"); |
| | 17 | 687 | | } |
| | | 688 | | } |