Refactor file storage API for extensibility and clarity

Refactored `IFileStorageManager` to introduce a more structured and extensible API:
- Replaced legacy methods with `CreateAsync` and `CreateWithVariantsAsync` for better file handling.
- Added support for associating files with entities via `IFileAttachable`.

Enhanced `InMemoryFileStorageManager` and `LocalFileStorageManager`:
- Implemented new methods to align with the updated interface.
- Improved handling of image variants (e.g., thumbnails, compressed files).
- Added utility methods for managing in-memory storage.

Introduced `IFileAttachable` interface to enable domain entities to manage file attachments directly.

Improved XML documentation, refactored path-handling logic, and removed unused code for better maintainability.

Author: Ghaith Prosoft

src/KitStack.Abstractions/Interfaces/IFileStorageManager.cs

@@ -1,4 +1,5 @@
-using Microsoft.AspNetCore.Http;
+using KitStack.Abstractions.Models;
+using Microsoft.AspNetCore.Http;
 
 namespace KitStack.Abstractions.Interfaces;
 
@@ -9,55 +10,43 @@ namespace KitStack.Abstractions.Interfaces;
 public interface IFileStorageManager
 {
     /// <summary>
-    /// Create / upload content for the given file entry.
+    /// Create and store a file for the specified entity type <typeparamref name="T"/>.
+    /// The implementation should produce a populated <see cref="IFileEntry"/> describing
+    /// the stored primary/original file. Providers may also create image variants according
+    /// to their configuration but this method returns the primary entry only.
     /// </summary>
-    //Task CreateAsync(IFileEntry fileEntry, Stream content, CancellationToken cancellationToken = default);
-
-    ///// <summary>
-    ///// Read the file content into a byte array.
-    ///// </summary>
-    //Task<byte[]> ReadAsync(IFileEntry fileEntry, CancellationToken cancellationToken = default);
-
-    ///// <summary>
-    ///// Open a read stream for the file content.
-    ///// Caller is responsible for disposing the returned stream.
-    ///// </summary>
-    //Task<Stream> ReadAsStreamAsync(IFileEntry fileEntry, CancellationToken cancellationToken = default);
-
-    ///// <summary>
-    ///// Delete the file referenced by fileEntry.
-    ///// </summary>
-    //Task DeleteAsync(IFileEntry fileEntry, CancellationToken cancellationToken = default);
-
-    ///// <summary>
-    ///// Mark or move the file into archive tier (provider-defined).
-    ///// </summary>
-    //Task ArchiveAsync(IFileEntry fileEntry, CancellationToken cancellationToken = default);
-
-    ///// <summary>
-    ///// Restore the file from archive tier (provider-defined).
-    ///// </summary>
-    //Task UnArchiveAsync(IFileEntry fileEntry, CancellationToken cancellationToken = default);
+    /// <typeparam name="T">Entity type the file is associated with.</typeparam>
+    /// <param name="file">The uploaded form file to store.</param>
+    /// <param name="category">Logical category or module name used to organize storage (required).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the stored <see cref="IFileEntry"/>.</returns>
+    Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, CancellationToken cancellationToken = default)
+        where T : class;
 
     /// <summary>
-    /// High-level convenience: upload an IFormFile for entity T into the configured local store.
-    /// If the file is an image and image-processing options are enabled, the manager will create
-    /// variants (thumbnail, compressed, additional sizes) according to configuration.
-    /// Returns the provider-relative path of the primary stored file (suitable for storing in DB).
+    /// Create and store a file associated with the provided entity instance.
+    /// Implementations may attach or mutate the entity (for example adding a FileEntry)
+    /// when the entity implements <see cref="IFileAttachable"/>.
     /// </summary>
