Implement Asynchronous EC2 Metadata Client (#3523)

* IMDS Async client

* Fix test classes

* JavaDoc

* PR comments and added IMDS to test-coverage-reporting
- Create a common builder Ec2MetadataClientBuilder
- Create a common test class BaseEc2MetadataClientTest
- Refactor common initialization logic for both sync and async client in BaseEc2MetadataClient class
- Use netty async client in unit tests
- fix Async error logic

* Improve JavaDoc and rename some variables
- fix one failing unit test

Author: L-Applin

.changes/next-release/feature-AWSSDKforJavav2-4a07ee0.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS SDK for Java v2",
+    "contributor": "L-Applin",
+    "description": "EC2Metadata Asynchronous Client"
+}

core/imds/pom.xml

@@ -58,7 +58,7 @@
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>url-connection-client</artifactId>
             <version>${awsjavasdk.version}</version>
-            <scope>compile</scope>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
@@ -114,7 +114,7 @@
         </dependency>
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
-            <artifactId>apache-client</artifactId>
+            <artifactId>netty-nio-client</artifactId>
             <version>${awsjavasdk.version}</version>
             <scope>test</scope>
         </dependency>

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2Metadata.java

@@ -0,0 +1,88 @@
+/*
+ * 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.imds;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.core.exception.SdkClientException;
+import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
+import software.amazon.awssdk.imds.internal.DefaultEc2MetadataAsyncClient;
+import software.amazon.awssdk.utils.SdkAutoCloseable;
+
+/**
+ * Interface to represent the Ec2Metadata Client Class. Used to access instance metadata from a running instance.
+ */
+@SdkPublicApi
+public interface Ec2MetadataAsyncClient extends SdkAutoCloseable {
+
+    /**
+     * Gets the specified instance metadata value by the given path.
+     *
+     * @param path Input path
+     * @return A CompletableFuture that completes when the MetadataResponse is made available.
+     */
+    CompletableFuture<MetadataResponse> get(String path);
+
+    /**
+     * Create an {@link Ec2MetadataAsyncClient} instance using the default values.
+     *
+     * @return
+     */
+    static Ec2MetadataAsyncClient create() {
+        return builder().build();
+    }
+
+    static Ec2MetadataAsyncClient.Builder builder() {
+        return DefaultEc2MetadataAsyncClient.builder();
+    }
+
+    /**
+     * The builder definition for a {@link Ec2MetadataClient}. All parameters are optional and have default values if not
+     * specified. Therefore, an instance can be simply created with {@code Ec2MetadataAsyncClient.builder().build()} or
+     * {@code Ec2MetadataAsyncClient.create()}, both having the same result.
+     */
+    interface Builder extends Ec2MetadataClientBuilder<Ec2MetadataAsyncClient.Builder, Ec2MetadataAsyncClient> {
+
+        /**
+         * Define the {@link ScheduledExecutorService} used to schedule asynchronous retry attempts. If provided, the
+         * Ec2MetadataClient will <em>NOT</em> manage the lifetime if the httpClient and must therefore be
+         * closed explicitly by calling the {@link SdkAsyncHttpClient#close()} method on it.
+         * <p>
+         * If not specified, defaults to {@link Executors#newScheduledThreadPool} with a default value of 3 thread in the
+         * pool.
+         * </p>
+         * @param scheduledExecutorService the ScheduledExecutorService to use for retry attempt.
+         * @return a reference to this builder
+         */
+        Builder scheduledExecutorService(ScheduledExecutorService scheduledExecutorService);
+
+        /**
+         * Define the http client used by the Ec2 Metadata client. If provided, the Ec2MetadataClient will <em>NOT</em> manage the
+         * lifetime if the httpClient and must therefore be closed explicitly by calling the {@link SdkAsyncHttpClient#close()}
+         * method on it.
+         * <p>
+         * If not specified, the IMDS client will look for a SdkAsyncHttpClient class included in the classpath of the
+         * application and creates a new instance of that class, managed by the IMDS Client, that will be closed when the IMDS
+         * Client is closed. If no such class can be found, will throw a {@link  SdkClientException}.
+         * </p>
+         * @param httpClient the http client
+         * @return a reference to this builder
+         */
+        Builder httpClient(SdkAsyncHttpClient httpClient);
+    }
+}

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataAsyncClient.java

