feat: configure client-credentials token refresh timing

[dpkass]

Description

What problem is being solved?

Five-minute access tokens are immediately considered stale by the fixed 300-second refresh buffer plus jitter, causing repeated token exchanges.

How is it being solved?

Make the refresh buffer and jitter configurable at the client level while preserving existing defaults.

What changes are made to solve it?

• Add nonnegative tokenExpiryBufferSeconds and tokenExpiryJitterSeconds settings to Configuration and fluent ClientConfiguration. Zero jitter disables jitter.
• Preserve these settings through configuration overrides and distinguish refresh policies in the OAuth client cache.
• Document configuration and extend authentication tests for token reuse, refresh thresholds, overrides, and cache separation.

Validation: ./gradlew build test-integration passed on Java 21. Formatting and focused tests also passed after removing a redundant setter-validation test.

References

Closes #388

Review Checklist

• I have allowed edits by maintainers.
• I have added documentation for new/changed functionality in this PR.
• The correct base branch is being used (main).
• I have added tests to validate that the change in functionality is working as expected.

Summary by CodeRabbit

• New Features
  • Added configurable token refresh timing for OAuth2 client-credentials authentication.
  • Tokens can now use an expiry buffer and optional random jitter before refresh.
  • Added validation to prevent negative timing values and support disabling jitter.
  • Refresh settings are preserved when applying per-request configuration overrides.
• Documentation
  • Documented token refresh timing, configuration options, defaults, and usage guidance.

[linux-foundation-easycla]

• ✅ login: dpkass / name: Taha El Amine Kassabi (148f93c, 5f0a0df, ea92495)
• ❌ - login: @oai-codex / name: Codex GPT-5. The commit (148f93c, 5f0a0df, ea92495) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please visit our EasyCLA portal and chat with our support bot.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 3339112d-74a5-4de6-bfb9-245e1e92a154

📥 Commits

Reviewing files that changed from the base of the PR and between 0c5c5c7 and 148f93c.

📒 Files selected for processing (8)

• README.md
• src/main/java/dev/openfga/sdk/api/auth/AccessToken.java
• src/main/java/dev/openfga/sdk/api/auth/OAuth2Client.java
• src/main/java/dev/openfga/sdk/api/client/ApiClient.java
• src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java
• src/main/java/dev/openfga/sdk/api/configuration/Configuration.java
• src/test/java/dev/openfga/sdk/api/auth/AccessTokenTest.java
• src/test/java/dev/openfga/sdk/api/client/ApiClientTest.java

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The change adds configurable token-expiry buffer and jitter settings. OAuth2 token validation uses these settings, configuration overrides preserve them, and OAuth2 client cache keys include them. Tests and documentation cover the new behavior.

Changes

OAuth2 refresh timing

Layer / File(s)	Summary
Refresh timing configuration src/main/java/dev/openfga/sdk/api/configuration/Configuration.java, src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java, README.md	Adds validated buffer and jitter settings, preserves them across overrides, exposes typed fluent methods, and documents the configuration.
Configurable token validity src/main/java/dev/openfga/sdk/api/auth/AccessToken.java, src/main/java/dev/openfga/sdk/api/auth/OAuth2Client.java, src/test/java/dev/openfga/sdk/api/auth/AccessTokenTest.java	Token validity now uses configured buffer and jitter values. OAuth2Client applies the settings in both cache-check paths.
Refresh-aware client caching src/main/java/dev/openfga/sdk/api/client/ApiClient.java, src/test/java/dev/openfga/sdk/api/client/ApiClientTest.java	OAuth2 client cache keys include refresh settings. Tests cover refresh-window behavior, request overrides, and separate caches.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant ApiClient
  participant OAuth2Client
  participant AccessToken
  ApiClient->>OAuth2Client: Request access token
  OAuth2Client->>AccessToken: Validate with buffer and jitter
  AccessToken-->>OAuth2Client: Return validity result
  OAuth2Client-->>ApiClient: Reuse or refresh token

Loading

Suggested reviewers: jimmyjames

Merge Risk: ⚪ Minimal · up to 148f9

The SDK now supports configurable client-credentials token refresh timing while preserving defaults. Configuration overrides, cache separation, and refresh behavior are covered, with no concrete merge-blocking risk evident.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 25 functions across 7 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: configurable client-credentials token refresh timing.
Linked Issues check	✅ Passed	The changes satisfy issue #388 by making token-expiry buffer and jitter configurable, preserving defaults, validating nonnegative values, supporting zero jitter, preserving settings through overrides,…
Out of Scope Changes check	✅ Passed	All code, documentation, and test changes directly support configurable client-credentials token refresh timing and the requirements in issue #388.

Full details: Docstring Coverage

Explanation

Docstring coverage is 28.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 25 functions across 7 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dpkass]

should i remove codex for cla to be accepted?