Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (49 loc) · 3.53 KB

AGENTS.md

File metadata and controls

65 lines (49 loc) · 3.53 KB

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
├── controller/
│   ├── *Controller.kt         # REST endpoints
│   ├── ControllerConfiguration.kt  # Controller beans + exception handlers
│   └── ControllerProperties.kt
├── dto/                       # XML/JSON models (*Result, request/response)
├── 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
└── util/
    ├── DigestUtil.kt          # ETag/checksum computation (replaces Apache Commons)
    ├── EtagUtil.kt            # ETag normalization
    ├── HeaderUtil.kt          # HTTP header helpers
    └── AwsHttpHeaders.kt      # AWS-specific header constants

Implementation Flow

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

  1. DTO (dto/): Data classes with Jackson annotations for XML/JSON models. In current DTOs, use @JsonRootName("...", namespace = "http://s3.amazonaws.com/doc/2006-03-01/") and @JsonProperty("...", namespace = "...") from com.fasterxml.jackson.annotation, plus XML-specific annotations such as @JacksonXmlElementWrapper(useWrapping = false) from tools.jackson.dataformat.xml.annotation for collections. See root AGENTS.md XML Serialization section. Verify element names against AWS S3 API docs.
  2. Store (store/): Filesystem path resolution, binary storage, metadata JSON. Key classes: BucketStore, ObjectStore, BucketMetadata, S3ObjectMetadata.
  3. Service (service/): Validation, store coordination. Throw S3Exception constants (e.g., S3Exception.NO_SUCH_BUCKET) — see docs/SPRING.md for exception handling rules.
  4. Controller (controller/): HTTP mapping only — delegate all logic to services. Controllers never catch exceptions.

Error Handling

  • S3MockExceptionHandler converts S3Exception → XML ErrorResponse with the correct HTTP status
  • IllegalStateExceptionHandler converts unexpected errors → 500 InternalError

See docs/SPRING.md for exception handling patterns and rules.

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

Running

make run
docker run -p 9090:9090 -p 9191:9191 adobe/s3mock:latest