Support background token refresh when using AuthTokenProvider

Supports refreshing an AuthToken in the background before it expires. By default, the background refresh is triggered 5 minutes before the expiration.

Author: rbygrave

.github/workflows/build.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java_version: [17, 21]
+        java_version: [21]
         os: [ubuntu-latest]
 
     steps:

http-client/pom.xml

@@ -94,6 +94,20 @@
 
   <build>
     <plugins>
+
+      <plugin> <!-- Multi-Release with 21 -->
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <version>3.3.0</version>
+        <configuration>
+          <archive>
+            <manifestEntries>
+              <Multi-Release>true</Multi-Release>
+            </manifestEntries>
+          </archive>
+        </configuration>
+      </plugin>
+
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-compiler-plugin</artifactId>
@@ -111,9 +125,51 @@
               </annotationProcessorPaths>
             </configuration>
           </execution>
+          <!-- Compile for base version Java 11 -->
+          <execution>
+            <id>base</id>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <release>11</release>
+              <compileSourceRoots>
+                <compileSourceRoot>${project.basedir}/src/main/java</compileSourceRoot>
+              </compileSourceRoots>
+            </configuration>
+          </execution>
+          <!-- Compile for Java 21 -->
+          <execution>
+            <id>java21</id>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <release>21</release>
+              <compileSourceRoots>
+                <compileSourceRoot>${project.basedir}/src/main/java21</compileSourceRoot>
+              </compileSourceRoots>
+              <outputDirectory>${project.build.outputDirectory}/META-INF/versions/21</outputDirectory>
+            </configuration>
+          </execution>
         </executions>
       </plugin>
 
+      <!-- generated by avaje inject -->
+      <plugin>
+        <groupId>io.avaje</groupId>
+        <artifactId>avaje-inject-maven-plugin</artifactId>
+        <version>11.4</version>
+        <executions>
+          <execution>
+            <?m2e execute?>
+            <phase>process-sources</phase>
+            <goals>
+              <goal>provides</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>
 </project>

http-client/src/main/java/io/avaje/http/client/AuthToken.java

@@ -1,5 +1,6 @@
 package io.avaje.http.client;
 
+import java.time.Duration;
 import java.time.Instant;
 
 /**
@@ -19,6 +20,11 @@ public interface AuthToken {
    */
   boolean isExpired();
 
+  /**
+   * Return the duration until expiry.
+   */
+  Duration expiration();
+
   /**
    * Create an return a AuthToken with the given token and time it is valid until.
    */
@@ -51,5 +57,10 @@ public String token() {
     public boolean isExpired() {
       return Instant.now().isAfter(validUntil);
     }
+
+    @Override
+    public Duration expiration() {
+      return Duration.between(Instant.now(), validUntil);
+    }
   }
 }

http-client/src/main/java/io/avaje/http/client/BGInvoke.java

@@ -0,0 +1,25 @@
+package io.avaje.http.client;
+
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+final class BGInvoke {
+
+  static void invoke(Runnable task) {
+    ExecutorService executor = Executors.newSingleThreadExecutor();
+    try {
+      executor.submit(task);
+    } finally {
+      executor.shutdown();
+      try {
+        if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {
+          executor.shutdownNow();
+        }
+      } catch (InterruptedException e) {
+        executor.shutdownNow();
+        Thread.currentThread().interrupt();
+      }
+    }
+  }
+}

http-client/src/main/java/io/avaje/http/client/DHttpClientBuilder.java

@@ -11,6 +11,7 @@
 import java.net.CookieManager;
 import java.net.ProxySelector;
 import java.time.Duration;
+import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
@@ -36,6 +37,7 @@ final class DHttpClientBuilder implements HttpClient.Builder, HttpClient.Builder
   private RetryHandler retryHandler;
   private Function<HttpException, RuntimeException> errorHandler;
   private AuthTokenProvider authTokenProvider;
+  private Duration backgroundRefreshDuration = Duration.of(5, ChronoUnit.MINUTES);
 
   private CookieHandler cookieHandler = new CookieManager();
   private java.net.http.HttpClient.Redirect redirect = java.net.http.HttpClient.Redirect.NORMAL;
