ScadaBridge/tests/ZB.MOM.WW.ScadaBridge.AuditLog.Tests/Site/SiteAuditBacklogReporterCadenceTests.cs

using System.Diagnostics;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using NSubstitute;
using ZB.MOM.WW.ScadaBridge.AuditLog.Site;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
using ZB.MOM.WW.ScadaBridge.Commons.Types;
using ZB.MOM.WW.ScadaBridge.HealthMonitoring;

namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Site;

/// <summary>
/// The backlog reporter's poll cadence is configurable via
/// <see cref="SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/> instead of the
/// old hard-coded 30 s constant.
/// </summary>
public class SiteAuditBacklogReporterCadenceTests
{
    private static SiteAuditBacklogReporter Create(
        IOptions<SqliteAuditWriterOptions>? options, TimeSpan? explicitInterval = null) =>
        new(
            Substitute.For<ISiteAuditQueue>(),
            Substitute.For<ISiteHealthCollector>(),
            NullLogger<SiteAuditBacklogReporter>.Instance,
            explicitInterval,
            options);

    /// <summary>Verifies that stopping the reporter while a probe is in flight lets the loop complete cleanly.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task StopAsync_WhileProbeInFlight_LoopCompletesCleanly()
    {
        // SafeProbeAsync rethrows OperationCanceledException by design so a shutdown
        // aborts the probe promptly — but RunLoopAsync must absorb it, because StopAsync
        // hands _loop straight to the host and a canceled task there throws out of
        // Host.StopAsync. Mirrors the guard SiteAuditRetentionService already carries
        // (arch-review 04 round 2, R7).
        var probeStarted = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
        var queue = Substitute.For<ISiteAuditQueue>();
        queue.GetBacklogStatsAsync(Arg.Any<CancellationToken>())
            .Returns(ci => BlockUntilCancelledAsync(probeStarted, ci.Arg<CancellationToken>()));

        var reporter = new SiteAuditBacklogReporter(
            queue,
            Substitute.For<ISiteHealthCollector>(),
            NullLogger<SiteAuditBacklogReporter>.Instance,
            TimeSpan.FromHours(1),
            null);

        await reporter.StartAsync(CancellationToken.None);
        await probeStarted.Task; // the immediate first probe is now in flight

        // The assertion is that awaiting the loop task does not throw.
        await reporter.StopAsync(CancellationToken.None);
        reporter.Dispose();
    }

    private static async Task<SiteAuditBacklogSnapshot> BlockUntilCancelledAsync(
        TaskCompletionSource started, CancellationToken ct)
    {
        started.TrySetResult();
        await Task.Delay(Timeout.Infinite, ct);
        throw new UnreachableException("the delay above always throws on cancellation");
    }

    /// <summary>Verifies that stopping the reporter after it has been disposed does not throw.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task StopAsync_AfterDispose_DoesNotThrow()
    {
        // Regression (follow-up): Dispose tears down the CTS StopAsync
        // cancels, and the host does not guarantee StopAsync is driven before the DI
        // container is disposed. Cancel() on a disposed CTS throws, and letting that
        // escape an IHostedService aborts the host's whole shutdown sequence.
        var reporter = Create(Options.Create(new SqliteAuditWriterOptions()), TimeSpan.FromHours(1));

        await reporter.StartAsync(CancellationToken.None);
        reporter.Dispose();

        // The assertion is the absence of ObjectDisposedException.
        await reporter.StopAsync(CancellationToken.None);
        reporter.Dispose();
    }

    /// <summary>Verifies that the poll cadence comes from the options when one is configured.</summary>
    [Fact]
    public void Cadence_ComesFromOptions_WhenConfigured()
    {
        var options = Options.Create(new SqliteAuditWriterOptions { BacklogPollIntervalSeconds = 12 });

        var reporter = Create(options);

        Assert.Equal(TimeSpan.FromSeconds(12), reporter.RefreshInterval);
    }

    /// <summary>Verifies that a non-positive configured interval falls back to the default cadence.</summary>
    [Fact]
    public void Cadence_FallsBackToDefault_WhenOptionsNonPositive()
    {
        var options = Options.Create(new SqliteAuditWriterOptions { BacklogPollIntervalSeconds = 0 });

        var reporter = Create(options);

        Assert.Equal(SiteAuditBacklogReporter.DefaultRefreshInterval, reporter.RefreshInterval);
    }

