Dynamic login token sourcing API contract

Author: Bret Ambrose

src/main/java/software/amazon/awssdk/crt/auth/credentials/CognitoCredentialsProvider.java

@@ -47,6 +47,7 @@ static public class CognitoCredentialsProviderBuilder {
         private String identity;
         private String customRoleArn;
         private ArrayList<CognitoLoginTokenPair> logins = new ArrayList<CognitoLoginTokenPair>();
+        private CognitoLoginTokenSource loginTokenSource;
 
         private TlsContext tlsContext;
         private ClientBootstrap clientBootstrap;
@@ -148,6 +149,23 @@ public CognitoCredentialsProviderBuilder withHttpProxyOptions(HttpProxyOptions h
 
         HttpProxyOptions getHttpProxyOptions() { return httpProxyOptions; }
 
+        /**
+         * Sets a login token source for the credentials provider.  The login token source will be used to
+         * gather additional login tokens to submit as part of the HTTP request sent to Cognito.  A login token source
+         * allows you to dynamically add login tokens on a per-request basis.  Using a login token source requires
+         * you to follow certain requirements in order to avoid undesirable behavior.  See the documentation for
+         * `CognitoLoginTokenSource` for further details.
+         *
+         * @param loginTokenSource object to source login tokens from before every HTTP request to Cognito
+         * @return The current builder
+         */
+        public CognitoCredentialsProviderBuilder withLoginTokenSource(CognitoLoginTokenSource loginTokenSource) {
+            this.loginTokenSource = loginTokenSource;
+
+            return this;
+        }
+
+        CognitoLoginTokenSource getLoginTokenSource() { return loginTokenSource; }
 
         /**
          * Creates a new Cognito credentials provider, based on this builder's configuration

src/main/java/software/amazon/awssdk/crt/auth/credentials/CognitoLoginTokenSource.java

@@ -0,0 +1,33 @@
+package software.amazon.awssdk.crt.auth.credentials;
+
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Interface to allow for dynamic sourcing (ie per fetch-credentials request submitted to Cognito) of Cognito login
+ * token pairs.  It is *critical* to follow the guidance given in the documentation for `startLoginTokenFetch`
+ */
+public interface CognitoLoginTokenSource {
+
+    /**
+     * Method that a Cognito credentials provider should invoke before sending a fetch credentials
+     * request to Cognito.  The CognitoLoginTokenPairs that the future gets completed with are joined
+     * with the (static) CognitoLoginTokenPairs that were specified in the credential provider configuration
+     * on construction.  The merged set of CognitoLoginTokenPairs are added to the HTTP request sent
+     * to Cognito that sources credentials.
+     *
+     * You must follow several guidelines to properly use this feature; not following these guidelines can result
+     * in deadlocks, poor performance, or other undesirable behavior.
+     *
+     * 1. If you use this feature, you must complete the future or the underlying connection attempt will hang forever.
+     * Credentials sourcing is halted until the future gets completed.  If something goes wrong during
+     * login token sourcing, complete the future exceptionally.
+     *
+     * 2. You must not block or wait for asynchronous operations in this function.  This function is invoked from a CRT
+     * event loop thread, and the event loop is halted until this function is returned from.  If you need to perform
+     * an asynchronous or non-trivial operation in order to source the necessary login token pairs, then you must
+     * ensure that sourcing task executes on another thread.  The easiest way to do this would be to pass the future
+     * to a sourcing task that runs on an external executor.
+     */
+    void startLoginTokenFetch(CompletableFuture<List<CognitoCredentialsProvider.CognitoLoginTokenPair>> tokenFuture);
+}