using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Jellyfin.Plugin.SSO_Auth.Api;

namespace Jellyfin.Plugin.SSO_Auth.State;

/// <summary>
/// Stores the in-flight OpenID authorization states of a login or linking flow.
/// </summary>
public interface ISsoStateStore
{
    /// <summary>
    /// Stores a newly prepared authorization state.
    /// </summary>
    /// <param name="state">The state to store, keyed on its OpenID state value.</param>
    /// <param name="expiry">How long the state remains usable.</param>
    /// <returns>A task representing the write.</returns>
    Task CreateAsync(TimedAuthorizeState state, TimeSpan expiry);

    /// <summary>
    /// Reads an authorization state without removing it.
    /// </summary>
    /// <param name="state">The OpenID state value.</param>
    /// <returns>The stored state, or <c>null</c> when it is unknown or expired.</returns>
    Task<TimedAuthorizeState> GetAsync(string state);

    /// <summary>
    /// Persists mutations made to an authorization state and refreshes its expiry.
    /// </summary>
    /// <param name="state">The state to persist, keyed on its OpenID state value.</param>
    /// <param name="expiry">How long the state remains usable.</param>
    /// <returns>A task representing the write.</returns>
    Task UpdateAsync(TimedAuthorizeState state, TimeSpan expiry);

    /// <summary>
    /// Reads an authorization state and removes it in the same operation, so it can only be redeemed once.
    /// </summary>
    /// <param name="state">The OpenID state value.</param>
    /// <returns>The stored state, or <c>null</c> when it is unknown, expired or already redeemed.</returns>
    Task<TimedAuthorizeState> ConsumeAsync(string state);

    /// <summary>
    /// Lists every authorization state currently in flight.
    /// </summary>
    /// <returns>The states in flight.</returns>
    Task<IReadOnlyList<TimedAuthorizeState>> ListAsync();
}