IntegratedS3

A modular ASP.NET Core library that exposes S3-compatible HTTP endpoints backed by pluggable storage providers.

• S3-compatible REST API — bucket and object operations over standard HTTP
• Pluggable backends — ship with disk and native S3 providers, or bring your own
• SigV4 / SigV4a authentication — optional AWS Signature V4 request signing and verification, with pluggable credential resolution and restart-free key rotation
• Multi-backend orchestration — replication policies across providers
• Presigned URLs — time-limited, shareable links for downloads, uploads, deletes, metadata reads, and multipart part uploads
• Multipart uploads — chunked uploads with server-managed assembly
• Versioning & object lock — per-bucket version history; bucket default retention blocks in-window permanent deletes (per-object retention and legal hold require a provider with native support)
• Bucket configuration — tagging, lifecycle, CORS, and policy support (the disk provider stores and serves lifecycle/replication/website/logging/notification configuration without executing it; the native S3 provider delegates to the backing service)
• Server-side encryption (SSE) — SSE and SSE-C request handling with the native S3 provider (the disk provider rejects encryption requests with NotImplemented)
• Health checks — liveness and readiness probes for each backend
• OpenTelemetry observability — built-in traces, metrics, and structured logging
• AOT & trimming compatible — targets .NET 10 with zero AOT warnings

Install the main consumer package and a storage provider:

dotnet add package IntegratedS3.AspNetCore
dotnet add package IntegratedS3.Provider.Disk

Program.cs

var builder = WebApplication.CreateSlimBuilder(args);

builder.Services.AddIntegratedS3(builder.Configuration);
builder.Services.AddDiskStorage(new DiskStorageOptions
{
    RootPath = "App_Data/IntegratedS3",
    CreateRootDirectory = true
});

var app = builder.Build();
app.MapIntegratedS3Endpoints();
app.Run();

appsettings.json

{
  "IntegratedS3": {
    "ServiceName": "My S3 Host"
  }
}

Your S3-compatible endpoint is now running at /integrated-s3.

AddIntegratedS3(builder.Configuration) binds the IntegratedS3 configuration section to IntegratedS3Options. Key properties:

See docs/webui-reference-host.md for the full configuration reference.

builder.Services.AddDiskStorage(new DiskStorageOptions
{
    RootPath = "App_Data/IntegratedS3",
    CreateRootDirectory = true
});

builder.Services.AddS3Storage(new S3StorageOptions
{
    Region = "us-east-1",
    ServiceUrl = "http://localhost:9000", // optional — for MinIO, LocalStack, etc.
    ForcePathStyle = true                 // required for most S3-compatible endpoints
});

Implement IStorageBackend and register it:

builder.Services.AddIntegratedS3Backend<MyCustomBackend>();

See docs/provider-contract-testing.md for the xUnit harness that validates your implementation against the full storage contract.

Not every provider supports every operation — per-object retention, legal hold, RestoreObject, SelectObjectContent, bucket default encryption, and SSE are native-S3-provider features that the disk provider rejects with NotImplemented. See the provider capability matrix for the full per-provider breakdown.

IntegratedS3 ships with ASP.NET Core health check integration for backend liveness and readiness:

builder.Services
    .AddHealthChecks()
    .AddIntegratedS3BackendHealthCheck();

// ...

app.MapIntegratedS3HealthEndpoints(); // maps /health/live + /health/ready

IntegratedS3 emits traces and metrics through a built-in ActivitySource and Meter (both named "IntegratedS3"). Wire them into the OpenTelemetry SDK:

using IntegratedS3.Abstractions.Observability;

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(IntegratedS3Observability.ActivitySourceName))
    .WithMetrics(m => m.AddMeter(IntegratedS3Observability.MeterName));

See docs/observability.md for the full list of instruments, correlation ID propagation, and per-layer telemetry details.

# Build
dotnet build src/IntegratedS3/IntegratedS3.slnx

# Test
dotnet test src/IntegratedS3/IntegratedS3.slnx

# Run the reference host
dotnet run --project src/IntegratedS3/WebUi/WebUi.csproj

# Validate AOT/trimming
dotnet publish -c Release --self-contained src/IntegratedS3/WebUi/WebUi.csproj

Contributions are welcome — see CONTRIBUTING.md for the development workflow, build/test requirements, and pull request process. Release history lives in CHANGELOG.md.

To report a security vulnerability, please use the private channel described in SECURITY.md — do not open a public issue.

Local-first suites for catching regressions early (no paid CI required):

• Benchmarks — IntegratedS3.Benchmarks is a BenchmarkDotNet suite over the hot paths (SigV4/SigV4a, S3 XML, checksums, Disk provider), reporting mean time + allocations. scripts/bench.sh runs it; scripts/bench-compare.sh fails when a benchmark's mean regresses > 15% or allocations grow versus the committed baseline.
• E2E — IntegratedS3.E2E.Tests boots the real host on a Kestrel loopback socket with the Disk provider and drives it with the AWS SDK for .NET. scripts/e2e-smoke.sh runs the fast offline subset; scripts/e2e.sh runs the full suite.

Both .sh and .ps1 wrappers are provided (plus a Makefile). CI runs only the fast free-tier checks automatically; benchmarks and the full E2E suite are opt-in. See docs/performance-benchmarks.md for details and the CI strategy.

This project is licensed under the terms of the BSD 3-Clause License.