HttpSigner interface changes (#4018)

* Fix generics related warning in Signer interfaces

* Remove <T> for HttpAuthOption.Builder.schemeId

* Remove wildcards from sign methods

* Make Identity explicit in HttpSignRequest

* Make IdentityT type extend Identity in HttpSigner

* Add consumer builder pattern to HttpSigner methods

They have default implementation that rely on new
DefaultHttpSignRequest.BuilderImpl constructor that relies on the
generic IdentityT without knowing the Class of that type. This class
is @SdkInternalApi so this constructor is considered private.

Also, make HttpSignRequest.builder take Class<IdentityT> as parameter.

Also, make IdentityT type extends Identity in HttpSignRequest.

* Add test to show HttpSigner usage

* Note identityType parameter is ignored in HttpSignRequest.builder

* Use separate interfaces for sync and async sign requests

This fixes HttpSignerTest.signAsync_usingRequest_works test.

* Use abstract DefaultHttpSignRequest to avoid duplication

* Split sync/async interfaces for SignedHttpRequest

And removed `payloadType()` accessor.

Also, HttpSignRequest builders take Identity as parameter instead of Class<IdentityT>.

* Minor fixes

* Added missing Builder method override for identity
* Fixed javadocs
* Fixed toString

* Make protected properties Map an unmodifiableMap

* Remove overriding in HttpSignRequest.Builder sub-interfaces

* Remove overriding in SignedHttpRequest.Builder sub-interfaces

* Allow sign methods take request with subtype of the IdentityT

* Make HttpSignRequest @SdkProtectedApi

* Make HttpSignRequest @SdkPublicApi

Author: gosar

core/http-auth-spi/pom.xml

@@ -70,6 +70,11 @@
             <artifactId>equalsverifier</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/AsyncHttpSignRequest.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.http.auth.spi;
+
+import java.nio.ByteBuffer;
+import org.reactivestreams.Publisher;
+import software.amazon.awssdk.annotations.Immutable;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+import software.amazon.awssdk.http.auth.spi.internal.DefaultAsyncHttpSignRequest;
+import software.amazon.awssdk.identity.spi.Identity;
+import software.amazon.awssdk.utils.builder.SdkBuilder;
+
+/**
+ * Input parameters to sign a request with async payload, using {@link HttpSigner}.
+ *
+ * @param <IdentityT> The type of the identity.
+ */
+@SdkPublicApi
+@Immutable
+@ThreadSafe
+public interface AsyncHttpSignRequest<IdentityT extends Identity> extends HttpSignRequest<Publisher<ByteBuffer>, IdentityT> {
+    /**
+     * Get a new builder for creating a {@link AsyncHttpSignRequest}.
+     */
+    static <IdentityT extends Identity> Builder<IdentityT> builder(IdentityT identity) {
+        return new DefaultAsyncHttpSignRequest.BuilderImpl<>(identity);
+    }
+
+    /**
+     * A builder for a {@link AsyncHttpSignRequest}.
+     */
+    interface Builder<IdentityT extends Identity>
+        extends HttpSignRequest.Builder<Builder<IdentityT>, Publisher<ByteBuffer>, IdentityT>,
+                SdkBuilder<Builder<IdentityT>, AsyncHttpSignRequest<IdentityT>> {
+    }
+}

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/AsyncSignedHttpRequest.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.http.auth.spi;
+
+import java.nio.ByteBuffer;
+import org.reactivestreams.Publisher;
+import software.amazon.awssdk.annotations.Immutable;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+import software.amazon.awssdk.http.auth.spi.internal.DefaultAsyncSignedHttpRequest;
+import software.amazon.awssdk.utils.builder.SdkBuilder;
+
+/**
+ * Represents a request with async payload that has been signed by {@link HttpSigner}.
+ */
+@SdkPublicApi
+@Immutable
+@ThreadSafe
+public interface AsyncSignedHttpRequest extends SignedHttpRequest<Publisher<ByteBuffer>> {
+
+    /**
+     * Get a new builder for creating a {@link AsyncSignedHttpRequest}.
+     */
+    static Builder builder() {
+        return new DefaultAsyncSignedHttpRequest.BuilderImpl();
+    }
+
+    /**
+     * A builder for a {@link AsyncSignedHttpRequest}.
+     */
+    interface Builder extends SignedHttpRequest.Builder<Builder, Publisher<ByteBuffer>>,
+                              SdkBuilder<Builder, AsyncSignedHttpRequest> {
+    }
+}

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/HttpAuthOption.java

@@ -81,7 +81,7 @@ interface SignerPropertyConsumer {
     }
 
     interface Builder extends SdkBuilder<Builder, HttpAuthOption> {
-        <T> Builder schemeId(String schemeId);
+        Builder schemeId(String schemeId);
 
         <T> Builder putIdentityProperty(IdentityProperty<T> key, T value);
 

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/HttpAuthScheme.java

@@ -58,5 +58,5 @@ public interface HttpAuthScheme<T extends Identity> {
      * Retrieve the signer associated with this authentication scheme. This signer is guaranteed to support the identity
      * generated by the identity provider in this authentication scheme.
      */
-    HttpSigner signer();
+    HttpSigner<T> signer();
 }

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/HttpSignRequest.java

@@ -20,30 +20,18 @@
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.annotations.ThreadSafe;
 import software.amazon.awssdk.http.SdkHttpRequest;
-import software.amazon.awssdk.http.auth.spi.internal.DefaultHttpSignRequest;
-import software.amazon.awssdk.utils.builder.SdkBuilder;
+import software.amazon.awssdk.identity.spi.Identity;
 
 /**
- * Represents a request to be signed by {@link HttpSigner}.
+ * Input parameters to sign a request using {@link HttpSigner}.
  *
- * @param <PayloadT> The type of payload of this request.
+ * @param <PayloadT> The type of payload of the request.
+ * @param <IdentityT> The type of the identity.
  */
 @SdkPublicApi
 @Immutable
 @ThreadSafe
-public interface HttpSignRequest<PayloadT> {
-
-    /**
-     * Get a new builder for creating a {@link HttpSignRequest}.
-     */
-    static <T> Builder<T> builder(Class<T> payloadType) {
-        return new DefaultHttpSignRequest.BuilderImpl(payloadType);
-    }
-
-    /**
-     * Returns the type of the payload.
-     */
-    Class<PayloadT> payloadType();
+public interface HttpSignRequest<PayloadT, IdentityT extends Identity> {
 
     /**
      * Returns the HTTP request object, without the request body payload.
@@ -56,28 +44,38 @@ static <T> Builder<T> builder(Class<T> payloadType) {
     Optional<PayloadT> payload();
 
     /**
-     * Returns the property that the {@link HttpSigner} can use during signing.
+     * Returns the identity.
+     */
+    IdentityT identity();
+
+    /**
+     * Returns the value of a property that the {@link HttpSigner} can use during signing.
      */
     <T> T property(SignerProperty<T> property);
 
     /**
      * A builder for a {@link HttpSignRequest}.
      */
-    interface Builder<PayloadT> extends SdkBuilder<Builder<PayloadT>, HttpSignRequest> {
+    interface Builder<B extends Builder<B, PayloadT, IdentityT>, PayloadT, IdentityT extends Identity> {
 
         /**
          * Set the HTTP request object, without the request body payload.
          */
-        Builder request(SdkHttpRequest request);
+        B request(SdkHttpRequest request);
 
         /**
          * Set the body payload of the request. A payload is optional. By default, the payload will be empty.
          */
-        Builder payload(PayloadT payload);
+        B payload(PayloadT payload);
+
+        /**
+         * Set the identity of the request.
+         */
+        B identity(IdentityT identity);
 
         /**
          * Set a property that the {@link HttpSigner} can use during signing.
          */
-        <T> Builder putProperty(SignerProperty<T> key, T value);
+        <T> B putProperty(SignerProperty<T> key, T value);
     }
 }

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/HttpSigner.java

@@ -15,31 +15,62 @@
 
 package software.amazon.awssdk.http.auth.spi;
 
-import java.nio.ByteBuffer;
-import org.reactivestreams.Publisher;
+import java.util.function.Consumer;
 import software.amazon.awssdk.annotations.SdkPublicApi;
-import software.amazon.awssdk.http.ContentStreamProvider;
+import software.amazon.awssdk.http.auth.spi.internal.DefaultAsyncHttpSignRequest;
+import software.amazon.awssdk.http.auth.spi.internal.DefaultSyncHttpSignRequest;
+import software.amazon.awssdk.identity.spi.Identity;
 
 /**
  * Interface for the process of modifying a request destined for a service so that the service can authenticate the SDK
- * customer’s identity
+ * customer’s identity.
+ *
+ * @param <IdentityT> The type of the identity.
  */
 @SdkPublicApi
-public interface HttpSigner {
+public interface HttpSigner<IdentityT extends Identity> {
+
+    /**
+     * Method that takes in inputs to sign a request with sync payload and returns a signed version of the request.
+     *
+     * @param request The inputs to sign a request.
+     * @return A signed version of the request.
+     */
+    SyncSignedHttpRequest sign(SyncHttpSignRequest<? extends IdentityT> request);
+
+    /**
+     * Method that takes in inputs to sign a request with sync payload and returns a signed version of the request.
+     * <p>
+     * Similar to {@link #sign(SyncHttpSignRequest)}, but takes a lambda to configure a new {@link SyncHttpSignRequest.Builder}.
+     * This removes the need to call {@link SyncHttpSignRequest#builder(IdentityT)}} and
+     * {@link SyncHttpSignRequest.Builder#build()}.
+     *
+     * @param consumer A {@link Consumer} to which an empty {@link SyncHttpSignRequest.Builder} will be given.
+     * @return A signed version of the request.
+     */
+    default SyncSignedHttpRequest sign(Consumer<SyncHttpSignRequest.Builder<IdentityT>> consumer) {
+        return sign(new DefaultSyncHttpSignRequest.BuilderImpl<IdentityT>().applyMutation(consumer).build());
+    }
 
     /**
-     * Method that takes in a request and returns a signed version of the request.
+     * Method that takes in inputs to sign a request with async payload and returns a signed version of the request.
      *
-     * @param request The request to sign, with sync payload
-     * @return A signed version of the input request
+     * @param request The inputs to sign a request.
+     * @return A signed version of the request.
      */
-    SignedHttpRequest<ContentStreamProvider> sign(HttpSignRequest<? extends ContentStreamProvider> request);
+    AsyncSignedHttpRequest signAsync(AsyncHttpSignRequest<? extends IdentityT> request);
 
     /**
-     * Method that takes in a request and returns a signed version of the request.
+     * Method that takes in inputs to sign a request with async payload and returns a signed version of the request.
+     * <p>
+     * Similar to {@link #signAsync(AsyncHttpSignRequest)}, but takes a lambda to configure a new
+     * {@link AsyncHttpSignRequest.Builder}. This removes the need to call {@link AsyncHttpSignRequest#builder(IdentityT)}} and
+     * {@link AsyncHttpSignRequest.Builder#build()}.
      *
-     * @param request The request to sign, with async payload
-     * @return A signed version of the input request
+     * @param consumer A {@link Consumer} to which an empty {@link HttpSignRequest.Builder} will be given.
+     * @return A signed version of the request.
      */
-    SignedHttpRequest<Publisher<ByteBuffer>> signAsync(HttpSignRequest<? extends Publisher<? extends ByteBuffer>> request);
+    default AsyncSignedHttpRequest signAsync(Consumer<AsyncHttpSignRequest.Builder<IdentityT>> consumer) {
+        return signAsync(new DefaultAsyncHttpSignRequest.BuilderImpl<IdentityT>().applyMutation(consumer).build());
+    }
 }

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/SignedHttpRequest.java

@@ -20,31 +20,17 @@
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.annotations.ThreadSafe;
 import software.amazon.awssdk.http.SdkHttpRequest;
-import software.amazon.awssdk.http.auth.spi.internal.DefaultSignedHttpRequest;
-import software.amazon.awssdk.utils.builder.SdkBuilder;
 
 /**
  * Represents a request that has been signed by {@link HttpSigner}.
  *
- * @param <PayloadT> The type of payload of this request.
+ * @param <PayloadT> The type of payload of the request.
  */
 @SdkPublicApi
 @Immutable
 @ThreadSafe
 public interface SignedHttpRequest<PayloadT> {
 
-    /**
-     * Get a new builder for creating a {@link SignedHttpRequest}.
-     */
-    static <T> Builder<T> builder(Class<T> payloadType) {
-        return new DefaultSignedHttpRequest.BuilderImpl(payloadType);
-    }
-
-    /**
-     * Returns the type of the payload.
-     */
-    Class<PayloadT> payloadType();
-
     /**
      * Returns the HTTP request object, without the request body payload.
      */
@@ -58,16 +44,16 @@ static <T> Builder<T> builder(Class<T> payloadType) {
     /**
      * A builder for a {@link SignedHttpRequest}.
      */
-    interface Builder<PayloadT> extends SdkBuilder<Builder<PayloadT>, SignedHttpRequest> {
+    interface Builder<B extends Builder<B, PayloadT>, PayloadT> {
 
         /**
          * Set the HTTP request object, without the request body payload.
          */
-        Builder request(SdkHttpRequest request);
+        B request(SdkHttpRequest request);
 
         /**
          * Set the body payload of the request. A payload is optional. By default, the payload will be empty.
          */
-        Builder payload(PayloadT payload);
+        B payload(PayloadT payload);
     }
 }

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/SignerProperty.java

@@ -24,7 +24,7 @@
 
 /**
  * A strongly-typed property for input to an {@link HttpSigner}.
- * @param <T> The type of the attribute.
+ * @param <T> The type of the property.
  */
 @SdkPublicApi
 @Immutable

core/http-auth-spi/src/main/java/software/amazon/awssdk/http/auth/spi/SyncHttpSignRequest.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.http.auth.spi;
+
+import software.amazon.awssdk.annotations.Immutable;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+import software.amazon.awssdk.http.ContentStreamProvider;
+import software.amazon.awssdk.http.auth.spi.internal.DefaultSyncHttpSignRequest;
+import software.amazon.awssdk.identity.spi.Identity;
+import software.amazon.awssdk.utils.builder.SdkBuilder;
+
+/**
+ * Input parameters to sign a request with sync payload, using {@link HttpSigner}.
+ *
+ * @param <IdentityT> The type of the identity.
+ */
+@SdkPublicApi
+@Immutable
+@ThreadSafe
+public interface SyncHttpSignRequest<IdentityT extends Identity> extends HttpSignRequest<ContentStreamProvider, IdentityT> {
+    /**
+     * Get a new builder for creating a {@link SyncHttpSignRequest}.
+     */
+    static <IdentityT extends Identity> Builder<IdentityT> builder(IdentityT identity) {
+        return new DefaultSyncHttpSignRequest.BuilderImpl<>(identity);
+    }
+
+    /**
+     * A builder for a {@link SyncHttpSignRequest}.
+     */
+    interface Builder<IdentityT extends Identity>
+        extends HttpSignRequest.Builder<Builder<IdentityT>, ContentStreamProvider, IdentityT>,
+                SdkBuilder<Builder<IdentityT>, SyncHttpSignRequest<IdentityT>> {
+    }
+}