using StellaOps.Scheduler.Models;

namespace StellaOps.Scheduler.ImpactIndex;

/// <summary>
/// Provides read access to the scheduler impact index.
/// </summary>
public interface IImpactIndex
{
    /// <summary>
    /// Resolves the impacted image set for the provided package URLs.
    /// </summary>
    /// <param name="purls">Package URLs to look up.</param>
    /// <param name="usageOnly">When true, restricts results to components marked as runtime/entrypoint usage.</param>
    /// <param name="selector">Selector scoping the query.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    ValueTask<ImpactSet> ResolveByPurlsAsync(
        IEnumerable<string> purls,
        bool usageOnly,
        Selector selector,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Resolves impacted images by vulnerability identifiers if the index has the mapping available.
    /// </summary>
    /// <param name="vulnerabilityIds">Vulnerability identifiers to look up.</param>
    /// <param name="usageOnly">When true, restricts results to components marked as runtime/entrypoint usage.</param>
    /// <param name="selector">Selector scoping the query.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    ValueTask<ImpactSet> ResolveByVulnerabilitiesAsync(
        IEnumerable<string> vulnerabilityIds,
        bool usageOnly,
        Selector selector,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Resolves all tracked images for the provided selector.
    /// </summary>
    /// <param name="selector">Selector scoping the query.</param>
    /// <param name="usageOnly">When true, restricts results to images with entrypoint usage.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    ValueTask<ImpactSet> ResolveAllAsync(
        Selector selector,
        bool usageOnly,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Removes an image digest and its component mappings from the index.
    /// Used when an image is deleted or aged out.
    /// </summary>
    ValueTask RemoveAsync(
        string imageDigest,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Creates a compacted snapshot of the index for persistence (e.g., RocksDB/Redis).
    /// </summary>
    ValueTask<ImpactIndexSnapshot> CreateSnapshotAsync(
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Restores index state from a previously persisted snapshot.
    /// </summary>
    ValueTask RestoreSnapshotAsync(
        ImpactIndexSnapshot snapshot,
        CancellationToken cancellationToken = default);
}