Pacem.Storage.Abstractions 1.0.2

Pacem Storage

About

Pacem.Storage.Abstractions defines IStorageService, a binary storage addressed by compatible paths (segment/segment/filename), and the StorageService base class its providers derive from:

Getting started

// Program.cs
services.AddPacemStorage().WithFileSystemServices(options =>
{
    options.RootPath = Path.Combine(environment.ContentRootPath, "storage");
    options.TempFolder = "_temp";
});

// anywhere
string path = storage.BuildCompatiblePath("photo-0001.jpg", tenant, "attachments", "2026", "11");
await storage.UploadIfNotExistsAsync(bytes, path, new Headers { ContentType = "image/jpeg" });
byte[]? stored = await storage.DownloadIfExistsAsync(path);

Uploads are if-not-exists: content already stored at a path is never overwritten, so sending the same content again (a retried request) is harmless.

Streams

Large content (photos, documents) doesn't need to sit in memory: upload from a Stream and read back as one.

// e.g. a multipart request's file part
await using Stream content = file.OpenReadStream();
await storage.UploadIfNotExistsAsync(content, path, new Headers { ContentType = file.ContentType }, cancellationToken);

// e.g. an endpoint answering with the stored content
Stream? stored = await storage.OpenReadIfExistsAsync(path, cancellationToken);
if (stored is null)
{
    return Results.NotFound();
}
return Results.Stream(stored, contentType);   // disposes the stream

• The content is read from the stream's current position to its end; the stream stays open, the caller disposes it.
• OpenReadIfExistsAsync answers null when nothing is stored; the caller disposes the stream it gets.
• Each provider streams natively:

• Retries need to read the content again. A stream that can't seek (a network body) is first copied to memory (pooled segments, never a temporary file; a MemoryStream is wrapped with no copy), by the providers that retry (AzureBlob, OneDrive, and AwsS3, whose SDK also resends from the start, so a seekable stream not at its start is copied too). FileSystem never copies.
• A custom implementation deriving from StorageService implements the two stream primitives, UploadIfNotExistsAsync(Stream, …, Headers, …) and OpenReadIfExistsAsync: the byte[] upload and DownloadIfExistsAsync are built on them. ReadAllBytesAsync and CopyToRewindableAsync (extensions of IStorageService) are there for providers that need a buffer.