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

/// <summary>
///     Persists the latest Galaxy Repository browse dataset to disk and reloads
///     it at startup. Lets <see cref="GalaxyHierarchyCache"/> serve last-known
///     browse data when the Galaxy database is unreachable on a cold start.
/// </summary>
public interface IGalaxyHierarchySnapshotStore
{
    /// <summary>
    ///     Writes <paramref name="snapshot"/> to disk, replacing any previous
    ///     snapshot atomically. A no-op when snapshot persistence is disabled.
    /// </summary>
    /// <param name="snapshot">The browse dataset to persist.</param>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    Task SaveAsync(GalaxyHierarchySnapshot snapshot, CancellationToken cancellationToken);

    /// <summary>
    ///     Reads the persisted Galaxy browse dataset.
    /// </summary>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    /// <returns>
    ///     The persisted snapshot, or <see langword="null"/> when none exists,
    ///     persistence is disabled, or the on-disk file uses an unrecognized
    ///     schema version.
    /// </returns>
    Task<GalaxyHierarchySnapshot?> TryLoadAsync(CancellationToken cancellationToken);
}