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

namespace Svrnty.CQRS.Events.ConsumerGroups.Abstractions;

/// <summary>
/// Store for managing consumer group offsets and consumer registration.
/// Enables multiple consumers to coordinate processing of event streams.
/// </summary>
public interface IConsumerOffsetStore
{
    /// <summary>
    /// Commit an offset for a consumer in a group.
    /// This records that the consumer has successfully processed all events up to this offset.
    /// </summary>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="consumerId">The consumer ID within the group.</param>
    /// <param name="streamName">The stream name.</param>
    /// <param name="offset">The offset to commit.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    Task CommitOffsetAsync(
        string groupId,
        string consumerId,
        string streamName,
        long offset,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get the last committed offset for a consumer group.
    /// Returns the minimum offset across all consumers in the group, representing
    /// the safe point up to which all events have been processed.
    /// </summary>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="streamName">The stream name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The last committed offset, or null if no offset has been committed.</returns>
    Task<long?> GetCommittedOffsetAsync(
        string groupId,
        string streamName,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get offsets for all consumers in a group.
    /// Useful for monitoring consumer lag and group status.
    /// </summary>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="streamName">The stream name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Dictionary mapping consumer IDs to their committed offsets.</returns>
    Task<IReadOnlyDictionary<string, long>> GetGroupOffsetsAsync(
        string groupId,
        string streamName,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Register a consumer as active (heartbeat).
    /// Consumers should call this periodically to signal they are alive.
    /// </summary>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="consumerId">The consumer ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    Task RegisterConsumerAsync(
        string groupId,
        string consumerId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Unregister a consumer (graceful shutdown).
    /// Should be called when a consumer is shutting down gracefully.
    /// </summary>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="consumerId">The consumer ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    Task UnregisterConsumerAsync(
        string groupId,
        string consumerId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get all active consumers in a group.
    /// Returns consumers that have registered and are sending heartbeats.
    /// </summary>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of active consumer information.</returns>
    Task<IReadOnlyList<ConsumerInfo>> GetActiveConsumersAsync(
        string groupId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get all registered consumer groups.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of group IDs.</returns>
    Task<IReadOnlyList<string>> GetAllGroupsAsync(
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Clean up stale consumers that haven't sent heartbeats within the timeout period.
    /// Typically called by a background health monitor.
    /// </summary>
    /// <param name="sessionTimeout">Time after which a consumer is considered stale.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of removed consumer infos.</returns>
    Task<IReadOnlyList<ConsumerInfo>> CleanupStaleConsumersAsync(
        TimeSpan sessionTimeout,
        CancellationToken cancellationToken = default);
}