// <copyright file="IPrimaryElectionService.cs" company="PlaceholderCompany">
// Copyright (c) PlaceholderCompany. All rights reserved.
// </copyright>

namespace Jellyfin.Server.Implementations.Clustering
{
    using System;
    using System.Threading;
    using System.Threading.Tasks;

    /// <summary>
    /// Service for managing primary instance election and coordination.
    /// </summary>
    public interface IPrimaryElectionService
    {
        /// <summary>
        /// Event raised when the primary instance changes.
        /// </summary>
        event EventHandler<PrimaryInstanceChangedEventArgs>? PrimaryInstanceChanged;

        /// <summary>
        /// Gets a value indicating whether the current instance is the primary instance.
        /// </summary>
        bool IsPrimary { get; }

        /// <summary>
        /// Gets the ID of the current primary instance, if any.
        /// </summary>
        Guid? PrimaryInstanceId { get; }

        /// <summary>
        /// Starts the primary election service and begins monitoring.
        /// </summary>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task StartAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Stops the primary election service.
        /// </summary>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task StopAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Runs the primary election algorithm.
        /// </summary>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>The ID of the elected primary instance.</returns>
        Task<Guid?> ElectPrimaryAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Checks if this instance should execute scheduled tasks.
        /// </summary>
        /// <returns>True if this instance should execute scheduled tasks, false otherwise.</returns>
        bool ShouldExecuteScheduledTasks();
    }
}