// <copyright file="IHlcSchedulerDequeueService.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>

using StellaOps.HybridLogicalClock;

namespace StellaOps.Scheduler.Queue.Hlc;

/// <summary>
/// Service for HLC-ordered scheduler job dequeuing.
/// </summary>
/// <remarks>
/// This service provides deterministic, HLC-ordered retrieval of scheduler log entries
/// for processing. The HLC ordering guarantees causal consistency across distributed nodes.
/// </remarks>
public interface IHlcSchedulerDequeueService
{
    /// <summary>
    /// Dequeues scheduler log entries in HLC order.
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="limit">Maximum number of entries to return.</param>
    /// <param name="partitionKey">Optional partition key to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The dequeue result with entries in HLC order.</returns>
    Task<SchedulerHlcDequeueResult> DequeueAsync(
        string tenantId,
        int limit,
        string? partitionKey = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Dequeues scheduler log entries within an HLC time range.
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="startHlc">HLC range start (inclusive, null for unbounded).</param>
    /// <param name="endHlc">HLC range end (inclusive, null for unbounded).</param>
    /// <param name="limit">Maximum number of entries to return.</param>
    /// <param name="partitionKey">Optional partition key to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The dequeue result with entries in HLC order.</returns>
    Task<SchedulerHlcDequeueResult> DequeueByRangeAsync(
        string tenantId,
        HlcTimestamp? startHlc,
        HlcTimestamp? endHlc,
        int limit,
        string? partitionKey = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Dequeues scheduler log entries after a specific HLC timestamp (cursor-based).
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="afterHlc">HLC timestamp to start after (exclusive).</param>
    /// <param name="limit">Maximum number of entries to return.</param>
    /// <param name="partitionKey">Optional partition key to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The dequeue result with entries in HLC order.</returns>
    Task<SchedulerHlcDequeueResult> DequeueAfterAsync(
        string tenantId,
        HlcTimestamp afterHlc,
        int limit,
        string? partitionKey = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a single scheduler log entry by job ID.
    /// </summary>
    /// <param name="tenantId">Tenant identifier.</param>
    /// <param name="jobId">The job identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The scheduler log entry if found, null otherwise.</returns>
    Task<Persistence.Postgres.Models.SchedulerLogEntry?> GetByJobIdAsync(
        string tenantId,
        Guid jobId,
        CancellationToken cancellationToken = default);
}