Ave.Extensions.FileSystem.MimeDetective 0.3.0-preview.1

Ave.Extensions.FileSystem

Cross-platform filesystem operations for .NET applications with advanced path mapping and security features.

Features

• Cross-platform file system operations - Consistent API across Windows, Linux, and macOS
• Canonical path mapping - Use Unix-style paths (/mnt/c/folder/file.txt) on all platforms
• Path security validation - Restrict file access to allowed directories with wildcard support
• Functional error handling - Uses Result<T, Error> pattern instead of exceptions
• Async enumeration - Stream large directory listings efficiently
• File system monitoring - Real-time change notifications with reactive streams
• High-performance move and copy operations - Native platform optimizations with progress reporting
• Dependency injection ready - Full integration with Microsoft.Extensions.DependencyInjection
• NetStandard 2.1 compatible - Works with .NET Core 3.0+ and .NET 5+

Packages

Getting Started

Install the packages from NuGet:

dotnet add package Ave.Extensions.FileSystem.Local

Basic Usage

using Ave.Extensions.FileSystem.Local;
using Microsoft.Extensions.DependencyInjection;

// Setup with DI
services.AddFileSystem();

// Usage
public class MyService 
{
    private readonly IFileSystem _fileSystem;
    
    public MyService(IFileSystem fileSystem)
    {
        _fileSystem = fileSystem;
    }
    
    public async Task ProcessFile(string path)
    {
        var result = await _fileSystem.FileExistsAsync(path);
        if (result.IsSuccess && result.Value)
        {
            var contentResult = await _fileSystem.ReadAllTextAsync(path);
            if (contentResult.IsSuccess)
            {
                var content = contentResult.Value;
                // Process content...
            }
        }
    }
}

Move and Copy Operations

The library provides high-performance move and copy operations with native platform optimizations, progress reporting, and comprehensive error handling.

File Operations

// Copy a file
var copyResult = await fileSystem.CopyFileAsync(
    source: "/data/original.txt",
    destination: "/backup/copy.txt",
    overwrite: true
);

if (copyResult.IsSuccess)
{
    Console.WriteLine("File copied successfully");
}

// Move a file
var moveResult = await fileSystem.MoveFileAsync(
    source: "/temp/upload.dat",
    destination: "/processed/upload.dat",
    overwrite: false
);

Directory Operations

// Copy entire directory structure
var copyDirResult = await fileSystem.CopyDirectoryAsync(
    source: "/source/project",
    destination: "/backup/project"
);

// Move directory
var moveDirResult = await fileSystem.MoveDirectoryAsync(
    source: "/temp/staging",
    destination: "/production/live"
);

Progress Reporting

Monitor progress for large file operations:

using Ave.Extensions.FileSystem;

// Create progress reporter
var progress = new Progress<ICopyProgress>(p => 
{
    Console.WriteLine($"Progress: {p.BytesTransferred:N0} / {p.TotalBytes:N0} bytes " +
                     $"({p.PercentComplete:F1}%) - {p.TransferRate:N0} bytes/sec");
});

// Copy with progress reporting
var result = await fileSystem.CopyFileAsync(
    source: "/data/large-file.zip",
    destination: "/backup/large-file.zip",
    progress: progress
);

Advanced Copy/Move Features

Cross-Volume Operations

The library automatically detects and handles cross-volume moves efficiently:

// Cross-volume move (automatically uses copy + delete)
var result = await fileSystem.MoveFileAsync(
    source: "/mnt/c/data/file.txt",     // C: drive
    destination: "/mnt/d/backup/file.txt" // D: drive
);

Cancellation Support

All operations support cancellation tokens:

using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));

try
{
    var result = await fileSystem.CopyDirectoryAsync(
        source: "/large/dataset",
        destination: "/backup/dataset",
        cancellationToken: cts.Token
    );
}
catch (OperationCanceledException)
{
    Console.WriteLine("Operation was cancelled");
}

File Attribute Preservation

File attributes, timestamps, and metadata are preserved when supported by the platform:

// Attributes are automatically preserved
var result = await fileSystem.CopyFileAsync(
    source: "/data/important.doc",
    destination: "/backup/important.doc"
);

