SyntaxCircus.Storage 0.1.3

SyntaxCircus.Storage

A stream-based file/blob storage abstraction, a local-disk implementation, and a config-driven provider switch. No ASP.NET Core dependency — usable from any .NET host.

No support guaranteed. Published as-is and maintained on a best-effort basis. Issues and PRs are welcome, but there's no SLA — fork it or vendor what you need if that's not enough.

Usage

builder.Services.AddStorageProvider(builder.Configuration); // binds "Storage" and "Storage:Local"

{ "Storage": { "Provider": "Local" }, "Storage:Local": { "RootPath": "/var/data/my-app" } }

public sealed class WidgetService(IStorageProvider storage)
{
    public async Task<StoredObject> UploadAsync(string id, Stream content, CancellationToken ct)
        => await storage.StoreAsync(new StoreObjectRequest($"widgets/{id}.bin", content), ct);
}

IStorageProvider — StoreAsync/ReadAsync/ExistsAsync/DeleteAsync, all keyed by an opaque string path-like key. ReadAsync returns StorageReadResult? (null if the key doesn't exist), which is itself an IAsyncDisposable wrapping the content stream — dispose it (or await using) once you're done reading.

Only "Local" is built in today (writes under a configured RootPath, with path-traversal and rooted/absolute keys rejected). Cloud-backed providers (S3, Azure Blob, etc.) aren't included yet — implement IStorageProvider yourself and register it directly instead of calling AddStorageProvider; the interface is designed so that isn't a breaking change to adopt later.

Building access URLs

{ "Storage": { "Provider": "Local" }, "Storage:Local": { "RootPath": "/var/data/my-app", "PublicBaseUrl": "https://cdn.example.com/files" } }

var url = await storage.GetAccessUrlAsync("widgets/abc.bin", ct); // https://cdn.example.com/files/widgets/abc.bin

GetAccessUrlAsync is a default interface method, so it's additive — any existing IStorageProvider implementation keeps compiling unchanged and simply doesn't support it (throws NotSupportedException) until it opts in. LocalFileStorageProvider builds a stable {PublicBaseUrl}/{key} URL and requires PublicBaseUrl to be configured; the expiry parameter exists for providers that support signed/time-limited URLs and is ignored on local disk.

Contributing

Issues and pull requests are welcome:

• Keep changes focused, with a clear description of the behavior change.
• Match the existing code style (see .editorconfig).
• Call out any breaking changes to the public API in your PR description.

License

MIT — see LICENSE.txt.