Document client assignment request reliability by leoromanovsky · Pull Request #39560 · DataDog/documentation

leoromanovsky · 2026-08-28T19:34:38Z

Motivation

Client applications need bounded assignment initialization without changing default SDK behavior. The guides must describe one consistent cross-SDK contract.

Changes and Decisions

Consolidate the client documentation and supersede [reorg fix] [DOCS-15300] Document Unity assignment request limits #38869, [reorg fix] [DOCS-15299] Document Flutter assignment request limits #38870, [reorg fix] [DOCS-15298] Document Android assignment request limits #38871, [reorg fix] [DOCS-15297] Document iOS assignment request limits #38872, and [reorg fix] [DOCS-15296] Document browser assignment request limits #38873.
Document timeout examples and assignment-only transport building blocks for JavaScript, iOS, Android, Flutter, and Unity.
Keep timeout and retry policies disabled by default. A timeout of zero disables the SDK timer.
Retry transient failures with randomized exponential backoff capped at 30 seconds.
Honor bounded HTTP 503 Retry-After values. Do not retry cancellation, HTTP 429, permanent failures, or other HTTP responses.
Document each SDK's configuration bounds, transport ownership, and policy composition.
Defer React Native documentation until released native dependencies are available.
Publish these docs after the documented SDK versions are released.

github-actions · 2026-08-28T19:39:24Z

Preview links (active after the `build_preview` check completes)

Modified Files

Document zero-default assignment timeout and retry controls for supported client SDKs, including composable transport examples. Defer React Native until released native dependencies are available. Environment: Datadog workspace

leoromanovsky · 2026-09-01T17:24:51Z

/review

github-actions

🤖 Automated review by Claude. AI-generated; verify before acting.

Content is accurate and complete. Two blocker-adjacent findings on the new snippets/alert copy, plus one consistency nit.

_{Reviewed 030aba59578b1c918e736d9f81fb2957934d7f5b — workflow run}

aarsilv

Nice! Thanks for getting this out so fast. Approving assuming the code issues caught by GitHub fixed up.

…ment-flag-assignment-reliability

clreaume

first round of suggestions/comments. please reach out if you need help deciphering any of this!

clreaume · 2026-09-04T14:50:20Z

+: Timeout in milliseconds for each flag assignment request, including the complete response-body download. The SDK does not add a timeout by default. Set a positive value to enable the timeout; `0` leaves it disabled. Negative values are coerced to `0`. When the HTTP call already has a nonzero timeout, the shorter timeout applies.
+
+`assignmentRequestRetryCount(retryCount)`
+: Number of retries after the initial flag assignment request. The default is `0`, so the SDK makes only the initial request unless you opt in to retries. Values outside the range from `0` to `10` are coerced to the nearest bound. Retries cover selected transient network errors, timeouts, HTTP 408, and HTTP 5xx responses. Canceled calls, HTTP 429, generic I/O errors, permanent protocol errors, and TLS failures are not retried. Retries use randomized exponential backoff capped at 30 seconds. The SDK reads `Retry-After` only for HTTP 503. A valid value up to 30 seconds is a minimum delay before the backoff. A response that requests a longer delay is not retried.


what does it mean for values outside 0 to 10 to be "coerced to the nearest bound"?

clreaume · 2026-09-04T15:41:29Z


 Choose the SDK that matches where the flag is evaluated and initialize the Datadog Feature Flags provider.

+<div class="alert alert-warning">Client SDKs do not add a flag assignment request timeout or retry by default, so the underlying platform transport remains authoritative. Configure a timeout of at most 1,500 milliseconds when initialization must finish within a known period. Retries cover transient network errors, timeouts, HTTP 408, and HTTP 5xx responses. They use randomized exponential backoff capped at 30 seconds. For HTTP 503, a valid <code>Retry-After</code> value up to 30 seconds is a minimum delay before the backoff. A response that requests a longer delay is not retried. Mobile SDKs do not retry cancellation, HTTP 429, generic I/O errors, permanent protocol errors, or TLS failures. Browser Fetch reports several failures as <code>TypeError</code> and cannot separate these causes. See the <a href="/feature_flags/client/">client SDK guides</a> for platform-specific timeout, retry, and transport APIs.</div>


