using System;
using Svrnty.CQRS.Events.Abstractions.Schema;
using System.Collections.Generic;

namespace Svrnty.CQRS.Events.Abstractions.Subscriptions;

/// <summary>
/// Represents a subscription configuration for consuming events from a stream.
/// </summary>
/// <remarks>
/// <para>
/// A subscription defines HOW and WHAT events should be consumed:
/// - Which stream to listen to
/// - Which subscription mode (Broadcast, Exclusive, ConsumerGroup, ReadReceipt)
/// - Optional event type filters
/// - Delivery options
/// </para>
/// <para>
/// <strong>Subscription vs Consumer:</strong>
/// - Subscription = Configuration (WHAT to listen to)
/// - Consumer = Active listener (WHO is listening)
/// - Multiple consumers can subscribe to the same subscription
/// </para>
/// </remarks>
public interface ISubscription
{
    /// <summary>
    /// Unique identifier for this subscription.
    /// </summary>
    string SubscriptionId { get; }

    /// <summary>
    /// Name of the stream to subscribe to.
    /// </summary>
    string StreamName { get; }

    /// <summary>
    /// Subscription mode determining how events are distributed to consumers.
    /// </summary>
    SubscriptionMode Mode { get; }

    /// <summary>
    /// Optional filter for specific event types.
    /// If null or empty, all event types are included.
    /// </summary>
    HashSet<string>? EventTypeFilter { get; }

    /// <summary>
    /// Whether this subscription is currently active.
    /// Inactive subscriptions do not deliver events.
    /// </summary>
    bool IsActive { get; }

    /// <summary>
    /// When this subscription was created.
    /// </summary>
    DateTimeOffset CreatedAt { get; }

    /// <summary>
    /// Optional description of this subscription's purpose.
    /// </summary>
    string? Description { get; }

    /// <summary>
    /// Maximum number of concurrent consumers allowed for this subscription.
    /// Only applies to ConsumerGroup mode. Null means unlimited.
    /// </summary>
    int? MaxConcurrentConsumers { get; }

    /// <summary>
    /// Visibility timeout for in-flight events (how long before auto-requeue).
    /// Only applies to Exclusive and ConsumerGroup modes.
    /// </summary>
    TimeSpan VisibilityTimeout { get; }

    /// <summary>
    /// Optional metadata for this subscription (tags, labels, etc.).
    /// </summary>
    IReadOnlyDictionary<string, string>? Metadata { get; }

    // ========================================================================
    // Phase 5: Schema Evolution Support
    // ========================================================================

    /// <summary>
    /// Whether to automatically upcast events to newer versions.
    /// </summary>
    /// <remarks>
    /// <para>
    /// When enabled, events are automatically upcast to the latest version
    /// (or specified <see cref="TargetEventVersion"/>) before being delivered
    /// to consumers.
    /// </para>
    /// <para>
    /// Requires <see cref="ISchemaRegistry"/> to be registered in DI.
    /// </para>
    /// </remarks>
    bool EnableUpcasting { get; }

    /// <summary>
    /// Target event version for upcasting (null = latest version).
    /// </summary>
    /// <remarks>
    /// <para>
    /// If null, events are upcast to the latest registered version.
    /// If specified, events are upcast to this specific version.
    /// </para>
    /// <para>
    /// Only used when <see cref="EnableUpcasting"/> is true.
    /// </para>
    /// </remarks>
    int? TargetEventVersion { get; }
}