using System.Collections.Concurrent;
using ZB.MOM.WW.ScadaBridge.Commons.Entities.InboundApi;

namespace ZB.MOM.WW.ScadaBridge.InboundAPI;

/// <summary>
/// WP2.6b (arch-review misc — Inbound API per-request SQL): a short-TTL cache of
/// resolved <c>ApiMethod</c> rows, sitting in front of <c>IInboundApiRepository.GetMethodByNameAsync</c>
/// so a repeated <c>POST /api/{methodName}</c> burst for the same method does not each pay a
/// database round-trip.
/// <para>
/// Two invalidation paths, by design:
/// </para>
/// <list type="bullet">
/// <item><description><b>Fast path.</b> <see cref="ScriptArtifactChangeSubscriber"/> calls
/// <see cref="Invalidate"/> for every name in an <c>ApiMethod</c>
/// <c>ScriptArtifactsChanged</c> notification (bundle-import changes today).</description></item>
/// <item><description><b>Fallback.</b> Every entry — including a negative (not-found) result —
/// expires after <see cref="InboundApiOptions.ApiMethodCacheTtl"/> regardless of whether an
/// invalidation notification ever arrives. This is what keeps an operator edit via the
/// Management API/UI (which does not publish to the change bus) correct within a bounded
/// window, and is also the correctness backstop for the bus's at-least-once/in-process-only
/// contract — a missed or duplicate notification is harmless.</description></item>
/// </list>
/// <para>
/// A negative (method not found) result is cached too — bounded by the same short TTL — so a
/// caller with a provisioned-but-nonexistent method scope (a real misconfiguration case, not an
/// enumeration probe: <c>EndpointExtensions</c> only reaches this cache after the in-memory
/// scope check already passed) does not repeatedly pay a miss query.
/// </para>
/// </summary>
public sealed class ApiMethodCache
{
    private sealed record Entry(ApiMethod? Method, DateTimeOffset ExpiresAtUtc);

    private readonly ConcurrentDictionary<string, Entry> _entries = new(StringComparer.Ordinal);
    private readonly TimeSpan _ttl;
    private readonly TimeProvider _timeProvider;

    /// <summary>Initializes the cache.</summary>
    /// <param name="ttl">How long a resolved (or not-found) entry stays valid.</param>
    /// <param name="timeProvider">Optional time source; defaults to <see cref="TimeProvider.System"/>.</param>
    public ApiMethodCache(TimeSpan ttl, TimeProvider? timeProvider = null)
    {
        if (ttl <= TimeSpan.Zero)
            throw new ArgumentOutOfRangeException(nameof(ttl), ttl, "ApiMethodCache TTL must be positive.");

        _ttl = ttl;
        _timeProvider = timeProvider ?? TimeProvider.System;
    }

    /// <summary>
    /// Returns the cached entry for <paramref name="methodName"/> if it has not expired;
    /// otherwise invokes <paramref name="fetch"/>, caches the result (found or not-found), and
    /// returns it. Concurrent callers on a cache miss for the SAME name may each invoke
    /// <paramref name="fetch"/> once (last write wins) — an acceptable, rare race in exchange
    /// for not serializing every miss behind a lock; the point of the cache is to absorb
    /// repeated hits, not to fully dedupe a first-request thundering herd.
    /// </summary>
    /// <param name="methodName">The method name to resolve.</param>
    /// <param name="fetch">Loads the current row from the repository on a cache miss.</param>
    /// <param name="cancellationToken">Cancellation token for the fetch.</param>
    public async Task<ApiMethod?> GetOrFetchAsync(
        string methodName,
        Func<CancellationToken, Task<ApiMethod?>> fetch,
        CancellationToken cancellationToken)
    {
        var now = _timeProvider.GetUtcNow();
        if (_entries.TryGetValue(methodName, out var cached) && cached.ExpiresAtUtc > now)
        {
            return cached.Method;
        }

        var method = await fetch(cancellationToken).ConfigureAwait(false);
        _entries[methodName] = new Entry(method, now + _ttl);
        return method;
    }

    /// <summary>Drops the cached entry for one method name. Safe to call for an unknown name.</summary>
    /// <param name="methodName">The method name to invalidate.</param>
    public void Invalidate(string methodName) => _entries.TryRemove(methodName, out _);

    /// <summary>Diagnostic helper — the number of currently-cached entries (including expired-but-not-evicted ones).</summary>
    internal int Count => _entries.Count;
}