[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]

The committers listed above are authorized under a signed CLA.

• ✅ login: dpkass / name: Taha El Amine Kassabi (501caed, 68e3af3, 7b53faa, a103ac0)

[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

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: c2f2b1d3-51c1-43be-b993-f7537d080b2e

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.

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 · previous review 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

Fix failing CI checks

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

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

ℹ️ 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.

[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

[hemanthreddy7]

Thanks for this, @dpkass, and for raising #388 alongside it. A hard-coded 300s buffer plus up-to-300s jitter means short-lived tokens get treated as stale almost immediately, so making the timing configurable is a sensible and backward-compatible fix. The direction is good. I've left inline comments on the Files changed tab; collecting the main points here so they're in one place.

1. Design

1. buffer and jitter config (client level vs request level vs under Credentials object) - here
2. removing buffer and jitter from the token cache key - here

2. Cross-SDK consistency
These SDKs are meant to behave consistently, so in parallel I'll check whether the other OpenFGA SDKs have the same hard-coded buffer/jitter and whether they expose configurable timing. If we settle on a shape here, it's worth tracking matching changes in the others (ideally coordinated through sdk-generator where it applies) so the behavior stays aligned across languages. This PR effectively sets the pattern the others would follow, which is another reason to get the design right here first.

3. Suggested sequencing
I'd suggest picking the comments related to buffer/jitter config and the cache-key design first so the other comments naturally follow.

4. Tests and coverage
Added inline comments where needed

Please let me know if there are any questions or if you need any clarifications.

Thank you again for the contribution.

[dpkass]

@hemanthreddy7 Addressed the review and fixed the CLA (removed the co-author). Ready for another look.