-    //Task<string> UploadAsync<T>(IFormFile? file, string? category, CancellationToken cancellationToken = default)
-    //    where T : class;
+    /// <typeparam name="T">Entity type which implements <see cref="IFileAttachable"/>.</typeparam>
+    /// <param name="entity">The entity instance to associate the file with.</param>
+    /// <param name="file">The uploaded form file to store.</param>
+    /// <param name="category">Logical category or module name used to organize storage (required).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the stored <see cref="IFileEntry"/>.</returns>
+    Task<IFileEntry> CreateAsync<T>(T entity, IFormFile file, string? category, CancellationToken cancellationToken = default)
+        where T : class, IFileAttachable;
 
     /// <summary>
-    /// High-level helper: create and store a file associated with the given entity.
-    /// Returns a populated IFileEntry describing the stored file (primary/original).
-    /// - The implementation SHOULD NOT mutate the entity by default, but if the entity exposes
-    ///   a compatible method (e.g. AddFileAttachment(FileEntry)) the provider MAY call it.
-    /// - Image variants (thumbnail/compressed/other sizes) are created according to provider options.
+    /// Create the primary/original file and any configured image variants (thumbnail, compressed,
+    /// or additional sizes). Returns the primary <see cref="IFileEntry"/> and a list of variant
+    /// entries that were created by the provider.
     /// </summary>
-    Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, CancellationToken cancellationToken = default)
-        where T : class;
-
+    /// <typeparam name="T">Entity type the file is associated with.</typeparam>
+    /// <param name="file">The uploaded form file to store.</param>
+    /// <param name="category">Logical category or module name used to organize storage (required).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to a tuple containing the primary entry and created variants.</returns>
     Task<(IFileEntry Primary, List<IFileEntry> Variants)> CreateWithVariantsAsync<T>(IFormFile file, string? category, CancellationToken cancellationToken = default)
     where T : class;
 }

src/KitStack.Abstractions/Models/FileEntry.cs

@@ -27,4 +27,4 @@ public class FileEntry : IFileEntry
     public DateTimeOffset UploadedTime { get; set; } = DateTimeOffset.UtcNow;
 
     public string? VariantType { get; set; }
-}
+}

src/KitStack.Abstractions/Models/IFileAttachable.cs

@@ -0,0 +1,16 @@
+using KitStack.Abstractions.Interfaces;
+
+namespace KitStack.Abstractions.Models;
+
+/// <summary>
+/// Optional interface for domain entities that can hold file attachments.
+/// Implement this on your entity classes to receive file entries directly from storage helpers.
+/// </summary>
+public interface IFileAttachable
+{
+    /// <summary>
+    /// Add a file attachment to the entity (should not persist by itself).
+    /// Implementations typically add to an in-memory collection; persistence is the caller's responsibility.
+    /// </summary>
+    void AddFileAttachment(IFileEntry fileEntry);
+}

src/KitStack.Fakes/Services/InMemoryFileStorageManager.cs

@@ -3,8 +3,6 @@
 using KitStack.Abstractions.Models;
 using KitStack.Abstractions.Utilities;
 using System.Runtime.InteropServices;
-using System.IO;
-using System.Linq;
 using KitStack.Fakes.Contracts;
 using KitStack.Fakes.Models;
 using KitStack.Fakes.Options;
@@ -22,7 +20,16 @@ public class InMemoryFileStorageManager(IOptions<FakeOptions>? options = null) :
     private readonly ConcurrentDictionary<string, FakeStoredFile> _store = new();
     private readonly FakeOptions _options = options?.Value ?? new FakeOptions();
 
-    // High-level convenience to create/store an IFormFile for an entity T (in-memory)
+    /// <summary>
+    /// Create and store an uploaded <see cref="IFormFile"/> for the specified entity type <typeparamref name="T"/>.
+    /// The file content is preserved in memory and a populated <see cref="IFileEntry"/> is returned.
+    /// The returned entry's <see cref="IFileEntry.FileLocation"/> is a provider-relative path (URL-safe).
+    /// </summary>
+    /// <typeparam name="T">Entity type the file is associated with.</typeparam>
+    /// <param name="file">Uploaded form file to store (required).</param>
+    /// <param name="category">Logical category or module name used to organize storage (required).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the stored <see cref="IFileEntry"/>.</returns>
     public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, CancellationToken cancellationToken = default)
         where T : class
     {
@@ -69,6 +76,37 @@ public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, C
         return fileEntry;
     }
 
