namespace FrameProcessor.UrlFetch;

/// <summary>
/// Fetches a remote image into an in-memory stream for the URL-ingestion endpoint
/// (SPEC.md §4.2). Enforces the guardrails from SPEC.md §8 — max response size,
/// timeout, and max redirect hops — surfacing failures as <see cref="ImageFetchException"/>
/// so callers can map them to <c>502 Bad Gateway</c>.
/// </summary>
public interface IImageUrlFetcher
{
    /// <summary>
    /// Fetch the image at <paramref name="uri"/>. The returned stream is positioned
    /// at zero and owned by the caller.
    /// </summary>
    /// <exception cref="ImageFetchException">
    /// Timeout, non-2xx status, response exceeding the configured maximum, or
    /// excessive redirect hops.
    /// </exception>
    Task<Stream> FetchAsync(Uri uri, CancellationToken cancellationToken);
}