Suggested change

<div class="alert alert-warning">Client SDKs do not add a flag assignment request timeout or retry by default, so the underlying platform transport remains authoritative. Configure a timeout of at most 1,500 milliseconds when initialization must finish within a known period. Retries cover transient network errors, timeouts, HTTP 408, and HTTP 5xx responses. They use randomized exponential backoff capped at 30 seconds. For HTTP 503, a valid <code>Retry-After</code> value up to 30 seconds is a minimum delay before the backoff. A response that requests a longer delay is not retried. Mobile SDKs do not retry cancellation, HTTP 429, generic I/O errors, permanent protocol errors, or TLS failures. Browser Fetch reports several failures as <code>TypeError</code> and cannot separate these causes. See the <a href="/feature_flags/client/">client SDK guides</a> for platform-specific timeout, retry, and transport APIs.</div>

I think this level of explanation, and its prominence, are overkill for a "getting started" guide. I'm suggesting removing this callout, and extracting the essence into a code comment below—just above the new line bounding the request to 1,500 milliseconds. see that separate suggestion below

clreaume · 2026-09-04T15:42:10Z

    service: '<SERVICE_NAME>',
-    version: '1.0.0'
+    version: '1.0.0',
+    // Bound each configuration request to 1,500 milliseconds.


Suggested change

// Bound each configuration request to 1,500 milliseconds.

// Client SDKs do not set a timeout or retry flag requests by default; the platform's HTTP transport decides how long a request can take. If initialization must finish within a known period, configure a timeout of at most 1,500 milliseconds. See the client SDK guides (/feature_flags/client/) for platform-specific timeout, retry, and transport options.

see comment above for explanation

clreaume · 2026-09-04T15:46:49Z

 val config = FlagsConfiguration.Builder()
-    // configure options here
+    .assignmentRequestTimeout(1_500L)
+    .assignmentRequestRetryCount(2)


Suggested change

.assignmentRequestRetryCount(2)

.assignmentRequestRetryCount(2)

// configure additional options here

as I suggested here, I think it's nice to have this placeholder for the other options, to not imply these are the only ones

clreaume · 2026-09-04T15:55:36Z

 Flags.enable(config)
 {{< /code-block >}}

+`assignmentRequestTimeout(timeoutMs)`


suggesting to move this info above the settings it references

Suggested change

`assignmentRequestTimeout(timeoutMs)`

<div class="alert alert-info">The assignment request timeout and retry settings below apply only to requests that fetch flag assignments. They do not affect exposure, aggregated flag evaluation, or RUM telemetry requests.</div>

`assignmentRequestTimeout(timeoutMs)`

clreaume · 2026-09-04T16:28:20Z

 Flags.enable(with: config)
 {{< /code-block >}}

+`assignmentRequestTimeout`


Suggested change

`assignmentRequestTimeout`

<div class="alert alert-info">Assignment request timeout and retry settings apply only to requests that fetch flag assignments. They do not affect exposure, aggregated flag evaluation, or RUM telemetry requests.</div>

`assignmentRequestTimeout`

moving callout from below

clreaume · 2026-09-04T16:32:54Z

