docs: Add per-request custom HTTP headers documentation #216
Conversation
- Added comprehensive documentation section for custom headers feature - Included examples showing headers usage with check and write requests - Added table of contents entry for easy navigation - Described common use cases: correlation IDs, tracing, client metadata, routing - Fixes #215
WalkthroughREADME reorganized with a new TOC, added documentation for per-request custom HTTP headers (duplicated in two sections), updated transaction example to include headers, and expanded retries customization guidance. Minor content rewording and new sections (documentation links, author, license) were added. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Assessment against linked issues
✨ Finishing Touches🧪 Generate 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. Comment |
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
Warning Review the following alerts detected in dependencies. According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Codecov Report✅ All modified and coverable lines are covered by tests. ❌ Your project status has failed because the head coverage (70.70%) 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 #216 +/- ##
=======================================
Coverage 70.70% 70.70%
=======================================
Files 134 134
Lines 10881 10881
=======================================
Hits 7693 7693
Misses 3188 3188 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
README.md (3)
63-68: Fix TOC nesting for OpenTelemetry"OpenTelemetry" is listed under "Documentation For Models" in the TOC, but in the document it’s a separate section. Adjust indentation so it’s a sibling (not a child) entry.
- - [Documentation For Models](#documentation-for-models) - - [OpenTelemetry](#opentelemetry) + - [Documentation For Models](#documentation-for-models) + - [OpenTelemetry](#opentelemetry) - [Contributing](#contributing)
615-619: Nice inline example showing per-request headers with write()Good placement and consistent with the new section. Consider mirroring a small headers snippet in the non-transaction example for parity, but optional.
1173-1213: Per-request headers docs are clear; add sync example + brief cautionsGreat section and example. Two small improvements:
- Include a synchronous-client example for completeness.
- Add a short note to avoid sending secrets and remind that intermediaries may log headers.
The `headers` option accepts a dictionary where keys are header names and values are header values. All values should be strings. These headers will be sent alongside the request to the OpenFGA server. **Common use cases for custom headers:** @@ **Note**: Custom headers are sent on a per-request basis. If you need to set headers for all requests, consider using the client configuration's default headers instead. +#### Synchronous client example +```python +from openfga_sdk.sync import OpenFgaClient +from openfga_sdk.client import ClientCheckRequest +from openfga_sdk.client import ClientConfiguration + +with OpenFgaClient(ClientConfiguration(api_url=FGA_API_URL, store_id=FGA_STORE_ID)) as fga_client: + options = { + "authorization_model_id": "01GXSA8YR785C4FYS3C0RTG7B1", + "headers": {"x-correlation-id": "sync-check-001"} + } + req = ClientCheckRequest(user="user:123", relation="viewer", object="document:abc") + resp = fga_client.check(req, options) +``` + +Security/ops notes: +- Do not place secrets in custom headers; intermediaries or logs may capture them. +- Prefer stable, non-PII correlation IDs (UUIDs) to avoid leaking sensitive data.
| **Note**: Custom headers are sent on a per-request basis. If you need to set headers for all requests, consider using the client configuration's default headers instead. | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify “default headers” capability in ClientConfiguration
The note mentions default headers via client configuration. Please confirm the actual parameter name and location (e.g., ClientConfiguration(..., default_headers=...)?), or adjust wording if not supported.
🏁 Script executed:
#!/bin/bash
# Locate default headers support in the SDK
rg -n -C2 -g '!**/dist/**' -g '!**/build/**' -P '\b(ClientConfiguration|Configuration)\b.*'
rg -n -C2 -P '\bdefault_headers\b|\bcustom_headers\b|\bheaders\b' openfga_sdkLength of output: 87389
Adjust “default headers” note in README
There is no default_headers parameter on ClientConfiguration; to set headers globally, use OpenFgaClient.set_default_header(name, value) on the client instance.
🤖 Prompt for AI Agents
In README.md around lines 1211-1212, the note incorrectly refers to a
non-existent ClientConfiguration parameter "default headers"; update the text to
instruct users to call OpenFgaClient.set_default_header(name, value) on the
client instance to set headers globally (and remove the reference to
ClientConfiguration.default_headers), optionally showing the single-line call
pattern and clarifying that custom headers remain per-request if not set via
set_default_header.
Description
What problem is being solved?
How is it being solved?
What changes are made to solve it?
References
Review Checklist
mainSummary by CodeRabbit