// The copied file will maintain:
// - Creation time
// - Last modified time
// - File attributes (ReadOnly, Hidden, etc.)
// - Extended attributes (when supported)

Error Handling

All operations return Result<T, FileSystemError> for functional error handling:

var result = await fileSystem.CopyFileAsync(source, destination);

if (result.IsFailure)
{
    switch (result.Error.Type)
    {
        case FileSystemErrorType.FileNotFound:
            Console.WriteLine($"Source file not found: {result.Error.Path}");
            break;
        case FileSystemErrorType.InsufficientSpace:
            Console.WriteLine("Not enough disk space for copy operation");
            break;
        case FileSystemErrorType.AccessDenied:
            Console.WriteLine("Permission denied");
            break;
        case FileSystemErrorType.FileAlreadyExists:
            Console.WriteLine("Destination already exists (use overwrite: true)");
            break;
        default:
            Console.WriteLine($"Copy failed: {result.Error.Message}");
            break;
    }
}

Platform-Specific Optimizations

Local File System

• Windows: Uses native MoveFileEx API for atomic moves within same volume
• Linux/macOS: Uses rename() system call for atomic moves within same filesystem
• Cross-volume: Automatically falls back to copy + delete with transactional cleanup

Azure File Storage

• Server-side copy: Uses Azure's native copy operations for efficient transfers
• Parallel uploads: Large files are transferred using optimized chunking
• Eventual consistency: Handles Azure's consistency model for directory operations

In-Memory File System

• Zero-copy moves: Memory-based moves are instantaneous within same volume
• Copy-on-write: Efficient copying using reference counting where possible

Extension Methods

Convenient extension methods are available in the Ave.Extensions.FileSystem namespace:

using Ave.Extensions.FileSystem;

// Generic move/copy operations (auto-detects file vs directory)
var result = await fileSystem.MoveAsync(source, destination, overwrite: true);
var result = await fileSystem.CopyAsync(source, destination, overwrite: false);

// Bulk operations with LINQ
var files = new[] { "/temp/file1.txt", "/temp/file2.txt", "/temp/file3.txt" };
var results = await files.ToAsyncEnumerable()
    .SelectAwait(async file => await fileSystem.MoveFileAsync(
        file, 
        file.Replace("/temp/", "/processed/")
    ))
    .ToListAsync();

Canonical Path Mapping

Use Unix-style paths across all platforms:

// Setup with canonical path mapping
services.AddFileSystem(options =>
{
    options.UseCanonicalPaths = true;
});

// Now you can use Unix-style paths on Windows
var result = await fileSystem.ReadAllTextAsync("/mnt/c/users/documents/file.txt");
// Automatically maps to C:\users\documents\file.txt on Windows

Path Security

Restrict file system access to specific directories:

services.AddFileSystem(options =>
{
    options.EnablePathSecurity = true;
    options.AllowedPaths.Add("/app/data");
    options.AllowedPaths.Add("/tmp/*");
    options.AllowedPaths.Add("/logs");
});

// Only paths under /app/data, /tmp/*, and /logs are accessible

Advanced Configuration

services.AddFileSystem(options =>
{
    // Enable canonical path mapping
    options.UseCanonicalPaths = true;
    
    // Enable security validation
    options.EnablePathSecurity = true;
    options.AllowedPaths.Add("/app/**");
    options.AllowedPaths.Add("/data/uploads/*");
    
    // Customize other features
    options.EnableMonitoring = true;
    options.DefaultBufferSize = 8192;
});

Path Mapping Reference

When canonical path mapping is enabled, the library automatically converts between platform-specific and Unix-style paths:

Windows Path Mapping

Unix Path Mapping

On Unix systems (Linux/macOS), canonical paths are used directly:

Security Pattern Examples

Development

Building

dotnet build

Running Tests

dotnet test

Publishing a New Version

1. Create a new tag with the version number:

   git tag v1.0.0
   git push origin v1.0.0
   

2. The GitHub Actions workflow will automatically:

   • Build and test the code
   • Generate NuGet packages
   • Create a GitHub Release
   • Publish packages to NuGet.org (when configured)

License

MIT