RepletoryLib.FileStorage.Abstractions 1.0.0

RepletoryLib.FileStorage.Abstractions

Provider-agnostic file storage interfaces, models, and options for upload, download, delete, copy, move, listing, and presigned URL generation.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.FileStorage.Abstractions defines the core contracts and models for file storage operations. It provides IFileStorageService for full CRUD operations on files (upload, download, delete, copy, move, metadata, listing, presigned URLs) and IFilePathStrategy for generating organized storage paths with multi-tenant and date-based partitioning.

This package contains no implementations -- it is the abstraction layer that concrete providers (AWS S3, local filesystem, Azure Blob, etc.) implement. Reference this package in your application code to program against interfaces, then swap providers without changing business logic.

Key Features

• IFileStorageService -- Full file storage contract: upload, bulk upload, download (stream and bytes), delete, bulk delete, copy, move, metadata, listing, presigned URLs, and public URLs
• IFilePathStrategy -- Pluggable strategy for generating organized storage paths from contextual information
• FileUploadRequest / FileUploadResult -- Request/result models with content type inference, visibility control, and custom metadata
• BulkUploadResult -- Partial-success model for bulk uploads with per-file outcomes
• FileMetadata -- Rich metadata model including size, timestamps, content type, visibility, and custom key-value pairs
• FileListRequest / FileListResult -- Paginated file listing with prefix filtering, delimiter support, and continuation tokens
• PresignedUrlRequest -- Configurable presigned URL generation with expiry and HTTP method control
• FileVisibility enum -- Public vs. Private access control
• FileStorageOptions -- Shared configuration for max file size, allowed extensions, default visibility, and path templates

Installation

dotnet add package RepletoryLib.FileStorage.Abstractions

Or add to your .csproj:

<PackageReference Include="RepletoryLib.FileStorage.Abstractions" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Quick Start

1. Reference the abstractions in your service layer

using RepletoryLib.FileStorage.Abstractions.Interfaces;
using RepletoryLib.FileStorage.Abstractions.Models;

public class DocumentService
{
    private readonly IFileStorageService _storage;

    public DocumentService(IFileStorageService storage) => _storage = storage;

    public async Task<FileUploadResult> UploadDocumentAsync(Stream content, string fileName)
    {
        var request = new FileUploadRequest
        {
            Content = content,
            FileName = fileName,
            Folder = "documents"
        };

        return await _storage.UploadAsync(request);
    }
}

2. Register a concrete provider in Program.cs

// AWS S3 provider
using RepletoryLib.FileStorage.Aws;
builder.Services.AddRepletoryAwsFileStorage(builder.Configuration);

// -- OR -- Local filesystem provider
using RepletoryLib.FileStorage.Local;
builder.Services.AddRepletoryLocalFileStorage(builder.Configuration);

Configuration

FileStorageOptions

Section name: "FileStorage"

{
  "FileStorage": {
    "MaxFileSizeBytes": 52428800,
    "AllowedExtensions": [".jpg", ".jpeg", ".png", ".gif", ".pdf", ".docx"],
    "DefaultVisibility": "Private",
    "PathTemplate": "{tenant}/{year}/{month}/{day}/{filename}",
    "PreserveOriginalFileName": true
  }
}

Path Template Tokens

Usage Examples

Upload a File

using RepletoryLib.FileStorage.Abstractions.Enums;
using RepletoryLib.FileStorage.Abstractions.Interfaces;
using RepletoryLib.FileStorage.Abstractions.Models;

public class ImageService
{
    private readonly IFileStorageService _storage;

    public ImageService(IFileStorageService storage) => _storage = storage;

    public async Task<FileUploadResult> UploadImageAsync(Stream imageStream, string fileName, Guid tenantId)
    {
        var request = new FileUploadRequest
        {
            Content = imageStream,
            FileName = fileName,
            ContentType = "image/jpeg",
            Folder = "avatars",
            Visibility = FileVisibility.Public,
            Metadata = new Dictionary<string, string>
            {
                ["uploaded-by"] = "image-service",
                ["tenant-id"] = tenantId.ToString()
            }
        };

        return await _storage.UploadAsync(request);
    }
}

Bulk Upload

public async Task<BulkUploadResult> UploadBatchAsync(IEnumerable<(Stream Content, string FileName)> files)
{
    var requests = files.Select(f => new FileUploadRequest
    {
        Content = f.Content,
        FileName = f.FileName,
        Folder = "batch-imports"
    });

    var result = await _storage.UploadBulkAsync(requests);

    // Partial success -- check individual results
    foreach (var r in result.Results.Where(r => !r.Success))
    {
        _logger.LogWarning("Failed to upload: {Error}", r.Error);
    }

    _logger.LogInformation("Bulk upload: {Success}/{Total} succeeded",
        result.SuccessCount, result.Results.Count);

    return result;
}

Download Files

