Decode.Storage.FileSystem 3.0.0

Decode.Storage.FileSystem

Local FileSystem storage implementation of IStorageService for the Decode.Storage ecosystem.

📦 Installation

dotnet add package Decode.Storage.FileSystem

🛠️ Usage

1. Register Services

In your Program.cs or Startup.cs:

using Decode.Storage.FileSystem.Extensions;

builder.Services.AddFileSystemStorage(options =>
{
    options.BasePath = "C:\\StorageRoot"; // Or load from configuration
});

2. Inject and Use in Services

using Decode.Storage.Abstractions;

public class DocumentService
{
    private readonly IStorageService _storage;

    public DocumentService(IStorageService storage)
    {
        _storage = storage;
    }

    public async Task SaveReportAsync(string fileName, Stream content)
    {
        // Writes to a temporary file first, then moves it into place, so readers never observe a
        // partially written file. See the note on atomicity below.
        string savedPath = await _storage.UploadAsync($"reports/{fileName}", content, "application/pdf");
    }

    public async Task<StorageFile?> GetReportAsync(string fileName)
    {
        // Safe streaming and reading
        return await _storage.DownloadAsync($"reports/{fileName}");
    }
}

✍️ Write semantics and atomicity

UploadAsync always writes the content to a temporary file in the destination directory first, then moves it into place with File.Move(temp, final, overwrite: true). The replacement is atomic on every supported target: a reader never sees a half-written file, the destination is never absent, and a crash mid-write leaves the original intact.

Changed in 3.0.0. Until 2.1.0 the netstandard2.1 build had no overwriting File.Move overload and fell back to delete-then-move, which opened a window where the destination did not exist. That was the only known behavioural difference between targets in the whole ecosystem, and it disappeared with the target.

Concurrency is otherwise unsynchronized by design: FileSystemStorageService holds no locks, and the temporary file name is unique per call. Two concurrent uploads to the same path therefore both succeed and the last Move wins — the file is never corrupted, but which write survives is not defined. Serialize at the application level if you need a specific winner.

🔒 Path Containment (changed in 2.0.0)

Every path is resolved against BasePath and verified to stay inside it. Paths that are rooted, or that resolve outside the base directory, are rejected with ArgumentException:

await _storage.UploadAsync("reports/2026/q1.pdf", content); // ok
await _storage.UploadAsync("../../etc/passwd", content);    // ArgumentException
await _storage.UploadAsync(@"C:\Windows\System32\x.dll", content); // ArgumentException

Versions before 2.0.0 sanitized by stripping ".." substrings and then called Path.Combine(basePath, cleanPath). Path.Combine discards its first argument when the second is rooted, so any absolute path escaped the storage root entirely — arbitrary read, write and delete across the filesystem. The substring stripping was also lossy: a legitimate name like report..v2.pdf was silently rewritten to reportv2.pdf.

Both are fixed: containment is now proven by canonicalizing the resolved path, and file names are never rewritten.

Note on GetUrlAsync. It returns a file:// URI containing the absolute server path. That leaks your directory layout if handed to a client — treat it as internal-only.

📄 License

MIT License.