Addressed comments.

Author: millems

core/auth/src/main/java/software/amazon/awssdk/auth/credentials/HttpCredentialsProvider.java

@@ -28,12 +28,11 @@
 public interface HttpCredentialsProvider extends AwsCredentialsProvider, SdkAutoCloseable {
     interface Builder<TypeToBuildT extends HttpCredentialsProvider, BuilderT extends Builder<?, ?>> {
         /**
-         * Configure whether this provider should fetch credentials asynchronously in the background. If this is true, threads are
-         * less likely to block when {@link #resolveCredentials()} is called, but additional resources are used to maintain the
-         * provider.
+         * Configure whether the provider should fetch credentials asynchronously in the background. If this is true,
+         * threads are less likely to block when credentials are loaded, but additional resources are used to maintain
+         * the provider.
          *
-         * <p>
-         * By default, this is disabled.
+         * <p>By default, this is disabled.</p>
          */
         BuilderT asyncCredentialUpdateEnabled(Boolean asyncCredentialUpdateEnabled);
 

core/auth/src/main/java/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProvider.java

@@ -16,12 +16,12 @@
 package software.amazon.awssdk.auth.credentials;
 
 import static java.time.temporal.ChronoUnit.MINUTES;
-import static java.time.temporal.ChronoUnit.SECONDS;
 import static software.amazon.awssdk.utils.ComparableUtils.minimum;
 
 import java.io.IOException;
 import java.net.URI;
 import java.time.Clock;
+import java.time.Duration;
 import java.time.Instant;
 import java.util.Collections;
 import java.util.Map;
@@ -151,7 +151,7 @@ private RefreshResult<AwsCredentials> refreshCredentials() {
                     // Choose whether to report this failure at the debug or warn level based on how much time is left on the
                     // credentials before expiration.
                     Supplier<String> errorMessage = () -> "Failure encountered when attempting to refresh credentials from IMDS.";
-                    Instant fifteenMinutesFromNow = Instant.now().plus(15, MINUTES);
+                    Instant fifteenMinutesFromNow = clock.instant().plus(15, MINUTES);
                     if (expiration.isBefore(fifteenMinutesFromNow)) {
                         log.warn(errorMessage, e);
                     } else {
@@ -164,7 +164,7 @@ private RefreshResult<AwsCredentials> refreshCredentials() {
         }
 
         return RefreshResult.builder(credentials.getAwsCredentials())
-                            .staleTime(null) // Allow use of expired credentials - they may still work
+                            .staleTime(Instant.MAX) // Allow use of expired credentials - they may still work
                             .prefetchTime(prefetchTime(credentials.getExpiration().orElse(null)))
                             .build();
     }
@@ -180,35 +180,18 @@ private boolean isLocalCredentialLoadingDisabled() {
     private Instant prefetchTime(Instant expiration) {
         Instant now = clock.instant();
 
-        // If expiration time doesn't exist, refresh in 60 minutes
         if (expiration == null) {
             return now.plus(60, MINUTES);
         }
 
-        // If expiration time is 60+ minutes from now, refresh in 30 minutes.
-        Instant sixtyMinutesBeforeExpiration = expiration.minus(60, MINUTES);
-        if (now.isBefore(sixtyMinutesBeforeExpiration)) {
-            return now.plus(30, MINUTES);
+        Duration timeUntilExpiration = Duration.between(now, expiration);
+        if (timeUntilExpiration.isNegative()) {
+            log.warn(() -> "IMDS credential expiration has been extended due to an IMDS availability outage. A refresh "
+                           + "of these credentials will be attempted again in ~5 minutes.");
+            return now.plus(5, MINUTES);
         }
 
-        // If expiration time is 15 minutes or more from now, refresh in 10 minutes.
-        Instant fifteenMinutesBeforeExpiration = expiration.minus(15, MINUTES);
-        if (now.isBefore(fifteenMinutesBeforeExpiration)) {
-            return now.plus(10, MINUTES);
-        }
-
-        // If expiration time is 0.25-15 minutes from now, refresh in 5 minutes, or 15 seconds before expiration, whichever is
-        // sooner.
-        Instant fifteenSecondsBeforeExpiration = expiration.minus(15, SECONDS);
-        if (now.isBefore(fifteenSecondsBeforeExpiration)) {
-            return minimum(now.plus(5, MINUTES), fifteenSecondsBeforeExpiration);
-        }
-
-        // These credentials are expired. Try refreshing again in 5 minutes. We can't be more aggressive than that, because we
-        // don't want to overload the IMDS endpoint.
-        log.warn(() -> "IMDS credential expiration has been extended due to an IMDS availability outage. A refresh "
-                       + "of these credentials will be attempted again in 5 minutes.");
-        return now.plus(5, MINUTES);
+        return now.plus(minimum(timeUntilExpiration.abs().dividedBy(2), Duration.ofMinutes(5)));
     }
 
     @Override

core/auth/src/main/java/software/amazon/awssdk/auth/credentials/ProcessCredentialsProvider.java

@@ -249,8 +249,9 @@ private Builder(ProcessCredentialsProvider provider) {
         }
 
         /**
-         * Configure whether the provider should fetch credentials asynchronously in the background. If this is true, threads are
-         * less likely to block when credentials are loaded, but additional resources are used to maintain the provider.
+         * Configure whether the provider should fetch credentials asynchronously in the background. If this is true,
+         * threads are less likely to block when credentials are loaded, but additional resources are used to maintain
+         * the provider.
          *
          * <p>By default, this is disabled.</p>
          */

core/auth/src/test/java/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProviderTest.java

@@ -361,18 +361,18 @@ public void resolveCredentials_callsImdsIfCredentialsWithin5MinutesOfExpiration(
         stubCredentialsResponse(aResponse().withBody(successfulCredentialsResponse1));
         AwsCredentials credentials24HoursAgo = credentialsProvider.resolveCredentials();
 
-        // Set the time to 3 minutes before expiration, and fail to call IMDS
-        clock.time = now.minus(3, MINUTES);
+        // Set the time to 10 minutes before expiration, and fail to call IMDS
+        clock.time = now.minus(10, MINUTES);
         stubCredentialsResponse(aResponse().withStatus(500));
-        AwsCredentials credentials3MinutesAgo = credentialsProvider.resolveCredentials();
+        AwsCredentials credentials10MinutesAgo = credentialsProvider.resolveCredentials();
 
         // Set the time to 10 seconds before expiration, and verify that we still call IMDS to try to get credentials in at the
         // last moment before expiration
         clock.time = now.minus(10, SECONDS);
         stubCredentialsResponse(aResponse().withBody(successfulCredentialsResponse2));
         AwsCredentials credentials10SecondsAgo = credentialsProvider.resolveCredentials();
 
-        assertThat(credentials24HoursAgo).isEqualTo(credentials3MinutesAgo);
+        assertThat(credentials24HoursAgo).isEqualTo(credentials10MinutesAgo);
         assertThat(credentials24HoursAgo.secretAccessKey()).isEqualTo("SECRET_ACCESS_KEY");
         assertThat(credentials10SecondsAgo.secretAccessKey()).isEqualTo("SECRET_ACCESS_KEY2");
     }

services/sso/src/main/java/software/amazon/awssdk/services/sso/auth/SsoCredentialsProvider.java

@@ -38,23 +38,16 @@
 import software.amazon.awssdk.utils.cache.RefreshResult;
 
 /**
- * <p>
- * An implementation of {@link AwsCredentialsProvider} that is extended within this package to provide support for
- * periodically updating session credentials. This credential provider maintains a {@link Supplier<GetRoleCredentialsRequest>}
- * for a {@link SsoClient#getRoleCredentials(Consumer)} call to retrieve the credentials needed.
- * </p>
+ * An implementation of {@link AwsCredentialsProvider} that periodically sends a {@link GetRoleCredentialsRequest} to the AWS
+ * Single Sign-On Service to maintain short-lived sessions to use for authentication. These sessions are updated using a single
+ * calling thread (by default) or asynchronously (if {@link Builder#asyncCredentialUpdateEnabled(Boolean)} is set).
  *
- * <p>
- * While creating the {@link GetRoleCredentialsRequest}, an access token is needed to be resolved from a token file.
- * In default, the token is assumed unexpired, and if it's expired then an {@link ExpiredTokenException} will be thrown.
- * If the users want to change the behavior of this, please implement your own token resolving logic and override the
- * {@link Builder#refreshRequest).
- * </p>
+ * If the credentials are not successfully updated before expiration, calls to {@link #resolveCredentials()} will block until
+ * they are updated successfully.
  *
- * <p>
- * When credentials get close to expiration, this class will attempt to update them asynchronously. If the credentials
- * end up expiring, this class will block all calls to {@link #resolveCredentials()} until the credentials can be updated.
- * </p>
+ * Users of this provider must {@link #close()} it when they are finished using it.
+ *
+ * This is created using {@link SsoCredentialsProvider#builder()}.
  */
 @SdkPublicApi
 public final class SsoCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable,
@@ -186,7 +179,10 @@ public interface Builder extends CopyableBuilder<Builder, SsoCredentialsProvider
 
         /**
          * Configure the amount of time, relative to SSO session token expiration, that the cached credentials are considered
-         * close to stale and should be updated. See {@link #asyncCredentialUpdateEnabled}.
+         * close to stale and should be updated.
+         *
+         * Prefetch updates will occur between the specified time and the stale time of the provider. Prefetch updates may be
+         * asynchronous. See {@link #asyncCredentialUpdateEnabled}.
          *
          * <p>By default, this is 5 minutes.</p>
          */

services/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsAssumeRoleCredentialsProvider.java

@@ -30,12 +30,13 @@
 
 /**
  * An implementation of {@link AwsCredentialsProvider} that periodically sends an {@link AssumeRoleRequest} to the AWS
- * Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated asynchronously
- * in the background as they get close to expiring. If the credentials are not successfully updated asynchronously in the
- * background, calls to {@link #resolveCredentials()} will begin to block in an attempt to update the credentials synchronously.
+ * Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated using a single
+ * calling thread (by default) or asynchronously (if {@link Builder#asyncCredentialUpdateEnabled(Boolean)} is set).
  *
- * This provider creates a thread in the background to periodically update credentials. If this provider is no longer needed,
- * the background thread can be shut down using {@link #close()}.
+ * If the credentials are not successfully updated before expiration, calls to {@link #resolveCredentials()} will block until
+ * they are updated successfully.
+ *
+ * Users of this provider must {@link #close()} it when they are finished using it.
  *
  * This is created using {@link StsAssumeRoleCredentialsProvider#builder()}.
  */

services/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsAssumeRoleWithSamlCredentialsProvider.java

@@ -29,14 +29,14 @@
 import software.amazon.awssdk.utils.builder.ToCopyableBuilder;
 
 /**
- * An implementation of {@link AwsCredentialsProvider} that periodically sends a {@link AssumeRoleWithSamlRequest}
- * to the AWS Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated
- * asynchronously in the background as they get close to expiring. If the credentials are not successfully updated asynchronously
- * in the background, calls to {@link #resolveCredentials()} will begin to block in an attempt to update the credentials
- * synchronously.
+ * An implementation of {@link AwsCredentialsProvider} that periodically sends an {@link AssumeRoleWithSamlRequest} to the AWS
+ * Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated using a single
+ * calling thread (by default) or asynchronously (if {@link Builder#asyncCredentialUpdateEnabled(Boolean)} is set).
  *
- * This provider creates a thread in the background to periodically update credentials. If this provider is no longer needed,
- * the background thread can be shut down using {@link #close()}.
+ * If the credentials are not successfully updated before expiration, calls to {@link #resolveCredentials()} will block until
+ * they are updated successfully.
+ *
+ * Users of this provider must {@link #close()} it when they are finished using it.
  *
  * This is created using {@link StsAssumeRoleWithSamlCredentialsProvider#builder()}.
  */

services/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsAssumeRoleWithWebIdentityCredentialsProvider.java

@@ -30,16 +30,16 @@
 import software.amazon.awssdk.utils.builder.ToCopyableBuilder;
 
 /**
- * An implementation of {@link AwsCredentialsProvider} that periodically sends a {@link AssumeRoleWithWebIdentityRequest}
- * to the AWS Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated
- * asynchronously in the background as they get close to expiring. If the credentials are not successfully updated asynchronously
- * in the background, calls to {@link #resolveCredentials()} will begin to block in an attempt to update the credentials
- * synchronously.
+ * An implementation of {@link AwsCredentialsProvider} that periodically sends an {@link AssumeRoleWithWebIdentityRequest} to the
+ * AWS Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated using a
+ * single calling thread (by default) or asynchronously (if {@link Builder#asyncCredentialUpdateEnabled(Boolean)} is set).
  *
- * This provider creates a thread in the background to periodically update credentials. If this provider is no longer needed,
- * the background thread can be shut down using {@link #close()}.
+ * If the credentials are not successfully updated before expiration, calls to {@link #resolveCredentials()} will block until
+ * they are updated successfully.
  *
- * This is created using {@link StsAssumeRoleWithWebIdentityCredentialsProvider#builder()}.
+ * Users of this provider must {@link #close()} it when they are finished using it.
+ *
+ * This is created using {@link #builder()}.
  */
 @SdkPublicApi
 @ThreadSafe

services/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.java

@@ -37,9 +37,13 @@
 
 /**
  * An implementation of {@link AwsCredentialsProvider} that is extended within this package to provide support for periodically-
- * updating session credentials. When credentials get close to expiration, this class will attempt to update them asynchronously
- * using {@link #getUpdatedCredentials(StsClient)}. If the credentials end up expiring, this class will block all calls to
- * {@link #resolveCredentials()} until the credentials can be updated.
+ * updating session credentials.
+ *
+ * When credentials get close to expiration, this class will attempt to update them automatically either with a single calling
+ * thread (by default) or asynchronously (if {@link #asyncCredentialUpdateEnabled} is true). If the credentials expire, this
+ * class will block all calls to {@link #resolveCredentials()} until the credentials are updated.
+ *
+ * Users of this provider must {@link #close()} it when they are finished using it.
  */
 @ThreadSafe
 @SdkInternalApi
@@ -49,12 +53,12 @@ abstract class StsCredentialsProvider implements AwsCredentialsProvider, SdkAuto
     private static final Duration DEFAULT_PREFETCH_TIME = Duration.ofMinutes(5);
 
     /**
-     * The STS client that should be used for periodically updating the session credentials in the background.
+     * The STS client that should be used for periodically updating the session credentials.
      */
     final StsClient stsClient;
 
     /**
-     * The session cache that will update the credentials asynchronously in the background when they get close to expiring.
+     * The session cache that handles automatically updating the credentials when they get close to expiring.
      */
     private final CachedSupplier<SessionCredentialsHolder> sessionCache;
 
@@ -174,7 +178,7 @@ public B asyncCredentialUpdateEnabled(Boolean asyncCredentialUpdateEnabled) {
 
         /**
          * Configure the amount of time, relative to STS token expiration, that the cached credentials are considered
-         * stale and should no longer be used. All threads will block until the value is updated.
+         * stale and must be updated. All threads will block until the value is updated.
          *
          * <p>By default, this is 1 minute.</p>
          */
@@ -186,7 +190,10 @@ public B staleTime(Duration staleTime) {
 
         /**
          * Configure the amount of time, relative to STS token expiration, that the cached credentials are considered
-         * close to stale and should be updated. See {@link #asyncCredentialUpdateEnabled}.
+         * close to stale and should be updated.
+         *
+         * Prefetch updates will occur between the specified time and the stale time of the provider. Prefetch updates may be
+         * asynchronous. See {@link #asyncCredentialUpdateEnabled}.
          *
          * <p>By default, this is 5 minutes.</p>
          */

services/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsGetFederationTokenCredentialsProvider.java

@@ -28,16 +28,16 @@
 import software.amazon.awssdk.utils.builder.ToCopyableBuilder;
 
 /**
- * An implementation of {@link AwsCredentialsProvider} that periodically sends a {@link GetFederationTokenRequest} to the
- * AWS Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated
- * asynchronously in the background as they get close to expiring. If the credentials are not successfully updated asynchronously
- * in the background, calls to {@link #resolveCredentials()} will begin to block in an attempt to update the credentials
- * synchronously.
+ * An implementation of {@link AwsCredentialsProvider} that periodically sends a {@link GetFederationTokenRequest} to the AWS
+ * Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated using a single
+ * calling thread (by default) or asynchronously (if {@link Builder#asyncCredentialUpdateEnabled(Boolean)} is set).
  *
- * This provider creates a thread in the background to periodically update credentials. If this provider is no longer needed,
- * the background thread can be shut down using {@link #close()}.
+ * If the credentials are not successfully updated before expiration, calls to {@link #resolveCredentials()} will block until
+ * they are updated successfully.
  *
- * This is created using {@link StsGetFederationTokenCredentialsProvider#builder()}.
+ * Users of this provider must {@link #close()} it when they are finished using it.
+ *
+ * This is created using {@link #builder()}.
  */
 @SdkPublicApi
 @ThreadSafe

services/sts/src/main/java/software/amazon/awssdk/services/sts/auth/StsGetSessionTokenCredentialsProvider.java

@@ -29,14 +29,15 @@
 
 /**
  * An implementation of {@link AwsCredentialsProvider} that periodically sends a {@link GetSessionTokenRequest} to the AWS
- * Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated asynchronously
- * in the background as they get close to expiring. If the credentials are not successfully updated asynchronously in the
- * background, calls to {@link #resolveCredentials()} will begin to block in an attempt to update the credentials synchronously.
+ * Security Token Service to maintain short-lived sessions to use for authentication. These sessions are updated using a single
+ * calling thread (by default) or asynchronously (if {@link Builder#asyncCredentialUpdateEnabled(Boolean)} is set).
  *
- * This provider creates a thread in the background to periodically update credentials. If this provider is no longer needed,
- * the background thread can be shut down using {@link #close()}.
+ * If the credentials are not successfully updated before expiration, calls to {@link #resolveCredentials()} will block until
+ * they are updated successfully.
  *
- * This is created using {@link StsGetSessionTokenCredentialsProvider#builder()}.
+ * Users of this provider must {@link #close()} it when they are finished using it.
+ *
+ * This is created using {@link #builder()}.
  */
 @SdkPublicApi
 @ThreadSafe