Replace async-disabling mechanism with retry backoff on refresh failure

[mihaimitrea-db]

Summary

Replace the cache's staleness tracking with a cached staleAfter timestamp and preserve the legacy staleDuration builder path. Async refresh failures now use a short retry backoff instead of suppressing background refresh until the token expires.

Why

CachedTokenSource previously mixed relative stale-window calculations with token expiry checks, which made the cache state harder to reason about and made it easier to regress callers that explicitly configure staleDuration through the builder. At the same time, a failed async refresh effectively disabled further async refreshes until a blocking refresh happened on expiry, which meant a brief transient failure could prevent the SDK from recovering proactively for the rest of the token lifetime.

This PR moves the cache to an absolute staleAfter threshold that is computed whenever a token is stored. That makes the state model much clearer: callers now classify tokens by comparing the current time against staleAfter and the expiry buffer. It also preserves the legacy fixed-window behavior for callers that set staleDuration, and replaces the old async-failure suppression behavior with a one-minute retry backoff so transient failures can recover without waiting for full expiry.

What changed

Interface changes

None.

Behavioral changes

Calls that set staleDuration through CachedTokenSource.Builder#setStaleDuration(...) continue to get the legacy fixed-window behavior. The cache now recomputes staleAfter from that configured duration each time a token is stored, so both the initial cached token and later refreshed tokens honor the same caller-provided setting.

Failed async refreshes no longer block future async refresh attempts until a blocking refresh on expiry. Instead, the cache moves staleAfter one minute into the future, treats the token as fresh during that cooldown, and retries async refresh the next time the token becomes stale again.

Older async refresh results are also ignored when the cache already holds a newer token. This prevents a late async refresh from overwriting a token with a later expiry that was installed by another refresh path.

Internal changes

CachedTokenSource now stores an absolute staleAfter instant rather than reasoning about staleness from relative durations at read time. When callers do not provide staleDuration, the stale threshold is derived from the token's remaining TTL at the moment the token is stored and capped at 20 minutes. This centralizes stale-threshold computation in updateToken() and reduces token-state checks to direct time comparisons.

The implementation adds _ASYNC_REFRESH_RETRY_BACKOFF-equivalent behavior for Java via ASYNC_REFRESH_RETRY_BACKOFF, introduces handleFailedAsyncRefresh() to apply the retry cooldown, and adds cachedTokenIsNewer() to discard async refresh results that would otherwise roll the cache back to an older token.

CachedTokenSourceTest was updated to replace the old async-failure fallback coverage with parameterized staleAfter initialization coverage and explicit retry-backoff tests.

How is this tested?

Ran the focused unit test suite for CachedTokenSource and the module formatting check locally:

• mvn --errors -pl databricks-sdk-java -Dtest=CachedTokenSourceTest test
• mvn --errors -pl databricks-sdk-java spotless:check

Test coverage now includes:

• Existing async refresh state coverage in testAsyncRefreshParametrized
• testStaleAfterComputationParametrized for staleAfter initialization across legacy builder-provided staleDuration, default computed thresholds, null initial tokens, and expired tokens
• testGetTokenDoesNotRetryBeforeAsyncBackoffElapses to verify repeated reads during the cooldown do not trigger additional refreshes
• testGetTokenRetriesAfterAsyncBackoffElapsesAndUpdatesToken to verify a read after the cooldown elapses starts a new async refresh and updates the cached token

[renaudhartert-db]

The PR looks great!

A few things I'd like to see addressed:

1. refreshInProgress should likely be reset in a finally block. Right now, if updateToken or cachedTokenIsNewer throw unexpectedly, refreshInProgress stays true permanently and all future async refreshes are deadlocked. Something like:

try {
  Token newToken = tokenSource.getToken();
  synchronized (this) {
    if (newToken != null && !cachedTokenIsNewer(newToken)) {
      updateToken(newToken);
    }
  }
} catch (Exception e) {
  synchronized (this) {
    handleFailedAsyncRefresh();
    logger.error("Asynchronous token refresh failed", e);
  }
} finally {
  synchronized (this) {
    refreshInProgress = false;
  }
}

2. The memory ordering comment in updateToken ("The stale threshold is written before the volatile token write...") is accurate for the success path, but handleFailedAsyncRefresh writes to staleAfter without a subsequent volatile write to token. Could a thread calling getToken (unsynchronized path) read a stale staleAfter after handleFailedAsyncRefresh ran? In practice the consequence is just one extra async trigger, so not a real bug, but the comment should acknowledge the failure path too.

3. I think a test for the cachedTokenIsNewer discard path would be valuable. This is a real concurrent scenario and the current test suite doesn't cover it.

4. Minor: triggerAsyncRefresh changed from != FRESH to == STALE. This is correct (the EXPIRED case is handled by getTokenBlocking), but it's a subtle behavioral change — a one-line comment explaining why EXPIRED is excluded would help.

[github-actions]

If integration tests don't run automatically, an authorized user can run them manually by following the instructions below:

Trigger:
go/deco-tests-run/sdk-java

Inputs:

• PR number: 696
• Commit SHA: edacf5d0c73ea0f607ac59917b9af64e21940ebf

Checks will be approved automatically on success.