fix: ensure headers can be set and overriden

[ewanharris]

Description

What problem is being solved?

The project does not document or test custom headers support

How is it being solved?

Documentation and tests added, fixes made where relevant

What changes are made to solve it?

Adds tests and documentation for setting default headers and overriding them per-request, this also extended to a few fixes due to issue uncovered, they are:

• c4b416f - Overriding defaultHeaders on ClientConfiguration so typing works correctly
• 705472f - Correctly handles calling readAuthorizationModel with options but no model ID set
• 67a625e - Sets the headers when copying over to the ClientBatchCheck options

There is one discussion point I have that I will comment in the PR regarding

References

openfga/sdk-generator#569

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features

  • Fluent configuration for default HTTP headers in the client.

• Bug Fixes

  • Prefer per-call authorization model when provided; otherwise fall back to configuration.
  • Copy per-request header maps to prevent unintended mutations.

• Documentation

  • Added README examples for default and per-request headers (note: content was inserted twice).

• Tests

  • Added comprehensive header tests covering merging, overrides, edge cases, and request verification.

[coderabbitai]

Walkthrough

Documentation adds examples for default and per-request headers. ClientConfiguration gains a fluent defaultHeaders setter. Header maps are defensively copied when building nested options. OpenFgaClient prefers a non-blank options authorizationModelId over configuration and standardizes header preparation. Tests add/adjust extensive header-behavior coverage.

Changes

Cohort / File(s)	Summary
Docs: Header usage in README README.md	Adds sections explaining default headers via ClientConfiguration.defaultHeaders and per-request headers via additionalHeaders, with examples; content inserted twice.
Client config: fluent default headers src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java	Adds overridden defaultHeaders(Map<String,String>) that delegates to super and returns this to support fluent chaining.
Header propagation: defensive copies src/main/java/dev/openfga/sdk/api/configuration/ClientListRelationsOptions.java, src/main/java/dev/openfga/sdk/api/configuration/ClientBatchCheckClientOptions.java	When converting/building nested options, additionalHeaders are passed as a defensive copy (new HashMap<>(...)) if non-null; null preserved.
Client: header handling & auth model selection src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java	Selection now prefers a non-blank options.getAuthorizationModelId...() value and falls back to configuration.getAuthorizationModelId...() when options are null/blank. Header-preparation logic standardized to avoid mutating caller maps across many endpoints (check, batchCheck, listRelations, expand, listObjects, listUsers, readAssertions, writeAssertions, etc.).
Tests: header behavior coverage src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java	New comprehensive test suite validating default/per-request header merging, overrides, null/empty handling, special characters, and header propagation across many operations using HttpClientMock.
Tests: client-method header updates src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java	Updated expected X-OpenFGA-Client-Method header value from "ClientBatchCheck" to "ListRelations" in relevant tests.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Caller
  participant Client as OpenFgaClient
  participant Config as ClientConfiguration

  Caller->>Client: readAuthorizationModel(options)
  alt options has non-blank authorizationModelId
    Client->>Client: use options.getAuthorizationModelIdChecked()
  else fallback
    Client->>Config: configuration.getAuthorizationModelIdChecked()
    Config-->>Client: authorizationModelId
  end
  Client->>Client: prepare request (defensive headers copy, merge)
  Client-->>Caller: AuthorizationModel

Loading

sequenceDiagram
  autonumber
  actor Caller
  participant Client as OpenFgaClient
  participant Config as ClientConfiguration
  participant HTTP as HttpClient

  Caller->>Client: any API call (opts may include additionalHeaders)
  Client->>Config: config.getDefaultHeaders()
  Client->>Client: build headers map
  Note right of Client #DDEBF7: start from defaultHeaders\nif additionalHeaders != null use new HashMap<>(additionalHeaders)\nputIfAbsent/put to merge without mutating caller map
  Client->>HTTP: send HTTP request with merged headers
  HTTP-->>Client: response
  Client-->>Caller: mapped result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat: merge various fixes #175 — similar changes to BatchCheck handling and preferring an options-provided authorizationModelId over client config.
• release: v0.8.2 #180 — touches BatchCheck/authorizationModelId selection and related client request-building/header handling.

Suggested reviewers

• jimmyjames

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.53% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title accurately and concisely summarizes the main objective of the changeset by indicating that header setting and overriding capabilities are fixed, which directly reflects the documentation, tests, and code updates provided.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/settings-headers

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d478606 and 33fa182.

