Indiko.Blocks.Storage.S3 4.0.0

Indiko.Blocks.Storage.S3

S3 implementation of IFileProvider, for Amazon S3 and S3-compatible object storage.

Overview

This package stores files as objects in a bucket. It works against Amazon S3 and against S3-compatible services such as MinIO, Ceph RGW, Wasabi, Cloudflare R2 and Backblaze B2. Uploads and downloads stream instead of being buffered in memory, and large uploads are split into a multipart transfer automatically.

Key Components

• S3StorageBlock (block entry point)
• S3StorageFileProvider (IFileProvider implementation)
• AddS3Storage(configuration, logger) extension
• S3StorageOptions

DI Registration Entry Points

• S3StorageBlock.ConfigureServices(...)
• services.AddS3Storage(configuration, logger)

Registers IAmazonS3 and ITransferUtility as singletons and IFileProvider as scoped.

Configuration

Configuration section: S3StorageOptions

Amazon S3 with an IAM role

{
  "S3StorageOptions": {
    "Enabled": true,
    "BucketName": "my-app-documents",
    "Folder": "invoices",
    "Region": "eu-central-1",
    "MaxFileSize": 25,
    "AllowedFileTypes": [ ".pdf", ".png" ],
    "ServerSideEncryption": "AwsManagedKey"
  }
}

No credentials in the configuration: the SDK resolves them from the environment, the ECS task role, IRSA on EKS or the EC2 instance profile. That is the recommended setup on AWS, because those credentials rotate on their own.

MinIO or another S3-compatible service

{
  "S3StorageOptions": {
    "Enabled": true,
    "BucketName": "documents",
    "ServiceUrl": "https://minio.internal:9000",
    "Region": "us-east-1",
    "AccessKey": "...",
    "SecretKey": "...",
    "MaxFileSize": 100,
    "AllowedFileTypes": [ ".pdf", ".png", ".zip" ]
  }
}

ForcePathStyle defaults to on for a custom ServiceUrl. Region is still worth setting: several compatible services need it for request signing.

Minimal Usage

var provider = serviceProvider.GetRequiredService<IFileProvider>();

// Upload, streaming -- the payload is never held in memory in full
await using var file = File.OpenRead("invoice.pdf");
var fileName = await provider.SaveFileAsync(".pdf", "invoice-2026-001.pdf", file, cancellationToken);

// Hand out a link valid for 15 minutes
var url = await provider.GetFullPathAsync(fileName, cancellationToken);

// Download, streaming
await using var download = await provider.OpenReadAsync(fileName, cancellationToken);

Runtime Behavior and Caveats

• SaveFileAsync(fileExtension, content) expects Base64, like the Azure Blob Storage provider. The local provider stores the same argument as raw text, so this overload is not portable -- prefer a stream overload.
• Uploads overwrite. S3 PutObject has no "fail if exists"; use ExistsAsync first when that matters.
• CopyFileAsync / MoveFileAsync refuse an existing destination with ConflictException, matching the local provider. Copies run server-side; objects above 5 GiB are copied in parts. MoveFileAsync deletes the source only after the copy has completed -- an interruption leaves both copies, never neither.
• A pre-signed URL is a bearer token. Anyone holding it can read the object until it expires, and it cannot be revoked. Keep PresignedUrlExpiration short. SigV4 caps the lifetime at seven days, and a URL signed with temporary credentials dies with them.
• UsePresignedUrls: false returns the plain object URL, which only works on a public bucket or behind a CDN that signs requests itself.
• The size limit on a non-seekable stream is enforced mid-transfer. A request body has no known length, so the upload is aborted once the limit is passed and the partial object is removed. A seekable stream is rejected before anything is sent.
• The bucket is never created. Creation carries decisions (region, versioning, lifecycle, public access block) that do not belong in application startup. VerifyBucketOnStartup only checks reachability.
• ListFilesAndDirectoriesAsync pages to the end. A prefix holding many objects produces many requests and a large result.
• Thrown exceptions: ConfigurationException (bucket missing or unreachable, invalid configuration), NotFoundException, ConflictException, NotAllowedException (extension not allowed, invalid file name, non-Base64 content), LimitExceededException. Other S3 failures surface as AmazonS3Exception.

Only One Storage Block Per Application

Every storage block registers IFileProvider under the same contract, and block discovery resolves one IStorageBlock. Reference Indiko.Blocks.Storage.S3 or .Local or .AzureBlobStorage, not several at once.

IAM Permissions

The minimum for normal operation on the configured prefix:

• s3:PutObject, s3:GetObject, s3:DeleteObject
• s3:ListBucket for ListFilesAndDirectoriesAsync and VerifyBucketOnStartup
• s3:AbortMultipartUpload for aborting a failed multipart transfer
• kms:GenerateDataKey and kms:Decrypt when using KmsManagedKey

A lifecycle rule for incomplete multipart uploads is worth having: parts of an upload that was never completed or aborted stay billable.

Target Framework

• .NET 10

Related Packages

• Indiko.Blocks.Storage.Abstractions
• Indiko.Blocks.Storage.Local
• Indiko.Blocks.Storage.AzureBlobStorage