namespace ErsatzTV.Core.Interfaces.Streaming;

/// <summary>
///     Fetches a remote (http/https) image for the graphics engine, under a bounded timeout and a
///     bounded response size.
/// </summary>
public interface IRemoteImageFetcher
{
    /// <summary>
    ///     Fetches <paramref name="uri" /> fully into memory.
    /// </summary>
    /// <returns>
    ///     A seekable, fully-buffered stream positioned at zero. The caller owns and must dispose it.
    /// </returns>
    /// <remarks>
    ///     Throws rather than returning a failure value: every call site already wraps element
    ///     initialization in a catch that disables the element, so a throw degrades to "no watermark"
    ///     rather than a killed stream. An implementation's own deadline should surface as
    ///     <see cref="TimeoutException" /> and caller cancellation as
    ///     <see cref="OperationCanceledException" /> — though note the current call sites catch both
    ///     alike, so today the distinction only sharpens the log message.
    /// </remarks>
    Task<Stream> Fetch(Uri uri, CancellationToken cancellationToken);
}