Add a backoff mechanism for the CommunicationTokenCredential (Azure#25299)

* Added a backoff mechanism for the CommunicationTokenCredential

Author: AikoBB

sdk/communication/azure-communication-common/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ### Features Added
 
+- Added new constructor with required param `tokenRefresher` for `CommunicationTokenRefreshOptions`
+- Deprecated old constructor overloads in `CommunicationTokenRefreshOptions` and replaced by fluent setters
+- Added fluent setters for optional properties:
+    - Added `setRefreshProactively(boolean refreshProactively)` setter that allows setting whether the token should be proactively renewed prior to its expiry or on demand.
+    - Added `setInitialToken(String initialToken)` setter that allows setting the optional serialized JWT token
+- Added a synchronous token refresher getter `getTokenRefresherSync` for `CommunicationTokenRefreshOptions`
+- Optimization added: When the proactive refreshing is enabled and the token refresher fails to provide a token that's not about to expire soon, the subsequent refresh attempts will be scheduled for when the token reaches half of its remaining lifetime until a token with long enough validity (>10 minutes) is obtained.
+
 ### Breaking Changes
 
 ### Bugs Fixed
@@ -45,55 +53,71 @@
 - Upgraded azure-core to 1.21.0.
 
 ## 1.0.4 (2021-09-09)
+
 ### Dependency updates
+
 - Added `azure-communication-networktraversal` package
 
 ## 1.0.3 (2021-06-28)
+
 Updated `azure-communication-common` version
 
 ## 1.0.2 (2021-06-09)
+
 Updated `azure-communication-common` version
 
 ## 1.0.1 (2021-05-27)
+
 - Dependency versions updated.
 
 ### Bug Fixes
+
 - Fixed bug with AzureKeyCredential authentication
 
 ## 1.0.0 (2021-03-29)
 ### Breaking Changes
+
 - Updated `CommunicationCloudEnvironment(String environmentValue)` constructor to `CommunicationCloudEnvironment()`.
 - Updated `public CommunicationCloudEnvironment fromString(String environmentValue)` to `public static CommunicationCloudEnvironment fromString(String environmentValue)`.
 - Renamed `TokenRefresher.getTokenAsync()` to `TokenRefresher.getToken()`.
 
 ## 1.0.0-beta.6 (2021-03-09)
+
 ### Breaking Changes
+
 - Renamed `CommunicationTokenRefreshOptions.getRefreshProactively()` to `CommunicationTokenRefreshOptions.isRefreshProactively()`
 - Constructor for `CommunicationCloudEnvironment` has been removed and now to set an environment value, the `fromString()` method must be called
-- `CommunicationCloudEnvironment`, `CommunicationTokenRefreshOptions `, `CommunicationUserIdentifier`, `MicrosoftTeamsUserIdentifier`,
+- `CommunicationCloudEnvironment`, `CommunicationTokenRefreshOptions`, `CommunicationUserIdentifier`, `MicrosoftTeamsUserIdentifier`,
 `PhoneNumberIdentifier`, `UnknownIdentifier`, are all final classes now.
 
 ## 1.0.0-beta.5 (2021-03-02)
+
 - Updated `azure-communication-common` version
 
 ## 1.0.0-beta.4 (2021-02-09)
+
 ### Breaking Changes
+
 - Renamed `CommunicationUserCredential` to `CommunicationTokenCredential`
 - Replaced constructor `CommunicationTokenCredential(TokenRefresher tokenRefresher, String initialToken, boolean refreshProactively)` and `CommunicationTokenCredential(TokenRefresher tokenRefresher)` with `CommunicationTokenCredential(CommunicationTokenRefreshOptions tokenRefreshOptions)`
 - Renamed `PhoneNumber` to `PhoneNumberIdentifier`
-- Renamed `CommunicationUser` to `CommunicationUserIdentifier `
+- Renamed `CommunicationUser` to `CommunicationUserIdentifier`
 - Renamed `CallingApplication` to `CallingApplicationIdentifier`
 
 ### Added
+
 - Added `MicrosoftTeamsUserIdentifier`
 
 ## 1.0.0-beta.3 (2020-11-16)
+
 Updated `azure-communication-common` version
 
 ## 1.0.0-beta.2 (2020-10-06)
+
 Updated `azure-communication-common` version
 
 ## 1.0.0-beta.1 (2020-09-22)
+
 This package contains common code for Azure Communication Service libraries. For more information, please see the [README][read_me].
 
 This is a Public Preview version, so breaking changes are possible in subsequent releases as we improve the product. To provide feedback, please submit an issue in our [Azure SDK for Java GitHub repo](https://github.com/Azure/azure-sdk-for-java/issues).

sdk/communication/azure-communication-common/README.md

@@ -42,6 +42,7 @@ and then include the direct dependency in the dependencies section without the v
 ```
 
 #### Include direct dependency
+
 If you want to take dependency on a particular version of the library that is not present in the BOM,
 add the direct dependency to your project as follows.
 
@@ -57,29 +58,50 @@ add the direct dependency to your project as follows.
 
 ## Key concepts
 
-To work with Azure Communication Services, a resource access key is used for authentication. 
+To work with Azure Communication Services, a resource access key is used for authentication.
 
 Azure Communication Service supports HMAC authentication with resource access key. To
-apply HMAC authentication, construct CommunicationClientCredential with the access key and instantiate
-a CommunicationIdentityClient to manage users and tokens.
+apply HMAC authentication, construct `CommunicationClientCredential` with the access key and instantiate
+a `CommunicationIdentityClient` to manage users and tokens.
 
 ### CommunicationTokenCredential
 
-It is up to you the developer to first create valid user tokens with the Communication Identity SDK. Then you use these tokens with the `CommunicationTokenCredential`.
+The `CommunicationTokenCredential` object is used to authenticate a user with Communication Services, such as Chat or Calling. It optionally provides an auto-refresh mechanism to ensure a continuously stable authentication state during communications.
 
-`CommunicationTokenCredential` authenticates a user with Communication Services, such as Chat or Calling. It optionally provides an auto-refresh mechanism to ensure a continuously stable authentication state during communications.
+Depending on your scenario, you may want to initialize the `CommunicationTokenCredential` with:
 
-## Contributing
+- a static token (suitable for short-lived clients used to e.g. send one-off Chat messages) or
+- a callback function that ensures a continuous authentication state (ideal e.g. for long Calling sessions).
 
-This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution.
+The tokens supplied to the `CommunicationTokenCredential` either through the constructor or via the token refresher callback can be obtained using the Azure Communication Identity library.
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+## Examples
 
-This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
+### Create a credential with a static token
 
-## Examples
+For short-lived clients, refreshing the token upon expiry is not necessary and `CommunicationTokenCredential` may be instantiated with a static token.
 
-In progress.
+```java
+String token = System.getenv("COMMUNICATION_SERVICES_USER_TOKEN");
+CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(token);
+```
+
+### Create a credential with proactive refreshing with a callback
+
+Alternatively, for long-lived clients, you can create a `CommunicationTokenCredential` with a callback to renew tokens if expired.
+Here we assume that we have a function `fetchTokenFromMyServerForUser` that makes a network request to retrieve a token string for a user.
+It's necessary that the `fetchTokenFromMyServerForUser` function returns a valid token (with an expiration date set in the future) at all times.
+
+Optionally, you can enable proactive token refreshing where a fresh token will be acquired as soon as the
+previous token approaches expiry. Using this method, your requests are less likely to be blocked to acquire a fresh token:
+
+```java
+String token = System.getenv("COMMUNICATION_SERVICES_USER_TOKEN");
+CommunicationTokenRefreshOptions tokenRefreshOptions = new CommunicationTokenRefreshOptions(fetchTokenFromMyServerForUser)
+    .setRefreshProactively(true)
+    .setInitialToken(token);
+CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(tokenRefreshOptions);     
+```
 
 ## Troubleshooting
 
@@ -89,6 +111,14 @@ In progress.
 
 Check out other client libraries for Azure communication service
 
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
+
 <!-- LINKS -->
 [cla]: https://cla.microsoft.com
 [coc]: https://opensource.microsoft.com/codeofconduct/

sdk/communication/azure-communication-common/src/main/java/com/azure/communication/common/CommunicationTokenCredential.java

@@ -2,28 +2,27 @@
 // Licensed under the MIT License.
 package com.azure.communication.common;
 
+import com.azure.communication.common.implementation.TokenParser;
+import com.azure.core.credential.AccessToken;
 import com.azure.core.util.FluxUtil;
 import com.azure.core.util.logging.ClientLogger;
-
 import reactor.core.publisher.Mono;
 
-import com.azure.core.credential.AccessToken;
-
 import java.io.IOException;
 import java.time.OffsetDateTime;
 import java.util.Date;
 import java.util.Objects;
 import java.util.Timer;
 import java.util.TimerTask;
+import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
 
-import com.azure.communication.common.implementation.TokenParser;
-
 /**
  * Provide user credential for Communication service user
  */
 public final class CommunicationTokenCredential implements AutoCloseable {
     private static final int DEFAULT_EXPIRING_OFFSET_MINUTES = 10;
+    private static final int DEFAULT_REFRESH_AFTER_TTL_DIVIDER = 2;
 
     private final ClientLogger logger = new ClientLogger(CommunicationTokenCredential.class);
 
@@ -47,22 +46,45 @@ public CommunicationTokenCredential(String token) {
      * Create with tokenRefreshOptions, which includes a token supplier and optional serialized JWT token.
      * If refresh proactively is true, callback function tokenRefresher will be called
      * ahead of the token expiry by the number of minutes specified by
-     * CallbackOffsetMinutes defaulted to ten minutes. To modify this default, call
-     * setCallbackOffsetMinutes after construction
+     * CallbackOffsetMinutes defaulted to ten minutes.
      *
      * @param tokenRefreshOptions implementation to supply fresh token when reqested
      */
     public CommunicationTokenCredential(CommunicationTokenRefreshOptions tokenRefreshOptions) {
-        Supplier<Mono<String>> tokenRefresher = tokenRefreshOptions.getTokenRefresher();
-        Objects.requireNonNull(tokenRefresher, "'tokenRefresher' cannot be null.");
-        refresher = tokenRefresher;
+        Supplier<String> tokenRefresher = tokenRefreshOptions.getTokenRefresherSync();
+        refresher = tokenRefresher != null
+                ? () -> Mono.fromSupplier(tokenRefresher)
+                : tokenRefreshOptions.getTokenRefresher();
+        Objects.requireNonNull(refresher, "'tokenRefresher' cannot be null.");
         if (tokenRefreshOptions.getInitialToken() != null) {
             setToken(tokenRefreshOptions.getInitialToken());
-            if (tokenRefreshOptions.isRefreshProactively()) {
-                OffsetDateTime nextFetchTime = accessToken.getExpiresAt().minusMinutes(DEFAULT_EXPIRING_OFFSET_MINUTES);
-                fetchingTask = new FetchingTask(this, nextFetchTime);
-            }
         }
+        if (tokenRefreshOptions.isRefreshProactively()) {
+            scheduleRefresher();
+        }
+    }
+
+    private void scheduleRefresher() {
+        OffsetDateTime nextFetchTime;
+        if (isTokenExpired(accessToken)) {
+            nextFetchTime = OffsetDateTime.now();
+        } else {
+            OffsetDateTime now = OffsetDateTime.now();
+            long tokenTtlMs = accessToken.getExpiresAt().toInstant().toEpochMilli() - now.toInstant().toEpochMilli();
+            long nextFetchTimeMs = isTokenExpiringSoon()
+                    ? tokenTtlMs / DEFAULT_REFRESH_AFTER_TTL_DIVIDER
+                    : tokenTtlMs - TimeUnit.MILLISECONDS.convert(DEFAULT_EXPIRING_OFFSET_MINUTES, TimeUnit.MINUTES);
+            nextFetchTime = now.plusNanos(TimeUnit.NANOSECONDS.convert(nextFetchTimeMs, TimeUnit.MILLISECONDS));
+        }
+        fetchingTask = new FetchingTask(this, nextFetchTime);
+    }
+
+    private boolean isTokenExpired(AccessToken accessToken) {
+        return accessToken == null || accessToken.isExpired();
+    }
+
+    private boolean isTokenExpiringSoon() {
+        return accessToken == null || OffsetDateTime.now().compareTo(accessToken.getExpiresAt().minusMinutes(DEFAULT_EXPIRING_OFFSET_MINUTES)) > 0;
     }
 
     /**
@@ -73,17 +95,21 @@ public CommunicationTokenCredential(CommunicationTokenRefreshOptions tokenRefres
     public Mono<AccessToken> getToken() {
         if (isClosed) {
             return FluxUtil.monoError(logger,
-                new RuntimeException("getToken called on closed CommunicationTokenCredential object"));
+                    new RuntimeException("getToken called on closed CommunicationTokenCredential object"));
         }
-        if ((accessToken == null || accessToken.isExpired()) && refresher != null) {
+        if (isTokenExpired(accessToken) && refresher != null) {
             synchronized (this) {
                 // no valid token to return and can refresh
-                if ((accessToken == null || accessToken.isExpired()) && refresher != null) {
+                if (isTokenExpired(accessToken) && refresher != null) {
                     return fetchFreshToken()
-                        .map(token -> {
-                            accessToken = tokenParser.parseJWTToken(token);
-                            return accessToken;
-                        });
+                            .flatMap(token -> {
+                                accessToken = tokenParser.parseJWTToken(token);
+                                if (isTokenExpired(accessToken)) {
+                                    return FluxUtil.monoError(logger,
+                                            new IllegalArgumentException("The token returned from the tokenRefresher is expired."));
+                                }
+                                return Mono.just(accessToken);
+                            });
                 }
             }
         }
@@ -107,18 +133,16 @@ boolean hasProactiveFetcher() {
 
     private void setToken(String freshToken) {
         accessToken = tokenParser.parseJWTToken(freshToken);
-
-        if (fetchingTask != null) {
-            OffsetDateTime nextFetchTime = accessToken.getExpiresAt().minusMinutes(DEFAULT_EXPIRING_OFFSET_MINUTES);
-            fetchingTask.setNextFetchTime(nextFetchTime);
+        if (hasProactiveFetcher()) {
+            scheduleRefresher();
         }
     }
 
     private Mono<String> fetchFreshToken() {
         Mono<String> tokenAsync = refresher.get();
         if (tokenAsync == null) {
             return FluxUtil.monoError(logger,
-                new RuntimeException("get() function of the token refresher should not return null."));
+                    new RuntimeException("get() function of the token refresher should not return null."));
         }
         return tokenAsync;
     }
@@ -129,14 +153,9 @@ private static class FetchingTask {
         private OffsetDateTime nextFetchTime;
 
         FetchingTask(CommunicationTokenCredential tokenHost,
-            OffsetDateTime nextFetchAt) {
+                     OffsetDateTime nextFetchAt) {
             host = tokenHost;
             nextFetchTime = nextFetchAt;
-            startTimer();
-        }
-
-        private synchronized void setNextFetchTime(OffsetDateTime newFetchTime) {
-            nextFetchTime = newFetchTime;
             stopTimer();
             startTimer();
         }
@@ -165,6 +184,10 @@ private void setToken(String freshTokenString) {
             host.setToken(freshTokenString);
         }
 
+        private boolean isTokenExpired(String freshTokenString) {
+            return host.tokenParser.parseJWTToken(freshTokenString).isExpired();
+        }
+
         private class TokenExpiringTask extends TimerTask {
             private final ClientLogger logger = new ClientLogger(TokenExpiringTask.class);
             private final FetchingTask tokenCache;
@@ -177,7 +200,13 @@ private class TokenExpiringTask extends TimerTask {
             public void run() {
                 try {
                     Mono<String> tokenAsync = tokenCache.fetchFreshToken();
-                    tokenCache.setToken(tokenAsync.block());
+                    tokenAsync.subscribe(token -> {
+                        if (!tokenCache.isTokenExpired(token)) {
+                            tokenCache.setToken(token);
+                        } else {
+                            logger.logExceptionAsError(new IllegalArgumentException("The token returned from the tokenRefresher is expired."));
+                        }
+                    });
                 } catch (Exception exception) {
                     logger.logExceptionAsError(new RuntimeException(exception));
                 }