    /// <summary>Verifies that the default cadence is used when no options are supplied.</summary>
    [Fact]
    public void Cadence_FallsBackToDefault_WhenNoOptions()
    {
        var reporter = Create(options: null);

        Assert.Equal(SiteAuditBacklogReporter.DefaultRefreshInterval, reporter.RefreshInterval);
    }

    /// <summary>Verifies that an explicitly supplied interval takes precedence over the options value.</summary>
    [Fact]
    public void ExplicitInterval_WinsOverOptions()
    {
        var options = Options.Create(new SqliteAuditWriterOptions { BacklogPollIntervalSeconds = 12 });

        var reporter = Create(options, explicitInterval: TimeSpan.FromSeconds(3));

        Assert.Equal(TimeSpan.FromSeconds(3), reporter.RefreshInterval);
    }

    // ----- Stale-Pending signal (review F5) ----- //

    /// <summary>Verifies that a stale pending backlog is logged as a warning and that repeat warnings are then rate-limited.</summary>
    [Fact]
    public void StalePendingBacklog_IsWarned_ThenRateLimited()
    {
        // Pending rows are exempt from the retention purge by design, so a standing Pending
        // backlog is the one site-store condition that never self-heals on age — it clears
        // only when central acknowledges the rows. It is worth a log line, not just a number
        // on the health report, and the warning must not spam every 30 s poll.
        var logger = new CapturingLogger();
        var reporter = new SiteAuditBacklogReporter(
            Substitute.For<ISiteAuditQueue>(),
            Substitute.For<ISiteHealthCollector>(),
            logger,
            TimeSpan.FromHours(1),
            null);

        var stale = DateTime.UtcNow - SiteAuditBacklogReporter.StalePendingThreshold - TimeSpan.FromHours(1);
        reporter.WarnIfPendingIsStale(stale, pendingCount: 4321);
        reporter.WarnIfPendingIsStale(stale, pendingCount: 4321); // same poll cycle-ish

        var warning = Assert.Single(logger.Entries, e => e.Level == LogLevel.Warning);
        Assert.Contains("4321", warning.Message);
        Assert.Contains("pending", warning.Message, StringComparison.OrdinalIgnoreCase);
    }

    /// <summary>Verifies that a fresh or empty pending backlog does not log a warning.</summary>
    [Fact]
    public void FreshOrEmptyPendingBacklog_IsNotWarned()
    {
        var logger = new CapturingLogger();
        var reporter = new SiteAuditBacklogReporter(
            Substitute.For<ISiteAuditQueue>(),
            Substitute.For<ISiteHealthCollector>(),
            logger,
            TimeSpan.FromHours(1),
            null);

        reporter.WarnIfPendingIsStale(null, pendingCount: 0);                    // nothing pending
        reporter.WarnIfPendingIsStale(DateTime.UtcNow.AddMinutes(-5), 12);       // a normal drain lag

        Assert.DoesNotContain(logger.Entries, e => e.Level == LogLevel.Warning);
    }

    /// <summary>Captures log entries so the stale-pending signal can be asserted.</summary>
    private sealed class CapturingLogger : ILogger<SiteAuditBacklogReporter>
    {
        /// <summary>Gets the log entries captured so far.</summary>
        public List<(LogLevel Level, Exception? Exception, string Message)> Entries { get; } = new();

        /// <summary>Returns no scope; the fake logger does not track scopes.</summary>
        /// <typeparam name="TState">The type of the scope state.</typeparam>
        /// <param name="state">The scope state, ignored.</param>
        /// <returns>Always null or a no-op scope.</returns>
        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;

        /// <summary>Reports every log level as enabled.</summary>
        /// <param name="logLevel">The log level being queried.</param>
        /// <returns>Always true.</returns>
        public bool IsEnabled(LogLevel logLevel) => true;

        /// <summary>Records the log entry for later assertions.</summary>
        /// <typeparam name="TState">The type of the log state.</typeparam>
        /// <param name="logLevel">The severity of the entry.</param>
        /// <param name="eventId">The event identifier.</param>
        /// <param name="state">The log state.</param>
        /// <param name="exception">The associated exception, if any.</param>
        /// <param name="formatter">Formats the state and exception into the message.</param>
        public void Log<TState>(
            LogLevel logLevel,
            EventId eventId,
            TState state,
            Exception? exception,
            Func<TState, Exception?, string> formatter)
        {
            Entries.Add((logLevel, exception, formatter(state, exception)));
        }
    }
}