@@ -185,6 +187,7 @@ private DHttpClientContext buildClient() {
       errorHandler,
       buildListener(),
       authTokenProvider,
+      backgroundRefreshDuration,
       buildIntercept());
   }
 
@@ -257,6 +260,12 @@ public HttpClient.Builder authTokenProvider(AuthTokenProvider authTokenProvider)
     return this;
   }
 
+  @Override
+  public HttpClient.Builder backgroundTokenRefresh(Duration backgroundRefreshDuration) {
+    this.backgroundRefreshDuration = backgroundRefreshDuration;
+    return this;
+  }
+
   @Override
   public HttpClient.Builder cookieHandler(CookieHandler cookieHandler) {
     this.cookieHandler = cookieHandler;

http-client/src/main/java/io/avaje/http/client/DHttpClientContext.java

@@ -1,12 +1,15 @@
 package io.avaje.http.client;
 
+import io.avaje.applog.AppLog;
+
 import java.lang.invoke.MethodHandles;
 import java.lang.invoke.MethodType;
 import java.lang.reflect.Type;
 import java.net.http.HttpHeaders;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.time.Duration;
+import java.time.Instant;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -18,8 +21,12 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+import static java.lang.System.Logger.Level.WARNING;
+
 final class DHttpClientContext implements HttpClient, SpiHttpClient {
 
+  private static final System.Logger log = AppLog.getLogger("io.avaje.http.client");
+
   static final String AUTHORIZATION = "Authorization";
   private static final String BEARER = "Bearer ";
 
@@ -33,6 +40,8 @@ final class DHttpClientContext implements HttpClient, SpiHttpClient {
   private final boolean withAuthToken;
   private final AuthTokenProvider authTokenProvider;
   private final AtomicReference<AuthToken> tokenRef = new AtomicReference<>();
+  private final AtomicReference<Instant> backgroundRefreshLease = new AtomicReference<>();
+  private final Duration backgroundRefreshDuration;
 
   private final LongAdder metricResTotal = new LongAdder();
   private final LongAdder metricResError = new LongAdder();
@@ -50,6 +59,7 @@ final class DHttpClientContext implements HttpClient, SpiHttpClient {
       Function<HttpException, RuntimeException> errorHandler,
       RequestListener requestListener,
       AuthTokenProvider authTokenProvider,
+      Duration backgroundRefreshDuration,
       RequestIntercept intercept) {
     this.httpClient = httpClient;
     this.baseUrl = baseUrl;
@@ -59,6 +69,7 @@ final class DHttpClientContext implements HttpClient, SpiHttpClient {
     this.errorHandler = errorHandler;
     this.requestListener = requestListener;
     this.authTokenProvider = authTokenProvider;
+    this.backgroundRefreshDuration = backgroundRefreshDuration;
     this.withAuthToken = authTokenProvider != null;
     this.requestIntercept = intercept;
   }
@@ -328,14 +339,45 @@ void beforeRequest(DHttpClientRequest request) {
   }
 
   private String authToken() {
-    AuthToken authToken = tokenRef.get();
-    if (authToken == null || authToken.isExpired()) {
-      authToken = authTokenProvider.obtainToken(request().skipAuthToken());
-      tokenRef.set(authToken);
+    final AuthToken authToken = tokenRef.get();
+    if (authToken == null) {
+      return obtainNewAuthToken();
+    }
+    final Duration expiration = authToken.expiration();
+    if (expiration.isNegative()) {
+      return obtainNewAuthToken();
     }
+    if (backgroundRefreshDuration != null && expiration.compareTo(backgroundRefreshDuration) < 0) {
+      backgroundTokenRequest();
+    }
+    return authToken.token();
+  }
+
+  private String obtainNewAuthToken() {
+    final AuthToken authToken = authTokenProvider.obtainToken(request().skipAuthToken());
+    tokenRef.set(authToken);
     return authToken.token();
   }
 
+  private void backgroundTokenRequest() {
+    final Instant lease = backgroundRefreshLease.get();
+    if (lease != null && Instant.now().isBefore(lease)) {
+      // a refresh is already in progress
+      return;
+    }
+    // other requests should not trigger a refresh for the next 10 seconds
+    backgroundRefreshLease.set(Instant.now().plusMillis(10_000));
+    BGInvoke.invoke(this::backgroundNewTokenTask);
+  }
+
+  private void backgroundNewTokenTask() {
+    try {
+      obtainNewAuthToken();
+    } catch (Exception e) {
+      log.log(WARNING, "Error refreshing AuthToken in background", e);
+    }
+  }
+
   String maxResponseBody(String body) {
     return body.length() > 1_000 ? body.substring(0, 1_000) + " <truncated> ..." : body;
   }

http-client/src/main/java/io/avaje/http/client/HttpClient.java

@@ -1,5 +1,9 @@
 package io.avaje.http.client;
 
+import io.avaje.inject.BeanScope;
+
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLParameters;
 import java.net.Authenticator;
 import java.net.CookieHandler;
 import java.net.ProxySelector;
@@ -8,11 +12,6 @@
 import java.util.concurrent.Executor;
 import java.util.function.Function;
 
-import javax.net.ssl.SSLContext;
-import javax.net.ssl.SSLParameters;
-
-import io.avaje.inject.BeanScope;
-
 /**
  * The HTTP client context that we use to build and process requests.
  *
@@ -227,6 +226,15 @@ interface Builder {
      */
     Builder authTokenProvider(AuthTokenProvider authTokenProvider);
 
+    /**
+     * Duration before token expiry where a background task will refresh the token. Defaults to 5 minutes.
+     * <p>
+     * Set to null to disable background token refresh.
+     *
+     * @param backgroundTokenRefresh The duration before token expiry that triggers a background refresh.
+     */
+    Builder backgroundTokenRefresh(Duration backgroundTokenRefresh);
+
     /**
      * Set the underlying HttpClient to use.
      * <p>

http-client/src/main/java21/io/avaje/http/client/BGInvoke.java

@@ -0,0 +1,12 @@
+package io.avaje.http.client;
+
+import java.util.concurrent.Executors;
+
+final class BGInvoke {
+
+  static void invoke(Runnable task) {
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+      executor.submit(task);
+    }
+  }
+}

http-client/src/test/java/io/avaje/http/client/AuthTokenTest.java

@@ -9,6 +9,9 @@
 
 import java.net.http.HttpResponse;
 import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+
+import static org.assertj.core.api.Assertions.assertThat;
 
 public class AuthTokenTest {
 
@@ -41,6 +44,15 @@ public AuthToken obtainToken(HttpClientRequest tokenRequest) {
     }
   }
 
+  @Test
+  void expiration() {
+    Instant plus = Instant.now().plus(120, ChronoUnit.SECONDS);
+    AuthToken authToken = AuthToken.of("foo", plus);
+
+    assertThat(authToken.isExpired()).isFalse();
+    assertThat(authToken.expiration().toSeconds()).isBetween(118L, 120L);
+  }
+
   @Disabled
   @Test
   void sendEmail() {

http-client/src/test/java/io/avaje/http/client/DHttpClientContextTest.java

@@ -1,6 +1,5 @@
 package io.avaje.http.client;
 
-import org.example.github.BasicClientInterface;
 import org.junit.jupiter.api.Test;
 
 import java.nio.charset.StandardCharsets;
@@ -9,7 +8,7 @@
 
 class DHttpClientContextTest {
 
-  private final DHttpClientContext context = new DHttpClientContext(null, null, null, null, null, null, null, null, null);
+  private final DHttpClientContext context = new DHttpClientContext(null, null, null, null, null, null, null, null, null, null);
 
   @Test
   void gzip_gzipDecode() {

http-client/src/test/java/io/avaje/http/client/DHttpClientRequestTest.java

@@ -10,7 +10,7 @@
 
 class DHttpClientRequestTest {
 
-  final DHttpClientContext context = new DHttpClientContext(null, null, null, null, null, null, null, null, null);
+  final DHttpClientContext context = new DHttpClientContext(null, null, null, null, null, null, null, null, null, null);
 
   @Test
   void suppressLogging_listenerEvent_expect_suppressedPayloadContent() {