Acontplus.S3Application 2.0.2

Acontplus.S3Application

Production-ready AWS S3 storage library with enterprise-grade scalability, resilience, and performance optimizations. Built for high-throughput cloud-native applications.

📑 Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Advanced Usage
• Performance
• Upgrade Guide
• Dependencies
• Error Handling
• Contributing
• License

🚀 Features

v2.0.0 - Scalability & Resilience

• ⚡ Connection Pooling: Reuses S3 clients per credentials/region (25x faster)
• 🔄 Polly Retry Policy: Automatic exponential backoff for transient failures
• 🚦 Rate Limiting: Prevents AWS throttling (configurable requests/second)
• ⚙️ Configurable Resilience: Customize timeouts, retries, and delays
• 📊 Structured Logging: Detailed operation metrics and diagnostics
• 🧵 Thread-Safe: ConcurrentDictionary for multi-threaded workloads
• ♻️ IDisposable: Proper resource cleanup and disposal
• 🎯 Dependency Injection: Full DI support with IOptions<T> pattern

Core Capabilities

• Async S3 CRUD: Upload, update, delete, and retrieve S3 objects
• Presigned URLs: Generate secure, time-limited download links
• Strong Typing: Models for S3 objects, credentials, and responses
• Business Error Handling: Consistent, metadata-rich responses
• .NET 10: Nullable, required properties, and latest C# features

📦 Installation

NuGet Package Manager

Install-Package Acontplus.S3Application -Version 2.0.0

.NET CLI

dotnet add package Acontplus.S3Application --version 2.0.0

PackageReference

<PackageReference Include="Acontplus.S3Application" Version="2.0.0" />

🎯 Quick Start

1. Register the Service (Required in v2.0+)

using Acontplus.S3Application.Extensions;

// In Program.cs or Startup.cs
var builder = WebApplication.CreateBuilder(args);

// Option 1: Load configuration from appsettings.json (recommended)
builder.Services.AddS3Storage(builder.Configuration);

// Option 2: Configure explicitly
builder.Services.AddS3Storage(options =>
{
    options.MaxRequestsPerSecond = 100;
    options.TimeoutSeconds = 60;
    options.MaxRetries = 3;
    options.RetryBaseDelayMs = 500;
    options.Region = "us-east-1";
});

// Option 3: Use all defaults
builder.Services.AddS3Storage();

2. Configure appsettings.json (Flexible - All Optional)

{
  "AWS": {
    "S3": {
      "MaxRequestsPerSecond": 100,
      "TimeoutSeconds": 60,
      "MaxRetries": 3,
      "RetryBaseDelayMs": 500,
      "Region": "us-east-1",
      "DefaultBucketName": "my-bucket",
      "ForcePathStyle": false,
      "EnableMetrics": false
    },
    "AccessKey": "AKIA...",
    "SecretKey": "secret..."
  }
}

Note:

• All AWS:S3 settings are optional with sensible defaults
• Use AWS:AccessKey/SecretKey for credentials (modern approach)
• Credentials are optional when using IAM roles or EC2 instance profiles
• Legacy keys (S3Bucket, AwsConfiguration) are supported for backward compatibility but deprecated - avoid in new projects

3. Basic Usage Example

public class FileUploadController : ControllerBase
{
    private readonly IS3StorageService _s3Service;
    private readonly IConfiguration _configuration;

    public FileUploadController(IS3StorageService s3Service, IConfiguration configuration)
    {
        _s3Service = s3Service;
        _configuration = configuration;
    }

    [HttpPost("upload")]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        var s3Object = new S3ObjectCustom(_configuration);
        await s3Object.Initialize("uploads/", file);

        var response = await _s3Service.UploadAsync(s3Object);

        return response.StatusCode == 201
            ? Ok(new { message = response.Message, url = s3Object.S3ObjectUrl })
            : StatusCode(response.StatusCode, response.Message);
    }
}

⚙️ Configuration

S3StorageOptions (AWS:S3 section)

All settings are optional with production-ready defaults:

AWS Credentials Configuration

Credentials can be configured via unified keys (recommended) or legacy keys (deprecated):

⚠️ Deprecation Notice: Legacy keys (S3Bucket:*, AwsConfiguration:*) are maintained for backward compatibility but should not be used in new projects. They will be removed in v3.0.0.

* Credentials are optional when using:

• IAM roles (EC2 instances, ECS tasks)
• Instance profiles
• AWS credentials file (~/.aws/credentials)

** Required only when using S3ObjectCustom with IConfiguration

Flexible Configuration Examples

Recommended (unified keys):

{
  "AWS": {
    "S3": {
      "DefaultBucketName": "my-bucket",
      "Region": "us-east-1"
    },
    "AccessKey": "AKIA...",
    "SecretKey": "secret..."
  }
}

⚠️ Legacy keys (deprecated - avoid in new projects):

