SharepointToolbox-Web/Services/Reports/ScheduledRunCoordinator.cs

using System.Collections.Concurrent;

namespace SharepointToolbox.Web.Services.Reports;

/// <summary>
/// Process-wide coordinator for scheduled-report execution. Covers two operator needs:
///   • <b>Cancel an in-flight run</b> — every active run registers a linked
///     <see cref="CancellationTokenSource"/> keyed by schedule id, so the UI (or a
///     global stop) can abort a report that is currently executing, whether it was
///     started by the scheduler or by "Run now".
///   • <b>Pause future runs</b> — a global flag the background scheduler honours,
///     letting an admin suspend all cadence-triggered runs at once without toggling
///     each schedule's <c>Enabled</c> flag.
///
/// In-memory and singleton. The pause flag does NOT survive a process restart (a
/// restart resumes the scheduler); per-schedule <c>Enabled</c> flags persist and are
/// the durable way to keep a schedule off.
/// </summary>
public sealed class ScheduledRunCoordinator
{
    private readonly ConcurrentDictionary<string, CancellationTokenSource> _active = new();
    private volatile bool _paused;

    /// <summary>True while the scheduler is globally paused (no schedules fire).</summary>
    public bool IsPaused => _paused;

    public void Pause()  => _paused = true;
    public void Resume() => _paused = false;

    /// <summary>True while a run is registered for this schedule id.</summary>
    public bool IsRunning(string scheduleId) => _active.ContainsKey(scheduleId);

    /// <summary>Snapshot of schedule ids with a run in progress.</summary>
    public IReadOnlyCollection<string> RunningIds => _active.Keys.ToArray();

    /// <summary>
    /// Registers a run for <paramref name="scheduleId"/> and returns a token that trips
    /// when either the caller's <paramref name="linked"/> token (e.g. app shutdown) or a
    /// <see cref="Cancel"/>/<see cref="CancelAll"/> call fires. Returns <c>null</c> if a
    /// run is already registered for this schedule — callers must skip to avoid overlap.
    /// Always pair a non-null return with <see cref="Complete"/> in a <c>finally</c>.
    /// </summary>
    public CancellationToken? TryBegin(string scheduleId, CancellationToken linked)
    {
        var cts = CancellationTokenSource.CreateLinkedTokenSource(linked);
        if (!_active.TryAdd(scheduleId, cts)) { cts.Dispose(); return null; }
        return cts.Token;
    }

    /// <summary>Deregisters and disposes the run for this schedule id.</summary>
    public void Complete(string scheduleId)
    {
        if (_active.TryRemove(scheduleId, out var cts)) cts.Dispose();
    }

    /// <summary>Signals cancellation to the run for this schedule id. Returns false if none.</summary>
    public bool Cancel(string scheduleId)
    {
        if (_active.TryGetValue(scheduleId, out var cts))
        {
            try { cts.Cancel(); return true; }
            catch (ObjectDisposedException) { return false; } // completed between lookup and cancel
        }
        return false;
    }

    /// <summary>Signals cancellation to every run in progress. Returns the count signalled.</summary>
    public int CancelAll()
    {
        int n = 0;
        foreach (var cts in _active.Values)
        {
            try { cts.Cancel(); n++; }
            catch (ObjectDisposedException) { /* completed concurrently */ }
        }
        return n;
    }
}