ScadaBridge/tests/ZB.MOM.WW.ScadaBridge.InboundAPI.Tests/ApiMethodCacheTests.cs

using ZB.MOM.WW.ScadaBridge.Commons.Entities.InboundApi;

namespace ZB.MOM.WW.ScadaBridge.InboundAPI.Tests;

/// <summary>
/// <see cref="ApiMethodCache"/>
/// hit/miss/expiry/invalidation behavior, independent of the endpoint and subscriber wiring
/// (covered separately by <see cref="ScriptArtifactChangeSubscriberTests"/>).
/// </summary>
public class ApiMethodCacheTests
{
    private static ApiMethod Method(string name) => new(name, "return 1;") { Id = 1 };

    /// <summary>Verifies that a second call within the TTL is served from the cache without refetching.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetOrFetchAsync_SecondCallWithinTtl_ServesFromCache_NoRefetch()
    {
        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
        var fetchCount = 0;
        Task<ApiMethod?> Fetch(CancellationToken _)
        {
            fetchCount++;
            return Task.FromResult<ApiMethod?>(Method("m"));
        }

        var first = await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
        var second = await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);

        Assert.Equal(1, fetchCount);
        Assert.Same(first, second);
    }

    /// <summary>Verifies that a call after the TTL expires refetches the method.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetOrFetchAsync_AfterTtlExpiry_Refetches()
    {
        var time = new FakeTimeProvider(DateTimeOffset.UtcNow);
        var cache = new ApiMethodCache(TimeSpan.FromSeconds(1), time);
        var fetchCount = 0;
        Task<ApiMethod?> Fetch(CancellationToken _)
        {
            fetchCount++;
            return Task.FromResult<ApiMethod?>(Method("m"));
        }

        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
        time.Advance(TimeSpan.FromSeconds(2));
        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);

        Assert.Equal(2, fetchCount);
    }

    /// <summary>Verifies that a negative result is cached until the TTL expires.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetOrFetchAsync_NegativeResult_IsCachedUntilTtlExpires()
    {
        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
        var fetchCount = 0;
        Task<ApiMethod?> Fetch(CancellationToken _)
        {
            fetchCount++;
            return Task.FromResult<ApiMethod?>(null);
        }

        var first = await cache.GetOrFetchAsync("missing", Fetch, CancellationToken.None);
        var second = await cache.GetOrFetchAsync("missing", Fetch, CancellationToken.None);

        Assert.Null(first);
        Assert.Null(second);
        Assert.Equal(1, fetchCount);
    }

    /// <summary>Verifies that invalidating an entry makes the next call refetch it.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Invalidate_DropsEntry_NextCallRefetches()
    {
        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
        var fetchCount = 0;
        Task<ApiMethod?> Fetch(CancellationToken _)
        {
            fetchCount++;
            return Task.FromResult<ApiMethod?>(Method("m"));
        }

        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
        cache.Invalidate("m");
        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);

        Assert.Equal(2, fetchCount);
    }

    /// <summary>Verifies that invalidating an unknown method name does not throw.</summary>
    [Fact]
    public void Invalidate_UnknownName_DoesNotThrow()
    {
        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
        cache.Invalidate("never-cached");
    }

    /// <summary>Verifies that a non-positive TTL makes the constructor throw.</summary>
    [Fact]
    public void Constructor_NonPositiveTtl_Throws()
    {
        Assert.Throws<ArgumentOutOfRangeException>(() => new ApiMethodCache(TimeSpan.Zero));
        Assert.Throws<ArgumentOutOfRangeException>(() => new ApiMethodCache(TimeSpan.FromSeconds(-1)));
    }

    /// <summary>Minimal controllable <see cref="TimeProvider"/> for TTL-expiry tests.</summary>
    private sealed class FakeTimeProvider : TimeProvider
    {
        private DateTimeOffset _now;
        /// <summary>Initializes the provider at the given start time.</summary>
        /// <param name="start">The initial UTC time.</param>
        public FakeTimeProvider(DateTimeOffset start) => _now = start;
        /// <summary>Advances the current time.</summary>
        /// <param name="by">The amount of time to advance.</param>
        public void Advance(TimeSpan by) => _now += by;
        /// <inheritdoc />
        public override DateTimeOffset GetUtcNow() => _now;
    }

    /// <summary>Verifies that expired entries are pruned on a miss once the cache is large.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetOrFetchAsync_Miss_PrunesExpiredEntries()
    {
        // Review 2026-10-21 05/M3: expired entries for methods no longer called were never evicted.
        var time = new FakeTimeProvider(DateTimeOffset.UtcNow);
        var cache = new ApiMethodCache(TimeSpan.FromSeconds(1), time);
        Task<ApiMethod?> Fetch(CancellationToken _) => Task.FromResult<ApiMethod?>(null);

        for (var i = 0; i < 300; i++)
            await cache.GetOrFetchAsync("m" + i, Fetch, CancellationToken.None);
        Assert.Equal(300, cache.Count);

        time.Advance(TimeSpan.FromSeconds(2));
        await cache.GetOrFetchAsync("fresh", Fetch, CancellationToken.None);

        Assert.Equal(1, cache.Count);
    }
}