{
  "S3Bucket": {
    "Name": "my-bucket",
    "Region": "us-east-1"
  },
  "AwsConfiguration": {
    "AWSAccessKey": "AKIA...",
    "AWSSecretKey": "secret..."
  }
}

IAM Roles (no credentials needed):

{
  "AWS": {
    "S3": {
      "DefaultBucketName": "my-bucket",
      "Region": "us-east-1"
    }
  }
}

High-Throughput Workload:

{
  "AWS": {
    "S3": {
      "MaxRequestsPerSecond": 200,
      "MaxRetries": 5,
      "TimeoutSeconds": 120
    }
  }
}

S3-Compatible Services (MinIO, DigitalOcean Spaces):

{
  "AWS": {
    "S3": {
      "ForcePathStyle": true,
      "Region": "us-east-1"
    }
  }
}

🛠️ Advanced Usage

Downloading an Object

var s3Object = new S3ObjectCustom(_configuration);
s3Object.Initialize("uploads/invoice-2024.pdf");

var response = await _s3Service.GetObjectAsync(s3Object);

if (response.StatusCode == 200)
{
    return File(response.Content, response.ContentType, response.FileName);
}

Generating a Presigned URL

var s3Object = new S3ObjectCustom(_configuration);
s3Object.Initialize("uploads/report.pdf");

var urlResponse = await _s3Service.GetPresignedUrlAsync(s3Object, expirationInMinutes: 30);

if (urlResponse.StatusCode == 200)
{
    var presignedUrl = urlResponse.FileName;
    // Share URL with users - expires in 30 minutes
}

Checking if an Object Exists

var exists = await _s3Service.DoesObjectExistAsync(s3Object);

if (exists)
{
    // File exists in S3
}

Deleting an Object

var response = await _s3Service.DeleteAsync(s3Object);

if (response.StatusCode == 200)
{
    // Successfully deleted
}

🚀 Performance

v2.0.0 Performance Improvements

Rate Limiting Behavior

The service automatically enforces configured rate limits:

// This will automatically throttle to 100 req/s (default)
var tasks = Enumerable.Range(0, 500)
    .Select(i => _s3Service.UploadAsync(objects[i]));

await Task.WhenAll(tasks); // Completes in ~5 seconds with smooth throttling

Connection Pooling

Clients are pooled by credentials + region:

// First call: Creates new client
await _s3Service.UploadAsync(s3Object); // ~200ms

// Subsequent calls: Reuses pooled client
await _s3Service.UploadAsync(s3Object2); // ~50ms (4x faster!)

🔄 Upgrade Guide

Migrating from v1.x to v2.0.0

Breaking Changes:

1. Service registration changed from direct instantiation to DI
2. Constructor requires IOptions<S3StorageOptions> and ILogger<S3StorageService>

Migration Steps:

// OLD (v1.x) - Remove this
services.AddScoped<IS3StorageService, S3StorageService>();

// NEW (v2.0.0) - Add this
services.AddS3Storage(configuration);

Benefits:

• Automatic retry for transient AWS errors (503, 500, timeouts)
• Connection pooling reduces latency by 66%
• Rate limiting prevents throttling errors
• Detailed logging for diagnostics

See UPGRADE_GUIDE_v2.0.0.md for complete migration instructions.

📚 Dependencies

• .NET 10+
• AWSSDK.Core 4.0.3.6+
• AWSSDK.S3 4.0.15+
• Polly 8.6.5+ (NEW in v2.0)
• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Options

🛡️ Error Handling

All service methods return an S3Response object with comprehensive error information:

public class S3Response
{
    public int StatusCode { get; set; }      // HTTP-like: 200, 201, 404, 500
    public string Message { get; set; }       // Success or error message
    public byte[]? Content { get; set; }      // File bytes (downloads)
    public string? ContentType { get; set; }  // MIME type
    public string? FileName { get; set; }     // File name or presigned URL
}

Retry Behavior

The service automatically retries these transient errors:

• 503 Service Unavailable (AWS overload)
• 500 Internal Server Error (AWS issue)
• RequestTimeout / SlowDown (AWS throttling)
• HttpRequestException (network issues)

Retry Schedule (default):

• Attempt 1: Immediate
• Attempt 2: 500ms delay
• Attempt 3: 1s delay
• Attempt 4: 2s delay
• Attempt 5: 4s delay (if MaxRetries=4)

Logging

The service logs all operations with structured context:

// Successful operations
_logger.LogInformation("Successfully uploaded {Key} to bucket {Bucket}",
    "uploads/file.pdf", "my-bucket");

// Retry attempts
_logger.LogWarning("S3 operation retry {RetryCount}/{MaxRetries} after {Delay}. Error: SlowDown",
    2, 3, "1s");

// Errors
_logger.LogError("S3 error uploading {Key}: {ErrorCode} - {Message}",
    "uploads/file.pdf", "AccessDenied", "Insufficient permissions");

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

MIT License. See LICENSE for details.

👤 Author

Ivan Paz

🏢 Company

Acontplus