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

namespace Jellyfin.Server.Implementations.Clustering
{
    using System;
    using System.Collections.Generic;
    using System.Threading;
    using System.Threading.Tasks;
    using Jellyfin.Database.Implementations.Entities;

    /// <summary>
    /// Interface for managing Jellyfin instance registration and lifecycle.
    /// </summary>
    public interface IInstanceRegistry
    {
        /// <summary>
        /// Gets the unique identifier for the current instance.
        /// </summary>
        Guid CurrentInstanceId { get; }

        /// <summary>
        /// Registers the current instance in the database.
        /// </summary>
        /// <param name="hostname">The hostname of the instance.</param>
        /// <param name="processId">The process ID of the instance.</param>
        /// <param name="httpPort">The HTTP port.</param>
        /// <param name="httpsPort">The HTTPS port (optional).</param>
        /// <param name="version">The Jellyfin version.</param>
        /// <param name="capabilities">Instance capabilities (JSON).</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task RegisterInstanceAsync(
            string hostname,
            int processId,
            int httpPort,
            int? httpsPort,
            string version,
            string? capabilities,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Updates the heartbeat timestamp for the current instance.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task UpdateHeartbeatAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Marks the current instance as shutdown in the database.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task ShutdownInstanceAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets all active instances from the database.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>List of active instances.</returns>
        Task<IReadOnlyList<Instance>> GetActiveInstancesAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets a specific instance by ID.
        /// </summary>
        /// <param name="instanceId">The instance ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The instance, or null if not found.</returns>
        Task<Instance?> GetInstanceAsync(Guid instanceId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Removes stale instances from the database.
        /// </summary>
        /// <param name="staleThreshold">Time after which an instance is considered stale.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>Number of instances removed.</returns>
        Task<int> CleanupStaleInstancesAsync(TimeSpan staleThreshold, CancellationToken cancellationToken = default);

        /// <summary>
        /// Checks if the current instance is the primary instance.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>True if this instance is primary.</returns>
        Task<bool> IsPrimaryInstanceAsync(CancellationToken cancellationToken = default);
    }
}