using System.Collections.Generic;
using Svrnty.CQRS.Events.Abstractions.Storage;
using Svrnty.CQRS.Events.Abstractions.Models;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Events.Abstractions.Storage;

/// <summary>
/// Storage abstraction for event stream retention policies.
/// Manages retention policy configuration and enforcement.
/// </summary>
public interface IRetentionPolicyStore
{
    /// <summary>
    /// Set or update a retention policy for a stream.
    /// </summary>
    /// <param name="policy">The retention policy to set.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    /// <remarks>
    /// If a policy already exists for the stream, it will be updated.
    /// Use stream name "*" to set the default policy for all streams.
    /// </remarks>
    Task SetPolicyAsync(
        IRetentionPolicy policy,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get the retention policy for a specific stream.
    /// </summary>
    /// <param name="streamName">The stream name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The retention policy, or null if no specific policy exists.</returns>
    /// <remarks>
    /// Returns the stream-specific policy if it exists.
    /// Does NOT automatically return the default ("*") policy as a fallback.
    /// </remarks>
    Task<IRetentionPolicy?> GetPolicyAsync(
        string streamName,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get all configured retention policies.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of all retention policies, including the default policy.</returns>
    Task<IReadOnlyList<IRetentionPolicy>> GetAllPoliciesAsync(
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Delete a retention policy for a stream.
    /// </summary>
    /// <param name="streamName">The stream name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the policy was deleted, false if it didn't exist.</returns>
    /// <remarks>
    /// Cannot delete the default ("*") policy. Attempting to do so will return false.
    /// </remarks>
    Task<bool> DeletePolicyAsync(
        string streamName,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Apply all enabled retention policies and delete events that exceed retention limits.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Statistics about the cleanup operation.</returns>
    /// <remarks>
    /// This method:
    /// - Iterates through all enabled retention policies
    /// - Deletes events that are older than MaxAge (if configured)
    /// - Deletes events that exceed MaxEventCount (if configured)
    /// - Returns statistics about streams processed and events deleted
    ///
    /// This is typically called by a background service on a schedule.
    /// </remarks>
    Task<RetentionCleanupResult> ApplyRetentionPoliciesAsync(
        CancellationToken cancellationToken = default);
}