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

namespace StellaOps.Cryptography;

/// <summary>
/// Provides per-tenant crypto provider ordering.
/// Implementations are expected to cache results internally (recommended TTL: 60s-5min)
/// to avoid hitting persistence on every crypto operation.
/// </summary>
public interface ITenantCryptoPreferenceProvider
{
    /// <summary>
    /// Returns the tenant's preferred provider ordering, or an empty list if no preferences are set.
    /// Only active preferences should be returned, ordered by priority (ascending).
    /// </summary>
    /// <param name="tenantId">Tenant identifier (normalised, lower-case).</param>
    /// <param name="algorithmScope">
    /// Algorithm scope filter (e.g., "SM", "GOST", or "*" for global).
    /// Implementations should return global ("*") preferences when no scope-specific preferences exist.
    /// </param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Ordered list of provider names; empty list means "use default ordering".</returns>
    Task<IReadOnlyList<string>> GetPreferredProvidersAsync(
        string tenantId,
        string algorithmScope = "*",
        CancellationToken cancellationToken = default);
}