Agent Context for S3Mock Server Module

Inherits all conventions from the root AGENTS.md. Below are module-specific additions only.

Core S3Mock server implementation.

Structure

server/src/main/kotlin/com/adobe/testing/s3mock/
├── S3MockApplication.kt       # Spring Boot entry
├── S3MockConfiguration.kt     # Top-level config
├── S3MockProperties.kt        # Properties binding
├── common/                    # Shared leaf package (s3 and vectors may both depend on it)
│   ├── StripedLocks.kt
│   └── AwsHttpHeaders.kt      # AWS-specific header constants
├── s3/                        # Core S3 API bounded context
│   ├── S3Exception.kt
│   ├── controller/
│   │   ├── *Controller.kt         # REST endpoints
│   │   ├── ControllerConfiguration.kt  # Controller beans + exception handlers
│   │   └── ControllerProperties.kt
│   ├── dto/                       # XML/JSON models (*Result, request/response)
│   ├── model/                     # Persisted metadata (BucketMetadata, S3ObjectMetadata, ...)
│   ├── service/
│   │   ├── *Service.kt            # Business logic
│   │   └── ServiceConfiguration.kt  # Service beans (used in @SpringBootTest)
│   └── store/
│       ├── *Store.kt              # Persistence
│       ├── StoreConfiguration.kt  # Store beans (used in @SpringBootTest)
│       └── StoreProperties.kt
└── vectors/                   # S3 Vectors API bounded context (separate ports, JSON wire format)
    ├── controller/ service/ store/ dto/

s3 and vectors are independent bounded contexts — neither may depend on the other (enforced by ArchitectureTest).

Implementation Flow

Adding S3 operation: Follow DTO → Store → Service → Controller → IT:

1. DTO (s3/dto/): Data classes with Jackson annotations — see root AGENTS.md § XML Serialization for the correct tools.jackson annotations and namespace. Verify element names against AWS S3 API docs.
2. Store (s3/store/): Filesystem path resolution, binary storage, metadata JSON. Key classes: BucketStore, ObjectStore, BucketMetadata, S3ObjectMetadata. Acquire the appropriate lock (see Locking section below).
3. Service (s3/service/): Validation, store coordination. Throw S3Exception constants (e.g., S3Exception.NO_SUCH_BUCKET) — see docs/SPRING.md for exception handling rules.
4. Controller (s3/controller/): HTTP mapping only — delegate all logic to services. Controllers never catch exceptions.
5. Integration test (integration-tests/): Real AWS SDK v2 against the Docker container — see integration-tests/AGENTS.md. Run make integration-tests to verify XML serialization against the AWS S3 API.
6. Update docs: CHANGELOG.md (user-facing entry) and root AGENTS.md Configuration table if new properties are added.

Locking

Each store uses a ConcurrentHashMap keyed by entity identity to hold one plain Any() lock object per entity. All reads and writes of metadata files must hold the corresponding lock.

Pattern for adding a store method that reads or writes metadata:

// Register lock lazily (writes only — reads rely on the lock already existing)
lockStore.putIfAbsent(id, Any())
// Acquire lock
synchronized(lockStore[id]!!) {
    // read or write metadata here
}

Rules:

• Never skip the lock for reads — getBucketMetadata and getS3ObjectMetadata are also synchronized.
• Never acquire more than one lock in a single call path — there is no established ordering, so taking two locks risks deadlock.
• Do not introduce ReentrantLock, ReadWriteLock, or other lock types — the existing synchronized/Any() pattern is intentional and consistent throughout all stores.

Storage Schema

Filesystem layout:

<root>/<bucket>/bucketMetadata.json
<root>/<bucket>/<uuid>/binaryData
<root>/<bucket>/<uuid>/objectMetadata.json
<root>/<bucket>/<uuid>/<version-id>-binaryData              # versioning
<root>/<bucket>/<uuid>/<version-id>-objectMetadata.json      # versioning
<root>/<bucket>/multiparts/<upload-id>/multipartMetadata.json
<root>/<bucket>/multiparts/<upload-id>/<part-number>.part
<root>/<bucket>/multiparts/<upload-id>/<part-number>.partmeta.json  # per-part checksum + size

bucketMetadata.json fields (BucketMetadata):

objectMetadata.json fields (S3ObjectMetadata):

<part-number>.partmeta.json fields (PartMetadata) — written alongside each .part file during UploadPart; deleted after CompleteMultipartUpload:

Testing

See docs/TESTING.md for the full strategy. Service and store tests use @SpringBootTest with @MockitoBean; controller tests use @WebMvcTest with @MockitoBean and BaseControllerTest. Always extend the appropriate base class (ServiceTestBase, StoreTestBase, BaseControllerTest).

Configuration

Three @ConfigurationProperties classes bind environment variables to typed properties:

• StoreProperties (com.adobe.testing.s3mock.store.*) — storage root, buckets, KMS, region
• ControllerProperties (com.adobe.testing.s3mock.controller.*) — context path
• S3MockProperties (com.adobe.testing.s3mock.*) — top-level settings

When adding, renaming, or removing a property, you must also update the testsupport modules that expose it to users:

• testsupport/testcontainers/ — add/update a withX() method and PROP_X env var constant in S3MockContainer (uppercase Spring key, replace . with _)
• testsupport/common/ — add/update a withX() method and PROP_X constant in S3MockStarter (Spring key form)
• AGENTS.md (root) — update the Configuration section env var table if the property is user-facing
• README.md — update the configuration table if the property is user-facing