fix(java): configurable proactive offset

Author: dgawande12

README.md

@@ -180,6 +180,26 @@ RequestOptions reqOpt = RequestOptions.builder()
         .build();
 ```
 
+### Access Token Proactive Expiry Offset
+
+The `ConfidentialClient` refreshes access tokens proactively before their actual server-declared expiry to reduce the risk of a token expiring mid-request (e.g. due to latency or clock skew).
+
+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).
+
+You can override the proactive offset by supplying a custom value (milliseconds) via the constructor overload.
+
+#### Example
+```java
+ConfidentialClient client10s = new ConfidentialClient(
+    "./path/to/config.json",
+    RequestOptions.builder().build(),
+    10000L // 10 second proactive expiry offset
+);
+```
+
 ## Modules
 
 Information about the various utility modules contained in this library can be found below.

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

@@ -51,6 +51,7 @@ public class ConfidentialClient implements OAuth2Client {
     private long jwsIssuedAt;
     private long accessTokenExpireTime;
     private AccessToken accessToken;
+    private final long accessTokenExpiryOffsetMillis;
 
     /**
      * Creates a new ConfidentialClient. When setting up the OAuth 2.0 client, this constructor reaches out to
@@ -66,7 +67,7 @@ public class ConfidentialClient implements OAuth2Client {
     public ConfidentialClient(final String configPath)
         throws AuthServerMetadataContentException, AuthServerMetadataException,
         ConfigurationException {
-        this(new Configuration(configPath));
+        this(new Configuration(configPath), RequestOptions.builder().build(), Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
     }
 
     /**
@@ -84,7 +85,19 @@ public ConfidentialClient(final String configPath)
     public ConfidentialClient(final String configPath, RequestOptions requestOptions)
             throws AuthServerMetadataContentException, AuthServerMetadataException,
             ConfigurationException {
-        this(new Configuration(configPath), requestOptions);
+        this(new Configuration(configPath), requestOptions, Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
+    }
+
+    /**
+     * Creates a new ConfidentialClient with a custom proactive expiry offset.
+     * @param configPath path to config file
+     * @param requestOptions request options (proxy/ssl)
+     * @param accessTokenExpiryOffsetMillis milliseconds subtracted from server expiry (non-negative)
+     */
+    public ConfidentialClient(final String configPath, RequestOptions requestOptions, long accessTokenExpiryOffsetMillis)
+            throws AuthServerMetadataContentException, AuthServerMetadataException,
+            ConfigurationException {
+        this(new Configuration(configPath), requestOptions, accessTokenExpiryOffsetMillis);
     }
 
     /**
@@ -99,7 +112,7 @@ public ConfidentialClient(final String configPath, RequestOptions requestOptions
      */
     public ConfidentialClient(final Configuration config)
         throws AuthServerMetadataContentException, AuthServerMetadataException {
-        this(config, RequestOptions.builder().build());
+        this(config, RequestOptions.builder().build(), Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
     }
 
     /**
@@ -115,11 +128,22 @@ public ConfidentialClient(final Configuration config)
      */
     public ConfidentialClient(final Configuration config, RequestOptions requestOptions)
             throws AuthServerMetadataContentException, AuthServerMetadataException {
+        this(config, requestOptions, Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
+    }
+
+    /**
+     * Core constructor with configurable access token proactive expiry offset.
+     * @param config configuration
+     * @param requestOptions request options
+     * @param accessTokenExpiryOffsetMillis milliseconds to subtract from token lifetime when computing internal expiry
+     */
+    public ConfidentialClient(final Configuration config, RequestOptions requestOptions, long accessTokenExpiryOffsetMillis)
+            throws AuthServerMetadataContentException, AuthServerMetadataException {
         Objects.requireNonNull(config, "Configuration object must not be null");
         this.config = config;
         LOGGER.debug("Finished initialising configuration");
         this.requestOptions = requestOptions == null ? RequestOptions.builder().build() : requestOptions;
-
+        this.accessTokenExpiryOffsetMillis = accessTokenExpiryOffsetMillis;
         this.requestProviderMetadata();
     }
 
@@ -139,7 +163,7 @@ protected ConfidentialClient(final String configPath, final TokenRequestBuilder
         throws AuthServerMetadataContentException,
         AuthServerMetadataException,
         ConfigurationException {
-        this(new Configuration(configPath));
+        this(new Configuration(configPath), RequestOptions.builder().build(), Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
         this.tokenRequestBuilder = tokReqBuilder.uri(this.providerMetadata.getTokenEndpointURI());
     }
 
@@ -157,7 +181,7 @@ protected ConfidentialClient(final String configPath, final TokenRequestBuilder
     protected ConfidentialClient(final Configuration config, final TokenRequestBuilder tokReqBuilder)
         throws AuthServerMetadataContentException,
         AuthServerMetadataException {
-        this(config);
+        this(config, RequestOptions.builder().build(), Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
         this.tokenRequestBuilder = tokReqBuilder.uri(this.providerMetadata.getTokenEndpointURI());
     }
 
@@ -176,7 +200,7 @@ protected ConfidentialClient(final Configuration config, final TokenRequestBuild
     protected ConfidentialClient(final Configuration config, final TokenRequestBuilder tokReqBuilder, RequestOptions requestOptions)
             throws AuthServerMetadataContentException,
             AuthServerMetadataException {
-        this(config, requestOptions);
+        this(config, requestOptions, Constants.DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS);
         this.tokenRequestBuilder = tokReqBuilder.uri(this.providerMetadata.getTokenEndpointURI());
     }
 
@@ -283,7 +307,7 @@ private String fetchAccessToken() throws AccessTokenException, SigningJwsExcepti
         if (tokenRes.indicatesSuccess()) {
             this.accessToken = tokenRes.toSuccessResponse().getTokens().getAccessToken();
             this.accessTokenExpireTime =
-                this.jwsIssuedAt + TimeUnit.SECONDS.toMillis(this.accessToken.getLifetime()) - Constants.ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS;
+                this.jwsIssuedAt + TimeUnit.SECONDS.toMillis(this.accessToken.getLifetime()) - this.accessTokenExpiryOffsetMillis;
             LOGGER.info("Fetched access token which expires in: {} seconds (buffered)", this.accessToken.getLifetime());
             return this.accessToken.toString();
         }

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

@@ -13,8 +13,10 @@ public final class Constants {
     // default values
     public static final String FACTSET_WELL_KNOWN_URI = "https://auth.factset.com/.well-known/openid-configuration";
 
-    // Buffer (in milliseconds) to refresh access token before actual expiry
-    public static final long ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS = 30000; // 30 seconds
+    /**
+     * Default buffer (in milliseconds) to refresh access token before actual expiry.
+     */
+    public static final long DEFAULT_ACCESS_TOKEN_EXPIRY_OFFSET_MILLIS = 30000L;
 
     private Constants() {
         throw new IllegalStateException("Utility class");

src/test/java/com/factset/sdk/utils/authentication/ConfidentialClientTest.java

@@ -336,6 +336,58 @@ void getAccessTokenForceRefreshThenCachedReturnsCorrectTokens() throws Exception
         verify(harness.httpRequestMock, times(1)).send();
     }
 
+    @Test
+    void accessTokenFiftySecondOffsetTriggersRefetchAfterEarlyExpirySingleToken() throws Exception {
+        long offsetMillis = 50_000L;
+        TestHarness harness = createClientTokenCustomOffset(offsetMillis);
+
+        String first = harness.client.getAccessToken();
+        assertEquals("tokenSingle", first);
+        verify(harness.httpRequestMock, times(1)).send();
+
+        java.lang.reflect.Field issuedAtField = ConfidentialClient.class.getDeclaredField("jwsIssuedAt");
+        java.lang.reflect.Field expiryField = ConfidentialClient.class.getDeclaredField("accessTokenExpireTime");
+        issuedAtField.setAccessible(true);
+        expiryField.setAccessible(true);
+        long issuedAt = (long) issuedAtField.get(harness.client);
+        long internalExpiry = (long) expiryField.get(harness.client);
+        long expectedDelta = 899_000L - offsetMillis;
+        assertEquals(expectedDelta, internalExpiry - issuedAt, "Internal expiry should be lifetime - offset");
+
+        expiryField.set(harness.client, System.currentTimeMillis() - 1);
+
+        String second = harness.client.getAccessToken();
+        assertEquals("tokenSingle", second);
+        verify(harness.httpRequestMock, times(2)).send();
+    }
+
+    private static TestHarness createClientTokenCustomOffset(long offsetMillis) throws Exception {
+        HttpURLConnection mockedConn = mock(HttpURLConnection.class);
+        URL mockedURL = getUrlMockResponse("exampleResponseWellKnownUri.txt", mockedConn);
+        Configuration configurationMock = getConfigSpyMockedResponse(mockedURL, "validConfig.txt");
+
+        AuthorizationGrant grant = new UnitTestGrant();
+        URI uriSpy = spy(new URI("https://test.test.com/.test-test/test-test"));
+        TokenRequest tokenRequestMock = spy(new TokenRequest(uriSpy, grant, new Scope()));
+        TokenRequestBuilder tokenRequestBuilderSpy = spy(new TokenRequestBuilder());
+        HTTPRequest httpRequestMock = mock(HTTPRequest.class);
+
+        HTTPResponse res = new HTTPResponse(HTTPResponse.SC_OK);
+        res.setContent("{\"access_token\":\"tokenSingle\",\"token_type\":\"Bearer\",\"expires_in\":899}");
+        res.setHeader("Content-Type", "application/json;charset=utf-8");
+
+        doReturn(tokenRequestMock).when(tokenRequestBuilderSpy).build();
+        doReturn(httpRequestMock).when(tokenRequestMock).toHTTPRequest();
+        when(httpRequestMock.send()).thenReturn(res, res);
+
+        ConfidentialClient client = new ConfidentialClient(configurationMock, RequestOptions.builder().build(), offsetMillis);
+        java.lang.reflect.Field f = ConfidentialClient.class.getDeclaredField("tokenRequestBuilder");
+        f.setAccessible(true);
+        f.set(client, tokenRequestBuilderSpy);
+
+        return new TestHarness(client, httpRequestMock);
+    }
+
     private static class TestHarness {
         final ConfidentialClient client;
         final HTTPRequest httpRequestMock;