namespace Svrnty.CQRS.Events.Abstractions.Delivery;

/// <summary>
/// Defines the delivery guarantee semantics for event streaming.
/// </summary>
/// <remarks>
/// <para>
/// <strong>AtMostOnce</strong>: Fire-and-forget delivery with no acknowledgment.
/// Fastest option but messages may be lost on failure. Suitable for metrics, telemetry.
/// </para>
/// <para>
/// <strong>AtLeastOnce</strong>: Messages are retried until acknowledged.
/// Most common choice. Messages may be delivered multiple times, so handlers should be idempotent.
/// </para>
/// <para>
/// <strong>ExactlyOnce</strong>: Deduplication ensures no duplicate deliveries.
/// Highest reliability but slowest due to deduplication overhead. Use for financial transactions.
/// </para>
/// </remarks>
public enum DeliverySemantics
{
    /// <summary>
    /// At-most-once delivery: Fire and forget, no retries, might lose messages.
    /// Fastest option with minimal overhead.
    /// </summary>
    AtMostOnce = 0,

    /// <summary>
    /// At-least-once delivery: Retry until acknowledged, might see duplicates.
    /// Recommended default for most scenarios. Requires idempotent handlers.
    /// </summary>
    AtLeastOnce = 1,

    /// <summary>
    /// Exactly-once delivery: Deduplication guarantees no duplicates.
    /// Slowest option due to deduplication checks. Use for critical operations.
    /// </summary>
    ExactlyOnce = 2
}