+    /// <summary>
+    /// Create and store an uploaded file and associate it with the provided <paramref name="entity"/>.
+    /// If the entity implements <see cref="IFileAttachable"/>, this method will call
+    /// <see cref="IFileAttachable.AddFileAttachment"/> to attach the created file entry.
+    /// </summary>
+    /// <typeparam name="T">Entity type which implements <see cref="IFileAttachable"/>.</typeparam>
+    /// <param name="entity">Entity instance to attach the file entry to (required).</param>
+    /// <param name="file">Uploaded form file to store (required).</param>
+    /// <param name="category">Logical category or module name used to organize storage (required).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The created primary <see cref="IFileEntry"/>.</returns>
+    public async Task<IFileEntry> CreateAsync<T>(T entity, IFormFile file, string? category, CancellationToken cancellationToken)
+        where T : class, IFileAttachable
+    {
+        var primary = await CreateAsync<T>(file, category, cancellationToken).ConfigureAwait(false);
+
+        entity.AddFileAttachment(primary);
+        return primary;
+    }
+
+    /// <summary>
+    /// Create the primary/original file and in-memory image variants (if the uploaded file is an image).
+    /// Returns the primary <see cref="IFileEntry"/> and a list of created variant entries. Variants are
+    /// stored in the in-memory fake store so tests can inspect them via <see cref="ListFiles"/> or
+    /// <see cref="TryGetFile"/>.
+    /// </summary>
+    /// <typeparam name="T">Entity type the file is associated with.</typeparam>
+    /// <param name="file">Uploaded form file to store (required).</param>
+    /// <param name="category">Logical category or module name used to organize storage (required).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to a tuple containing the primary entry and created variants.</returns>
     public async Task<(IFileEntry Primary, List<IFileEntry> Variants)> CreateWithVariantsAsync<T>(IFormFile file, string? category, CancellationToken cancellationToken = default)
         where T : class
     {
@@ -138,6 +176,13 @@ public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, C
         return (primary, variants);
     }
 
+    /// <summary>
+    /// Build a simple <see cref="FileEntry"/> describing an in-memory variant file.
+    /// The <paramref name="relativePath"/> should be a provider-relative path (URL-safe).
+    /// </summary>
+    /// <param name="relativePath">Provider-relative path for the variant.</param>
+    /// <param name="content">Byte content of the variant (used to set Size).</param>
+    /// <returns>A new <see cref="FileEntry"/> instance for the variant.</returns>
     private static FileEntry BuildVariantFileEntryInMemory(string relativePath, byte[] content)
     {
         // Derive VariantType from the containing folder name
@@ -159,16 +204,34 @@ private static FileEntry BuildVariantFileEntryInMemory(string relativePath, byte
         return entry;
     }
 
+    /// <summary>
+    /// Simulate a small operation delay when configured via <see cref="FakeOptions.OperationDelayMs"/>.
+    /// This helps tests exercise timeouts and concurrency scenarios without hitting real IO.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
     private async Task SimulateDelayAsync(CancellationToken cancellationToken)
     {
         if (_options.OperationDelayMs > 0)
             await Task.Delay(_options.OperationDelayMs, cancellationToken).ConfigureAwait(false);
     }
 
     // IFakeFileStore
+    /// <summary>
+    /// Return a read-only snapshot of files currently stored in the fake in-memory store.
+    /// Useful for assertions in unit tests.
+    /// </summary>
     public IReadOnlyCollection<FakeStoredFile> ListFiles() => _store.Values.ToList().AsReadOnly();
 
+    /// <summary>
+    /// Attempt to retrieve a stored file by its provider-relative location.
+    /// </summary>
+    /// <param name="fileLocation">Provider-relative file location to lookup.</param>
+    /// <param name="file">Out parameter set to the stored file when found; otherwise null.</param>
+    /// <returns>True if the file was found, false otherwise.</returns>
     public bool TryGetFile(string fileLocation, out FakeStoredFile? file) => _store.TryGetValue(fileLocation, out file);
 
+    /// <summary>
+    /// Clear all stored files from the in-memory fake store. Useful for test teardown.
+    /// </summary>
     public void Clear() => _store.Clear();
 }