// Download as stream (caller must dispose)
await using var stream = await _storage.DownloadAsync("default/2026/03/report.pdf");
await stream.CopyToAsync(httpResponse.Body);

// Download as byte array
byte[] bytes = await _storage.DownloadBytesAsync("default/2026/03/report.pdf");

Copy, Move, and Delete

// Copy a file
await _storage.CopyAsync("originals/photo.jpg", "backups/photo.jpg");

// Move a file (copy + delete source)
await _storage.MoveAsync("temp/upload.pdf", "documents/final.pdf");

// Delete a single file
await _storage.DeleteAsync("temp/upload.pdf");

// Bulk delete
await _storage.DeleteBulkAsync(new[] { "temp/file1.txt", "temp/file2.txt", "temp/file3.txt" });

Check Existence and Get Metadata

// Check if file exists
bool exists = await _storage.ExistsAsync("default/2026/03/report.pdf");

// Get file metadata
FileMetadata metadata = await _storage.GetMetadataAsync("default/2026/03/report.pdf");
Console.WriteLine($"File: {metadata.FileName}");
Console.WriteLine($"Size: {metadata.SizeBytes} bytes");
Console.WriteLine($"Type: {metadata.ContentType}");
Console.WriteLine($"Created: {metadata.CreatedAt}");
Console.WriteLine($"Visibility: {metadata.Visibility}");

List Files with Pagination

var request = new FileListRequest
{
    Prefix = "default/2026/03/",
    Delimiter = "/",
    MaxResults = 50
};

var result = await _storage.ListAsync(request);

foreach (var file in result.Files)
{
    Console.WriteLine($"{file.FileKey} ({file.SizeBytes} bytes)");
}

// Paginate through results
while (result.IsTruncated)
{
    request.ContinuationToken = result.ContinuationToken;
    result = await _storage.ListAsync(request);

    foreach (var file in result.Files)
    {
        Console.WriteLine($"{file.FileKey} ({file.SizeBytes} bytes)");
    }
}

Generate Presigned URLs

// Generate a download URL valid for 2 hours
var url = await _storage.GetPresignedUrlAsync(new PresignedUrlRequest
{
    FileKey = "default/2026/03/report.pdf",
    Expiry = TimeSpan.FromHours(2),
    Method = HttpMethod.Get
});

// Generate an upload URL valid for 15 minutes
var uploadUrl = await _storage.GetPresignedUrlAsync(new PresignedUrlRequest
{
    FileKey = "uploads/new-document.pdf",
    Expiry = TimeSpan.FromMinutes(15),
    Method = HttpMethod.Put
});

Custom File Path Strategy

using RepletoryLib.FileStorage.Abstractions.Interfaces;
using RepletoryLib.FileStorage.Abstractions.Models;

public class CustomFilePathStrategy : IFilePathStrategy
{
    public string GeneratePath(FilePathContext context)
    {
        var tenant = context.TenantId?.ToString() ?? "shared";
        var date = context.UploadDate;
        var uniqueName = $"{Guid.NewGuid()}{Path.GetExtension(context.FileName)}";

        var path = $"{tenant}/{date:yyyy}/{date:MM}/{date:dd}/{uniqueName}";

        if (!string.IsNullOrWhiteSpace(context.Folder))
        {
            path = $"{context.Folder.TrimEnd('/')}/{path}";
        }

        return path;
    }
}

// Register in DI (overrides the provider's default strategy)
builder.Services.AddSingleton<IFilePathStrategy, CustomFilePathStrategy>();

API Reference

IFileStorageService

IFilePathStrategy

FileUploadRequest

FileUploadResult

BulkUploadResult

FileMetadata

FileListRequest

FileListResult

PresignedUrlRequest

FilePathContext

FileVisibility Enum

Integration with Other RepletoryLib Packages

Testing

using NSubstitute;
using RepletoryLib.FileStorage.Abstractions.Interfaces;
using RepletoryLib.FileStorage.Abstractions.Models;

public class DocumentServiceTests
{
    [Fact]
    public async Task UploadDocumentAsync_returns_success_result()
    {
        // Arrange
        var storage = Substitute.For<IFileStorageService>();
        storage.UploadAsync(Arg.Any<FileUploadRequest>(), Arg.Any<CancellationToken>())
            .Returns(new FileUploadResult
            {
                Success = true,
                FileKey = "documents/default/2026/03/report.pdf",
                Url = "/files/documents/default/2026/03/report.pdf"
            });

        var service = new DocumentService(storage);

        // Act
        using var stream = new MemoryStream("test content"u8.ToArray());
        var result = await service.UploadDocumentAsync(stream, "report.pdf");

        // Assert
        result.Success.Should().BeTrue();
        result.FileKey.Should().Contain("report.pdf");
        await storage.Received(1).UploadAsync(
            Arg.Is<FileUploadRequest>(r => r.FileName == "report.pdf" && r.Folder == "documents"),
            Arg.Any<CancellationToken>());
    }
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.