// <copyright file="IFacetExtractor.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>

namespace StellaOps.Facet;

/// <summary>
/// Extracts facet information from container images.
/// </summary>
public interface IFacetExtractor
{
    /// <summary>
    /// Extract facets from a local directory (unpacked image).
    /// </summary>
    /// <param name="rootPath">Path to the unpacked image root.</param>
    /// <param name="options">Extraction options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Extraction result with all facet entries.</returns>
    Task<FacetExtractionResult> ExtractFromDirectoryAsync(
        string rootPath,
        FacetExtractionOptions? options = null,
        CancellationToken ct = default);

    /// <summary>
    /// Extract facets from a tar archive.
    /// </summary>
    /// <param name="tarStream">Stream containing the tar archive.</param>
    /// <param name="options">Extraction options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Extraction result with all facet entries.</returns>
    Task<FacetExtractionResult> ExtractFromTarAsync(
        Stream tarStream,
        FacetExtractionOptions? options = null,
        CancellationToken ct = default);

    /// <summary>
    /// Extract facets from an OCI image layer.
    /// </summary>
    /// <param name="layerStream">Stream containing the layer (tar.gz).</param>
    /// <param name="options">Extraction options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Extraction result with all facet entries.</returns>
    Task<FacetExtractionResult> ExtractFromOciLayerAsync(
        Stream layerStream,
        FacetExtractionOptions? options = null,
        CancellationToken ct = default);
}