chore(js): make [email protected] the minimum supported version#535
Merged
Conversation
|
Documentation Updates 1 document(s) were updated by changes in this PR: Retry-After Header and Retry StrategyView Changes@@ -1,11 +1,9 @@
## Retry Strategy Enhancements
-
OpenFGA SDKs implement a robust, configurable retry strategy to improve reliability and handle rate limiting and transient server errors. The enhancements include support for the RFC 9110 `Retry-After` header, exponential backoff with jitter as a fallback, strict enforcement of retry limits, and improved error reporting. This documentation details the retry strategy across the JavaScript, Java, Go, Python, and .NET SDKs, including configuration options and migration guidance for breaking changes.
---
### Common Principles
-
All OpenFGA SDKs now:
- Parse and respect the RFC 9110 `Retry-After` header (integer seconds or HTTP-date) for 429 and 5xx (except 501) responses, using the server-specified delay if valid (1–1800 seconds).
@@ -18,22 +16,25 @@
---
## SDK-Specific Details
-
### JavaScript SDK (`@openfga/sdk`)
**Version Introduced:** v0.9.1 (2025-11-05)
**[Changelog](https://github.com/openfga/js-sdk/blob/ca4b9fcf9eaed35170d44a4b3697f439b81187f6/CHANGELOG.md#L8-L10)**
-#### Retry-After Handling
-
+# SDK-Specific Details
+#### Node.js Version Support (JavaScript SDK)
+
+The minimum supported Node.js version for the JavaScript SDK is **v20.19.0**. Node.js v16 and v18 are no longer supported. For a detailed support policy and a list of tested Node.js versions, see [SUPPORTED_RUNTIMES.md](https://github.com/openfga/language/blob/main/pkg/js/SUPPORTED_RUNTIMES.md).
+
+We recommend using a Node.js version that is currently supported upstream (see [Node.js release schedule](https://nodejs.org/en/about/previous-releases)), such as 20 (maintenance), 22 (maintenance), 24 (LTS), or 25 (current).
+
+#### Retry-After Handling
The SDK parses the `Retry-After` header as either an integer (seconds) or HTTP-date. If the value is between 1 second and 30 minutes (1800 seconds), it waits for the specified delay before retrying. If the header is missing, invalid, or out of bounds, the SDK falls back to exponential backoff with jitter.
#### Exponential Backoff with Jitter
-
The delay is randomized between `2^retryAttempt * minWaitInMs` and `2^(retryAttempt+1) * minWaitInMs`, capped at 120 seconds. For example, with the default `minWaitInMs` of 100ms, the sequence is approximately 100ms, 200ms, 400ms, 800ms, 1.6s, 3.2s, 6.4s, 12.8s, 25.6s, 51.2s, 102.4s, and then capped at 120s for subsequent retries.
#### Configuration
-
Set retry parameters via the `retryParams` option when initializing the client:
```js
@@ -48,35 +49,28 @@
[See README for details](https://github.com/openfga/js-sdk/blob/ca4b9fcf9eaed35170d44a4b3697f439b81187f6/README.md#L857-L875)
#### Error Exposure
-
When retries are exhausted or not applicable, errors are thrown as specific classes: `FgaApiRateLimitExceededError` for 429, `FgaApiInternalError` for 5xx, and `FgaApiError` for other cases. These errors do not directly expose the `Retry-After` value, but the retry logic respects it internally.
#### Migration Guidance
-
- Upgrade to v0.9.1+ to use `Retry-After` support.
- If you previously relied on custom retry logic, review the new defaults and configuration.
-- The minimum Node.js version is now v16.15.0.
+- The minimum supported Node.js version is now **v20.19.0**. Update your runtime accordingly.
- The maximum allowed `maxRetry` is now enforced at 15.
- No retries are performed for 501 errors, even if a `Retry-After` header is present.
- If you used the old `batchCheck` method, migrate to `clientBatchCheck` as per the [changelog](https://github.com/openfga/js-sdk/blob/ca4b9fcf9eaed35170d44a4b3697f439b81187f6/CHANGELOG.md#L8-L44).
-
----
+- For details on supported Node.js versions and our support policy, see [SUPPORTED_RUNTIMES.md](https://github.com/openfga/language/blob/main/pkg/js/SUPPORTED_RUNTIMES.md).
### Java SDK
-
**Version Introduced:** v0.9.0
**[Changelog](https://github.com/openfga/java-sdk/blob/33a85203ec0af0935b0fa265a469a1851870fff7/CHANGELOG.md#L40-L52)**
#### Retry-After Handling
-
The SDK parses the `Retry-After` header as either an integer (seconds) or HTTP-date. If the value is between 1 and 1800 seconds, it is used as the retry delay. Otherwise, the SDK falls back to exponential backoff with jitter.
#### Exponential Backoff with Jitter
-
The delay is calculated as `2^retryCount * minimumRetryDelay` (default 100ms), with jitter randomized between this value and twice this value, capped at 120 seconds.
#### Configuration
-
Configure retries via `ClientConfiguration`:
```java
@@ -88,11 +82,9 @@
[See README for details](https://github.com/openfga/java-sdk/blob/33a85203ec0af0935b0fa265a469a1851870fff7/README.md#L1103-L1168)
#### Error Exposure
-
The `FgaError` exception exposes the `Retry-After` header value via `getRetryAfterHeader()`, allowing users to inspect the server-specified delay for debugging or custom logic.
#### Migration Guidance
-
- The maximum allowed `maxRetries` is now enforced at 15.
- `minimumRetryDelay` must be non-null and non-negative.
- Update error handling to use `getRetryAfterHeader()` if you need access to the `Retry-After` value.
@@ -101,20 +93,16 @@
---
### Go SDK
-
**Version Introduced:** v0.7.0
**[Changelog](https://github.com/openfga/go-sdk/blob/c52ca06c03934b954d50ca34845b73076b6fa9eb/CHANGELOG.md#L36-L51)**
#### Retry-After Handling
-
The SDK parses the `Retry-After` header (and related headers) as either integer seconds or HTTP-date. If the value is between 1 and 1800 seconds, it is used as the retry delay. Otherwise, the SDK falls back to exponential backoff with jitter.
#### Exponential Backoff with Jitter
-
The delay is randomized between `2^loopCount * minWaitInMs` and `2^(loopCount+1) * minWaitInMs`, capped at 120 seconds.
#### Configuration
-
Set retry parameters via the `RetryParams` struct in `ClientConfiguration`:
```go
@@ -129,11 +117,9 @@
[See README for details](https://github.com/openfga/go-sdk/blob/c52ca06c03934b954d50ca34845b73076b6fa9eb/README.md#L1099-L1127)
#### Error Exposure
-
Error types such as `FgaApiInternalError` and `FgaApiRateLimitExceededError` expose retry delay information via `RetryAfterDurationInMs()` and `RetryAfterEpoc()` methods.
#### Migration Guidance
-
- Upgrade to v0.7.0+ for improved retry and rate limit handling.
- The maximum allowed `MaxRetry` is now enforced at 15.
- The `BatchCheck` method was renamed to `ClientBatchCheck` (not directly related to retry logic).
@@ -141,20 +127,16 @@
---
### Python SDK
-
**Version Introduced:** v0.9.4 (2025-04-30)
**[Changelog](https://github.com/openfga/python-sdk/pull/189)**
#### Retry-After Handling
-
The SDK parses the `Retry-After` header as either integer seconds or HTTP-date. If the value is between 1 and 1800 seconds, it is used as the retry delay. Otherwise, the SDK falls back to exponential backoff with jitter, capped at a maximum wait time (default 120 seconds).
#### Exponential Backoff with Jitter
-
The delay is randomized between `2^retryAttempt * min_wait_in_ms` and `2^(retryAttempt+1) * min_wait_in_ms`, converted to seconds, and capped at `max_wait_in_sec` (default 120s).
#### Configuration
-
Set retry parameters via the `RetryParams` class in the client configuration:
```python
@@ -168,11 +150,9 @@
```
#### Error Exposure
-
If the `Retry-After` header is invalid or missing, a `ValueError` is raised and the SDK falls back to exponential backoff. Retry-related errors are surfaced through exceptions.
#### Migration Guidance
-
- The default `max_retry` is now 3 (was previously 15).
- Ensure any custom retry logic or error handling is updated to use the new configuration and error exposure patterns.
- Upgrade to v0.9.4+ for full `Retry-After` support.
@@ -180,20 +160,16 @@
---
### .NET SDK
-
**Version Introduced:** v0.8.0 (2025-10-22)
**[Changelog](https://github.com/openfga/dotnet-sdk/pull/142)**
#### Retry-After Handling
-
The SDK parses the `Retry-After` header as either integer seconds or HTTP-date. If the value is between 1 and 1800 seconds, it is used as the retry delay. Otherwise, the SDK falls back to exponential backoff with jitter.
#### Exponential Backoff with Jitter
-
The delay is randomized between `2^loopCount * 500ms` and `2^(loopCount+1) * 500ms`, capped at 120 seconds.
#### Configuration
-
Set retry parameters via the `RetryParams` object in `ClientConfiguration`:
```csharp
@@ -210,11 +186,9 @@
```
#### Error Exposure
-
When retries are exhausted, `FgaApiRateLimitExceededError` exposes the parsed `RetryAfter` delay in seconds, the raw header value, and the number of retry attempts made.
#### Migration Guidance
-
- All `OpenFgaApi` methods now accept an optional `IRequestOptions` parameter. Update direct API calls accordingly.
- The base client request options interface was renamed from `ClientRequestOptions` to `IClientRequestOptions`. Update any references or implementations.
- The maximum allowed `MaxRetry` is now enforced at 15.
@@ -223,7 +197,6 @@
---
## Comparison Table
-
| SDK | Retry-After Support | Exponential Backoff (Default) | Max Retries (Default/Max) | Min Retry Delay (Default) | Error Exposure | Version Introduced |
|-------------|--------------------|-------------------------------|---------------------------|--------------------------|---------------|-------------------|
| JavaScript | Yes (int/date, 1–1800s) | 2^n * minWaitInMs, jitter, cap 120s | 3 / 15 | 100ms | Error classes | v0.9.1 |
@@ -235,7 +208,6 @@
---
## References
-
- [JavaScript SDK Changelog](https://github.com/openfga/js-sdk/blob/ca4b9fcf9eaed35170d44a4b3697f439b81187f6/CHANGELOG.md#L8-L44)
- [Java SDK Changelog](https://github.com/openfga/java-sdk/blob/33a85203ec0af0935b0fa265a469a1851870fff7/CHANGELOG.md#L40-L52)
- [Go SDK Changelog](https://github.com/openfga/go-sdk/blob/c52ca06c03934b954d50ca34845b73076b6fa9eb/CHANGELOG.md#L36-L51)How did I do? Any feedback? |
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughUpdates Node.js support requirements from v16/v18 to minimum v20.19.0, expands CI test matrix to include Node 25.x, introduces git tag validation and improved npm publishing workflow, and documents the updated support policy in new and existing documentation files. Changes
Sequence Diagram(s)sequenceDiagram
participant Workflow as GitHub Actions Workflow
participant Validation as Tag Validation Step
participant NPM as NPM Registry
Workflow->>Validation: Extract git tag from ref
Validation->>Validation: Validate format (vX.Y.Z with optional pre-release)
alt Valid Tag Format
Validation->>Validation: Determine dist-tag (alpha/beta/rc/latest)
Validation-->>Workflow: Output determined tag
Workflow->>NPM: Publish via npx [email protected]<br/>with determined dist-tag
NPM-->>Workflow: Publish successful
else Invalid Tag Format
Validation-->>Workflow: Exit with error and guidance
end
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly Related PRs
Suggested Reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR drops Node.js 16/18 support for the JS package and updates package metadata and CI/release automation to reflect a Node.js v20+ baseline.
Changes:
- Add
engines.nodeconstraint topkg/js/package.json. - Document supported Node.js runtimes and link that policy from the JS package README/changelog.
- Update GitHub Actions workflows to test against Node 25 and adjust the npm publish flow.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
pkg/js/package.json |
Enforces a minimum Node version via engines. |
pkg/js/SUPPORTED_RUNTIMES.md |
Adds a Node.js support policy document. |
pkg/js/README.md |
Links to the support policy from the package README. |
pkg/js/CHANGELOG.md |
Notes the breaking change / Node support drop in Unreleased. |
.github/workflows/pkg-js-release.yaml |
Refactors Node setup and adds tag→npm-dist-tag logic for publishing. |
.github/workflows/pkg-js-build.yaml |
Expands the test matrix to include Node 25 and minor config cleanup. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/pkg-js-release.yaml (1)
93-96:⚠️ Potential issue | 🟡 MinorNote:
rcpre-releases won't be marked as prerelease GitHub releases.The
prerelease_regexon line 96 only matchesalpha|betasuffixes. Tags likev1.2.3-rc.1will be treated as full releases by the GitHub release action. If this is intentional (rc ≈ near-stable), no action needed — just flagging for awareness.
🤖 Fix all issues with AI agents
In @.github/workflows/pkg-js-release.yaml:
- Around line 51-77: The TAG extracted in the npm-tag step (variable TAG from
GITHUB_REF) can contain a leading path like "pkg/js/" so the current regex ^v...
will always fail; update the npm-tag step to strip any prefix path (e.g., remove
"pkg/js/" or anything before the last slash) from TAG after removing refs/tags/
and before running the regex/validation and npm-tag determination, ensuring the
regex is applied to the bare version string (refer to the npm-tag step and the
TAG/GITHUB_REF handling and the version regex).
In `@pkg/js/SUPPORTED_RUNTIMES.md`:
- Around line 3-12: The policy header in SUPPORTED_RUNTIMES.md says we support
Node.js versions in "LTS or Maintenance" but the table includes Node.js 25 as
"Current"; update the policy statement to accurately reflect what's listed in
the table (e.g., change the header sentence to "We support Node.js versions that
are currently in LTS, Maintenance, or Current status" or add a note that
"Current" is supported on a best-effort basis) so the description and the table
(specifically the entry for Node 25) are consistent.
SoulPancake
approved these changes
Feb 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Drop support for Node.js v16 & 18. We recommend updating to a node-runtime that is supported upstream - currently 20 (maintenance), 22 (maintenance), 24 (LTS) and 25 (current).
The minimum supported version of Node.js is now v20
What problem is being solved?
How is it being solved?
What changes are made to solve it?
References
Review Checklist
mainSummary by CodeRabbit
Release Notes
Documentation
Chores