iteration

Author: KSemenenko

AGENTS.md

@@ -9,7 +9,10 @@ If I tell you to remember something, you do the same, update
 
 
 ## Rules to follow
-TBA
+- Ensure storage-related changes keep broad automated coverage around 85-90% using generic, provider-agnostic tests across file systems, storages, and integrations.
+- Deliver ASP.NET integrations that expose upload/download controllers, SignalR streaming, and matching HTTP and SignalR clients built on the storage layer for files, streams, and chunked transfers.
+- Provide base ASP.NET controllers with minimal routing so consumers can inherit and customize routes, authorization, and behaviors without rigid defaults.
+- Favor controller extension patterns and optionally expose interfaces to guide consumers on recommended actions so they can implement custom endpoints easily.
 
 # Repository Guidelines
 

Integraions/ManagedCode.Storage.Server/Controllers/IStorageController.cs

@@ -0,0 +1,56 @@
+using System.Threading;
+using System.Threading.Tasks;
+using ManagedCode.Communication;
+using ManagedCode.Storage.Core.Models;
+using ManagedCode.Storage.Server.Models;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ManagedCode.Storage.Server.Controllers;
+
+/// <summary>
+/// Describes the recommended set of endpoints for storage-backed controllers.
+/// Implementations can inherit <see cref="StorageControllerBase{TStorage}"/> or compose their own controllers using the extension methods.
+/// </summary>
+public interface IStorageController
+{
+    /// <summary>
+    /// Uploads a single file using a multipart/form-data request.
+    /// </summary>
+    Task<Result<BlobMetadata>> UploadAsync(IFormFile file, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Uploads a file using the raw request body stream and metadata headers.
+    /// </summary>
+    Task<Result<BlobMetadata>> UploadStreamAsync(string fileName, string? contentType, string? directory, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Returns a file download result for the specified path.
+    /// </summary>
+    Task<ActionResult> DownloadAsync(string path, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Streams file content to the caller, enabling range processing when supported.
+    /// </summary>
+    Task<IActionResult> StreamAsync(string path, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Materialises a file into memory and returns it as a <see cref="FileContentResult"/>.
+    /// </summary>
+    Task<ActionResult> DownloadBytesAsync(string path, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Persists a chunk within an active chunked-upload session.
+    /// </summary>
+    Task<Result> UploadChunkAsync(FileUploadPayload payload, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Completes an upload session by merging chunks and optionally committing to backing storage.
+    /// </summary>
+    Task<Result<ChunkUploadCompleteResponse>> CompleteChunksAsync(ChunkUploadCompleteRequest request, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Aborts an active chunked upload and removes temporary state.
+    /// </summary>
+    IActionResult AbortChunks(string uploadId);
+}

Integraions/ManagedCode.Storage.Server/Controllers/StorageController.cs

@@ -0,0 +1,25 @@
+using ManagedCode.Storage.Core;
+using ManagedCode.Storage.Server.ChunkUpload;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ManagedCode.Storage.Server.Controllers;
+
+/// <summary>
+/// Default storage controller exposing all storage endpoints using the shared <see cref="IStorage"/> instance.
+/// </summary>
+[Route("api/storage")]
+public class StorageController : StorageControllerBase<IStorage>
+{
+    /// <summary>
+    /// Initialises a new instance of the default storage controller.
+    /// </summary>
+    /// <param name="storage">The shared storage instance.</param>
+    /// <param name="chunkUploadService">Chunk upload coordinator.</param>
+    /// <param name="options">Server behaviour options.</param>
+    public StorageController(
+        IStorage storage,
+        ChunkUploadService chunkUploadService,
+        StorageServerOptions options) : base(storage, chunkUploadService, options)
+    {
+    }
+}

Integraions/ManagedCode.Storage.Server/Controllers/StorageControllerBase.cs

@@ -0,0 +1,219 @@
+using System;
+using System.IO;
+using System.Net;
+using System.Threading;
+using System.Threading.Tasks;
+using ManagedCode.Communication;
+using ManagedCode.MimeTypes;
+using ManagedCode.Storage.Core;
+using ManagedCode.Storage.Core.Models;
+using ManagedCode.Storage.Server.ChunkUpload;
+using ManagedCode.Storage.Server.Extensions.Controller;
+using ManagedCode.Storage.Server.Models;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ManagedCode.Storage.Server.Controllers;
+
+/// <summary>
+/// Provides a reusable ASP.NET Core controller that wires storage upload, download, and chunked-transfer endpoints.
+/// </summary>
+public abstract class StorageControllerBase<TStorage> : ControllerBase, IStorageController where TStorage : IStorage
+{
+    private readonly StorageServerOptions _options;
+
+    /// <summary>
+    /// Initialises a new instance that exposes storage functionality through HTTP endpoints.
+    /// </summary>
+    /// <param name="storage">Storage provider used to fulfil requests.</param>
+    /// <param name="chunkUploadService">Chunk upload orchestrator.</param>
+    /// <param name="options">Runtime options controlling streaming behaviour.</param>
+    protected StorageControllerBase(
+        TStorage storage,
+        ChunkUploadService chunkUploadService,
+        StorageServerOptions options)
+    {
+        Storage = storage ?? throw new ArgumentNullException(nameof(storage));
+        ChunkUploadService = chunkUploadService ?? throw new ArgumentNullException(nameof(chunkUploadService));
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    /// <summary>
+    /// Gets the storage provider used by the controller.
+    /// </summary>
+    protected TStorage Storage { get; }
+
+    /// <summary>
+    /// Gets the chunk upload coordinator used for large uploads.
+    /// </summary>
+    protected ChunkUploadService ChunkUploadService { get; }
+
+    [HttpPost("upload"), ProducesResponseType(typeof(Result<BlobMetadata>), StatusCodes.Status200OK)]
+    /// <inheritdoc />
+    public virtual async Task<Result<BlobMetadata>> UploadAsync([FromForm] IFormFile file, CancellationToken cancellationToken)
+    {
+        if (file is null)
+        {
+            return Result<BlobMetadata>.Fail(HttpStatusCode.BadRequest, "File payload is missing");
+        }
+
+        try
+        {
+            return await Result.From(() => this.UploadFormFileAsync(Storage, file, cancellationToken: cancellationToken), cancellationToken);
+        }
+        catch (Exception ex)
+        {
+            return Result<BlobMetadata>.Fail(ex);
+        }
+    }
+
+    [HttpPost("upload/stream"), ProducesResponseType(typeof(Result<BlobMetadata>), StatusCodes.Status200OK)]
+    /// <inheritdoc />
+    public virtual async Task<Result<BlobMetadata>> UploadStreamAsync(
+        [FromHeader(Name = StorageServerHeaders.FileName)] string fileName,
+        [FromHeader(Name = StorageServerHeaders.ContentType)] string? contentType,
+        [FromHeader(Name = StorageServerHeaders.Directory)] string? directory,
+        CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(fileName))
+        {
+            return Result<BlobMetadata>.Fail(HttpStatusCode.BadRequest, "X-File-Name header is required");
+        }
+
+        var options = new UploadOptions(fileName, directory, contentType);
+
+        try
+        {
+            await using var uploadStream = Request.Body;
+            var result = await Storage.UploadAsync(uploadStream, options, cancellationToken);
+            return result;
+        }
+        catch (Exception ex)
+        {
+            return Result<BlobMetadata>.Fail(ex);
+        }
+    }
+
+    [HttpGet("download/{*path}")]
+    /// <inheritdoc />
+    public virtual async Task<ActionResult> DownloadAsync([FromRoute] string path, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return Problem("File name is required", statusCode: StatusCodes.Status400BadRequest);
+        }
+
+        var result = await Storage.GetStreamAsync(path, cancellationToken);
+        if (result.IsFailed)
+        {
+            return Problem(result.Problem?.Title ?? "File not found", statusCode: (int?)result.Problem?.StatusCode ?? StatusCodes.Status404NotFound);
+        }
+
+        return File(result.Value, MimeHelper.GetMimeType(path), path, enableRangeProcessing: _options.EnableRangeProcessing);
+    }
+
+    [HttpGet("stream/{*path}")]
+    /// <inheritdoc />
+    public virtual async Task<IActionResult> StreamAsync([FromRoute] string path, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return Problem("File name is required", statusCode: StatusCodes.Status400BadRequest);
+        }
+
+        var streamResult = await Storage.GetStreamAsync(path, cancellationToken);
+        if (streamResult.IsFailed)
+        {
+            return Problem(streamResult.Problem?.Title ?? "File not found", statusCode: (int?)streamResult.Problem?.StatusCode ?? StatusCodes.Status404NotFound);
+        }
+
+        return File(streamResult.Value, MimeHelper.GetMimeType(path), fileDownloadName: null, enableRangeProcessing: _options.EnableRangeProcessing);
+    }
+
+    [HttpGet("download-bytes/{*path}")]
+    /// <inheritdoc />
+    public virtual async Task<ActionResult> DownloadBytesAsync([FromRoute] string path, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return Problem("File name is required", statusCode: StatusCodes.Status400BadRequest);
+        }
+
+        var download = await Storage.DownloadAsync(path, cancellationToken);
+        if (download.IsFailed)
+        {
+            return Problem(download.Problem?.Title ?? "File not found", statusCode: (int?)download.Problem?.StatusCode ?? StatusCodes.Status404NotFound);
+        }
+
+        await using var tempStream = new MemoryStream();
+        await download.Value.FileStream.CopyToAsync(tempStream, cancellationToken);
+        return File(tempStream.ToArray(), MimeHelper.GetMimeType(path), path);
+    }
+
+    [HttpPost("upload-chunks/upload"), ProducesResponseType(typeof(Result), StatusCodes.Status200OK)]
+    /// <inheritdoc />
+    public virtual async Task<Result> UploadChunkAsync([FromForm] FileUploadPayload payload, CancellationToken cancellationToken)
+    {
+        if (payload?.File is null)
+        {
+            return Result.Fail(HttpStatusCode.BadRequest, "File chunk payload is required");
+        }
+
+        if (payload.Payload is null || string.IsNullOrWhiteSpace(payload.Payload.UploadId))
+        {
+            return Result.Fail(HttpStatusCode.BadRequest, "UploadId is required");
+        }
+
+        return await ChunkUploadService.AppendChunkAsync(payload, cancellationToken);
+    }
+
+    [HttpPost("upload-chunks/complete"), ProducesResponseType(typeof(Result<ChunkUploadCompleteResponse>), StatusCodes.Status200OK)]
+    /// <inheritdoc />
+    public virtual async Task<Result<ChunkUploadCompleteResponse>> CompleteChunksAsync([FromBody] ChunkUploadCompleteRequest request, CancellationToken cancellationToken)
+    {
+        if (request is null)
+        {
+            return Result<ChunkUploadCompleteResponse>.Fail(HttpStatusCode.BadRequest, "Completion request is required");
+        }
+        return await ChunkUploadService.CompleteAsync(request, Storage, cancellationToken);
+    }
+
+    [HttpDelete("upload-chunks/{uploadId}")]
+    /// <inheritdoc />
+    public virtual IActionResult AbortChunks([FromRoute] string uploadId)
+    {
+        if (string.IsNullOrWhiteSpace(uploadId))
+        {
+            return Problem("Upload id is required", statusCode: StatusCodes.Status400BadRequest);
+        }
+
+        ChunkUploadService.Abort(uploadId);
+        return NoContent();
+    }
+}
+
+public static class StorageServerHeaders
+{
+    /// <summary>
+    /// Header name conveying the file name supplied for stream uploads.
+    /// </summary>
+    public const string FileName = "X-File-Name";
+
+    /// <summary>
+    /// Header name conveying the MIME type supplied for stream uploads.
+    /// </summary>
+    public const string ContentType = "X-Content-Type";
+
+    /// <summary>
+    /// Header name conveying the logical directory for stream uploads.
+    /// </summary>
+    public const string Directory = "X-Directory";
+}
+
+public class StorageServerOptions
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether range processing is enabled for streaming responses.
+    /// </summary>
+    public bool EnableRangeProcessing { get; set; } = true;
+}

Integraions/ManagedCode.Storage.Server/Extensions/DependencyInjection/StorageServerBuilderExtensions.cs

@@ -0,0 +1,35 @@
+using System;
+using ManagedCode.Storage.Server.ChunkUpload;
+using ManagedCode.Storage.Server.Controllers;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ManagedCode.Storage.Server.Extensions.DependencyInjection;
+
+/// <summary>
+/// Provides helpers for wiring storage server components into an <see cref="IServiceCollection"/>.
+/// </summary>
+public static class StorageServerBuilderExtensions
+{
+    /// <summary>
+    /// Registers server-side services required for HTTP controllers and chunk uploads.
+    /// </summary>
+    /// <param name="services">The service collection.</param>
+    /// <param name="configureServer">Optional configuration for <see cref="StorageServerOptions"/>.</param>
+    /// <param name="configureChunks">Optional configuration for <see cref="ChunkUploadOptions"/>.</param>
+    /// <returns>The original <paramref name="services"/> for chaining.</returns>
+    public static IServiceCollection AddStorageServer(this IServiceCollection services, Action<StorageServerOptions>? configureServer = null, Action<ChunkUploadOptions>? configureChunks = null)
+    {
+        var serverOptions = new StorageServerOptions();
+        configureServer?.Invoke(serverOptions);
+        services.AddSingleton(serverOptions);
+
+        services.Configure<ApiBehaviorOptions>(options =>
+        {
+            options.SuppressModelStateInvalidFilter = true;
+        });
+
+        services.AddChunkUploadHandling(configureChunks);
+        return services;
+    }
+}

Integraions/ManagedCode.Storage.Server/Extensions/DependencyInjection/StorageSignalRServiceCollectionExtensions.cs

@@ -0,0 +1,25 @@
+using System;
+using ManagedCode.Storage.Server.Hubs;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ManagedCode.Storage.Server.Extensions.DependencyInjection;
+
+/// <summary>
+/// Provides registration helpers for SignalR-based storage streaming.
+/// </summary>
+public static class StorageSignalRServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers <see cref="StorageHubOptions"/> for SignalR storage hubs.
+    /// </summary>
+    /// <param name="services">Target service collection.</param>
+    /// <param name="configure">Optional configuration delegate for hub options.</param>
+    /// <returns>The original <paramref name="services"/>.</returns>
+    public static IServiceCollection AddStorageSignalR(this IServiceCollection services, Action<StorageHubOptions>? configure = null)
+    {
+        var options = new StorageHubOptions();
+        configure?.Invoke(options);
+        services.AddSingleton(options);
+        return services;
+    }
+}

Integraions/ManagedCode.Storage.Server/Extensions/StorageEndpointRouteBuilderExtensions.cs

@@ -0,0 +1,14 @@
+using ManagedCode.Storage.Server.Hubs;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Routing;
+
+namespace ManagedCode.Storage.Server.Extensions;
+
+public static class StorageEndpointRouteBuilderExtensions
+{
+    public static IEndpointRouteBuilder MapStorageHub(this IEndpointRouteBuilder endpoints, string pattern = "/hubs/storage")
+    {
+        endpoints.MapHub<StorageHub>(pattern);
+        return endpoints;
+    }
+}