Ticomix.Attachments.Storage.S3

Purpose Statement

A .NET library that provides AWS S3 (and S3-compatible) storage for the Ticomix attachments system, enabling secure and scalable cloud storage for application file attachments on Amazon S3 or an S3-compatible endpoint.

Technical Context

• Implements the IAttachments<TKey> interface from the Ticomix.Attachments.Common library
• Built on the AWS SDK for .NET (AWSSDK.S3 version 4.0.24.1)
• Supports .NET 8.0 and .NET 10.0 frameworks
• Uses generics to support multiple key types for attachment identification

Key Capabilities

• Object-Key Addressing: Addresses objects by the row's StorageKey (the S3 object key), falling back to Directory + FileName when StorageKey is unset
• Streaming Content Delivery: Streaming download via GetObject
• Attachment Lifecycle Management: Upload, download, copy, exists, and delete
• S3-Compatible Endpoints: Works against real AWS S3 or an S3-compatible proxy (e.g. S3Proxy over Azure Blob in dev) via S3AttachmentClientFactory

S3-compatible endpoint workarounds (#97376)

The dev S3Proxy (Azure-Blob-backed) is not AWS, so two AWS SDK v4 behaviours must be worked around. Both are proven out in the well-intel project and carried here:

1. Single-part upload — the proxy rejects SDK v4 multipart part uploads (HTTP 400). Construct S3Attachments<TKey> with forceSinglePartUpload: true for the proxy; leave it false for real AWS S3 so large objects keep multipart. Single PUT caps at 5 GB.
2. Explicit-full-range GET — the SDK validates the ETag as a 32-char hex MD5 only when no byte range is set; the proxy's ETags aren't MD5s and it throws. The provider always requests an explicit full byte range on reads. S3AttachmentClientFactory additionally sets RequestChecksumCalculation/ResponseChecksumValidation to WHEN_REQUIRED for a configured ServiceURL.

Integration Points

• Integrates with the Ticomix attachments ecosystem via the standard IAttachments<TKey> interface
• Compatible with Entity Framework Core for database storage of attachment metadata
• Works alongside other storage providers in the Ticomix.Attachments namespace; the AttachmentDispatcher routes rows whose AttachmentLocation is "AwsS3" to this provider

Database Models Used

• Attachment: attachment metadata including StorageKey (the S3 object key), file name, and directory, stored in a context implementing IAttachmentsDbContext<TKey>

Classes and Functions

S3Attachments

Main implementation. AttachmentLocation = "AwsS3". Constructor takes an injected IAmazonS3, the bucket name, and the forceSinglePartUpload flag.

Key Functions:

• UploadAsync: uploads a stream to S3 and records the object key in Attachment.StorageKey
• DownloadStreamingAsync: downloads object content as a stream (explicit-full-range workaround)
• DeleteAsync: removes the row and the S3 object
• CopyAsync: server-side CopyObject of an existing attachment
• ExistsAsync: HEAD via GetObjectMetadata

S3AttachmentClientFactory

Builds a configured IAmazonS3. A configured serviceUrl selects the S3-compatible proxy (with the checksum opt-out); no serviceUrl selects real AWS S3 with the default credential chain.

IAttachmentBlobStore (path-addressed blobs)

S3Attachments also implements IAttachmentBlobStore for low-level, row-less object access (path download/upload/exists, bulk prefix delete), matching the AzureBlob provider.