fix(java): thread reliability via sync

Author: dgawande12

README.md

@@ -139,7 +139,7 @@ public class Console {
 }
 ```
 
-> Token refresh note: `getAccessToken()` (or `getAccessToken(false)`) returns the cached token while valid. Call `getAccessToken(true)` to bypass the cache and force retrieval of a new token.
+> Token refresh note: `getAccessToken()` (or `getAccessToken(false)`) returns the cached token while valid. Call `getAccessToken(true)` to bypass the cache and force retrieval of a new token. (See [Access Token Proactive Expiry Offset](#access-token-proactive-expiry-offset) for details on token expiry handling.)
 
 ### Configure a Proxy
 
@@ -187,16 +187,16 @@ The `ConfidentialClient` refreshes access tokens proactively before their actual
 Default behaviour:
 - A 30 second (30,000 ms) proactive offset is applied automatically.
 - Calls to `getAccessToken()` (or `getAccessToken(false)`) reuse the cached token while it is still considered valid under this adjusted expiry.
-- `getAccessToken(true)` always forces a fresh token (bypasses cache).
+- `getAccessToken(true)` forces a fresh token unless one was very recently refreshed (within 5 seconds) to avoid unnecessary duplicate requests from concurrent threads.
 
 You can override the proactive offset by configuring it in `RequestOptions`:
 
 #### Example
 ```java
-RequestOptions options10s = RequestOptions.builder()
-    .accessTokenExpiryOffsetMillis(90_000L) // 90 seconds
+RequestOptions options = RequestOptions.builder()
+    .accessTokenExpiryOffset(Duration.ofSeconds(90)) // 90 seconds
     .build();
