namespace ZB.MOM.WW.MxGateway.Server.Galaxy;

/// <summary>Cache for Galaxy Repository hierarchy data.</summary>
public interface IGalaxyHierarchyCache
{
    /// <summary>The latest cache entry. Status freshness is recomputed against the clock.</summary>
    GalaxyHierarchyCacheEntry Current { get; }

    /// <summary>
    ///     Forces a refresh against the Galaxy Repository. Performs a cheap
    ///     <c>time_of_last_deploy</c> probe first and only re-queries the heavy hierarchy +
    ///     attributes rowsets when the deploy time has changed since the last successful
    ///     refresh.
    /// </summary>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    Task RefreshAsync(CancellationToken cancellationToken);

    /// <summary>
    ///     Awaits the first completed refresh attempt (success or failure). Useful for
    ///     gRPC handlers that want to serve from cache without returning Unavailable on the
    ///     very first request after gateway start.
    /// </summary>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    Task WaitForFirstLoadAsync(CancellationToken cancellationToken);
}