@@ -0,0 +1,73 @@
+/*
+ * 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.imds;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.core.exception.SdkClientException;
+import software.amazon.awssdk.http.SdkHttpClient;
+import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
+import software.amazon.awssdk.imds.internal.DefaultEc2MetadataClient;
+import software.amazon.awssdk.utils.SdkAutoCloseable;
+
+
+/**
+ *  Interface to represent the Ec2Metadata Client Class. Used to access instance metadata from a running instance.
+ */
+@SdkPublicApi
+public interface Ec2MetadataClient extends SdkAutoCloseable {
+
+    /**
+     * Gets the specified instance metadata value by the given path.
+     * @param path  Input path
+     * @return Instance metadata value as part of MetadataResponse Object
+     */
+    MetadataResponse get(String path);
+
+    /**
+     * Create an {@link Ec2MetadataClient} instance using the default values.
+     */
+    static Ec2MetadataClient create() {
+        return builder().build();
+    }
+
+    /**
+     * Creates a default builder for {@link Ec2MetadataClient}.
+     */
+    static Builder builder() {
+        return DefaultEc2MetadataClient.builder();
+    }
+
+    /**
+     * The builder definition for a {@link Ec2MetadataClient}.
+     */
+    interface Builder extends Ec2MetadataClientBuilder<Ec2MetadataClient.Builder, Ec2MetadataClient> {
+
+        /**
+         * Define the http client used by the Ec2 Metadata client. If provided, the Ec2MetadataClient will <em>NOT</em> manage the
+         * lifetime if the httpClient and must therefore be closed explicitly by calling the {@link SdkAsyncHttpClient#close()}
+         * method on it.
+         * <p>
+         * If not specified, the IMDS client will look for a SdkHttpClient class included in the classpath of the
+         * application and creates a new instance of that class, managed by the IMDS Client, that will be closed when the IMDS
+         * Client is closed. If no such class can be found, will throw a {@link  SdkClientException}.
+         * </p>
+         * @param httpClient the http client
+         * @return a reference to this builder
+         */
+        Builder httpClient(SdkHttpClient httpClient);
+    }
+
+}

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataClient.java

@@ -0,0 +1,86 @@
+/*
+ * 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.imds;
+
+import java.net.URI;
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.core.retry.RetryMode;
+import software.amazon.awssdk.core.retry.backoff.BackoffStrategy;
+import software.amazon.awssdk.imds.internal.Ec2MetadataEndpointProvider;
+import software.amazon.awssdk.utils.builder.SdkBuilder;
+
+/**
+ * Base shared builder interface for Ec2MetadataClient
+ * @param <B> the Builder Type
+ * @param <T> the Ec2MetadataClient Type
+ */
+@SdkPublicApi
+public interface Ec2MetadataClientBuilder<B, T> extends SdkBuilder<Ec2MetadataClientBuilder<B, T>, T> {
+    /**
+     * Define the retry policy which includes the number of retry attempts for any failed request.
+     * <p>
+     * If not specified, defaults to 3 retry attempts and a {@link BackoffStrategy#defaultStrategy()}  backoff strategy} that
+     * uses {@link RetryMode#STANDARD}
+     * </p>
+     * @param retryPolicy The retry policy which includes the number of retry attempts for any failed request.
+     * @return a reference to this builder
+     */
+    B retryPolicy(Ec2MetadataRetryPolicy retryPolicy);
+
+    Ec2MetadataRetryPolicy getRetryPolicy();
+
+    /**
+     * Define the endpoint of IMDS.
+     * <p>
+     * If not specified, the IMDS client will attempt to automatically resolve the endpoint value
+     * based on the logic of {@link Ec2MetadataEndpointProvider}.
+     * </p>
+     * @param endpoint The endpoint of IMDS.
+     * @return a reference to this builder
+     */
+    B endpoint(URI endpoint);
+
+    URI getEndpoint();
+
+    /**
+     * Define the Time to live (TTL) of the token. The token represents a logical session. The TTL specifies the length of time
+     * that the token is valid and, therefore, the duration of the session. Defaults to 21,600 seconds (6 hours) if not specified.
+     *
+     * @param tokenTtl The Time to live (TTL) of the token.
+     * @return a reference to this builder
+     */
+    B tokenTtl(Duration tokenTtl);
+
+    Duration getTokenTtl();
+
+    /**
+     * Define the endpoint mode of IMDS. Supported values include IPv4 and IPv6. Used to determine the endpoint of the IMDS
+     * Client only if {@link Ec2MetadataClientBuilder#endpoint(URI)} is not specified. Only one of both endpoint or endpoint mode
+     * but not both. If both are specified in the Builder, a {@link IllegalArgumentException} will be thrown.
+     * <p>
+     * If not specified, the IMDS client will attempt to automatically resolve the endpoint mode value
+     * based on the logic of {@link Ec2MetadataEndpointProvider}.
+     * </p>
+     *
+     * @param endpointMode The endpoint mode of IMDS. Supported values include IPv4 and IPv6.
+     * @return a reference to this builder
+     */
+    B endpointMode(EndpointMode endpointMode);
+
+    EndpointMode getEndpointMode();
+
+}

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataClientBuilder.java

@@ -34,12 +34,14 @@
 @SdkPublicApi
 public class Ec2MetadataRetryPolicy implements ToCopyableBuilder<Ec2MetadataRetryPolicy.Builder, Ec2MetadataRetryPolicy> {
 
+    private static final int DEFAULT_RETRY_ATTEMPTS = 3;
+
     private final BackoffStrategy backoffStrategy;
     private final int numRetries;
 
     private Ec2MetadataRetryPolicy(BuilderImpl builder) {
 
-        this.numRetries = builder.numRetries != null ? builder.numRetries : 3;
+        this.numRetries = builder.numRetries != null ? builder.numRetries : DEFAULT_RETRY_ATTEMPTS;
 
         this.backoffStrategy = builder.backoffStrategy != null ? builder.backoffStrategy :
                                BackoffStrategy.defaultStrategy(RetryMode.STANDARD);