using System;
using Svrnty.CQRS.Events.Abstractions.Delivery;
using Svrnty.CQRS.Events.Abstractions.EventStore;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Events.Abstractions.Delivery;

/// <summary>
/// Abstraction for event delivery mechanisms (gRPC, RabbitMQ, Kafka, etc.).
/// </summary>
/// <remarks>
/// <para>
/// Delivery providers are responsible for transporting events from the stream store
/// to consumers using a specific protocol or technology.
/// </para>
/// <para>
/// <strong>Phase 1 Implementation:</strong>
/// gRPC bidirectional streaming for low-latency push-based delivery.
/// </para>
/// <para>
/// <strong>Future Implementations:</strong>
/// - RabbitMQ provider for cross-service messaging
/// - Kafka provider for high-throughput scenarios
/// - SignalR provider for browser clients
/// </para>
/// </remarks>
public interface IEventDeliveryProvider
{
    /// <summary>
    /// Name of this delivery provider (e.g., "gRPC", "RabbitMQ", "Kafka").
    /// </summary>
    string ProviderName { get; }

    /// <summary>
    /// Notify the provider that a new event has been enqueued and is ready for delivery.
    /// </summary>
    /// <param name="streamName">The name of the stream containing the event.</param>
    /// <param name="event">The event that was enqueued.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the async notification.</returns>
    /// <remarks>
    /// <para>
    /// This method is called by the event stream store when new events arrive.
    /// The provider can then push the event to connected consumers or queue it
    /// for later delivery.
    /// </para>
    /// <para>
    /// <strong>Important:</strong>
    /// This method should be fast and non-blocking. Heavy work should be offloaded
    /// to background tasks or channels.
    /// </para>
    /// </remarks>
    Task NotifyEventAvailableAsync(
        string streamName,
        ICorrelatedEvent @event,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Start the delivery provider (initialize connections, background workers, etc.).
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that completes when the provider is started.</returns>
    Task StartAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Stop the delivery provider (close connections, shutdown workers, etc.).
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that completes when the provider is stopped.</returns>
    Task StopAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Get the number of active connections/consumers for this provider.
    /// </summary>
    /// <returns>The number of active consumers.</returns>
    /// <remarks>
    /// Used for monitoring and metrics.
    /// </remarks>
    int GetActiveConsumerCount();

    /// <summary>
    /// Check if this provider is currently healthy and ready to deliver events.
    /// </summary>
    /// <returns>True if healthy, false otherwise.</returns>
    bool IsHealthy();
}