namespace ErsatzTV.Core.Interfaces.Streaming;

/// <summary>
///     Checks whether a media-server remote-stream URL still resolves to playable media.
/// </summary>
public interface IRemoteStreamProber
{
    /// <summary>
    ///     Probes <paramref name="url" />, following redirects as ffmpeg would.
    /// </summary>
    /// <returns>
    ///     <c>false</c> only when the media server itself reported the media gone — i.e. a 404 that
    ///     arrived <em>after</em> ErsatzTV's own <c>/media/{provider}/...</c> endpoint redirected.
    ///     Every other outcome returns <c>true</c> (fail-open), including an un-redirected 404: that
    ///     one came from ErsatzTV's own endpoint, which also 404s when the media source is
    ///     unconfigured or momentarily missing, and honouring it would blank every item on that
    ///     source. Timeouts, transport failures and all other status codes likewise return
    ///     <c>true</c>, so a probe that cannot answer never prevents a tune that would have worked.
    /// </returns>
    /// <exception cref="OperationCanceledException">
    ///     May propagate when <paramref name="cancellationToken" /> is cancelled while the probe is
    ///     in flight. Caller cancellation is a genuine signal (shutdown / client disconnect), not a
    ///     probe failure, so it is not absorbed by the fail-open behaviour above. Cancelling after
    ///     the probe has already completed returns normally. The prober's own internal timeout does
    ///     <em>not</em> throw — it fails open.
    /// </exception>
    Task<bool> IsAvailable(string url, CancellationToken cancellationToken);
}