+For lower-level transport control, compose an assignment-only fetch implementation:
+
+{{< code-block lang="swift" >}}
+let assignmentFetch = Flags.AssignmentRequestFetch
+    .urlSession()
+    .withTimeout(1.5)
+    .withRetry(2)
+
+var config = Flags.Configuration()
+config.assignmentRequestFetch = assignmentFetch
+Flags.enable(with: config)
+{{< /code-block >}}
+
+The SDK still constructs the URL, body, authentication, and custom headers. A supplied `assignmentRequestFetch` replaces the scalar timeout and retry settings. The SDK accepts at most one completion from the supplied fetch for each request and validates the HTTP response status. The custom transport applies only to assignment requests. The caller retains ownership of a supplied `URLSession` and other custom transport resources. The SDK does not invalidate or close them.
+
+`withTimeout(timeout)`
+: Adds a timeout that includes the complete response-body download. A positive, finite value enables the timeout. A nonpositive or non-finite value leaves the transport unchanged. Values greater than `2_147_483.647` seconds are reduced to this maximum.
+
+`withRetry(retryCount)`
+: Adds SDK-managed retries after the initial attempt. Values outside the range from `0` to `10` are reduced to the nearest bound. The retry policy matches `assignmentRequestRetryCount`. The SDK reads `Retry-After` only for HTTP 503.
+
+In the example, `withTimeout` is inside `withRetry`. Therefore, each attempt has its own 1.5-second timeout. Reverse the wrappers to use one 1.5-second timeout for the initial request and all retries:
+
+{{< code-block lang="swift" >}}
+let assignmentFetch = Flags.AssignmentRequestFetch
+    .urlSession()
+    .withRetry(2)
+    .withTimeout(1.5)
+{{< /code-block >}}
+
+With this reversed order, one timeout covers all attempts and retry delays. With the original order, total duration includes each attempt timeout and all retry delays.
+


