API consistency: Bucket API / DTOs

Checking AWS APIs for changes and S3Mock for implementations and tests.

Fixes #2340

Author: afranken

integration-tests/src/test/kotlin/com/adobe/testing/s3mock/its/BucketIT.kt

@@ -26,13 +26,16 @@ import software.amazon.awssdk.awscore.exception.AwsServiceException
 import software.amazon.awssdk.services.s3.S3Client
 import software.amazon.awssdk.services.s3.model.AbortIncompleteMultipartUpload
 import software.amazon.awssdk.services.s3.model.BucketLifecycleConfiguration
+import software.amazon.awssdk.services.s3.model.BucketType
 import software.amazon.awssdk.services.s3.model.BucketVersioningStatus
+import software.amazon.awssdk.services.s3.model.DataRedundancy
 import software.amazon.awssdk.services.s3.model.DeleteBucketRequest
 import software.amazon.awssdk.services.s3.model.ExpirationStatus
 import software.amazon.awssdk.services.s3.model.GetBucketLifecycleConfigurationRequest
 import software.amazon.awssdk.services.s3.model.LifecycleExpiration
 import software.amazon.awssdk.services.s3.model.LifecycleRule
 import software.amazon.awssdk.services.s3.model.LifecycleRuleFilter
+import software.amazon.awssdk.services.s3.model.LocationType
 import software.amazon.awssdk.services.s3.model.MFADelete
 import software.amazon.awssdk.services.s3.model.MFADeleteStatus
 import software.amazon.awssdk.services.s3.model.NoSuchBucketException
@@ -68,6 +71,35 @@ internal class BucketIT : S3TestBase() {
     }
   }
 