src/KitStack.Storage.Local/Services/LocalFileStorageManager.cs

@@ -84,6 +84,15 @@ public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, C
     }
 
 
+    public async Task<IFileEntry> CreateAsync<T>(T entity, IFormFile file, string? category, CancellationToken cancellationToken = default)
+        where T : class, IFileAttachable
+    {
+        var primary = await CreateAsync<T>(file, category, cancellationToken).ConfigureAwait(false);
+
+        entity.AddFileAttachment(primary);
+        return primary;
+    }
+
     /// <summary>
     /// Create and store the primary file and image variants as configured.
     /// Returns the primary FileEntry and a list of FileEntry objects for variants that were created.
@@ -106,10 +115,12 @@ public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, C
         await stream.CopyToAsync(ms, cancellationToken).ConfigureAwait(false);
         var bytes = ms.ToArray();
 
+        var relativeFolderPath = Path.GetDirectoryName(primary.FileLocation) ?? string.Empty;
+        var uplaodFolderPath =  Path.Combine(_basePath, relativeFolderPath);
         // Compressed variant
         if (_option.ImageProcessing.CreateCompressed)
         {
-            var compressedRelative = await CreateCompressedVariantAsync(bytes, Path.Combine(_basePath, Path.GetDirectoryName(primary.FileLocation) ?? string.Empty), Path.GetDirectoryName(primary.FileLocation) ?? string.Empty, new Guid(primary.Id.ToString()), cancellationToken).ConfigureAwait(false);
+            var compressedRelative = await CreateCompressedVariantAsync(bytes, uplaodFolderPath, relativeFolderPath, new Guid(primary.Id.ToString()), cancellationToken).ConfigureAwait(false);
             var compressedEntry = BuildVariantFileEntry(compressedRelative);
             compressedEntry.Metadata ??= new Dictionary<string, string>();
             compressedEntry.VariantType = "compressed";
@@ -123,7 +134,7 @@ public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, C
         // Thumbnail variant
         if (_option.ImageProcessing.CreateThumbnail)
         {
-            var thumbRelative = await CreateThumbnailVariantAsync(bytes, Path.Combine(_basePath, Path.GetDirectoryName(primary.FileLocation) ?? string.Empty), Path.GetDirectoryName(primary.FileLocation) ?? string.Empty, new Guid(primary.Id.ToString()), cancellationToken).ConfigureAwait(false);
+            var thumbRelative = await CreateThumbnailVariantAsync(bytes, uplaodFolderPath, relativeFolderPath, new Guid(primary.Id.ToString()), cancellationToken).ConfigureAwait(false);
             var thumbEntry = BuildVariantFileEntry(thumbRelative);
             thumbEntry.Metadata ??= new Dictionary<string, string>();
             thumbEntry.VariantType = "thumbnail";
@@ -137,8 +148,7 @@ public async Task<IFileEntry> CreateAsync<T>(IFormFile file, string? category, C
         // Additional sizes
         if (_option.ImageProcessing.AdditionalSizes != null && _option.ImageProcessing.AdditionalSizes.Length > 0)
         {
-            var uplaodFolder = Path.Combine(_basePath, Path.GetDirectoryName(primary.FileLocation) ?? string.Empty);
-            var variantPaths = await CreateAdditionalVariantsAsync(bytes, uplaodFolder, Path.GetDirectoryName(primary.FileLocation) ?? string.Empty, _option.ImageProcessing.AdditionalSizes, cancellationToken).ConfigureAwait(false);
+            var variantPaths = await CreateAdditionalVariantsAsync(bytes, uplaodFolderPath, relativeFolderPath, _option.ImageProcessing.AdditionalSizes, cancellationToken).ConfigureAwait(false);
             var variantEntries = variantPaths.Select(p =>
             {
                 var ve = BuildVariantFileEntry(p);