using w4c_workflows.Models.Nodes;

namespace w4c_workflows.Services.Nodes.Binary;

// ---------------------------------------------------------------------------
// Binary payloads never travel inline through the item graph: a FlowItem only
// holds a BinaryAttachment reference, and the bytes live in a store reached
// through this interface. That keeps run history small, lets large downloads
// stream to disk instead of item JSON, and leaves the concrete backing store
// swappable (local volume today, the product asset service later).
// ---------------------------------------------------------------------------

/// <summary>
/// Persists and retrieves binary payloads by an opaque, content-addressed id.
/// Implementations must be safe to call concurrently and must reject ids that
/// do not belong to them.
/// </summary>
public interface IBinaryStore
{
    /// <summary>
    /// Stores <paramref name="content"/> and returns a reference to it. The same
    /// bytes stored twice yield the same <see cref="BinaryAttachment.AssetId"/>,
    /// so repeated downloads do not duplicate the payload.
    /// </summary>
    Task<BinaryAttachment> SaveAsync(
        Stream content,
        string? fileName,
        string? mimeType,
        CancellationToken ct = default);

    /// <summary>
    /// Opens a stored payload for reading. Returns <c>null</c> when the asset is
    /// unknown or the id is malformed; the caller decides whether that is fatal.
    /// </summary>
    Task<Stream?> OpenAsync(string assetId, CancellationToken ct = default);

    /// <summary>
    /// Reads an asset's metadata without opening the payload, or <c>null</c> when
    /// it is unknown.
    /// </summary>
    Task<BinaryAttachment?> DescribeAsync(string assetId, CancellationToken ct = default);
}