using DeepDrftModels.Enums;

namespace DeepDrftContent.Processors.Opus;

/// <summary>
/// The outcome of resolving a track + requested <see cref="AudioFormat"/> to a concrete artifact
/// (Phase 18.2; read-path streaming). Carries an <em>open, seekable, disk-backed</em> <see cref="Stream"/>
/// over the artifact's bytes — never a buffered <c>byte[]</c>, so a ~220 MB Opus file or ~970 MB lossless
/// source is never materialized in a managed array per request. Also carries the content-type that matches
/// <em>what was actually returned</em>, and the format actually served — which may differ from the requested
/// one when the C2 fallback fires (Opus requested, no Opus artifact → the lossless artifact + its
/// content-type). The delivery layer (18.3) sets the response <c>Content-Type</c> from
/// <see cref="ContentType"/> so the eventual decoder picks the right decoder for the bytes it receives.
/// <para>
/// Ownership: the resolver opens the stream; the caller takes ownership. On the success path the caller hands
/// <see cref="Stream"/> to <c>File(..., enableRangeProcessing: true)</c>, which disposes it after the
/// response. On any pre-handoff throw the caller disposes this instance (which disposes the stream) so the
/// underlying <see cref="FileStream"/> never leaks — mirroring the lossless disk-stream path's catch-path
/// disposal.
/// </para>
/// </summary>
/// <param name="Stream">An open, seekable, disk-backed stream over the resolved artifact. The caller owns it.</param>
/// <param name="ContentType">The MIME type of the bytes in <paramref name="Stream"/> (e.g. <c>audio/ogg</c>
/// for Opus, or the source's real MIME for lossless).</param>
/// <param name="ResolvedFormat">The format actually returned. Equal to the requested format on a direct
/// hit; <see cref="AudioFormat.Lossless"/> when an Opus request fell back.</param>
public sealed record ResolvedAudio(Stream Stream, string ContentType, AudioFormat ResolvedFormat)
    : IDisposable, IAsyncDisposable
{
    /// <summary>True when an Opus request was served the lossless artifact because no Opus existed (C2).</summary>
    public bool DidFallBack(AudioFormat requested) => requested != ResolvedFormat;

    public void Dispose() => Stream.Dispose();

    public ValueTask DisposeAsync() => Stream.DisposeAsync();
}