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: SoulPancake / name: Anurag Bandyopadhyay (adbecd7)
• ✅ 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]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 4587c818-62d2-40f0-a46f-9de4caf6f58d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

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.)

✨ 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?

[curfew-marathon]

@dpkass yes, you'll need to remove codex

[codecov-commenter]

Codecov Report

❌ Patch coverage is 69.69697% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.42%. Comparing base (209bd3d) to head (adbecd7).

Files with missing lines	Patch %	Lines
...fga/sdk/api/configuration/ClientConfiguration.java	0.00%	4 Missing ⚠️
...v/openfga/sdk/api/configuration/Configuration.java	71.42%	2 Missing and 2 partials ⚠️
...in/java/dev/openfga/sdk/api/auth/OAuth2Client.java	75.00%	0 Missing and 1 partial ⚠️
...ain/java/dev/openfga/sdk/api/client/ApiClient.java	87.50%	0 Missing and 1 partial ⚠️

❌ Your project status has failed because the head coverage (39.42%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #389      +/-   ##
============================================
+ Coverage     39.34%   39.42%   +0.08%     
- Complexity     1336     1341       +5     
============================================
  Files           202      202              
  Lines          7791     7815      +24     
  Branches        912      913       +1     
============================================
+ Hits           3065     3081      +16     
- Misses         4579     4585       +6     
- Partials        147      149       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[SoulPancake]

Hi @dpkass
You can rebase and amend author to just you and force push it