StorageBridge 1.0.1

StorageBridge

<p align="center"> <img src="assets/logo.png" width="140" alt="StorageBridge Logo" /> <h2 align="center">One SDK. Every Cloud Storage.</h2> <p align="center">A universal, high-performance .NET SDK providing one unified API to seamlessly integrate with any cloud object storage provider without changing application code.</p> </p>

<p align="center"> <a href="https://www.nuget.org/packages/StorageBridge"><img src="https://img.shields.io/nuget/v/StorageBridge.svg?style=flat-square&color=2563EB" alt="NuGet Version" /></a> <a href="https://www.nuget.org/packages/StorageBridge"><img src="https://img.shields.io/nuget/dt/StorageBridge.svg?style=flat-square&color=06B6D4" alt="NuGet Downloads" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10B981.svg?style=flat-square" alt="License" /></a> <a href="#"><img src="https://img.shields.io/badge/.NET-8.0%20%7C%20Standard%202.1-0F172A.svg?style=flat-square" alt="Target Frameworks" /></a> </p>

🌟 Why StorageBridge?

Cloud object storage APIs are fragmented. Switching from AWS S3 to Azure Blob Storage, Cloudflare R2, or MinIO usually requires rewriting storage adapters, modifying credential handlers, and updating application code.

StorageBridge solves this by offering a single, standardized C# API (IStorageBridge). Write your storage logic once, configure your cloud providers, and switch target environments or failover seamlessly without breaking your application code.

🚀 Supported Providers (10 Major Cloud Providers)

📦 Installation

Install the official package from NuGet via .NET CLI:

dotnet add package StorageBridge

Or Package Manager Console:

Install-Package StorageBridge

⚡ Quickstart & Code Examples

1. Direct Initialization

using StorageBridge;
using StorageBridge.Models;

// Instantiate client and register desired cloud providers
var storage = StorageBridgeClient.Create(options =>
{
    // Primary Provider: Azure Blob Storage
    options.UseAzureBlob(
        connectionString: "DefaultEndpointsProtocol=https;AccountName=myacc;AccountKey=mykey;...",
        containerName: "media-assets"
    );

    // Optional Secondary Provider: Amazon S3
    options.UseAwsS3(
        accessKey: "AKIAIOSFODNN7EXAMPLE",
        secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        region: "us-east-1",
        bucketName: "global-media"
    );

    // Optional Edge CDN Integration
    options.UseCDN("https://cdn.mycompany.com");
});

2. File Upload & Rich Public/CDN URL Resolution

When you upload files, StorageBridge returns a rich StorageUploadResult that automatically resolves direct cloud storage URLs vs. CDN edge URLs:

using var fileStream = File.OpenRead("report.pdf");

StorageUploadResult result = await storage.UploadAsync("documents/2026/report.pdf", fileStream, new UploadOptions
{
    ContentType = "application/pdf",
    IsPublic = true,
    Metadata = new Dictionary<string, string> { ["Author"] = "Jane Doe" }
});

Console.WriteLine($"Direct S3/Azure URL : {result.DirectUrl}");
Console.WriteLine($"Edge CDN URL        : {result.CdnUrl}");
Console.WriteLine($"Best Public URL     : {result.PublicUrl}"); // Automatically uses CDN URL if CDN is enabled!

3. Open Read Streams, Downloads & Pre-signed URLs

// Open a read stream directly from cloud storage
using var readStream = await storage.OpenReadAsync("documents/2026/report.pdf");

// Download complete file payload as byte array
byte[] bytes = await storage.DownloadAsync("documents/2026/report.pdf");

// Generate a temporary pre-signed URL (valid for 1 Hour)
string presignedUrl = await storage.GetPreSignedUrlAsync("documents/2026/report.pdf", TimeSpan.FromHours(1));

// Delete object
await storage.DeleteAsync("documents/2026/report.pdf");

4. ASP.NET Core Dependency Injection

Register StorageBridge in Program.cs for clean dependency injection in Controllers and Services:

// Program.cs
builder.Services.AddStorageBridge(options =>
{
    options.DefaultProvider = "CloudflareR2";

    options.UseCloudflareR2(
        accountId: builder.Configuration["Storage:R2:AccountId"]!,
        accessKeyId: builder.Configuration["Storage:R2:AccessKeyId"]!,
        secretAccessKey: builder.Configuration["Storage:R2:SecretAccessKey"]!,
        bucketName: "edge-media"
    );

    options.UseCDN(builder.Configuration["Storage:CDN:BaseUrl"]!);
});

// Inject in Service or Controller:
public class DocumentService
{
    private readonly IStorageBridge _storage;

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

    public async Task<string> SaveUserAvatarAsync(string userId, Stream avatarStream)
    {
        var upload = await _storage.UploadAsync($"avatars/{userId}.png", avatarStream, new UploadOptions { ContentType = "image/png" });
        return upload.PublicUrl;
    }
}

5. Power Developer Utility Suite ("Free Hand" Capabilities)

// 1. Server-side Fast Copy & Move
await storage.CopyAsync("avatars/john.png", "backups/john_copy.png");
await storage.MoveAsync("backups/john_copy.png", "archived/john_archived.png");

// 2. Parallel Batch Upload with Real-Time Progress Callbacks
var items = new List<BatchUploadItem>
{
    new("files/doc1.pdf", File.OpenRead("doc1.pdf")),
    new("files/doc2.pdf", File.OpenRead("doc2.pdf"))
};

var progress = new Progress<BatchProgress>(p =>
{
    Console.WriteLine($"Uploaded {p.CompletedItems}/{p.TotalItems} ({p.Percentage:F0}%) - Current: {p.CurrentProcessingPath}");
});

await storage.BatchUploadAsync(items, progress);

// 3. Bulk Delete
await storage.BatchDeleteAsync(new[] { "files/doc1.pdf", "files/doc2.pdf" });

// 4. Edge CDN Invalidation
await storage.CDN.PurgeCacheAsync("avatars/john.png");

// 5. On-The-Fly Provider Switcher
storage.SwitchProvider("AmazonS3");

6. Provider Requirements & Strict Validation Exceptions

StorageBridge validates required credentials on setup. If any required configuration key is omitted, it throws a detailed StorageConfigurationException:

try
{
    // Inspect requirements schema at runtime
    var requirements = StorageBridgeClient.GetProviderRequirements("AmazonS3");
    Console.WriteLine($"AWS Required Parameters: {string.Join(", ", requirements.RequiredKeys)}");
}
catch (StorageConfigurationException ex)
{
    Console.WriteLine($"Missing Setting : {ex.MissingKey}");
    Console.WriteLine($"Provider        : {ex.ProviderName}");
}

🔒 Security & Resilience

• Secure Credentials: Supports environment variables, Azure Managed Identities, AWS IAM Roles, OIDC, and HashiCorp Vault key references.
• Automatic Retry Policy: Built-in exponential backoff and circuit breaker handling for transient cloud network failures.
• Zero Allocation Streaming: High-throughput memory pipeline optimizations for minimal garbage collection pressure during large file transfers.

📜 License

This project is licensed under the MIT License.