// <copyright file="ICacheCoordinator.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 coordinating cache invalidation across multiple instances.
    /// </summary>
    public interface ICacheCoordinator
    {
        /// <summary>
        /// Starts the cache coordinator.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task StartAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Stops the cache coordinator.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task StopAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates an item cache across all instances.
        /// </summary>
        /// <param name="itemId">The item ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidateItemAsync(Guid itemId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates user data cache across all instances.
        /// </summary>
        /// <param name="userId">The user ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidateUserDataAsync(Guid userId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates an image cache across all instances.
        /// </summary>
        /// <param name="itemId">The item ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidateImageAsync(Guid itemId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates all caches of a specific type across all instances.
        /// </summary>
        /// <param name="cacheType">The cache type.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidateAllAsync(CacheInvalidationType cacheType, CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates a library cache across all instances.
        /// </summary>
        /// <param name="libraryId">The library ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidateLibraryAsync(Guid libraryId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates a person cache across all instances.
        /// </summary>
        /// <param name="personId">The person ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidatePersonAsync(Guid personId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Invalidates metadata for an item across all instances.
        /// </summary>
        /// <param name="itemId">The item ID.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        Task InvalidateMetadataAsync(Guid itemId, CancellationToken cancellationToken = default);
    }
}