suggesting to move this into a new H3 (titled ### Supply a custom assignment transport) after line 525 (customFlagsHeaders entry), before ## Testing (527)

clreaume · 2026-09-04T19:15:04Z

+
+### Bound flag configuration requests
+
+The browser provider does not add a timeout or retries by default. Use `withTimeout` and `withRetry` to bound each request attempt and retry transient failures:


Suggested change

The browser provider does not add a timeout or retries by default. Use `withTimeout` and `withRetry` to bound each request attempt and retry transient failures:

The browser provider does not add a timeout or retries by default. Use `withTimeout` and `withRetry` to limit each request attempt and retry transient failures:

<div class="alert alert-info">The `flagConfigurationFetch` option applies only to flag configuration requests. It does not affect exposure, aggregated flag evaluation, or RUM telemetry requests.</div>

suggesting moving alert from below up here. also updating "bound" to "limit"

clreaume · 2026-09-04T19:15:19Z

+
+In the example, `withTimeout` is inside `withRetry`. Therefore, each attempt has its own 1,500-millisecond timeout.
+
+<div class="alert alert-info">The `flagConfigurationFetch` option applies only to flag configuration requests. It does not affect exposure, aggregated flag evaluation, or RUM telemetry requests.</div>


Suggested change

<div class="alert alert-info">The `flagConfigurationFetch` option applies only to flag configuration requests. It does not affect exposure, aggregated flag evaluation, or RUM telemetry requests.</div>

suggesting moving this above

clreaume · 2026-09-04T19:19:57Z

 | `overwriteRequestHeaders` | `false` | Replace default request headers with `customHeaders`. |
+| `flagConfigurationFetch` | `globalThis.fetch` | Provide a Fetch-compatible implementation for flag configuration requests. |
+
+### Bound flag configuration requests


Suggested change

### Bound flag configuration requests

### Set a timeout and retries for flag configuration requests

leoromanovsky changed the title ~~Document client assignment request timeouts and retries~~ Document client assignment request reliability Aug 28, 2026

leoromanovsky mentioned this pull request Aug 28, 2026

[FFL-2891] Add Flags initialization timeout DataDog/dd-sdk-ios#3167

Open

docs: document opt-in assignment request reliability

a1b96ad

Document zero-default assignment timeout and retry controls for supported client SDKs, including composable transport examples. Defer React Native until released native dependencies are available. Environment: Datadog workspace

leoromanovsky force-pushed the leo.romanovsky/document-flag-assignment-reliability branch from bb55615 to a1b96ad Compare August 28, 2026 23:20

docs: recommend bounded assignment timeouts in setup

030aba5

leoromanovsky marked this pull request as ready for review September 1, 2026 17:24

leoromanovsky requested a review from a team as a code owner September 1, 2026 17:24

github-actions Bot reviewed Sep 1, 2026

View reviewed changes

Comment thread hugo/content/en/feature_flags/client/flutter.md

Comment thread hugo/content/en/getting_started/feature_flags/_index.md Outdated

Comment thread hugo/content/en/feature_flags/client/javascript.md Outdated

aarsilv approved these changes Sep 1, 2026

View reviewed changes

hestonhoffman added the editorial review Waiting on a more in-depth review label Sep 1, 2026

docs: use the shipped browser fetch option

ea97412

leoromanovsky mentioned this pull request Sep 3, 2026

[FFL-2929] Add Flags initialization timeout DataDog/dd-sdk-android#3693

Open

leoromanovsky added 10 commits September 2, 2026 22:46

docs: correct browser retry and timeout limits

b220ec9

docs: clarify assignment transport behavior

783375e

docs: address assignment reliability feedback

added44

Merge remote-tracking branch 'origin/master' into leo.romanovsky/docu…

dec541c

…ment-flag-assignment-reliability

docs: align assignment request retry policies

526cfe1

docs: clarify Android timeout composition

324773a

docs: use browser flag configuration fetch option

c97477d

docs: describe iOS assignment request bounds

5e59f39

docs: document Android custom call requirements

325c289

docs: clarify assignment retry duration and ownership

b802ff0

clreaume reviewed Sep 4, 2026

View reviewed changes


		Choose the SDK that matches where the flag is evaluated and initialize the Datadog Feature Flags provider.

		<div class="alert alert-warning">Client SDKs do not add a flag assignment request timeout or retry by default, so the underlying platform transport remains authoritative. Configure a timeout of at most 1,500 milliseconds when initialization must finish within a known period. Retries cover transient network errors, timeouts, HTTP 408, and HTTP 5xx responses. They use randomized exponential backoff capped at 30 seconds. For HTTP 503, a valid <code>Retry-After</code> value up to 30 seconds is a minimum delay before the backoff. A response that requests a longer delay is not retried. Mobile SDKs do not retry cancellation, HTTP 429, generic I/O errors, permanent protocol errors, or TLS failures. Browser Fetch reports several failures as <code>TypeError</code> and cannot separate these causes. See the <a href="/feature_flags/client/">client SDK guides</a> for platform-specific timeout, retry, and transport APIs.</div>

	// Bound each configuration request to 1,500 milliseconds.
	// Client SDKs do not set a timeout or retry flag requests by default; the platform's HTTP transport decides how long a request can take. If initialization must finish within a known period, configure a timeout of at most 1,500 milliseconds. See the client SDK guides (/feature_flags/client/) for platform-specific timeout, retry, and transport options.

	.assignmentRequestRetryCount(2)
	.assignmentRequestRetryCount(2)
	// configure additional options here


		### Bound flag configuration requests

		The browser provider does not add a timeout or retries by default. Use `withTimeout` and `withRetry` to bound each request attempt and retry transient failures:


		In the example, `withTimeout` is inside `withRetry`. Therefore, each attempt has its own 1,500-millisecond timeout.

		<div class="alert alert-info">The `flagConfigurationFetch` option applies only to flag configuration requests. It does not affect exposure, aggregated flag evaluation, or RUM telemetry requests.</div>

	### Bound flag configuration requests
	### Set a timeout and retries for flag configuration requests

Uh oh!

Conversation

leoromanovsky commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes and Decisions

Uh oh!

github-actions Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview links (active after the build_preview check completes)

Modified Files

Uh oh!

leoromanovsky commented Sep 1, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aarsilv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clreaume left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

leoromanovsky commented Aug 28, 2026 •

edited

Loading

github-actions Bot commented Aug 28, 2026 •

edited

Loading

Preview links (active after the `build_preview` check completes)