namespace foodmarket.Api.Storage;

/// <summary>Абстракция для хранилища бинарных файлов (картинки товаров,
/// CSV-импорт и т.д.). Реализации: <see cref="LocalObjectStorage"/>
/// (файлы в <c>{ContentRoot}/uploads/</c>, доступны nginx'ом) и
/// <see cref="MinioObjectStorage"/> (S3-совместимый bucket).
///
/// Принцип идентификации: <c>key</c> — относительный путь типа
/// <c>products/{productId:N}/{guid}.png</c>. URL для публичной отдачи
/// возвращает <see cref="PublicUrl"/> — для Local это
/// <c>/uploads/{key}</c>, для Minio — тот же путь, но nginx уже его
/// проксирует на API (см. GET /uploads/{**path}).</summary>
public interface IObjectStorage
{
    /// <summary>Сохранить поток. Возвращает <c>key</c> (то что
    /// каллер передал).</summary>
    Task<string> SaveAsync(string key, Stream content, string contentType, CancellationToken ct = default);

    /// <summary>Открыть на чтение. null если объекта нет.</summary>
    Task<(Stream Stream, string ContentType)?> OpenAsync(string key, CancellationToken ct = default);

    /// <summary>Удалить. Не бросает если объекта уже нет.</summary>
    Task DeleteAsync(string key, CancellationToken ct = default);

    /// <summary>Публичный URL для отдачи через API/nginx. Не presigned —
    /// в обоих реализациях возвращает <c>/uploads/{key}</c>. Nginx/api
    /// прокси решает, откуда взять (диск или MinIO).</summary>
    string PublicUrl(string key) => $"/uploads/{key.TrimStart('/')}";

    /// <summary>Имя реализации — для логов и диагностики.</summary>
    string Kind { get; }
}