docs: plan for provider.setConfiguration offline init (FFL-2666)

[btthomas]

Offline feature flags — related PRs

• Plan: docs: plan for provider.setConfiguration offline init (FFL-2666) #1326 ← you are here
• Parse & decode ConfigurationWire: feat(flags): ConfigurationWire parse + precomputed decode [PR1] (FFL-2686, FFL-2687) #1330
• Core offline API (FlagsClient.setConfiguration): feat(flags): FlagsClient.setConfiguration + context matching [PR2] (FFL-2688) #1331
• Offline OpenFeature provider: feat(openfeature): DatadogOfflineOpenFeatureProvider [PR3] (FFL-2689, FFL-2690) #1332

---

Summary

Adds provider_set_configuration.md, the design doc for offline feature-flag initialization in the React Native SDK: letting a customer load a flag configuration they fetched themselves and evaluate it exactly as if it came from the edge CDN, via

configurationFromString(wire) -> setConfiguration(configuration) -> evaluate(...)

and a dedicated offline OpenFeature provider that never touches the network. Documentation only — no code.

It covers the scope (precomputed, static single-context) and non-goals, the ConfigurationWire/precomputed formats, context matching, the offline provider, and how the work breaks down. See the doc for detail.

[btthomas]

@codex review

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[aarsilv]

Nice work! 💪 Digging what I'm seeing! I've attempted to answer your open questions. Feel free to get a head start on prototyping this out while people comment on your plan. 🐎

[aarsilv]

The CDN currently returns the backend PrecomputedAssignments / PrecomputedFlag shape

[btthomas]

So is my inlined example above correct?

[aarsilv]

If an error we should return default value but with a PROVIDER_NOT_READY code (@dd-oleksii can fact check me here)

[btthomas]

Above, you just said we should have a PROVIDER_ERROR on mismatch. Which is preferred?

[btthomas]

106ed16

[aarsilv]

I don't see a huge downside to setConfiguration being asynchronous as I imagine being called infrequently and in a non blocking way.

[btthomas]

Our mobile customers are more focused on startup performance, correct? So that means we should make setConfiguration async, so they can do other app init things while our config is loaded, correct? Is that a good or bad assumption?

[aarsilv]

Side note, I am concerned about this being async due to race conditions. See: https://docs.google.com/document/d/12i0O__eHWWj1q5qSXID7VILiWxacHclLef-Y5oSea58/edit?disco=AAAB_VOdxLw

[btthomas]

That comment is related to dynamic (multi-user ruleset) when setContext passes in a new context. Does that concern apply here? Do we need to get it right in this stack of PRs or can it wait until we implement the dynamic context offline init?

[aarsilv]

Future us! Since the current edge compute doesn't do this I think its fine to punt to sometime in the future (or never)

[aarsilv]

On mismatch, values are
not served.

Should we instead return coded default value with a PROVIDER_ERROR code?

[btthomas]

errorCode: INVALID_CONTEXT is in the OpenFeature spec. That's the closest we have to "mismatch".

[btthomas]

106ed16

[aarsilv]

Is plan to unleash agents for stacked PRs here? Note you can have agents use tools like git machete or jj--useful for propagating changes up the stack when iterating on lower down PRs.

[btthomas]

That is exactly my plan. A stack of PRs optimized for review while we can test the top of the stack end-to-end.

[datadog-datadog-prod-us1-2]

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 3a284a7 | Docs | Datadog PR Page | Give us feedback!}

[dd-oleksii]

aside: while we're here, shall we rename FlagCacheEntry and flagsCache? (because it's not a cache and calling it cache is confusing)

I believe in other sdks we call it either "precomputed flag" or "flag configuration"

[dd-oleksii]

"Parsed" seems like a bad describer here — it's not something that we want to highlight. Also having both FlagsConfiguration and an unrelated ParsedFlagsConfiguration makes it way more confusing. I don't have a good suggestion though 😢 having FlagsConfiguration already used is unfortunate

[btthomas]

What should we do? FlagsConfiguration is already defined/exported as the parameter for the public enable() method.

[dd-oleksii]

I'd start with ALWAYS and NEVER. "On mismatch" is not well-defined yet (e.g. we don't have a way to produce context-agnostic config). We might also add "poll" later.

Proposing to go with the minimal set of options for now because it's easy to add options in the future but it's hard to remove them

[dd-oleksii]

Consider moving precomputed configuration types, configuration wire parsing/serializing functions, and precomputed "evaluator" into core

UPD: it looks like they are already there — anything that prevents us from reusing the core?

[btthomas]

anything that prevents us from reusing the core?

I think @sameerank is going to get everything into core this week, so we can import it for dynamic evaluation (the workstream after the current one).

[dd-oleksii]

Could you update the wiki to align it with actual returned type?

[dd-oleksii]

hm... I'm not familiar with RN implementation. Does native side have any state? if native setEvaluationContext returns a configuration, does it actually set anything?

[btthomas]

Native side does save state. I made a note that we should think about whether setConfiguration persists (or doesn't) to disk: 7b8af9c

[sbarrio]

I don't think this is correct. Not propagating the flags configuration to the native SDK level means that hybrid RN apps that want to fetch the flags config from the native SDK won't be able to, since we only set it at JS level.

This could be considered a non-blocker but it is definitely a gap that will need to be acknowledged and solved later down the line.

Also, if we also want to provide users with offline flags persistence we will still need to store this on disk, meaning that we will also need to communicate this to the native SDK.

I think we should keep this in mind going forward. The FFlags SDK on RN needs to be kept in sync with its native counterpart.

[btthomas]

Also, if we also want to provide users with offline flags persistence we will still need to store this on disk, meaning that we will also need to communicate this to the native SDK.

I disagree. When we say "Offline precomputed" we mean that the customer is supplying the precomputed variants to the SDK to initialize. In that case, we don't need to store it because the customer can just supply the same rules again, right?

The FFlags SDK on RN needs to be kept in sync with its native counterpart.

Why? What benefits do we get? Why not keep the RN SDK kept in sync with Browser? Seems easy since we can do them both in javascript and skip the native part.

[sbarrio]

I disagree. When we say "Offline precomputed" we mean that the customer is supplying the precomputed variants to the SDK to initialize. In that case, we don't need to store it because the customer can just supply the same rules again, right?

For that use case yes, it's not necessary. But I assume that at some point a client will want to have a working offline mode that works out of the box, meaning that the last set of flags fetched from Datadog are persisted even if the app goes offline, without them having to worry of persisting those flags on disk on their own. (Growthbook SDK for RN provides this: https://docs.growthbook.io/lib/react-native#caching)

Why? What benefits do we get? Why not keep the RN SDK kept in sync with Browser? Seems easy since we can do them both in javascript and skip the native part.

Because as I mentioned earlier, doing this will break hybrid apps relying on the FFlags module. If the flags configuration is kept at JS level and not propagated to the underlying native SDK, any native code on that hybrid app that asks for the Flags configuration will get an empty or unsynced state.