add support for presigned head urls (#6158)

* adding headobject and headbucket functionality and test coverage

* Fixing identation and adding changelog and attribution

* adding javadoc

* Adding default implementation to maintain backwards compatibility

Author: RanVaknin

.changes/next-release/feature-AWSS3-da364d2.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS S3",
+    "contributor": "tmccombs",
+    "description": "Adds the ability to presign HeadObject and HeadBucket requests with the S3 Presigner"
+}

services/s3/src/it/java/software/amazon/awssdk/services/s3/S3PresignerIntegrationTest.java

@@ -52,6 +52,8 @@
 import software.amazon.awssdk.services.s3.presigner.model.PresignedCreateMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedDeleteObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedGetObjectRequest;
+import software.amazon.awssdk.services.s3.presigner.model.PresignedHeadBucketRequest;
+import software.amazon.awssdk.services.s3.presigner.model.PresignedHeadObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedPutObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedUploadPartRequest;
 import software.amazon.awssdk.services.s3.utils.S3TestUtils;
@@ -363,6 +365,50 @@ public void abortMultipartUpload_CanBePresigned() throws IOException {
         assertThat(getMultipartUpload(objectKey)).isNotPresent();
     }
 
+    @Test
+    public void headObject_CanBePresigned() throws IOException {
+        PresignedHeadObjectRequest presigned =
+            presigner.presignHeadObject(r -> r.signatureDuration(Duration.ofMinutes(5))
+                                             .headObjectRequest(hor -> hor.bucket(testBucket)
+                                                                         .key(testGetObjectKey)));
+
+        assertThat(presigned.isBrowserExecutable()).isFalse();
+
+        SdkHttpClient httpClient = ApacheHttpClient.builder().build(); // or UrlConnectionHttpClient.builder().build()
+
+        HttpExecuteRequest request = HttpExecuteRequest.builder()
+                                                       .request(presigned.httpRequest())
+                                                       .build();
+
+        HttpExecuteResponse response = httpClient.prepareRequest(request).call();
+
+        assertThat(response.httpResponse().isSuccessful()).isTrue();
+        assertThat(response.httpResponse().firstMatchingHeader("Content-Length")).isPresent();
+        assertThat(response.httpResponse().firstMatchingHeader("ETag")).isPresent();
+        assertThat(response.httpResponse().firstMatchingHeader("Last-Modified")).isPresent();
+
+    }
+
+    @Test
+    public void headBucket_CanBePresigned() throws IOException {
+        PresignedHeadBucketRequest presigned =
+            presigner.presignHeadBucket(r -> r.signatureDuration(Duration.ofMinutes(5))
+                                              .headBucketRequest(hbr -> hbr.bucket(testBucket)));
+
+        assertThat(presigned.isBrowserExecutable()).isFalse();
+
+        SdkHttpClient httpClient = ApacheHttpClient.builder().build(); // or UrlConnectionHttpClient.builder().build()
+
+        HttpExecuteRequest request = HttpExecuteRequest.builder()
+                                                       .request(presigned.httpRequest())
+                                                       .build();
+
+        HttpExecuteResponse response = httpClient.prepareRequest(request).call();
+
+        assertThat(response.httpResponse().isSuccessful()).isTrue();
+        assertThat(response.httpResponse().firstMatchingHeader("x-amz-bucket-region")).isPresent();
+    }
+
     private Consumer<CreateMultipartUploadRequest.Builder> createMultipartUploadRequest(String objectKey) {
         return r -> r.bucket(testBucket).key(objectKey);
     }

services/s3/src/main/java/software/amazon/awssdk/services/s3/internal/signing/DefaultS3Presigner.java

@@ -97,6 +97,8 @@
 import software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
 import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
+import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
 import software.amazon.awssdk.services.s3.model.PutObjectRequest;
 import software.amazon.awssdk.services.s3.model.UploadPartRequest;
 import software.amazon.awssdk.services.s3.presigner.S3Presigner;
@@ -105,11 +107,15 @@
 import software.amazon.awssdk.services.s3.presigner.model.CreateMultipartUploadPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.DeleteObjectPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.GetObjectPresignRequest;
+import software.amazon.awssdk.services.s3.presigner.model.HeadBucketPresignRequest;
+import software.amazon.awssdk.services.s3.presigner.model.HeadObjectPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedAbortMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedCompleteMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedCreateMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedDeleteObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedGetObjectRequest;
+import software.amazon.awssdk.services.s3.presigner.model.PresignedHeadBucketRequest;
+import software.amazon.awssdk.services.s3.presigner.model.PresignedHeadObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedPutObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedUploadPartRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PutObjectPresignRequest;
@@ -120,6 +126,8 @@
 import software.amazon.awssdk.services.s3.transform.CreateMultipartUploadRequestMarshaller;
 import software.amazon.awssdk.services.s3.transform.DeleteObjectRequestMarshaller;
 import software.amazon.awssdk.services.s3.transform.GetObjectRequestMarshaller;
