IntegratedS3

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

---

Features

• 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

---

Quick Start

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.

---

Packages

Package	Description
IntegratedS3.AspNetCore	ASP.NET Core DI registration + endpoint mapping (main consumer package)
IntegratedS3.Provider.Disk	Disk-backed storage provider
IntegratedS3.Provider.S3	Native AWS S3 / S3-compatible storage provider
IntegratedS3.Abstractions	Provider-agnostic contracts and observability surface
IntegratedS3.Core	Orchestration, replication policies, authorization
IntegratedS3.Protocol	S3 wire protocol — XML serialization, SigV4, presigning
IntegratedS3.EntityFramework	EF Core catalog and multipart state persistence
IntegratedS3.Client	First-party .NET HTTP client for IntegratedS3 hosts
IntegratedS3.Testing	Provider contract tests and test helpers (xUnit)

---

Configuration

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

Property	Default	Description
ServiceName	"Integrated S3"	Display name for the service
RoutePrefix	"/integrated-s3"	Base path for all S3 endpoints
EnableAwsSignatureV4Authentication	false	Require SigV4 signed requests
SignatureAuthenticationRegion	"us-east-1"	SigV4 signing region
AccessKeyCredentials	[]	List of access key / secret key pairs
MaximumPresignedUrlExpirySeconds	3600	Max presigned URL lifetime
EnableVirtualHostedStyleAddressing	false	Support virtual-hosted-style bucket URLs

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

---

Storage Providers

Disk

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

S3

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
});

Custom

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.

---

Health Checks

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

---

Observability

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.

---

Documentation

Document	Description
Getting Started	First-time setup, installation, and basic usage guide
Protocol Compatibility	S3 protocol coverage, per-provider capability matrix, and compatibility notes
Implementation Plan	Architecture overview, module breakdown, and roadmap
WebUi Reference Host	Full configuration and wiring reference for the sample host
Consumer Samples	Minimal API, MVC/Razor, and Blazor WASM sample apps
Observability	Traces, metrics, structured logging, and OpenTelemetry integration
Provider Contract Testing	xUnit harness for validating custom IStorageBackend implementations
Host Maintenance Jobs	Opt-in recurring maintenance hosted service
Performance Benchmarks	Custom Stopwatch-based hot-path benchmark harness and scenario catalog
AOT/Trimming Guidance	Guidelines for AOT and trimming compatibility

---

Building & Testing

# 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

---

Contributing & Security

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.

---

Benchmarks & E2E tests

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.

---

License

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