using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

namespace Dpz.Core.Infrastructure.Imaging;

/// <summary>
/// 通过文件头(magic bytes) 识别图片格式。仅做轻量识别，不做编解码、缩放等图像处理。
/// </summary>
public interface IImageFormatDetector
{
    /// <summary>
    /// 从字节数组识别图片格式。
    /// </summary>
    /// <param name="bytes">图片原始字节</param>
    /// <returns>识别结果；若无法识别则返回 <see cref="ImageFormatInfo.Unknown"/></returns>
    ImageFormatInfo Detect(ReadOnlySpan<byte> bytes);

    /// <summary>
    /// 从流识别图片格式。会读取流头部少量字节；调用者负责流的生命周期。
    /// 若流支持 Seek，会在读取后回到原位置；否则流的位置会前进。
    /// </summary>
    /// <param name="stream">图片字节流</param>
    /// <param name="cancellationToken">取消标记</param>
    /// <returns>识别结果；若无法识别则返回 <see cref="ImageFormatInfo.Unknown"/></returns>
    ValueTask<ImageFormatInfo> DetectAsync(
        Stream stream,
        CancellationToken cancellationToken = default
    );
}