+import software.amazon.awssdk.services.s3.transform.HeadBucketRequestMarshaller;
+import software.amazon.awssdk.services.s3.transform.HeadObjectRequestMarshaller;
 import software.amazon.awssdk.services.s3.transform.PutObjectRequestMarshaller;
 import software.amazon.awssdk.services.s3.transform.UploadPartRequestMarshaller;
 import software.amazon.awssdk.utils.AttributeMap;
@@ -141,6 +149,8 @@ public final class DefaultS3Presigner extends DefaultSdkPresigner implements S3P
     private final S3Configuration serviceConfiguration;
     private final List<ExecutionInterceptor> clientInterceptors;
     private final GetObjectRequestMarshaller getObjectRequestMarshaller;
+    private final HeadObjectRequestMarshaller headObjectRequestMarshaller;
+    private final HeadBucketRequestMarshaller headBucketRequestMarshaller;
     private final PutObjectRequestMarshaller putObjectRequestMarshaller;
     private final CreateMultipartUploadRequestMarshaller createMultipartUploadRequestMarshaller;
     private final UploadPartRequestMarshaller uploadPartRequestMarshaller;
@@ -193,6 +203,10 @@ private DefaultS3Presigner(Builder b) {
         // Copied from DefaultS3Client#getObject
         this.getObjectRequestMarshaller = new GetObjectRequestMarshaller(protocolFactory);
 
+        this.headObjectRequestMarshaller = new HeadObjectRequestMarshaller(protocolFactory);
+
+        this.headBucketRequestMarshaller = new HeadBucketRequestMarshaller(protocolFactory);
+
         // Copied from DefaultS3Client#putObject
         this.putObjectRequestMarshaller = new PutObjectRequestMarshaller(protocolFactory);
 
@@ -273,6 +287,28 @@ public PresignedGetObjectRequest presignGetObject(GetObjectPresignRequest reques
             .build();
     }
 
+    @Override
+    public PresignedHeadObjectRequest presignHeadObject(HeadObjectPresignRequest request) {
+        return presign(PresignedHeadObjectRequest.builder(),
+                       request,
+                       request.headObjectRequest(),
+                       HeadObjectRequest.class,
+                       headObjectRequestMarshaller::marshall,
+                       "HeadObject")
+            .build();
+    }
+
+    @Override
+    public PresignedHeadBucketRequest presignHeadBucket(HeadBucketPresignRequest request) {
+        return presign(PresignedHeadBucketRequest.builder(),
+                       request,
+                       request.headBucketRequest(),
+                       HeadBucketRequest.class,
+                       headBucketRequestMarshaller::marshall,
+                       "HeadBucket")
+            .build();
+    }
+
     @Override
     public PresignedPutObjectRequest presignPutObject(PutObjectPresignRequest request) {
         return presign(PresignedPutObjectRequest.builder(),

services/s3/src/main/java/software/amazon/awssdk/services/s3/presigner/S3Presigner.java

@@ -40,18 +40,24 @@
 import software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
 import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
+import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
 import software.amazon.awssdk.services.s3.model.PutObjectRequest;
 import software.amazon.awssdk.services.s3.model.UploadPartRequest;
 import software.amazon.awssdk.services.s3.presigner.model.AbortMultipartUploadPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.CompleteMultipartUploadPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.CreateMultipartUploadPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.DeleteObjectPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.GetObjectPresignRequest;
+import software.amazon.awssdk.services.s3.presigner.model.HeadBucketPresignRequest;
+import software.amazon.awssdk.services.s3.presigner.model.HeadObjectPresignRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedAbortMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedCompleteMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedCreateMultipartUploadRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedDeleteObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedGetObjectRequest;
+import software.amazon.awssdk.services.s3.presigner.model.PresignedHeadBucketRequest;
+import software.amazon.awssdk.services.s3.presigner.model.PresignedHeadObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedPutObjectRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PresignedUploadPartRequest;
 import software.amazon.awssdk.services.s3.presigner.model.PutObjectPresignRequest;
@@ -328,7 +334,7 @@ static Builder builder() {
      * <p />
      * This is a shorter method of invoking {@link #presignGetObject(GetObjectPresignRequest)} without needing
      * to call {@code GetObjectPresignRequest.builder()} or {@code .build()}.
-     * 
+     *
      * @see #presignGetObject(GetObjectPresignRequest)
      */
     default PresignedGetObjectRequest presignGetObject(Consumer<GetObjectPresignRequest.Builder> request) {
@@ -337,6 +343,128 @@ default PresignedGetObjectRequest presignGetObject(Consumer<GetObjectPresignRequ
         return presignGetObject(builder.build());
     }
 
+    /**
+     * Presign a {@link HeadObjectRequest} so that it can be executed at a later time without requiring additional
+     * signing or authentication.
+     * <p/>
+     *
+     * <b>Example Usage</b>
+     * <p/>
+     *
+     * <pre>
+     * {@code
+     *     S3Presigner presigner = ...;
+     *
+     *     // Create a HeadObjectRequest to be pre-signed
+     *     HeadObjectRequest headObjectRequest =
+     *         HeadObjectRequest.builder()
+     *                          .bucket("my-bucket")
+     *                          .key("my-key")
+     *                          .build();
+     *
+     *     // Create a HeadObjectPresignRequest to specify the signature duration
+     *     HeadObjectPresignRequest headObjectPresignRequest =
+     *         HeadObjectPresignRequest.builder()
+     *                                .signatureDuration(Duration.ofMinutes(10))
+     *                                .headObjectRequest(headObjectRequest)
+     *                                .build();
+     *
+     *     // Generate the presigned request
+     *     PresignedHeadObjectRequest presignedHeadObjectRequest =
+     *         presigner.presignHeadObject(headObjectPresignRequest);
+     *
+     *     // The presigned URL can be used with an HTTP client to retrieve object metadata
+     *     SdkHttpClient httpClient = ApacheHttpClient.builder().build();
+     *     HttpExecuteRequest request = HttpExecuteRequest.builder()
+     *                                                   .request(presignedHeadObjectRequest.httpRequest())
+     *                                                   .build();
+     *     HttpExecuteResponse response = httpClient.prepareRequest(request).call();
+     *
+     *     // Extract metadata from response headers
+     *     String contentLength = response.httpResponse().firstMatchingHeader("Content-Length").orElse("0");
+     * }
+     * </pre>
+     */
+    default PresignedHeadObjectRequest presignHeadObject(HeadObjectPresignRequest request) {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Presign a {@link HeadObjectRequest} so that it can be executed at a later time without requiring additional
+     * signing or authentication.
+     * <p />
+     * This is a shorter method of invoking {@link #presignHeadObject(HeadObjectPresignRequest)} without needing
+     * to call {@code HeadObjectPresignRequest.builder()} or {@code .build()}.
+     *
+     * @see #presignHeadObject(HeadObjectPresignRequest)
+     */
+    default PresignedHeadObjectRequest presignHeadObject(Consumer<HeadObjectPresignRequest.Builder> request) {
+        HeadObjectPresignRequest.Builder builder = HeadObjectPresignRequest.builder();
+        request.accept(builder);
+        return presignHeadObject(builder.build());
+    }
+
+    /**
+     * Presign a {@link HeadBucketRequest} so that it can be executed at a later time without requiring additional
+     * signing or authentication.
+     * <p/>
+     *
+     * <b>Example Usage</b>
+     * <p/>
+     *
+     * <pre>
+     * {@code
+     *     S3Presigner presigner = ...;
+     *
+     *     // Create a HeadBucketRequest to be pre-signed
+     *     HeadBucketRequest headBucketRequest =
+     *         HeadBucketRequest.builder()
+     *                          .bucket("my-bucket")
+     *                          .build();
+     *
+     *     // Create a HeadBucketPresignRequest to specify the signature duration
+     *     HeadBucketPresignRequest headBucketPresignRequest =
+     *         HeadBucketPresignRequest.builder()
+     *                                .signatureDuration(Duration.ofMinutes(10))
+     *                                .headBucketRequest(headBucketRequest)
+     *                                .build();
+     *
+     *     // Generate the presigned request
+     *     PresignedHeadBucketRequest presignedHeadBucketRequest =
+     *         presigner.presignHeadBucket(headBucketPresignRequest);
+     *
+     *     // The presigned URL can be used with an HTTP client to check bucket existence and access
+     *     SdkHttpClient httpClient = ApacheHttpClient.builder().build();
+     *     HttpExecuteRequest request = HttpExecuteRequest.builder()
+     *                                                   .request(presignedHeadBucketRequest.httpRequest())
+     *                                                   .build();
+     *     HttpExecuteResponse response = httpClient.prepareRequest(request).call();
+     *
+     *     // Check if bucket exists and is accessible
+     *     boolean bucketExists = response.httpResponse().isSuccessful();
+     *     String region = response.httpResponse().firstMatchingHeader("x-amz-bucket-region").orElse("");
+     * }
+     * </pre>
+     */
+    default PresignedHeadBucketRequest presignHeadBucket(HeadBucketPresignRequest request) {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Presign a {@link HeadBucketRequest} so that it can be executed at a later time without requiring additional
+     * signing or authentication.
+     * <p>
+     * This is a shorter method of invoking {@link #presignHeadBucket(HeadBucketPresignRequest)} without needing
+     * to call {@code HeadBucketPresignRequest.builder()} or {@code .build()}.
+     *
+     * @see #presignHeadBucket(HeadBucketPresignRequest)
+     */
+    default PresignedHeadBucketRequest presignHeadBucket(Consumer<HeadBucketPresignRequest.Builder> request) {
+        HeadBucketPresignRequest.Builder builder = HeadBucketPresignRequest.builder();
+        request.accept(builder);
+        return presignHeadBucket(builder.build());
+    }
+
     /**
      * Presign a {@link PutObjectRequest} so that it can be executed at a later time without requiring additional
      * signing or authentication.