-ConfidentialClient client10s = new ConfidentialClient("./path/to/config.json", options10s);
+ConfidentialClient client = new ConfidentialClient("./path/to/config.json", options);
 ```
 
 ## Modules

src/main/java/com/factset/sdk/utils/authentication/ConfidentialClient.java

@@ -33,6 +33,7 @@
 import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
+import java.time.Duration; // added for internal duration usage
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -51,7 +52,8 @@ public class ConfidentialClient implements OAuth2Client {
     private long jwsIssuedAt;
     private long accessTokenExpireTime;
     private AccessToken accessToken;
-    private final long accessTokenExpiryOffsetMillis;
+    private final Duration accessTokenExpiryOffset;
+    private long lastRefreshTime;
 
     /**
      * Creates a new ConfidentialClient. When setting up the OAuth 2.0 client, this constructor reaches out to
@@ -120,7 +122,7 @@ public ConfidentialClient(final Configuration config, RequestOptions requestOpti
         this.config = config;
         LOGGER.debug("Finished initialising configuration");
         this.requestOptions = requestOptions == null ? RequestOptions.builder().build() : requestOptions;
-        this.accessTokenExpiryOffsetMillis = this.requestOptions.getAccessTokenExpiryOffsetMillis();
+        this.accessTokenExpiryOffset = this.requestOptions.getAccessTokenExpiryOffset();
         this.requestProviderMetadata();
     }
 
@@ -184,18 +186,31 @@ protected ConfidentialClient(final Configuration config, final TokenRequestBuild
     /**
      * Returns an access token that can be used for authentication. If the cache contains a valid access token,
      * it's returned. Otherwise, a new access token is retrieved from FactSet's authorization server.
-     * If forceRefresh is true, always fetches a new token regardless of cache.
+     * If forceRefresh is true, fetches a new token unless one was very recently refreshed (within 5 seconds)
+     * to avoid unnecessary duplicate requests from concurrent threads.
      *
      * @param forceRefresh If true, forces fetching a new token from the server.
      * @return The access token in string format.
      * @throws AccessTokenException If it can't make a successful request or parse the TokenRequest.
      * @throws SigningJwsException  If the signing of the JWS fails.
      */
-    public String getAccessToken(boolean forceRefresh) throws AccessTokenException, SigningJwsException {
-        if (!forceRefresh && this.isCachedTokenValid()) {
-            LOGGER.info("Retrieved access token which expires in: {} seconds", TimeUnit.MILLISECONDS.toSeconds(this.accessTokenExpireTime - System.currentTimeMillis()));
-            return this.accessToken.toString();
+    public synchronized String getAccessToken(boolean forceRefresh) throws AccessTokenException, SigningJwsException {
+        if (this.isCachedTokenValid()) {
+            if (!forceRefresh) {
+                LOGGER.info("Retrieved access token which expires in: {} seconds", TimeUnit.MILLISECONDS.toSeconds(this.accessTokenExpireTime - System.currentTimeMillis()));
+                return this.accessToken.toString();
+            }
+
+            long currentTime = System.currentTimeMillis();
+
+            // Implementing a grace period of 5 seconds to avoid unnecessary token refreshes
+            boolean recentlyRefreshed = (currentTime - this.lastRefreshTime) < 5000;
+            if (recentlyRefreshed) {
+                LOGGER.debug("Force refresh requested but token was recently refreshed within grace period, returning cached token");
+                return this.accessToken.toString();
+            }
         }
+
         return this.fetchAccessToken();
     }
 
@@ -210,7 +225,7 @@ public String getAccessToken(boolean forceRefresh) throws AccessTokenException,
      * @throws SigningJwsException  If the signing of the JWS fails.
      */
     @Override
-    public String getAccessToken() throws AccessTokenException, SigningJwsException {
+    public synchronized String getAccessToken() throws AccessTokenException, SigningJwsException {
         if (this.isCachedTokenValid()) {
             LOGGER.info("Retrieved access token which expires in: {} seconds", TimeUnit.MILLISECONDS.toSeconds(this.accessTokenExpireTime - System.currentTimeMillis()));
             return this.accessToken.toString();
@@ -249,7 +264,7 @@ private void requestProviderMetadata() throws AuthServerMetadataContentException
                 new TokenRequestBuilder().uri(this.providerMetadata.getTokenEndpointURI());
     }
 
-    private boolean isCachedTokenValid() {
+    private synchronized boolean isCachedTokenValid() {
         if (this.accessToken == null) {
             return false;
         }
@@ -283,21 +298,13 @@ private String fetchAccessToken() throws AccessTokenException, SigningJwsExcepti
 
         if (tokenRes.indicatesSuccess()) {
             this.accessToken = tokenRes.toSuccessResponse().getTokens().getAccessToken();
-            long lifetimeMillis = TimeUnit.SECONDS.toMillis(this.accessToken.getLifetime());
-            long rawOffset = this.accessTokenExpiryOffsetMillis;
-
-            long clampedOffset;
-            if (rawOffset >= 899_000L) {
-                clampedOffset = 899_000L - 1;
-                LOGGER.warn("Proactive expiry offset {}ms >= 899 seconds. Clamped to {}ms.", rawOffset, clampedOffset);
-            } else {
-                clampedOffset = rawOffset;
-            }
-
-            long effectiveLifetime = lifetimeMillis - clampedOffset;
+            long lifetimeMillis = java.util.concurrent.TimeUnit.SECONDS.toMillis(this.accessToken.getLifetime());
+            long offsetMillis = this.accessTokenExpiryOffset.toMillis();
+            long effectiveLifetime = lifetimeMillis - offsetMillis;
             this.accessTokenExpireTime = this.jwsIssuedAt + effectiveLifetime;
-            LOGGER.info("Fetched access token (serverLifetime={}s, offsetApplied={}ms, effectiveLifetime={}ms)",
-                    this.accessToken.getLifetime(), clampedOffset, effectiveLifetime);
+            LOGGER.info("Fetched access token (serverLifetime={}s, configuredOffset={}ms, effectiveLifetime={}ms)",
+                    this.accessToken.getLifetime(), offsetMillis, effectiveLifetime);
+            this.lastRefreshTime = System.currentTimeMillis();
             return this.accessToken.toString();
         }
 

src/main/java/com/factset/sdk/utils/authentication/RequestOptions.java

@@ -7,6 +7,9 @@
 import javax.net.ssl.HttpsURLConnection;
 import javax.net.ssl.SSLSocketFactory;
 import java.net.Proxy;
+import java.time.Duration;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 @Value
 @Builder
@@ -23,6 +26,30 @@ public class RequestOptions {
     @Builder.Default
     String userAgent = "fds-sdk/java/utils/1.1.5 (" + System.getProperty("os.name") + "; Java" + System.getProperty("java.version") + ")";
 
+    /**
+     * Maximum allowed proactive refresh offset (894 seconds).
+     */
+    public static final Duration MAX_PROACTIVE_OFFSET = Duration.ofSeconds(894);
+
+    private static final Logger LOG = LoggerFactory.getLogger(RequestOptions.class);
+
     @Builder.Default
-    long accessTokenExpiryOffsetMillis = 30_000L;
+    Duration accessTokenExpiryOffset = Duration.ofSeconds(30);
+
+
+    public static RequestOptionsBuilder builder() {
+        return new RequestOptionsBuilder() {
+
+            @Override
+            public RequestOptionsBuilder accessTokenExpiryOffset(Duration d) {
+                if (d == null) throw new IllegalArgumentException("accessTokenExpiryOffset cannot be null");
+                if (d.compareTo(MAX_PROACTIVE_OFFSET) > 0) {
+                    LOG.warn("Configured accessTokenExpiryOffset {} exceeds max {}; clamped to {}.", d, MAX_PROACTIVE_OFFSET, MAX_PROACTIVE_OFFSET);
+                    return super.accessTokenExpiryOffset(MAX_PROACTIVE_OFFSET);
+                }
+
+                return super.accessTokenExpiryOffset(d);
+            }
+        };
+    }
 }