using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace MediaBrowser.Controller.Session;

/// <summary>
/// The shared record of which instance holds which session. Entries expire, so an instance that stops
/// refreshing them drops out of every other instance's view instead of lingering.
/// </summary>
public interface ISessionDirectory
{
    /// <summary>
    /// Allocates the next connection epoch for a session. The counter lives in the shared store, so the
    /// epochs of every instance are ordered by one clock instead of being compared across machines.
    /// </summary>
    /// <param name="sessionId">The session identifier.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The allocated epoch, which is greater than every epoch allocated for the session before it.</returns>
    Task<long> AllocateConnectionEpochAsync(string sessionId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Claims a session for the publishing instance and restarts its expiry. The claim is refused when
    /// another instance holds the connection, so an instance that merely served a request for the session
    /// cannot take ownership of it.
    /// </summary>
    /// <param name="entry">The entry.</param>
    /// <param name="connectionEpoch">The epoch of the publishing instance's connection to the session, or zero when it holds none.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns><c>true</c> if the entry was written.</returns>
    Task<bool> PublishAsync(SessionDirectoryEntry entry, long connectionEpoch, CancellationToken cancellationToken = default);

    /// <summary>
    /// Removes an entry, but only while the calling instance still owns it.
    /// </summary>
    /// <param name="sessionId">The session identifier.</param>
    /// <param name="ownerPod">The instance requesting the removal.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task representing the operation.</returns>
    Task RemoveAsync(string sessionId, string ownerPod, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets one entry by session identifier.
    /// </summary>
    /// <param name="sessionId">The session identifier.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The entry, or <c>null</c> when the session is in no instance's directory.</returns>
    /// <exception cref="System.Exception">The store could not be read. An unreadable store is not an absent session.</exception>
    Task<SessionDirectoryEntry?> GetAsync(string sessionId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets every entry that has not expired.
    /// </summary>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The entries.</returns>
    Task<IReadOnlyList<SessionDirectoryEntry>> GetAllAsync(CancellationToken cancellationToken = default);
}