+  @Test
+  @S3VerifiedSuccess(year = 2025)
+  fun `creating a bucket with configuration is successful`(testInfo: TestInfo) {
+    val bucketName = bucketName(testInfo)
+    val createBucketResponse = s3Client.createBucket {
+      it.bucket(bucketName)
+      it.createBucketConfiguration {
+        it.locationConstraint("ap-southeast-5")
+        it.bucket {
+          it.dataRedundancy(DataRedundancy.SINGLE_AVAILABILITY_ZONE)
+          it.type(BucketType.DIRECTORY)
+        }
+        it.location {
+          it.name("SomeName")
+          it.type(LocationType.AVAILABILITY_ZONE)
+        }
+      }
+    }
+    assertThat(createBucketResponse.sdkHttpResponse().statusCode()).isEqualTo(200)
+    assertThat(createBucketResponse.location()).isEqualTo("/$bucketName")
+
+    val bucketCreated = s3Client.waiter().waitUntilBucketExists { it.bucket(bucketName) }
+    val bucketCreatedResponse = bucketCreated.matched().response().get()
+    assertThat(bucketCreatedResponse).isNotNull
+
+    //does not throw exception if bucket exists.
+    s3Client.headBucket { it.bucket(bucketName) }
+  }
+
   @Test
   @S3VerifiedSuccess(year = 2025)
   fun `deleting a non-empty bucket fails`(testInfo: TestInfo) {

server/src/main/java/com/adobe/testing/s3mock/BucketController.java

@@ -16,7 +16,10 @@
 
 package com.adobe.testing.s3mock;
 
+import static com.adobe.testing.s3mock.util.AwsHttpHeaders.X_AMZ_BUCKET_LOCATION_NAME;
+import static com.adobe.testing.s3mock.util.AwsHttpHeaders.X_AMZ_BUCKET_LOCATION_TYPE;
 import static com.adobe.testing.s3mock.util.AwsHttpHeaders.X_AMZ_BUCKET_OBJECT_LOCK_ENABLED;
+import static com.adobe.testing.s3mock.util.AwsHttpHeaders.X_AMZ_BUCKET_REGION;
 import static com.adobe.testing.s3mock.util.AwsHttpHeaders.X_AMZ_OBJECT_OWNERSHIP;
 import static com.adobe.testing.s3mock.util.AwsHttpParameters.CONTINUATION_TOKEN;
 import static com.adobe.testing.s3mock.util.AwsHttpParameters.ENCODING_TYPE;
@@ -39,15 +42,21 @@
 import static com.adobe.testing.s3mock.util.AwsHttpParameters.VERSION_ID_MARKER;
 import static org.springframework.http.MediaType.APPLICATION_XML_VALUE;
 
+import com.adobe.testing.S3Verified;
 import com.adobe.testing.s3mock.dto.BucketLifecycleConfiguration;
+import com.adobe.testing.s3mock.dto.BucketType;
+import com.adobe.testing.s3mock.dto.CreateBucketConfiguration;
 import com.adobe.testing.s3mock.dto.ListAllMyBucketsResult;
 import com.adobe.testing.s3mock.dto.ListBucketResult;
 import com.adobe.testing.s3mock.dto.ListBucketResultV2;
 import com.adobe.testing.s3mock.dto.ListVersionsResult;
 import com.adobe.testing.s3mock.dto.LocationConstraint;
 import com.adobe.testing.s3mock.dto.ObjectLockConfiguration;
+import com.adobe.testing.s3mock.dto.ObjectOwnership;
+import com.adobe.testing.s3mock.dto.Region;
 import com.adobe.testing.s3mock.dto.VersioningConfiguration;
 import com.adobe.testing.s3mock.service.BucketService;
+import com.adobe.testing.s3mock.store.BucketMetadata;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.CrossOrigin;
@@ -60,8 +69,6 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestMethod;
 import org.springframework.web.bind.annotation.RequestParam;
-import software.amazon.awssdk.regions.Region;
-import software.amazon.awssdk.services.s3.model.ObjectOwnership;
 
 /**
  * Handles requests related to buckets.
@@ -123,15 +130,34 @@ public ResponseEntity<ListAllMyBucketsResult> listBuckets() {
           NOT_VERSIONING
       }
   )
+  @S3Verified(year = 2025)
   public ResponseEntity<Void> createBucket(@PathVariable final String bucketName,
       @RequestHeader(value = X_AMZ_BUCKET_OBJECT_LOCK_ENABLED,
           required = false, defaultValue = "false") boolean objectLockEnabled,
       @RequestHeader(value = X_AMZ_OBJECT_OWNERSHIP,
-          required = false, defaultValue = "BucketOwnerEnforced") ObjectOwnership objectOwnership) {
+          required = false, defaultValue = "BucketOwnerEnforced") ObjectOwnership objectOwnership,
+      @RequestBody(required = false) CreateBucketConfiguration createBucketRequest) {
     bucketService.verifyBucketNameIsAllowed(bucketName);
     bucketService.verifyBucketDoesNotExist(bucketName);
-    bucketService.createBucket(bucketName, objectLockEnabled, objectOwnership);
-    return ResponseEntity.ok().build();
+    bucketService.createBucket(bucketName,
+        objectLockEnabled,
+        objectOwnership,
+        getRegion(createBucketRequest),
+        createBucketRequest != null ? createBucketRequest.bucket() : null,
+        createBucketRequest != null ? createBucketRequest.location() : null
+    );
+    return ResponseEntity.ok()
+        .header(LOCATION, "/" + bucketName)
+        .build();
+  }
+
+  private String getRegion(CreateBucketConfiguration createBucketRequest) {
+    if (createBucketRequest != null
+        && createBucketRequest.locationConstraint() != null
+        && createBucketRequest.locationConstraint().region() != null) {
+      return createBucketRequest.locationConstraint().region().toString();
+    }
+    return this.region.toString();
   }
 
   /**
@@ -151,11 +177,24 @@ public ResponseEntity<Void> createBucket(@PathVariable final String bucketName,
       },
       method = RequestMethod.HEAD
   )
+  @S3Verified(year = 2025)
   public ResponseEntity<Void> headBucket(@PathVariable final String bucketName) {
-    bucketService.verifyBucketExists(bucketName);
-    //return bucket region
-    //return bucket location
-    return ResponseEntity.ok().build();
+    BucketMetadata bucketMetadata = bucketService.verifyBucketExists(bucketName);
+    return ResponseEntity
+        .ok()
+        .header(X_AMZ_BUCKET_REGION, bucketMetadata.bucketRegion())
+        .headers(h -> {
+          if (bucketMetadata.bucketInfo() != null
+              && bucketMetadata.bucketInfo().type() != null
+              && bucketMetadata.bucketInfo().type() == BucketType.DIRECTORY
+              && bucketMetadata.locationInfo() != null
+              && bucketMetadata.locationInfo().name() != null
+              && bucketMetadata.locationInfo().type() != null) {
+            h.add(X_AMZ_BUCKET_LOCATION_NAME, bucketMetadata.locationInfo().name());
+            h.add(X_AMZ_BUCKET_LOCATION_TYPE, bucketMetadata.locationInfo().type().toString());
+          }
+        })
+        .build();
   }
 
   /**
@@ -392,8 +431,11 @@ public ResponseEntity<Void> deleteBucketLifecycleConfiguration(
   )
   public ResponseEntity<LocationConstraint> getBucketLocation(
       @PathVariable String bucketName) {
-    bucketService.verifyBucketExists(bucketName);
-    return ResponseEntity.ok(new LocationConstraint(region));
+    BucketMetadata bucketMetadata = bucketService.verifyBucketExists(bucketName);
+    String bucketRegion = bucketMetadata.bucketRegion() != null
+        ? bucketMetadata.bucketRegion()
+        : region.toString();
+    return ResponseEntity.ok(new LocationConstraint(bucketRegion));
   }
 
   /**

server/src/main/java/com/adobe/testing/s3mock/ObjectCannedAclHeaderConverter.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2024 Adobe.
+ *  Copyright 2017-2025 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -16,11 +16,11 @@
 
 package com.adobe.testing.s3mock;
 
+import com.adobe.testing.s3mock.dto.ObjectCannedACL;
 import com.adobe.testing.s3mock.util.AwsHttpHeaders;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.lang.NonNull;
 import org.springframework.lang.Nullable;
-import software.amazon.awssdk.services.s3.model.ObjectCannedACL;
 
 /**
  * Converts values of the {@link AwsHttpHeaders#X_AMZ_ACL} which is sent by the Amazon client.

server/src/main/java/com/adobe/testing/s3mock/ObjectController.java

@@ -82,6 +82,7 @@
 import com.adobe.testing.s3mock.dto.GetObjectAttributesOutput;
 import com.adobe.testing.s3mock.dto.LegalHold;
 import com.adobe.testing.s3mock.dto.ObjectAttributes;
+import com.adobe.testing.s3mock.dto.ObjectCannedACL;
 import com.adobe.testing.s3mock.dto.ObjectKey;
 import com.adobe.testing.s3mock.dto.Owner;
 import com.adobe.testing.s3mock.dto.Retention;
@@ -124,7 +125,6 @@
 import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.multipart.MultipartFile;
 import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
-import software.amazon.awssdk.services.s3.model.ObjectCannedACL;
 
 /**
  * Handles requests related to objects.

server/src/main/java/com/adobe/testing/s3mock/ObjectOwnershipHeaderConverter.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2024 Adobe.
+ *  Copyright 2017-2025 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -16,11 +16,11 @@
 
 package com.adobe.testing.s3mock;
 
+import com.adobe.testing.s3mock.dto.ObjectOwnership;
 import com.adobe.testing.s3mock.util.AwsHttpHeaders;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.lang.NonNull;
 import org.springframework.lang.Nullable;
-import software.amazon.awssdk.services.s3.model.ObjectOwnership;
 
 /**
  * Converts values of the {@link AwsHttpHeaders#X_AMZ_OBJECT_OWNERSHIP} which is sent by the Amazon

server/src/main/java/com/adobe/testing/s3mock/S3MockProperties.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2022 Adobe.
+ *  Copyright 2017-2025 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -16,9 +16,9 @@
 
 package com.adobe.testing.s3mock;
 
+import com.adobe.testing.s3mock.dto.Region;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.boot.context.properties.bind.DefaultValue;
-import software.amazon.awssdk.regions.Region;
 
 @ConfigurationProperties("com.adobe.testing.s3mock")
 public record S3MockProperties(

server/src/main/java/com/adobe/testing/s3mock/dto/Bucket.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2024 Adobe.
+ *  Copyright 2017-2025 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -25,6 +25,7 @@
  * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_Bucket.html">API Reference</a>.
  */
 public record Bucket(@JsonIgnore Path path,
+              @JsonProperty("BucketRegion") String bucketRegion,
               @JsonProperty("Name") String name,
               @JsonProperty("CreationDate") String creationDate) {
 
@@ -33,6 +34,7 @@ public static Bucket from(BucketMetadata bucketMetadata) {
       return null;
     }
     return new Bucket(bucketMetadata.path(),
+        bucketMetadata.bucketRegion(),
         bucketMetadata.name(),
         bucketMetadata.creationDate());
   }

server/src/main/java/com/adobe/testing/s3mock/dto/BucketInfo.java

@@ -0,0 +1,33 @@
+/*
+ *  Copyright 2017-2025 Adobe.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.adobe.testing.s3mock.dto;
+
+import com.adobe.testing.S3Verified;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_BucketInfo.html">API Reference</a>.
+ */
+@S3Verified(year = 2025)
+public record BucketInfo(
+    @JsonProperty("DataRedundancy")
+    DataRedundancy dataRedundancy,
+    @JsonProperty("Type")
+    BucketType type
+) {
+
+}

server/src/main/java/com/adobe/testing/s3mock/dto/BucketType.java

@@ -0,0 +1,50 @@
+/*
+ *  Copyright 2017-2025 Adobe.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.adobe.testing.s3mock.dto;
+
+import com.adobe.testing.S3Verified;
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_BucketInfo.html">API Reference</a>.
+ */
+@S3Verified(year = 2025)
+public enum BucketType {
+  DIRECTORY("Directory");
+
+  private final String value;
+
+  @JsonCreator
+  BucketType(String value) {
+    this.value = value;
+  }
+
+  public static BucketType fromValue(String value) {
+    return switch (value) {
+      case "Directory" -> DIRECTORY;
+      default -> null;
+    };
+  }
+
+  @Override
+  @JsonValue
+  public String toString() {
+    return this.value;
+  }
+
+}