📒 Files selected for processing (2)

• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java (5 hunks)
• src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java

🧰 Additional context used

🪛 Gitleaks (8.28.0)

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java

[high] 38-38: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

🔇 Additional comments (3)

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java (3)

36-44: LGTM! Static analysis false positive can be ignored.

The test constants are well-defined and follow clear naming conventions. The Gitleaks warning about DEFAULT_AUTH_MODEL_ID on line 38 is a false positive—this is clearly test fixture data, not a real API key.

---

50-73: LGTM!

The test setup is clean and well-organized. Configuring default headers in the ClientConfiguration (lines 63-65) provides a solid foundation for testing header override behavior across all test methods.

---

75-974: Excellent comprehensive test coverage!

The test suite thoroughly covers header functionality across all client operations:

• Default headers: Verified across all operations
• Per-call overrides: Tested with Map.of() consistently (e.g., lines 88, 199, 226, 251, 279, 313, 343, 381, etc.)
• Edge cases: Null headers (lines 143, 818, 851), empty headers (line 116), no default headers (line 886), multiple overrides (line 922), special characters (lines 959-961)
• Consistency: All tests use immutable Map.of() throughout, resolving the concerns from previous reviews

Each test follows a clear Given-When-Then structure and verifies HTTP method, URL, headers, and response data. The mock-based approach provides fast, reliable test execution.

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

README.md (1)

239-267: Docs: add a call using options; note mutable map for some ops

• Consider adding a line showing how options are passed, e.g., fgaClient.read(request, options); for completeness.
• For operations that add SDK headers (e.g., batchCheck, listRelations, non-transactional write), prefer a mutable map (e.g., new HashMap<>(Map.of(...))) for additionalHeaders.

Also applies to: 279-299

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5441476 and cba8f6a.

📒 Files selected for processing (5)

• README.md (1 hunks)
• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java (1 hunks)
• src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java (1 hunks)
• src/main/java/dev/openfga/sdk/api/configuration/ClientListRelationsOptions.java (1 hunks)
• src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Test and Build OpenFGA (21)
• GitHub Check: Test and Build OpenFGA (17)
• GitHub Check: Analyze (java)

🔇 Additional comments (2)

src/main/java/dev/openfga/sdk/api/configuration/ClientConfiguration.java (1)

144-148: Fluent override for defaultHeaders looks good

Enables proper chaining, delegates correctly.

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java (1)

329-358: Great coverage; add two edge-case tests for readAuthorizationModel

• options provided with no model ID (null/blank) should fall back to configuration.
• null options passed to the overload should behave like the no-arg variant (and not NPE).

[ewanharris]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.32258% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 35.97%. Comparing base (5441476) to head (33fa182).

Files with missing lines	Patch %	Lines
...java/dev/openfga/sdk/api/client/OpenFgaClient.java	96.29%	0 Missing and 1 partial ⚠️
...i/configuration/ClientBatchCheckClientOptions.java	0.00%	0 Missing and 1 partial ⚠️
.../api/configuration/ClientListRelationsOptions.java	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #226      +/-   ##
============================================
+ Coverage     35.19%   35.97%   +0.78%     
- Complexity     1071     1116      +45     
============================================
  Files           187      187              
  Lines          7087     7096       +9     
  Branches        803      806       +3     
============================================
+ Hits           2494     2553      +59     
+ Misses         4483     4438      -45     
+ Partials        110      105       -5     

☔ View full report in Codecov by Sentry.
📢 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.

[ewanharris]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 45669df and d478606.

📒 Files selected for processing (2)

• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java (3 hunks)
• src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java

🔇 Additional comments (2)

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java (2)

1-73: LGTM! Well-structured test setup.

The test class initialization is clean and comprehensive:

• Clear constant definitions for test data
• Proper mock setup for HttpClient and ApiClient
• Default headers configured in ClientConfiguration for testing merge/override scenarios

---

76-942: Excellent comprehensive test coverage.

The test suite thoroughly validates header behavior across all client operations:

• Default header merging and per-call overrides
• Null and empty header map handling
• Edge cases: no default headers, multiple overrides, special characters
• Consistent Given-When-Then structure with proper assertions
• Good use of mocks to verify HTTP method, URL, headers, and request bodies

[ewanharris]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.