// <copyright file="IDistributedLockManager.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>
    /// Interface for managing distributed locks across multiple instances.
    /// </summary>
    public interface IDistributedLockManager
    {
        /// <summary>
        /// Attempts to acquire a distributed lock.
        /// </summary>
        /// <param name="lockName">The unique name of the lock.</param>
        /// <param name="timeout">The maximum time to wait for the lock.</param>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A disposable lock handle, or null if lock could not be acquired.</returns>
        Task<IDistributedLockHandle?> TryAcquireLockAsync(
            string lockName,
            TimeSpan timeout,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Acquires a distributed lock, waiting indefinitely if necessary.
        /// </summary>
        /// <param name="lockName">The unique name of the lock.</param>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A disposable lock handle.</returns>
        Task<IDistributedLockHandle> AcquireLockAsync(
            string lockName,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Checks if a lock is currently held.
        /// </summary>
        /// <param name="lockName">The name of the lock to check.</param>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>True if the lock is held, false otherwise.</returns>
        Task<bool> IsLockHeldAsync(
            string lockName,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Releases all locks held by the current instance.
        /// </summary>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task ReleaseAllLocksAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Cleans up expired locks from the database.
        /// </summary>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>The number of locks cleaned up.</returns>
        Task<int> CleanupExpiredLocksAsync(CancellationToken cancellationToken = default);
    }

    /// <summary>
    /// Represents a handle to a distributed lock that can be disposed to release the lock.
    /// </summary>
    public interface IDistributedLockHandle : IAsyncDisposable
    {
        /// <summary>
        /// Gets the name of the lock.
        /// </summary>
        string LockName { get; }

        /// <summary>
        /// Gets the instance ID holding the lock.
        /// </summary>
        Guid InstanceId { get; }

        /// <summary>
        /// Gets the time when the lock was acquired.
        /// </summary>
        DateTime AcquiredAt { get; }

        /// <summary>
        /// Gets the time when the lock will expire.
        /// </summary>
        DateTime ExpiresAt { get; }

        /// <summary>
        /// Gets a value indicating whether the lock is still valid.
        /// </summary>
        bool IsValid { get; }

        /// <summary>
        /// Renews the lock by extending its expiration time.
        /// </summary>
        /// <param name="additionalTime">The additional time to extend the lock.</param>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task RenewAsync(TimeSpan additionalTime, CancellationToken cancellationToken = default);
    }
}