feat(s3): add object annotations support

[rafaelsierra]

Summary

Adds S3 Object Annotations: named UTF-8 payloads (1 B to 1 MiB, up to 1,000 per object version) attached to object versions without re-uploading the object, matching the AWS annotations API. Closes #3239.

• PutObjectAnnotation, GetObjectAnnotation, ListObjectAnnotations, DeleteObjectAnnotation via the ?annotation subresource (REST XML), including x-amz-object-if-match,x-amz-checksum-mode, checksum validation, and pagination with continuation tokens
• Annotations are per-object-version: new versions do not inherit them, overwrites and non-versioned deletes drop them, delete markers preserve them
• CopyObject copies annotations by default; x-amz-annotation-directive: COPY | EXCLUDE
• s3:ObjectAnnotation:Put / s3:ObjectAnnotation:Delete notification events and CloudTrail events; IAM actions enforced when auth is enabled
• Storage: annotation metadata in a new s3-annotations.json store; payload bytes as .s3ann blobs (object-body pattern), keeping payloads out of the single-document serialization of the metadata stores

Known follow-ups (not in this PR): S3 Metadata annotation tables, annotation replication, XXH*/SHA512/MD5 checksum algorithms, O(total-annotations) scan on annotation-heavy stores, and the residual non-atomicity window between annotation cleanup and the replacement metadata publish on overwrite. Note: DeleteObject now takes the bucket monitor, so notification delivery serializes with other writes on the same bucket.

Type of change

• Bug fix (fix:)
• New feature (feat:)
• Breaking change (feat!: or fix!:)
• Docs / chore

AWS Compatibility

Verified against AWS SDK for Java v2 2.52.0 (compat suite, S3AnnotationsTest, 11/11 passing
against a running Floci container): SDK round-trips for put/get/list/delete-object-annotation, checksum headers with checksumMode(ENABLED), aws-chunked/streaming-trailer PUT framing, the modeled NoSuchAnnotationException, versioned-bucket per-version attachment, and the x-amz-object-annotation-directive COPY/EXCLUDE directive on CopyObject (the real header name, which this PR also accepts alongside the x-amz-annotation-directive spelling).

Verified with AWS CLI 2.36.41: put/get/list/delete-object-annotation round-trip, including
the CRC64NVME default checksum. The existing S3Test compat suite still passes.

Checklist

• ./mvnw test passes locally
• New or updated integration test added
• Commit messages follow Conventional Commits

[greptile-apps]

Greptile Summary

Adds AWS-compatible S3 object annotations, including REST-XML operations, version-aware storage, checksums, IAM authorization, notifications, CloudTrail classification, copy directives, persistence, documentation, and SDK compatibility coverage. Changes since the previous review:

• Resolve source and destination bucket monitors through the global namespace during CopyObject, preserving valid cross-account copies while retaining annotation-copy serialization.
• Log compatibility-test cleanup failures with bucket and object context.
• Fully address the previously reported copy atomicity, reset cleanup, cross-account locking, and swallowed cleanup-exception concerns.

Confidence Score: 5/5

The PR appears safe to merge; no blocking or non-blocking actionable issue remains.

The latest changes use the globally resolved source and destination bucket instances as copy monitors while leaving the intentionally caller-scoped object and annotation storage behavior unchanged, and teardown exceptions are now logged with useful context. All five previous findings were manually resolved without explanatory replies, and the current code addresses their reported failure modes.

Important Files Changed

Filename	Overview
src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java	Implements annotation lifecycle, storage, versioning, checksums, copy semantics, cleanup, locking, and event delivery; the latest monitor-resolution fix preserves cross-account copy behavior.
src/main/java/io/github/hectorvent/floci/services/s3/S3Controller.java	Adds REST-XML routing, request validation, response generation, authorization, checksum handling, and CloudTrail emission for annotation operations.
src/main/java/io/github/hectorvent/floci/services/s3/model/ObjectAnnotation.java	Defines persisted annotation identity, metadata, checksum, encryption, and payload-location fields.
compatibility-tests/sdk-test-java/src/test/java/com/floci/test/S3AnnotationsTest.java	Exercises annotation operations through the AWS SDK and now logs tolerated teardown failures with diagnostic context.
src/test/java/io/github/hectorvent/floci/services/s3/S3AnnotationsIntegrationTest.java	Covers REST-level annotation behavior and compatibility constraints.
src/test/java/io/github/hectorvent/floci/services/s3/S3ServiceAnnotationsTest.java	Covers service-level annotation storage, versioning, copying, cleanup, limits, and concurrency behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Client[AWS SDK or CLI] --> Controller[S3 REST-XML controller]
    Controller --> Auth[IAM authorization]
    Auth --> Service[S3 service]
    Service --> ObjectStore[Object metadata and body]
    Service --> AnnotationStore[Annotation metadata]
    Service --> PayloadStore[Annotation payload blobs]
    Service --> Events[Notifications and CloudTrail]
    ObjectStore --> Copy[CopyObject]
    AnnotationStore --> Copy
    PayloadStore --> Copy

Loading

_{Reviews (3): Last reviewed commit: "fix(s3): lock cross-account copy buckets..." | Re-trigger Greptile}