using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

namespace StellaOps.Cryptography;

/// <summary>
/// Interface for cryptographic hashing operations with compliance profile support.
/// </summary>
public interface ICryptoHash
{
    #region Algorithm-based methods (backward compatible)

    /// <summary>
    /// Computes a hash using the specified or default algorithm.
    /// </summary>
    /// <param name="data">The data to hash.</param>
    /// <param name="algorithmId">Optional algorithm identifier. If null, uses the default algorithm.</param>
    /// <returns>The hash bytes.</returns>
    byte[] ComputeHash(ReadOnlySpan<byte> data, string? algorithmId = null);

    /// <summary>
    /// Computes a hash and returns it as a lowercase hex string.
    /// </summary>
    string ComputeHashHex(ReadOnlySpan<byte> data, string? algorithmId = null);

    /// <summary>
    /// Computes a hash and returns it as a Base64 string.
    /// </summary>
    string ComputeHashBase64(ReadOnlySpan<byte> data, string? algorithmId = null);

    /// <summary>
    /// Computes a hash from a stream asynchronously.
    /// </summary>
    ValueTask<byte[]> ComputeHashAsync(Stream stream, string? algorithmId = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Computes a hash from a stream and returns it as a lowercase hex string.
    /// </summary>
    ValueTask<string> ComputeHashHexAsync(Stream stream, string? algorithmId = null, CancellationToken cancellationToken = default);

    #endregion

    #region Purpose-based methods (preferred for compliance)

    /// <summary>
    /// Computes a hash for the specified purpose using the active compliance profile's algorithm.
    /// </summary>
    /// <param name="data">The data to hash.</param>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <returns>The hash bytes.</returns>
    byte[] ComputeHashForPurpose(ReadOnlySpan<byte> data, string purpose);

    /// <summary>
    /// Computes a hash for the specified purpose and returns it as a lowercase hex string.
    /// </summary>
    /// <param name="data">The data to hash.</param>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <returns>The hash as a lowercase hex string.</returns>
    string ComputeHashHexForPurpose(ReadOnlySpan<byte> data, string purpose);

    /// <summary>
    /// Computes a hash for the specified purpose and returns it as a Base64 string.
    /// </summary>
    /// <param name="data">The data to hash.</param>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <returns>The hash as a Base64 string.</returns>
    string ComputeHashBase64ForPurpose(ReadOnlySpan<byte> data, string purpose);

    /// <summary>
    /// Computes a hash for the specified purpose from a stream asynchronously.
    /// </summary>
    /// <param name="stream">The stream to hash.</param>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The hash bytes.</returns>
    ValueTask<byte[]> ComputeHashForPurposeAsync(Stream stream, string purpose, CancellationToken cancellationToken = default);

    /// <summary>
    /// Computes a hash for the specified purpose from a stream and returns it as a lowercase hex string.
    /// </summary>
    /// <param name="stream">The stream to hash.</param>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The hash as a lowercase hex string.</returns>
    ValueTask<string> ComputeHashHexForPurposeAsync(Stream stream, string purpose, CancellationToken cancellationToken = default);

    #endregion

    #region Metadata methods

    /// <summary>
    /// Gets the algorithm that will be used for the specified purpose based on the active compliance profile.
    /// </summary>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <returns>The algorithm identifier.</returns>
    string GetAlgorithmForPurpose(string purpose);

    /// <summary>
    /// Gets the hash prefix for the specified purpose (e.g., "blake3:", "sha256:", "gost3411:").
    /// </summary>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <returns>The hash prefix string.</returns>
    string GetHashPrefix(string purpose);

    /// <summary>
    /// Computes a hash for the specified purpose and returns it with the appropriate prefix.
    /// </summary>
    /// <param name="data">The data to hash.</param>
    /// <param name="purpose">The hash purpose from <see cref="HashPurpose"/>.</param>
    /// <returns>The prefixed hash string (e.g., "blake3:abc123...").</returns>
    string ComputePrefixedHashForPurpose(ReadOnlySpan<byte> data, string purpose);

    #endregion
}